
************** File: testdoc.do.txt *****************
TITLE: A Document for Testing DocOnce
AUTHOR: Hans Petter Langtangen Email: hpl@simula.no at Center for Biomedical Computing, Simula Research Laboratory & Department of Informatics, University of Oslo
AUTHOR: Kaare Dump at Segfault, Cyberspace
AUTHOR: A. Dummy Author
AUTHOR: I. S. Overworked and Outburned at Inst1 & Inst2, Somewhere & Third Inst, Elsewhere & Fourth Inst
AUTHOR: J. Doe mail: j_doe@cyberspace.com
DATE: today

TOC: on

# #include "_testdoc.do.txt"

************** File: _testdoc.do.txt *****************

!split

<%doc>
This is Mako comment block
to test the use of Mako as preprocessor.
</%doc>


The format of this document is
% if FORMAT == 'html':
plain, homemade HTML (from DocOnce).
  % elif FORMAT == 'latex':
plain, homemade LaTeX (from DocOnce).
  % elif FORMAT == 'pdflatex':
plain, homemade pdfLaTeX (from DocOnce).
  %else:
${FORMAT}
% endif

% if SOMEVAR is not UNDEFINED:
# Just a comment
% endif

__Abstract.__
This is a document with many test constructions for doconce syntax.
It was used heavily for the development and kept for testing
numerous constructions, also special and less common cases.

And exactly for test purposes we have an extra line here, which
is part of the abstract.

# Cannot demonstrate chapter headings since abstract and chapter
# are mutually exclusive in LaTeX

======= Section 1 =======
label{sec1}

Here is a nested list:

  * item1
  * item2
  * item3 which continues
    on the next line to test that feature
  * and a sublist
    * with indented subitem1
    * and a subitem2
  * and perhaps an ordered sublist
    o first item
    o second item,
      continuing on a new line

__Here is a list with paragraph heading.__

  * item1
  * item2

=== Here is a list with subsubsection heading ===

  * item1
  * item2

!bquote
Here are two lines that make up
a block quote for testing *emphasized words* and _boldface words_,
also with hypens:
*pre*-fix, post-*fix*, _pre_-fix, post-_fix_.
!equote

Here are two references. Equation~(ref{my:eq1}) is fine. Eq.~(ref{my:eq1}) too.
Even Equation (ref{my:eq1}) without the tilde.
# #if FORMAT in ("sphinx", "html")
This equation appears in another part if this document is split.
# #endif

# #if FORMAT == 'html'
Let us add a paragraph to
test that HTML,
with WordPress
(`--wordpress` option)
can handle linebreaks
*correctly*,
even when lines begin with
_bold words_ and
`verbatim words` in
color{red}{red color}, and
"links": "https://google.com" as well as math:
$1+1=2$.

Test also that *emphasize*
at the end of line, and _bold_
works, as well as color{blue}{color}
and "links2": "https://google.com"
and `verbatim`
as well.
# #endif

===== Subsection 1 =====
label{subsec1}

idx{`somefunc` function}

# Refer to section/appendix etc. at the beginning of the line
# and other special fix situations for HTML.

More text, with a reference back to
Section ref{sec1} and ref{subsec1}, and further to the
sections    ref{subsec1} and ref{subsubsec:ex}, which
encourages you to do the tasks in the
Exercises ref{demo:ex:1} and ref{exer:some:formula}.
Appendices     ref{app1} and ref{app2} are also nice elements.

=== Test Section reference at beginning of line and after a sentence ===

Section ref{subsec1} is fine.
Section ref{subsubsec:ex} too.


# sphinx code-blocks: pycod=python cod=fortran cppcod=c++ sys=console

=== Computer code ===

Let's do some copying from files too. First from subroutine up to the very end,

@@@CODE ../doc/src/manual/__testcode.f fromto: subroutine@
and then just the subroutine,
@@@CODE ../doc/src/manual/__testcode.f from-to:a comment@^C\s+END1
and finally the complete file with a plain text verbatim environment
(`envir=ccq`):
@@@CODE ../doc/src/manual/__testcode.f envir=ccq

Testing other code environments. First Python:

!bc
|bc pycod
def f(x):
    return x+1
|ec
!ec
which gets rendered as

!bc pycod-t
def f(x):
    return x+1
!ec

# #if FORMAT not in ("rst", "plain", "epytext", "st")
Test paragraph and subsubsection headings before
before code.

__Paragraph heading before code.__

!bc pycod-t
import sys
sys.path.insert(0, os.pardir)
!ec

=== Subsubsection heading before code ===

!bc pycod-t
def h(z):
    return z+1
!ec
# #endif

# #if FORMAT in ("sphinx", "html", "latex", "pdflatex")
Now a complete program to be shown via Python Online Tutorial:
# #else
Here is a program that is supposed to be interactive via
Python Online Tutorial, but that service is not accessible
for the present format.
# #endif

!bc pyoptpro
class Line:
    def __init__(self, a, b):
        self.a, self.b = a, b

    def __call__(self, x):
        a, b = self.a, self.b
        return a*x + b

line = Line(2, 1)
y = line(x=3)
print(y)
!ec

# #if FORMAT == "sphinx"
Another complete program to be typeset as a sage cell:
# #else
Some more Python code (actually specified as a sage cell, but
such cells are not supported by this format).
# #endif

!bc pyscpro
a = 2
b = 3
print('a+b:', a + b)

# In a sage cell we can also plot
from matplotlib.pyplot import *
from numpy import *
x = linspace(0, 4*pi, 101)
y = exp(-0.1*x)*cos(x)
plot(x, y)
xlabel('x'); ylabel('y')
show()
!ec

## Should also test that one can read .pyopt and .pysc programs

Then Cython (with -h option so it is hidden in html/sphinx):

!bc cycod-h
cpdef f(double x):
    return x + 1
!ec

Standard Python shell sessions:

!bc pyshell
>>> from numpy import linspace, sin
>>> # Some comment
>>> x = linspace(0, 2, 11)
>>> y = sin(x)
>>> y[0]
0
>>> import matplotlib.pyplot as plt
>>> plt.plot(x, y)
!ec

Similar IPython sessions:

!bc ipy
In [1]: from numpy import linspace, sin
In [2]: # Some comment
In [3]: x = linspace(0, 2, 11)
In [4]: y = sin(x)
In [5]: y[0]
Out[5]: 0
In [6]: import matplotlib.pyplot as plt
In [7]: plt.plot(x, y)
In [8]: a='multiple-\nline\noutput'
In [9]: a
Out[9]: 'multiple-\nline\noutput'
In [10]: print(a)
multiple-
line
output
!ec

Here is the interactive session again, but with `pyshell-t`.
% if FORMAT == 'ipynb':
This makes a significant difference in the Jupyter Notebook, but
not in other formats: code is not typset in cells, but printed
verbatim in plain text (`-t` for text).
% endif

!bc pyshell-t
>>> from numpy import linspace, sin
>>> # Some comment
>>> x = linspace(0, 2, 11)
>>> y = sin(x)
>>> y[0]
0
>>> import matplotlib.pyplot as plt
>>> plt.plot(x, y)
!ec

# This one tests a + sign before a code environment
C++:
!bc cpppro-t
#include <iostream>

int main()
{
   std::cout << "Sample output" << std::endl;
   return 0
}
!ec
# The next should get correctly typset in sphinx (cod is fcod)
# It also tests emoji before code
And a little bit of Fortran: :dizzy_face:

!bc
|bc cod
      subroutine midpt(x, length, a, b)
      real*8 a, b, x
      x = (a + b)/2
      length = b - a
      return
      end
|ec
!ec
which then is typeset as

!bc cod-t
      subroutine midpt(x, length, a, b)
      real*8 a, b, x
      x = (a + b)/2
      length = b - a
      return
      end
!ec

HTML:

!bc htmlcod
<table>
<tr><td>Column 1</td><td>Column 2</td></tr>
<tr><td>0.67526 </td><td>0.92871 </td></tr>
<!-- comment -->
</table>
!ec

But inline HTML code is also important, like text that starts with
`<a href="` (which can destroy the following text if not properly
quoted).

Matlab with comments requires special typesetting:

!bc mcod
%% Comment on the beginning of the line can be escaped by %%
if a > b
  ${'%'} Indented comment needs this trick
  c = a + b
end
!ec

And here is a system call:

!bc sys-t
Terminal> mkdir test
Terminal> cd test
Terminal> myprog -f
output1
output2
!ec

Any valid pygments lexer/language name can appear to, e.g.,

!bc
|bc restructuredtext
=======
Heading
=======

Some text.
|ec
!ec
results in

!bc restructuredtext
=======
Heading
=======

Some text.
!ec

# Here goes hidden code.
# Python can be treated by some formats, Fortran is always out.

!bc pyhid
def f(x):
    """Secret, hidden function to be defined."""
    return 42
!ec

!bc fhid
       subroutine helper1(x)
       real*8 x
       x = 42
       return

       subroutine helper2(x)
       real*8 x
       x = 43
       return
!ec

Finally, `!bc do` supports highlighting of DocOnce source:

!bc do
======= DocOnce test file =======

===== Computer code =====

Inline verbatim code, as in `import numpy as np`, is allowed, as well as
code blocks:

|bc pycod
from math import sin

def f(x):
    """Example on a function."""
    return sin(x) + 1

print(f(0))
|ec


===== Mathematics =====

Formulas can be inline, as in $\nabla\cdot\bm{u} = 0$, or typeset
as equations:

|bt
\begin{align*}
\nabla\cdot\bm{u} &= 0,\\
\bm{u} &= \nabla\phi .
\end{align*}
|et

=== Subsubsection heading ===

DocOnce files can have chapters, sections, subsections, and subsubsections.

__Paragraph heading.__ Paragraphs may have headings.
!ec

It is time to test `verbatim inline font` especially with `a newline
inside the text` and an exclamation mark at the end: `BEGIN`! For
spellcheck, test `a verbatim expression` in `another` in a `third`.
Also test exclamation mark as in `!bc` and `!ec` as well as `a != b`.
Also test backslashes and braces like `\begin`, `\begin{enumerate}`,
`\end{this}\end{that}`, and `{something \inside braces}`.

# #if FORMAT not in ("latex", "pdflatex", "html")
The following attempt to exemplify colored text does not work in
format ${FORMAT}.
# #endif
Here is some color{red}{red color} and an attempt to write color{green}{with
green color containing a linebreak<linebreak>
code.} Some formats will only display <linebreak>
this correctly when `html` <linebreak>
is the output format.
But here some more running text is added which is not part of
the previous blocks with line breaks.

=== Running OS commands ===

@@@OSCMD python -c 'print("Testing\noutput\nfrom\nPython.")'

=== Footnotes ===

Here is a test of footnotes [^footnote], which are handy in text.
They are used in different flavors, now in

 * list items (note below that footnotes work after math, verbatim, and URLs - bin fact old and emphasize too!)
 * even with math $\nabla^2u$[^math1]
 * and code `h[i] += 1`[^code]
   (*must* have space between inline code and footnote!)
 * and "links": "https://google.com"[^google-search]

which gives flexibility in writing.
This is the third[^example-of-the-third-footnote] example.

  [^footnote]: Typesetting of the footnote depends on the format.
Plain text does nothing, LaTeX removes the
definition and inserts the footnote as part of the LaTeX text.
reStructuredText and Sphinx employ a similar type of typesetting
as Extended Markdown and DocOnce, and in HTML we keep the same
syntax, just displayed properly in HTML.
[^math1]: Math footnotes can be dangerous since it
interferes with an exponent.
[^code]: One-line footnote.

[^google-search]: URL: "google.com" is perhaps the most famous
web site today.

Here is some more text before a new definition of a footnote that was
used above.

!bnotice Non-breaking space character
This paragraph aims to test "non-breaking space character":
"https://en.wikipedia.org/wiki/Non-breaking_space", and a typical
example where this is needed is in physical units: 7.4~km is traveled
in~$7.4/5.5\approx 1.345$~s.  Also check that a~"link": "https://google.com"~is
not broken across lines (drag the browser window to test this).
(On the other hand, the tilde is used in
computer code, e.g., as in `[~x for x in y]` or in `y=~x`, and should
of course remain a tilde in those contexts.)
!enotice

===== Subsection 2: Testing figures =====
label{subsec:ex}
idx{figures}

Test of figures. In particular we refer to Figure ref{fig:impact} in which
there is a flow.

FIGURE:[../doc/src/manual/fig/wave1D, width=200] Visualization _of_ a *wave*. label{fig:impact}

Figures without captions are allowed and will be inlined.

FIGURE:[../doc/src/manual/fig/wave1D, width=200]

idx{movies}


# Test multi-line caption in figure with sidecap=True

Here is figure ref{myfig} with a long (illegal) multi-line caption
containing inline verbatim text:

FIGURE: [../doc/src/manual/fig/wave1D.png, width=500 sidecap=True] A long
caption spanning
several lines and containing verbatim words like `my_file_v1` and `my_file_v2`
as well as math with subscript as in $t_{i+1}$. label{myfig}

# Must be a blank line after MOVIE or FIGURE to detect this problem

Test URL as figure name:

FIGURE: [https://raw.github.com/doconce/doconce/master/doc/src/blog/f_plot.png, width=500 frac=0.8]

# #if FORMAT in ("html", "sphinx")
Test SVG figure:

FIGURE: [https://openclipart.org/people/jpneok/junebug.svg, width=200]
# #endif

# Test wikimedia type of files that otherwise reside in subdirs
# #if FORMAT == "mwiki"
FIGURE: [testfigs/df_plot.png, width=800] This is a wikimedia figure file.

# Non-uploaded file with no caption
FIGURE: [testfigs/df2s8765s_plot.png, width=200, frac=0.4]
# #endif

# #if FORMAT == 'html'
HTML output may feature Bokeh plots:

FIGURE: [bokeh_test]
# #endif

__Remark.__
Movies are tested in separate file `movies.do.txt`.


# Somewhat challenging heading with latex math, \t, \n, ? and parenthesis

===== The $\theta$ parameter (not $\nabla$?) =====
label{decay:sec:theta}

Functions do not always need to be advanced, here is one
involving $\theta$:
!bc
def f(theta):
    return theta**2
!ec

__More on $\theta$.__ Here is more text following headline with math.

Newcommands must also be tested in this \report:
$\half$, $\halfi$, $\x$, $\Ddt{u}$,
both inline and in block:

!bt
\begin{align}
\Ddt{u} &= 0\nonumber
\\
\half &= \halfi\\
\half\x &= \normalvec
\end{align}
!et

Or with align with label and numbers:

!bt
\begin{align}
\Ddt{u} &= 0
label{aligneq1}
\\
\half &= \halfi\\
\half\x &= \normalvec

label{aligneq2}
\end{align}
!et

% if FORMAT == "sphinx":
Sphinx makes a fix here and splits align into multiple equation
environments.
% endif
% if FORMAT == "mwiki":
The labels above are removed in mwiki since mwiki cannot refer to
labels in equations.
% endif

% if FORMAT not in ("sphinx", "pandoc", "ipynb"):
# Must test more complicated align and matrix compositions
# where DocOnce inserts auto-numbered labels etc.

First one numbered (automatically):

!bt
\begin{align}
\begin{pmatrix}
G_2 + G_3 & -G_3 & -G_2 & 0 \\
-G_3 & G_3 + G_4 & 0 & -G_4 \\
-G_2 & 0 & G_1 + G_2 & 0 \\
0 & -G_4 & 0 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
 v_1 \\
 v_2 \\
 v_3 \\
 v_4
\end{pmatrix}
+ \cdots \\
\begin{pmatrix}
 C_5 + C_6 & -C_6 & 0 & 0 \\
 -C_6 & C_6 & 0 & 0 \\
 0 & 0 & 0 & 0 \\
 0 & 0 & 0 & 0
\end{pmatrix}
  &= \frac{d}{dt}\begin{pmatrix}
 v_1 \\
 v_2 \\
 v_3 \\
 v_4
\end{pmatrix} +
\begin{pmatrix}
 0 \\
 0 \\
 0 \\
 -i_0
\end{pmatrix}
\nonumber
\end{align}
!et

Second numbered (automatically):

!bt
\begin{align}
\begin{pmatrix}
G_1 + G_2\\
-G_3 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
 v_1 \\
 v_2
\end{pmatrix}
+ \cdots\nonumber
\\
\left(\begin{array}{ll}
y & 2\\
2 & 1
\end{array}\right)
\left(\begin{array}{ll}
0 \\ x
\end{array}\right)
&= \begin{pmatrix}
A \\ B
\end{pmatrix}
\end{align}
!et

Both numbered, with label by the user:

!bt
\begin{align}
\begin{pmatrix}
G_1 + G_2\\
-G_3 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
 v_1 \\
 v_2
\end{pmatrix}
+ \cdots label{mymatrix:eq1}
\\
label{mymatrix:eq2}
\left(\begin{array}{ll}
y & 2\\
2 & 1
\end{array}\right)
\left(\begin{array}{ll}
0 \\ x
\end{array}\right)
&= \begin{pmatrix}
A \\ B
\end{pmatrix}
\end{align}
!et
Now we refer to (ref{mymatrix:eq1})-(ref{mymatrix:eq2}).
% endif

===== Custom Environments =====

Here is an attempt to create a theorem environment via Mako
(for counting theorems) and comment lines to help replacing lines in
the `.tex` by proper begin-end LaTeX environments for theorems.
Should look nice in most formats!

<%
theorem_counter = 4
%>

# begin theorem
label{theorem:fundamental1}
<%
theorem_counter += 1
theorem_fundamental1 = theorem_counter
%>

__Theorem ${theorem_counter}.__
Let $a=1$ and $b=2$. Then $c=3$.
# end theorem

# begin proof
__Proof.__
Since $c=a+b$, the result follows from straightforward addition.
$\Diamond$|$END$
# end proof

As we see, the proof of Theorem ${theorem_counter} is a modest
achievement.


===== Tables =====
label{subsec:table}

idx{test index with `verbatim text` which is possible}
idx{test `two` (separate) `verbatim expressions` which is also possible}
idx{index with!subindex}
idx{_boldface word_ in index}
idx{index with _boldface word_}
idx{index with!_boldface word_ in subentry}
idx{double _boldface word_!_boldface word_ in subentry too}

# index with comma could fool sphinx
idx{index, with comma, and one more}

Let us take this table from the manual:

% if FORMAT in ("latex", "pdflatex"):
\begin{table}
\caption{
Testing table environment in LaTeX, enabled by testing on the "latex" format
with the preprocessor.
label{mytab}
}

% endif

  |--------------------------------|
  |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    |
  |--------------------------------|

% if FORMAT in ("latex", "pdflatex"):
\end{table}
% endif

The DocOnce source code reads
!bc ccq

  |--------------------------------|
  |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

Here is yet another table to test that we can handle more than
one table:

  |--l-------l----------l----------|
  |time  | velocity | acceleration |
  |--l-------l----------l----------|
  | 0.0  | 1.4186   | -5.01        |
  | 1.0  | 1.376512 | 11.919       |
  | 3.0  | 1.1E+1   | 14.717624    |
  |--------------------------------|

And one with math headings (that are expanded and must be treated
accordingly), verbatim heading and entry, and no space around the pipe
symbol:

|--------------------------|
|$i$|$h_i$|$\bar T_i$|`L_i`|
|-l-----r-------r----r-----|
|0   |0     |288   |-0.0065|
|1   |11,000|216   |0.0	   |
|2   |20,000|216   |0.001  |
|3   |32,000|228   |0.0028 |
|4   |47,000|270   |0.0	   |
|5   |51,000|270   |-0.0028|
|6   |71,000|214   |`NaN`  |
|--------------------------|

And add one with verbatim headings (with underscores),
and rows starting with `|-` because of a negative number,
and `|` right before and after verbatim word (with no space):
## +`v_2` does not work, need space + `v_2`

|-----------------------------------------|
| exact | `v_1`   |$a_i$ + `v_2`|`verb_3_`|
|---r--------r---------r-----------r------|
|9      | 9.62    | 5.57      |  8.98     |
|-20    | -23.39  | -7.65     | -19.93    |
|10     | 17.74   | -4.50     |  9.96     |
|0      | -9.19   | 4.13      | -0.26     |
|-----------------------------------------|

Pipe symbols in verbatim and math text in tables used to pose difficulties,
but not
# #if FORMAT in ('plain', 'matlabnb')
anymore (except for plain text and matlabnb).
# #else
anymore:

|-----------------------------|
| $S$         | command       |
|-----l---------------r-------|
| $||a_0||$   | `norm|length` |
| $x\cap y$   | `x|y`         |
|-----------------------------|

# #endif

Here is a table with X alignment:

|---------------------|
| Type | Description  |
|--c---------X--------|
| X    | Alignment character that is used for specifying a potentially very long text in a column in a table. It makes use of the `tabularx` package in LaTeX, otherwise (for other formats) it means `l` (centered alignment). |
| l,r,c | standard alignment characters |
|---------------------|

Finally, a table with math
# #if FORMAT in ("rst", "html", "sphinx", "pandoc")
(`bm` that expands to `boldsymbol`, was tricky, but
cleanly handled now)
# #endif
and URLs.

# Mako code to expand URLs in the table
# (These types of tables did not work before Jan 2014)
<%
def tfig(fileno):
    p = '../doc/src/manual/mov/wave_frames/frame_0' + fileno + '.png'  # path
    if FORMAT in ("latex", "pdflatex"):
        text = r'\includegraphics[width=2cm]{%s}' % p
    elif FORMAT == "html":
        text = '<a href="%s"><img src="%s" width="300"></a>' % (p, p)
    else:
        text = '"`%s`": "%s"' % (fileno, p)  # plain link
    return text
%>

|-----------------------------------------------------------|
|                         |                |                |
|--------------c------------------c----------------c--------|
| $\mathcal{L}=0$         | ${tfig('080')} | ${tfig('085')} |
| $a=b$                   | ${tfig('090')} | ${tfig('095')} |
| $\nabla\cdot\bm{u} =0 $ | ${tfig('100')} | ${tfig('105')} |
|-----------------------------------------------------------|


===== A test of verbatim words in heading with subscript $a_i$: `my_file_v1` and `my_file_v2` =====

__Paragraph with verbatim and math: `my_file_v1.py` and `my_file_v2.py` define some math $a_{i-1}$.__ Here is more `__verbatim__` code and
some plain text on a new line.

# Test various types of headlines
% for heading in ('_Just bold_', '*Just emphasize*', '`Just verbatim`', '_Bold_ beginning', '*Emphasize* beginning', '`Verbatim` beginning', 'Maybe _bold end_', 'Maybe *emphasize end*', 'Maybe `verbatim end`', 'The middle has _bold_ word', 'The middle has *emphasize* word', 'The middle has `verbatim` word'):
===== ${heading} =====

Some text.

% endfor
% for heading in ('*Just emphasize*', '`Just verbatim`', '*Emphasize* beginning', '`Verbatim beginning`', 'Maybe *emphasize end*', 'Maybe `verbatim end`', 'The middle has *emphasize* word', 'The middle has `verbatim` word'):

__${heading}.__ Some text.

% endfor

__Ampersand.__
We can test Hennes & Mauritz, often abbreviated H & M, but written
as `Hennes & Mauritz` and `H & M`.
A sole `&` must also work.
# Note: substitutions must not occur inside verbatim, just in ordinary text.

!bc
# Just to check that ampersand works in code blocks:
c = a & b
!ec

__Quotes.__
Let us also add a test of quotes such as ``double quotes, with numbers
like 3.14 and newline/comma and hyphen (as in double-quote)''; written
in the standard LaTeX-style that gives correct LaTeX formatting and
ordinary double quotes for all non-LaTeX formats.  Here is another
sentence that ``caused'' a bug in the past because double backtick
quotes could imply verbatim text up to a verbatim word starting with
period, like `.txt`.

More quotes to be tested for spellcheck:
(``with parenthesis''), ``with newline''
and ``with comma'', ``hyphen''-wise, and ``period''.


===== Bibliography test =====

Here is an example: cite{Langtangen_Pedersen_2002} discussed propagation of
large destructive water waves, cite{Langtangen_et_al_2002} gave
an overview of numerical methods for solving the Navier--Stokes equations,
while the use of Backward Kolmogorov equations for analyzing
random vibrations was investigated in cite{Langtangen_1994a}.
The book chapter cite{Mardal_et_al_2003a} contains information on
C++ software tools for programming multigrid methods. A real retro
reference is cite{Langtangen_1988d} about a big FORTRAN package.
Multiple references are also possible, e.g., see
cite{Langtangen_Pedersen_2002,Mardal_et_al_2003a}.

We need to cite more than 10 papers to reproduce an old formatting
problem with blanks in the keys in reST format:
cite{Langtangen_1992c,Langtangen_1994a,Mortensen_et_al_2011,Langtangen_Pedersen_2002}
and
cite{Langtangen_et_al_2002,Glimsdal_et_al_20006,Rahman_et_al_2006b,Haga_et_al_2011a,Langtangen_2003a,Langtangen_2008a,Langtangen:95}
and all the work of
cite{Langtangen_2012,Mardal_et_al_2003a,Jeberg_et_al_2004} as well as
old work cite{Langtangen_1988d} and cite{Langtangen_1989e}, and the
talk cite{Langtangen_talk_2007a}.
Langtangen also had two thesis cite{Langtangen:85,Langtangen_1989e}
back in the days.
More retro citations are
the old ME-IN323 book cite{Langtangen:91} and the
cite{Langtangen:94b} OONSKI '94 paper.


===== Example: Examples can be typeset as exercises =====
label{Example}

Examples can start with a subsection heading starting with `Example:`
and then, with the command-line option `--examples_as_exercises` be
typeset as exercises. This is useful if one has solution
environments as part of the example.


!bsubex
State some problem.

!bsol
The answer to this subproblem can be written here.
!esol
!esubex

!bsubex
State some other problem.

!bhint
A hint can be given.
!ehint

!bhint
Maybe even another hint?
!ehint

!bsol
The answer to this other subproblem goes here,
maybe over multiple doconce input lines.
!esol
!esubex

===== User-defined environments =====

<%
def refex(label, capital=False):
    if FORMAT in ('latex', 'pdflatex'):
        return 'Example ref{%s}' % label
    else:
        s = 'The ' if capital else 'the '
        s += 'example in Section ref{%s}' % label
        return s
%>

${refex('ex:test:1p1', capital=True)} demonstrates how to write a test function.
That is, a special test function for a function `add` appears in
${refex('ex:test:1p1')}.

!bu-example A test function label=ex:test:1p1
Suppose we want to write a test function for checking the
implementation of a Python function for addition.

!bc pycod
def add(a, b):
    return a + b

def test_add():
    a = 1; b = 1
    expected = a + b
    computed = add(a, b)
    assert expected == computed
!ec
!eu-example

!bu-example Addition label=ex:math:1p1
We have

!bt
\[ 1 + 1 = 2 \]
!et
or in tabular form:

|-------------------|
| Problem | Result  |
|----c--------c-----|
| $1+1$   |  $2$    |
|-------------------|

!eu-example

!bu-highlight Highlight box!
This environment is used to highlight something:

!bt
\[ E = mc^2 \]
!et
!eu-highlight


===== URLs =====
label{subsubsec:ex}

Testing of URLs: hpl's home page "hpl":"https://folk.uio.no/hpl", or
the entire URL if desired, "URL": "https://folk.uio.no/hpl".  Here is a
plain file link "URL": "testdoc.do.txt", or "url":"testdoc.do.txt", or
URL: "testdoc.do.txt" or url : "testdoc.do.txt" or "a link with
newline": "testdoc.do.txt". Can test spaces with the link with word
too: "hpl": "https://folk.uio.no/hpl" or "hpl" :
"https://folk.uio.no/hpl". Also `file:///` works: "link to a
file":"file:///home/hpl/vc/doconce/doc/demos/manual/manual.html" is
fine to have. Moreover, ``loose'' URLs work, i.e., no quotes, just
the plain URL as in https://folk.uio.no/hpl, if followed by space, comma,
colon, semi-colon, question mark, exclamation mark, but not a period
(which gets confused with the periods inside the URL).

Mail addresses can also be used: "`hpl@simula.no`": "mailto:hpl@simula.no", or just a "mail link": "mailto:hpl@simula.no", or a raw URL: "mailto:hpl@simula.no".

Here are some tough tests of URLs, especially for the `latex` format:
"Newton-Cotes":
"https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas" formulas
and a "good book":
"https://www.springer.com/mathematics/computational+science+%26+engineering/book/978-3-642-23098-1". Need to test
Newton-Cotes with percentage in URL too:
URL: "https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas"
and URL: "https://en.wikipedia.org/wiki/Newton-Cotes#Open_Newton.E2.80.93Cotes_formulae" which has a shebang.

For the `--device=paper` option it is important to test that URLs with
monospace font link text get a footnote
(unless the `--latex_no_program_footnotelink`
is used), as in this reference to
"`decay_mod`":
"https://github.com/hplgit/INF5620/tree/gh-pages/src/decay/experiments/decay_mod.py", "`ball1.py`": "https://tinyurl.com/pwyasaa/formulas.ball1.py",
and "`ball2.py`": "https://tinyurl.com/pwyasaa/formulas.ball2.py".


# Comments should be inserted outside paragraphs (because in the rst
# format extra blanks make a paragraph break).

# Note that when there is no https: or file:, it can be a file link
# if the link name is URL, url, "URL", or "url". Such files should,
# if rst output is desired, but placed in a `_static*` folder.

More tough tests: repeated URLs whose footnotes when using the
`--device=paper` option must be correct. We have
"google": "https://google.com", "google": "https://google.com", and
"google": "https://google.com", which should result in exactly three
footnotes.


% if FORMAT in ("latex", "pdflatex"):

===== Test of Some LaTeX Fixes =====

Let's check abbr. of some common kind, e.g. the well-known i.e.
expression as an example, and 1 vs.  2 which is also often used.
Dr. Tang and Prof. Monsen, or maybe also prof.  Ting,
will go to the Dept. of Science to test how Mr.    Hansen is doing together
with Ms. Larsen. A reference like Sec. ref{subsubsec:ex} or
Ch. ref{subsubsec:ex}, or even App. ref{subsubsec:ex}, must also be
handled. Likewise, this is test no. $i$ of DocOnce features.
Also, look at Fig. 4 to see how the data compares with Tab. ref{mytab}.
Percentage must be fixed: 7%,  87.65% and
50% at the beginning of the line.

% endif

!split and check if these extra words are included properly in the comment

======= LaTeX Mathematics =======

Here is an equation without label using backslash-bracket environment:
!bt
\[ a = b + c \]
!et

or with number and label, as in (ref{my:eq1}), using the equation environment:

!bt
\begin{equation}
{\partial u\over\partial t} = \nabla^2 u label{my:eq1}
\end{equation}
!et

We can refer to this equation by (ref{my:eq1}).

Here is a system without equation numbers, using the align-asterisk environment:

!bt
\begin{align*}
\pmb{a} &= \pmb{q}\times\pmb{n} \\
b &= \nabla^2 u + \nabla^4 v
\end{align*}
!et


% if FORMAT in ('latex', 'pdflatex', 'sphinx', 'html', 'pandoc'):
And here is a system of equations with labels in an align environment:

!bt
\begin{align}
a &= q + 4 + 5+ 6 label{eq1} \\
b &= \nabla^2 u + \nabla^4 x label{eq2}
\end{align}

!et
We can refer to (ref{eq1})-(ref{eq2}). They are a bit simpler than
the Navier--Stokes equations. And test LaTeX hyphen in `CG-2`.
Also test $a_{i-j}$ as well as $kx-wt$.

Testing `alignat` environment:

!bt
\begin{alignat}{2}
a &= q + 4 + 5+ 6\qquad & \mbox{for } q\geq 0 label{eq1a} \\
b &= \nabla^2 u + \nabla^4 x & x\in\Omega label{eq2a}
\end{alignat}
!et

% if FORMAT in ("latex", "pdflatex"):
Many of the next environments will fail in non-latex formats.
Testing multiline:

!bt
\begin{multline}
a = b = q + \\
  f + \nabla\cdot\nabla u
label{multiline:eq1}
\end{multline}
!et

Testing split:

!bt
\begin{equation}
label{split:envir:eq}
\begin{split}
a = b = q &+ \\
  & f + \nabla\cdot\nabla u
\end{split}
\end{equation}
!et
We can refer to the last equation by (ref{split:envir:eq}).

Testing gather:
!bt
\begin{gather}
a = b \\
c = d + 7 + 9
\end{gather}
!et

Let us refer to (ref{eq1})-(ref{eq2}) again, and to the
alignat variant (ref{eq1a})-(ref{eq2a}), and to (ref{my:eq1}).

Testing eqnarray:
!bt
\begin{eqnarray}
{\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{eqnarray}
!et
% endif
% endif

More mathematical typesetting is demonstrated in the coming exercises.

Below, we have Problem ref{demo:ex:1} and Project ref{demo:ex:2},
as well as Projects ref{proj:circle1} and ref{exer:you}, and in
between there we have Exercise ref{exer:some:formula}.


======= Exercises =======

===== Problem: Flip a Coin =====
label{demo:ex:1}
files = flip_coin.py, flip_coin.pdf
solutions = mysol.txt, mysol_flip_coin.py
keywords = random numbers; Monte Carlo simulation; ipynb

# Torture tests
file=myfile_should_be_a_part_of_the_text
solutions = mysol.txt, mysol_flip_coin.py, yet_another.file

!bsubex
Make a program that simulates flipping a coin $N$ times.
Print out ``tail'' or ``head'' for each flip and
let the program count the number of heads.

!bhint
Use `r = random.random()` and define head as `r <= 0.5`.
!ehint

!bhint
Draw an integer among $\{1,2\}$ with
`r = random.randint(1,2)` and define head when `r` is 1.
!ehint

!bans
If the `random.random()` function returns a number $<1/2$, let it be
head, otherwise tail. Repeat this $N$ number of times.
!eans

!bsol
!bc pycod
import sys, random
N = int(sys.argv[1])
heads = 0
for i in range(N):
    r = random.random()
    if r <= 0.5:
        heads += 1
print('Flipping a coin %d times gave %d heads' % (N, heads))
!ec
!esol
!esubex

!bsubex
Vectorize the code in a) using boolean indexing.
!esubex

Vectorized code can be written in many ways.
Sometimes the code is less intuitive, sometimes not.
## Need a ref from this exer to the rest of the document
## when we run doconce extract_exercises and get this exercises
## out in its own document.
At least there is not much to find in Section ref{sec1}.

!bsubex
Vectorize the code in a) using `numpy.sum`.


!bans
`np.sum(np.where(r <= 0.5, 1, 0))` or `np.sum(r <= 0.5)`.
!eans
!esubex

In this latter subexercise, we have an
example where the code is easy to read.

!bremarks
These are the exercise remarks, appearing at the very end.
!eremarks

=== My remarks ===

Remarks with such a subsubsection is treated as more text
after the last subexercise. Test a list too:

 o Mark 1.
 o Mark 2.

===== Not an exercise =====

Should be possible to stick a normal section in the middle of many
exercises.

===== Exercise: Test of plain text exercise =====
label{my:exer1}
file=myexer1

Very short exercise. What is the capital
of Norway?

===== Project: Compute a Probability =====

# Minimalistic exercise

label{demo:ex:2}

What is the probability of getting a number between 0.5 and 0.6 when
drawing uniformly distributed random numbers from the interval $[0,1)$?

!bhint
To answer this question empirically, let a program
draw $N$ such random numbers using Python's standard `random` module,
count how many of them, $M$, that fall in the interval $(0.5,0.6)$, and
compute the probability as $M/N$.
!ehint

At the end we have a list because that caused problems in LaTeX
in previous DocOnce versions:

 o item1
 o item2

===== Project: Explore Distributions of Random Circles =====

label{proj:circle1}
file=circles
kw=ipynb

The formula for a circle is given by

!bt
\begin{align}
x &= x_0 + R\cos 2\pi t,
label{circle:x}\\
y &= y_0 + R\sin 2\pi t,
label{circle:y}
\end{align}
!et
where $R$ is the radius of the circle, $(x_0,y_0)$ is the
center point, and $t$ is a parameter in the unit interval $[0,1]$.
For any $t$, $(x,y)$ computed from (ref{circle:x})-(ref{circle:y})
is a point on the circle.
The formula can be used to generate `n` points on a circle:

!bc pypro
import numpy as np

def circle(R, x0, y0, n=501):
    t = np.linspace(0, 1, n)
    x = x0 + R*np.cos(2*np.pi*t)
    y = y0 + R*np.sin(2*np.pi*t)
    return x, y

x, y = circle(2.0, 0, 0)
!ec

# Often in an exercise we have some comments about the solution
# which we normally want to keep where they are.

The goal of this project is to draw $N$ circles with random
center and radius. Plot each circle using the `circle` function
above.

!bsubex
Let $R$ be normally distributed and $(x_0,y_0)$ uniformly distributed.

!bans
Here goes the short answer to part a).
!eans

!bsol
Here goes a full solution to part a).
!esol

!bhint
Use the `numpy.random` module to draw the
$x_0$, $y_0$, and $R$ quantities.
!ehint

!esubex

!bsubex
Let $R$ be uniformly distributed and $(x_0,y_0)$ normally distributed.

file=norm  # test local filename for subexercise
!esubex

!bsubex
Let $R$ and $(x_0,y_0)$ be normally distributed.
!esubex

!bremarks
At the very end of the exercise it may be appropriate to summarize
and give some perspectives.
!eremarks

===== Exercise: Determine some Distance =====
label{exer:dist}

Intro to this exercise. Questions are in subexercises below.

!bsubex
Subexercises are numbered a), b), etc.

file=subexer_a.pdf

!bans
Short answer to subexercise a).
With math in answer: $a=b$.
!eans

!bhint
First hint to subexercise a).
With math $a=b$ in hint:

!bt
\[ a=b. \]
!et
And with code (in plain verbatim) returning $x+1$ in hint:

!bc
def func(x):
    return x + 1  # with code in hint
!ec
!ehint

!bhint
Second hint to subexercise a).

Test list in hint:

 o item1
 o item2

!ehint
!esubex

!bsubex
Here goes the text for subexercise b).

file=subexer_b.pdf

Some math $\cos^2 x + \sin^2 x = 1$ written one a single line:

!bt
\[ \cos^2 x + \sin^2 x = 1 \thinspace .\]
!et

!bhint
A hint for this subexercise.
!ehint

!bsol
Here goes the solution of this subexercise.
!esol
!esubex

!bremarks
Some final closing remarks, e.g., summarizing the main findings
and their implications in other problems can be made. These
remarks will appear at the end of the typeset exercise.
!eremarks

!bsol
Here goes a full solution of the whole exercise.
With some math $a=b$ in this solution:
!bt
\[ \hbox{math in solution: } a = b \]
!et
And code `a=b` in this solution:
!bc
a = b  # code in solution
!ec
End of solution is here.
!esol

#  No meaning in this weired test example:
The text here belongs to the main (intro) part of the exercise. Need
closing remarks to have text after subexercises.

Test list in exercise:

 o item1
 o item2


===== {Exercise}: Some exercise without the "Exercise:" prefix =====

# Another minimalistic exercise

Just some text. And some math saying that $e^0=1$ on a single line,
to test that math block insertion is correct:

!bt
\[ \exp{(0)} = 1 \]
!et

And a test that the code `lambda x: x+2` is correctly placed here:

!bc
lambda x: x+2
!ec

# Have some comments at the end of the exercise to see that
# the Filename: ... is written correctly.


===== Exercise: Solution of differential equation =====
label{sec:this:exer:de}

!bquiz
H: SOlution of differential equation
K: derivatives; exponential function; equation, differential; differential equation
Q: Given

!bt
\[ \frac{dy}{dx} = -y(x),\quad y(0)=1 \]
!et
What is the solution of this equation?

L: quiz:diff:eq1

Cr: $y=e^{-y}$

Cw: $y=e^{y}$
E: Almost, but the sign is wrong (note the minus!).

Cw:
!bc pycod
from math import exp
def f(x):
    return exp(x)
!ec

E: Ooops, forgot a minus: `exp(-x)`, otherwise this Python code
must be considered as a good answer. It is more natural,
though, to write the solution to the problem
in mathematical notation:

!bt
\[ y(x) = e^{-y}.\]
!et

Cw: The solution cannot be found because there is a derivative in the equation.
E: Equations with derivatives can be solved;
they are termed *differential
equations*.

Cw: The equation is meaningless: an equation must be an equation
for $x$ or $y$, not a function $y(x)$.
E: Equations where the unknown is a function, as $y(x)$
here, are called *differential equations*, and are solved by
special techniques.
!equiz


===== Example: Just an example =====

# This example needs the --examples_as_exercises option, otherwise
# it is just typeset as it is written.

!bsubex
What is the capital of Norway?

!bans
Oslo.
!eans
!esubex

======= Here goes another section =======

With some text, before we continue with exercises.

======= More Exercises =======

===== Exercise: Make references to projects and problems =====

label{exer:some:formula}
file=verify_formula.py

# Test comments not at the end only
Pick a statement from Project ref{proj:circle1} or Problem ref{demo:ex:1}
and verify it.

Test list at the end of an exercise without other elements (like subexercise,
hint, etc.):

 o item1
 o item2

% if FORMAT in ('rst', 'sphinx', 'html'):
===== Project: References in a headings do not work well in ${FORMAT} =====
% else:
===== Project: References to Project ref{demo:ex:2} in a heading works for ${FORMAT} =====
% endif

label{exer:you}
file=selc_composed.pdf

Refer to the previous exercise as Exercise ref{exer:some:formula},
the two before that as Projects ref{demo:ex:2} and ref{proj:circle1},
and this one as Project ref{exer:you}.

======= References =======

BIBFILE: papers.pub


======= Appendix: Just for testing; part I =======
label{app1}

This is the first appendix.

===== A subsection within an appendix =====

Some text.

======= Appendix: Just for testing; part II =======
label{app2}

This is more stuff for an appendix.

===== Appendix: Testing identical titles =====

Without label.


===== Appendix: Testing identical titles =====
label{test:title:id1}

With label.

===== Appendix: Testing identical titles =====
label{test:title:id2}

What about inserting a quiz?

!bquiz
NP: Test of quizzes
H: Capital of Norway
K: capitals; basic intelligence; geography

Q: [Fundamental test:] What is the capital of Norway?
Cw: [Answer 1:] Stockholm
E: Stockholm is the capital of Sweden.
Cw: [Answer 2:] London
Cr: [Answer 3:] Oslo
Cw: Bergen
E: Those from Bergen would claim so, but nobody else.
!equiz


===== Appendix: Testing identical titles =====

Without label.

!bnotice Tip
Here is a tip or hint box, typeset as a notice box.
!enotice


# #if FORMAT in ("latex", "pdflatex")
\clearpage
# #endif

Need a lot of text to surround the summary box.
Version control systems allow you to record the history of files
and share files among several computers and collaborators in a
professional way. File changes on one computer are updated or
merged with changes on another computer. Especially when working
with programs or technical reports it is essential
to have changes documented and to
ensure that every computer and person involved in the project
have the latest updates of the files.
Greg Wilson' excellent "Script for Introduction to Version Control":
"https://software-carpentry.org/2010/07/script-for-introduction-to-version-control/" provides a more detailed motivation why you will benefit greatly
from using version control systems.

!bsummary
_Bold remark:_ Make some text with this summary.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
!esummary

Projects that you want to share among several computers or project
workers are today most conveniently stored at some web site "in the
cloud" and updated through communication with that site. I strongly
recommend you to use such sites for all serious programming and
scientific writing work - and all other important files.

The simplest services for hosting project files are "Dropbox":
"https://dropbox.com" and "Google Drive": "https://drive.google.com".
It is very easy to get started with these systems, and they allow you
to share files among laptops and mobile units with as many users as
you want. The systems offer a kind of version control in that the
files are stored frequently (several times per minute), and you can go
back to previous versions for the last 30 days. However, it is
challenging  to find the right version from the past when there are
so many of them.

More seriously, when several people may edit files simultaneously, it
can be difficult detect who did what when, roll back to previous
versions, and to manually merge the edits when these are
incompatible. Then one needs more sophisticated tools than Dropbox or
Google Drive: project hosting services with true version control
systems.  The following text aims at providing you with the minimum
information to started with such systems. Numerous other tutorials
contain more comprehensive material and in-depth explanations of the
concepts and tools.

The idea with project hosting services is that you have the files
associated with a project in the cloud. Many people may share these
files.  Every time you want to work on the project you explicitly
update your version of the files, edit the files as you like, and
synchronize the files with the "master version" at the site where the
project is hosted.  If you at some point need to go back to a
version of the files at some particular point in the past,
this is an easy operation. You can also use tools to see
what various people have done with the files in the various versions.

All these services are very similar. Below we describe how you get
started with Bitbucket, GitHub, and Googlecode. Launchpad works very
similarly to the latter three. All the project hosting services have
excellent introductions available at their web sites, but the recipes
below are much shorter and aim at getting you started as quickly as
possible by concentrating on the most important need-to-know steps.
The Git tutorials we refer to later in this document contain more
detailed information and constitute of course very valuable readings
when you use version control systems every day. The point now is
to get started.


===== Appendix: Testing inline comments =====

# Names can be [ A-Za-z0-9_'+-]+

Projects that you want to share among several computers or project
workers are today most conveniently stored at some web site "in the
cloud" and updated through communication with that
site. [hpl's semi opinion:
not sure if in the cloud is
understood by
all.] I strongly recommend you to use such sites for all serious
programming and scientific writing work - and all other important
files.

The simplest services for hosting project files is Dropbox. [mp:
Simply go to URL:"https://dropbox.com" and watch the video. It explains
how files, like `myfile.py`, perhaps containing much math, like
$\partial u/\partial t$, are easily communicated between machines.] It
is very easy to get started with Dropbox, and it allows you to share
files among [hpl: laptops and mobile units -> computers, tablets,
and phones].

# Test horizontal rule

------

# Coments for editing

First[add: ,] consider a quantity $Q$. [edit: To this end, -> We note that]
$Q>0$, because [del: a] negative [edit: quantity is -> quantities
are] [del: just] negative. [add: This comes as no surprise.]

# Test tailored latex figure references with page number
Let us refer to Figure ref{fig:impact} again.

Test references in a list:

 * ref{sec1}
 * ref{subsec1}
 * ref{fig:impact}


===== Appendix: Testing headings ending with `verbatim inline` =====

The point here is to test 1) `verbatim` code in headings, and 2)
ending a heading with verbatim code as this triggers a special
case in LaTeX.

We also test mdash---used as alternative to hyphen without spaces around,
or in quotes:

!bquote
*Fun is fun*.---Unknown.
!equote

The ndash should also be tested -- as in the Hanson--Nilson equations
on page 277--278.

And finally, what about admons, quotes, and boxes? They are tested
in a separate document: `admon.do.txt`.

[^example-of-the-third-footnote]: Not much to add here, but the footnote
is at the end with only one newline.

************** File: testdoc.html *****************
<!--
Automatically generated HTML file from DocOnce source
(https://github.com/doconce/doconce/)
-->
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="DocOnce: https://github.com/doconce/doconce/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="description" content="A Document for Testing DocOnce">
<meta name="keywords" content="figures,movies,index with subindex,_boldface word_ in index,index with _boldface word_,index with _boldface word_ in subentry,double _boldface word_  _boldface word_ in subentry too,index, with comma, and one more">

<title>A Document for Testing DocOnce</title>


<link href="https://raw.github.com/doconce/doconce/master/bundled/html_styles/style_solarized_box/css/solarized_light_code.css" rel="stylesheet" type="text/css" title="light"/>
<script src="https://raw.github.com/doconce/doconce/master/bundled/html_styles/style_solarized_box/js/highlight.pack.js"></script>
<script>hljs.initHighlightingOnLoad();</script>

<style type="text/css">
body, td {font-size: 140%;}
h1 {font-size: 200%;}
h2 {font-size: 180%;}

/* solarized style */
body {
  margin:5;
  padding:0;
  border:0; /* Remove the border around the viewport in old versions of IE */
  width:100%;
  background: #fdf6e3;
  min-width:600px;	/* Minimum width of layout - remove if not required */
  font-family: Verdana, Helvetica, Arial, sans-serif;
  font-size: 1.0em;
  line-height: 1.3em;
  color: #657b83;
}
a { color: #859900; text-decoration: underline; }
a:hover, a:active { outline:none }
a, a:active, a:visited { color: #859900; }
a:hover { color: #268bd2; }
h1, h2, h3 { margin:.8em 0 .2em 0; padding:0; line-height: 125%; }
h2 { font-variant: small-caps; }
tt, code { font-family: monospace, sans-serif; box-shadow: none; }
hr { border: 0; width: 80%; border-bottom: 1px solid #aaa; }
p { text-indent: 0px; }
p.caption { width: 80%; font-style: normal; text-align: left; }
hr.figure { border: 0; width: 80%; border-bottom: 1px solid #aaa; }
.alert-text-small   { font-size: 80%;  }
.alert-text-large   { font-size: 130%; }
.alert-text-normal  { font-size: 90%;  }
.alert {
  padding:8px 35px 8px 14px; margin-bottom:18px;
  text-shadow:0 1px 0 rgba(255,255,255,0.5);
  border:1px solid #93a1a1;
  border-radius: 4px;
  -webkit-border-radius: 4px;
  -moz-border-radius: 4px;
  color: #555;
  background-color: #eee8d5;
  background-position: 10px 5px;
  background-repeat: no-repeat;
  background-size: 38px;
  padding-left: 55px;
  width: 75%;
 }
.alert-block {padding-top:14px; padding-bottom:14px}
.alert-block > p, .alert-block > ul {margin-bottom:1em}
.alert li {margin-top: 1em}
.alert-block p+p {margin-top:5px}
.alert-notice { background-image: url(https://raw.github.com/doconce/doconce/master/bundled/html_images/small_yellow_notice.png); }
.alert-summary  { background-image:url(https://raw.github.com/doconce/doconce/master/bundled/html_images/small_yellow_summary.png); }
.alert-warning { background-image: url(https://raw.github.com/doconce/doconce/master/bundled/html_images/small_yellow_warning.png); }
.alert-question {background-image:url(https://raw.github.com/doconce/doconce/master/bundled/html_images/small_yellow_question.png); }

div { text-align: justify; text-justify: inter-word; }
</style>


<script src="https://sagecell.sagemath.org/static/jquery.min.js"></script>
<script src="https://sagecell.sagemath.org/embedded_sagecell.js"></script>
<link rel="stylesheet" type="text/css" href="https://sagecell.sagemath.org/static/sagecell_embed.css">
<script>
$(function () {
    // Make the div with id 'mycell' a Sage cell
    sagecell.makeSagecell({inputLocation:  '#mycell',
                           template:       sagecell.templates.minimal,
                           evalButtonText: 'Activate'});
    // Make *any* div with class 'compute' a Sage cell
    sagecell.makeSagecell({inputLocation: 'div.compute',
                           evalButtonText: 'Evaluate'});
});
</script>




<!-- Tools for embedded Bokeh plots -->
<link rel="stylesheet"
      href="https://cdn.pydata.org/bokeh/release/bokeh-0.9.0.min.css"
      type="text/css" />
<script type="text/javascript"
	src="https://cdn.pydata.org/bokeh/release/bokeh-0.9.0.min.js">
</script>
<script type="text/javascript">
  Bokeh.set_log_level("info");
</script>


</head>

<!-- tocinfo
{'highest level': 1,
 'sections': [('Table of contents',
               1,
               'table_of_contents',
               'table_of_contents'),
              ('Section 1', 1, 'sec1', 'sec1'),
              ('Here is a list with subsubsection heading',
               3,
               None,
               'here-is-a-list-with-subsubsection-heading'),
              ('Subsection 1', 2, 'subsec1', 'subsec1'),
              ('Test Section reference at beginning of line and after a '
               'sentence',
               3,
               None,
               'test-section-reference-at-beginning-of-line-and-after-a-sentence'),
              ('Computer code', 3, None, 'computer-code'),
              ('Subsubsection heading before code',
               3,
               None,
               'subsubsection-heading-before-code'),
              ('Running OS commands', 3, None, 'running-os-commands'),
              ('Footnotes', 3, None, 'footnotes'),
              ('Subsection 2: Testing figures', 2, 'subsec:ex', 'subsec:ex'),
              ('The $\\theta$ parameter (not $\\nabla$?)',
               2,
               'decay:sec:theta',
               'decay:sec:theta'),
              ('Custom Environments', 2, None, 'custom-environments'),
              ('Tables', 2, 'subsec:table', 'subsec:table'),
              ('A test of verbatim words in heading with subscript $a_i$: '
               '`my_file_v1` and `my_file_v2`',
               2,
               None,
               'a-test-of-verbatim-words-in-heading-with-subscript-a_i-my_file_v1-and-my_file_v2'),
              ('_Just bold_', 2, None, '_just-bold_'),
              ('*Just emphasize*', 2, None, 'just-emphasize'),
              ('`Just verbatim`', 2, None, 'just-verbatim'),
              ('_Bold_ beginning', 2, None, '_bold_-beginning'),
              ('*Emphasize* beginning', 2, None, 'emphasize-beginning'),
              ('`Verbatim` beginning', 2, None, 'verbatim-beginning'),
              ('Maybe _bold end_', 2, None, 'maybe-_bold-end_'),
              ('Maybe *emphasize end*', 2, None, 'maybe-emphasize-end'),
              ('Maybe `verbatim end`', 2, None, 'maybe-verbatim-end'),
              ('The middle has _bold_ word',
               2,
               None,
               'the-middle-has-_bold_-word'),
              ('The middle has *emphasize* word',
               2,
               None,
               'the-middle-has-emphasize-word'),
              ('The middle has `verbatim` word',
               2,
               None,
               'the-middle-has-verbatim-word'),
              ('Bibliography test', 2, None, 'bibliography-test'),
              ('Example 1: Examples can be typeset as exercises',
               2,
               'Example',
               'Example'),
              ('User-defined environments',
               2,
               None,
               'user-defined-environments'),
              ('Example 1: A test function', 2, 'ex:test:1p1', 'ex:test:1p1'),
              ('Example 2: Addition', 2, 'ex:math:1p1', 'ex:math:1p1'),
              ('URLs', 2, 'subsubsec:ex', 'subsubsec:ex'),
              ('LaTeX Mathematics', 1, None, 'latex-mathematics'),
              ('Exercises', 1, None, 'exercises'),
              ('Problem 2: Flip a Coin', 2, 'demo:ex:1', 'demo:ex:1'),
              ('My remarks', 3, None, 'my-remarks'),
              ('Remarks', 3, None, 'remarks'),
              ('Not an exercise', 2, None, 'not-an-exercise'),
              ('Exercise 3: Test of plain text exercise',
               2,
               'my:exer1',
               'my:exer1'),
              ('Project 4: Compute a Probability', 2, 'demo:ex:2', 'demo:ex:2'),
              ('Project 5: Explore Distributions of Random Circles',
               2,
               'proj:circle1',
               'proj:circle1'),
              ('Remarks', 3, None, 'remarks'),
              ('Exercise 6: Determine some Distance',
               2,
               'exer:dist',
               'exer:dist'),
              ('Remarks', 3, None, 'remarks'),
              ('Some exercise without the "Exercise:" prefix',
               2,
               None,
               'some-exercise-without-the-exercise-prefix'),
              ('Exercise 8: Solution of differential equation',
               2,
               'sec:this:exer:de',
               'sec:this:exer:de'),
              ('Example 9: Just an example',
               2,
               None,
               'example-9-just-an-example'),
              ('Here goes another section',
               1,
               None,
               'here-goes-another-section'),
              ('More Exercises', 1, None, 'more-exercises'),
              ('Exercise 10: Make references to projects and problems',
               2,
               'exer:some:formula',
               'exer:some:formula'),
              ('Project 11: References in a headings do not work well in html',
               2,
               'exer:you',
               'exer:you'),
              ('References', 1, None, 'references'),
              ('Appendix: Just for testing; part I', 1, 'app1', 'app1'),
              ('A subsection within an appendix',
               2,
               None,
               'a-subsection-within-an-appendix'),
              ('Appendix: Just for testing; part II', 1, 'app2', 'app2'),
              ('Appendix: Testing identical titles',
               2,
               None,
               'appendix-testing-identical-titles'),
              ('Appendix: Testing identical titles',
               2,
               'test:title:id1',
               'test:title:id1'),
              ('Appendix: Testing identical titles',
               2,
               'test:title:id2',
               'test:title:id2'),
              ('Appendix: Testing identical titles',
               2,
               None,
               'appendix-testing-identical-titles'),
              ('Appendix: Testing inline comments',
               2,
               None,
               'appendix-testing-inline-comments'),
              ('Appendix: Testing headings ending with `verbatim inline`',
               2,
               None,
               'appendix-testing-headings-ending-with-verbatim-inline')]}
end of tocinfo -->

<body>



<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  TeX: {
     equationNumbers: {  autoNumber: "none"  },
     extensions: ["AMSmath.js", "AMSsymbols.js", "autobold.js", "color.js"]
  }
});
</script>
<script type="text/javascript" async
 src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>



    
<a name="part0000"></a>
<!-- ------------------- main content ---------------------- -->



<center><h1>A Document for Testing DocOnce</h1></center>  <!-- document title -->

<p>
<!-- author(s): Hans Petter Langtangen, Kaare Dump, A. Dummy Author, I. S. Overworked and Outburned, and J. Doe -->

<center>
<b>Hans Petter Langtangen</b> [1, 2] (<tt>hpl at simula.no</tt>)
</center>

<center>
<b>Kaare Dump</b> [3]
</center>

<center>
<b>A. Dummy Author</b> 
</center>

<center>
<b>I. S. Overworked and Outburned</b> [4, 5, 6, 7]
</center>

<center>
<b>J. Doe</b>  (<tt>j_doe at cyberspace.com</tt>)
</center>

<p>
<!-- institution(s) -->

<center>[1] <b>Center for Biomedical Computing, Simula Research Laboratory</b></center>
<center>[2] <b>Department of Informatics, University of Oslo</b></center>
<center>[3] <b>Segfault, Cyberspace</b></center>
<center>[4] <b>Inst1</b></center>
<center>[5] <b>Inst2, Somewhere</b></center>
<center>[6] <b>Third Inst, Elsewhere</b></center>
<center>[7] <b>Fourth Inst</b></center>
<br>
<p>
<center><h4>Jan 32, 2100</h4></center> <!-- date -->
<br>

<h1 id="table_of_contents">Table of contents</h2>

<p>
<a href="._testdoc001.html#sec1"> Section 1 </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc001.html#subsec1"> Subsection 1 </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc001.html#subsec:ex"> Subsection 2: Testing figures </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc001.html#decay:sec:theta"> The \( \theta \) parameter (not \( \nabla \)?) </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc001.html#custom-environments"> Custom Environments </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc001.html#subsec:table"> Tables </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc001.html#a-test-of-verbatim-words-in-heading-with-subscript-a_i-my_file_v1-and-my_file_v2"> A test of verbatim words in heading with subscript \( a_i \): <code>my_file_v1</code> and <code>my_file_v2</code> </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc001.html#_just-bold_"> <b>Just bold</b> </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc001.html#just-emphasize"> <em>Just emphasize</em> </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc001.html#just-verbatim"> <code>Just verbatim</code> </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc001.html#_bold_-beginning"> <b>Bold</b> beginning </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc001.html#emphasize-beginning"> <em>Emphasize</em> beginning </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc001.html#verbatim-beginning"> <code>Verbatim</code> beginning </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc001.html#maybe-_bold-end_"> Maybe <b>bold end</b> </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc001.html#maybe-emphasize-end"> Maybe <em>emphasize end</em> </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc001.html#maybe-verbatim-end"> Maybe <code>verbatim end</code> </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc001.html#the-middle-has-<b>bold</b>-word"> The middle has <b>bold</b> word </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc001.html#the-middle-has-emphasize-word"> The middle has <em>emphasize</em> word </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc001.html#the-middle-has-verbatim-word"> The middle has <code>verbatim</code> word </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc001.html#bibliography-test"> Bibliography test </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc001.html#Example"> Example 1: Examples can be typeset as exercises </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc001.html#user-defined-environments"> User-defined environments </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc001.html#ex:test:1p1"> Example 1: A test function </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc001.html#ex:math:1p1"> Example 2: Addition </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc001.html#subsubsec:ex"> URLs </a><br>
<a href="._testdoc002.html#latex-mathematics"> LaTeX Mathematics </a><br>
<a href="._testdoc002.html#exercises"> Exercises </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc002.html#demo:ex:1"> Problem 2: Flip a Coin </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc002.html#not-an-exercise"> Not an exercise </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc002.html#my:exer1"> Exercise 3: Test of plain text exercise </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc002.html#demo:ex:2"> Project 4: Compute a Probability </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc002.html#proj:circle1"> Project 5: Explore Distributions of Random Circles </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc002.html#exer:dist"> Exercise 6: Determine some Distance </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc002.html#some-exercise-without-the-exercise-prefix"> Some exercise without the "Exercise:" prefix </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc002.html#sec:this:exer:de"> Exercise 8: Solution of differential equation </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc002.html#example-9-just-an-example"> Example 9: Just an example </a><br>
<a href="._testdoc002.html#here-goes-another-section"> Here goes another section </a><br>
<a href="._testdoc002.html#more-exercises"> More Exercises </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc002.html#exer:some:formula"> Exercise 10: Make references to projects and problems </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc002.html#exer:you"> Project 11: References in a headings do not work well in html </a><br>
<a href="._testdoc002.html#references"> References </a><br>
<a href="._testdoc002.html#app1"> Appendix: Just for testing; part I </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc002.html#a-subsection-within-an-appendix"> A subsection within an appendix </a><br>
<a href="._testdoc002.html#app2"> Appendix: Just for testing; part II </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc003.html#appendix-testing-identical-titles"> Appendix: Testing identical titles </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc002.html#test:title:id1"> Appendix: Testing identical titles </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc002.html#test:title:id2"> Appendix: Testing identical titles </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc003.html#appendix-testing-identical-titles"> Appendix: Testing identical titles </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc003.html#appendix-testing-inline-comments"> Appendix: Testing inline comments </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc003.html#appendix-testing-headings-ending-with-verbatim-inline"> Appendix: Testing headings ending with <code>verbatim inline</code> </a><br>
</p>
<p>
<p>
<!-- begin bottom navigation -->
<table style="width: 100%"><tr><td>
</td><td>
\
<div style="text-align: right;"><a href="._testdoc001.html"><img src="https://hplgit.github.io/doconce/bundled/html_images/next2.png" border=0 alt="Next &raquo;"></a></div>
</td></tr></table>
<!-- end bottom navigation -->
</p>

<!-- ------------------- end of main content --------------- -->

<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.js"></script>


</body>
</html>

************** File: testdoc.p.tex *****************
%%
%% Automatically generated file from DocOnce source
%% (https://github.com/hplgit/doconce/)
%%
%%
% #ifdef PTEX2TEX_EXPLANATION
%%
%% The file follows the ptex2tex extended LaTeX format, see
%% ptex2tex: https://code.google.com/p/ptex2tex/
%%
%% Run
%%      ptex2tex myfile
%% or
%%      doconce ptex2tex myfile
%%
%% to turn myfile.p.tex into an ordinary LaTeX file myfile.tex.
%% (The ptex2tex program: https://code.google.com/p/ptex2tex)
%% Many preprocess options can be added to ptex2tex or doconce ptex2tex
%%
%%      ptex2tex -DMINTED myfile
%%      doconce ptex2tex myfile envir=minted
%%
%% ptex2tex will typeset code environments according to a global or local
%% .ptex2tex.cfg configure file. doconce ptex2tex will typeset code
%% according to options on the command line (just type doconce ptex2tex to
%% see examples). If doconce ptex2tex has envir=minted, it enables the
%% minted style without needing -DMINTED.
% #endif

% #define PREAMBLE

% #ifdef PREAMBLE
%-------------------- begin preamble ----------------------

\documentclass[%
oneside,                 % oneside: electronic viewing, twoside: printing
final,                   % draft: marks overfull hboxes, figures with paths
10pt]{article}

\listfiles               %  print all files needed to compile this document

\usepackage{relsize,epsfig,makeidx,color,setspace,amsmath,amsfonts,amssymb}
\usepackage[table]{xcolor}
\usepackage{bm,ltablex,microtype}

\usepackage{graphicx}
\usepackage{sidecap}

% user-provided packages: --latex_packages=varioref
\usepackage{varioref}

% 'on page ...' reference with \vref{} and varioref package
\renewcommand\reftextfaceafter{on page~\thevpagerefnum}
\renewcommand\reftextfacebefore{on page~\thevpagerefnum}
\renewcommand\reftextafter{on page~\thevpagerefnum}
\renewcommand\reftextbefore{on page~\thevpagerefnum}

% Tools for marking corrections
\usepackage{soul}
\newcommand{\replace}[2]{{\color{red}\text{\st{#1} #2}}}
\newcommand{\remove}[1]{{\color{red}\st{#1}}}

\usepackage{ptex2tex}
% #ifdef MINTED
\usepackage{minted}
\usemintedstyle{default}
% #endif
\usepackage{fancyvrb}

\usepackage[T1]{fontenc}
%\usepackage[latin1]{inputenc}
\usepackage{ucs}
\usepackage[utf8x]{inputenc}

\usepackage{lmodern}         % Latin Modern fonts derived from Computer Modern

\newenvironment{doconcequiz}{}{}
\newcounter{doconcequizcounter}

% Hyperlinks in PDF:
\definecolor{linkcolor}{rgb}{0,0,0.4}
\usepackage{hyperref}
\hypersetup{
    breaklinks=true,
    colorlinks=true,
    linkcolor=linkcolor,
    urlcolor=linkcolor,
    citecolor=black,
    filecolor=black,
    %filecolor=blue,
    pdfmenubar=true,
    pdftoolbar=true,
    bookmarksdepth=3   % Uncomment (and tweak) for PDF bookmarks with more levels than the TOC
    }
%\hyperbaseurl{}   % hyperlinks are relative to this root

\setcounter{tocdepth}{2}  % levels in table of contents

%\VerbatimFootnotes must come after hyperref and footmisc packages
\VerbatimFootnotes

% Tricks for having figures close to where they are defined:
% 1. define less restrictive rules for where to put figures
\setcounter{topnumber}{2}
\setcounter{bottomnumber}{2}
\setcounter{totalnumber}{4}
\renewcommand{\topfraction}{0.95}
\renewcommand{\bottomfraction}{0.95}
\renewcommand{\textfraction}{0}
\renewcommand{\floatpagefraction}{0.75}
% floatpagefraction must always be less than topfraction!
% 2. ensure all figures are flushed before next section
\usepackage[section]{placeins}
% 3. enable begin{figure}[H] (often leads to ugly pagebreaks)
%\usepackage{float}\restylefloat{figure}

% newcommands for typesetting inline (doconce) comments
\newcommand{\shortinlinecomment}[3]{{\color{red}{\bf #1}: #2}}
\newcommand{\longinlinecomment}[3]{{\color{red}{\bf #1}: #2}}

\usepackage[framemethod=TikZ]{mdframed}

% --- begin definitions of admonition environments ---

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "notice" admon
\colorlet{mdfbox_notice_background}{gray!5}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_notice_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=mdfbox_notice_background,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{notice_mdfboxmdframed}

\newenvironment{notice_mdfboxadmon}[1][]{
\begin{notice_mdfboxmdframed}[frametitle=#1]
}
{
\end{notice_mdfboxmdframed}
}

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "summary" admon
\colorlet{mdfbox_summary_background}{gray!5}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_summary_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=mdfbox_summary_background,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{summary_mdfboxmdframed}

\newenvironment{summary_mdfboxadmon}[1][]{
\begin{summary_mdfboxmdframed}[frametitle=#1]
}
{
\end{summary_mdfboxmdframed}
}

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "warning" admon
\colorlet{mdfbox_warning_background}{gray!5}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_warning_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=mdfbox_warning_background,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{warning_mdfboxmdframed}

\newenvironment{warning_mdfboxadmon}[1][]{
\begin{warning_mdfboxmdframed}[frametitle=#1]
}
{
\end{warning_mdfboxmdframed}
}

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "question" admon
\colorlet{mdfbox_question_background}{gray!5}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_question_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=mdfbox_question_background,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{question_mdfboxmdframed}

\newenvironment{question_mdfboxadmon}[1][]{
\begin{question_mdfboxmdframed}[frametitle=#1]
}
{
\end{question_mdfboxmdframed}
}

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "block" admon
\colorlet{mdfbox_block_background}{gray!5}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_block_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=mdfbox_block_background,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{block_mdfboxmdframed}

\newenvironment{block_mdfboxadmon}[1][]{
\begin{block_mdfboxmdframed}[frametitle=#1]
}
{
\end{block_mdfboxmdframed}
}

% --- end of definitions of admonition environments ---

% prevent orhpans and widows
\clubpenalty = 10000
\widowpenalty = 10000

\usepackage{calc}

\newenvironment{doconceexercise}{}{}
\newcounter{doconceexercisecounter}
% --- begin definition of \listofexercises command ---
\makeatletter
\newcommand\listofexercises{\section*{List of Examples, Exercises, Problems, and Projects}
\@starttoc{loe}
}
\newcommand*{\l@doconceexercise}{\@dottedtocline{0}{0pt}{6.5em}}
\makeatother
% --- end definition of \listofexercises command ---



% ------ header in subexercises ------
%\newcommand{\subex}[1]{\paragraph{#1}}
%\newcommand{\subex}[1]{\par\vspace{1.7mm}\noindent{\bf #1}\ \ }
\makeatletter
% 1.5ex is the spacing above the header, 0.5em the spacing after subex title
\newcommand\subex{\@startsection{paragraph}{4}{\z@}%
                  {1.5ex\@plus1ex \@minus.2ex}%
                  {-0.5em}%
                  {\normalfont\normalsize\bfseries}}
\makeatother


% --- end of standard preamble for documents ---


\usepackage{amsthm,tcolorbox}
\theoremstyle{definition}
\newtheorem{example}{Example}[section]



% insert custom LaTeX commands...

\raggedbottom
\makeindex
\usepackage[totoc]{idxlayout}   % for index in the toc
\usepackage[nottoc]{tocbibind}  % for references/bibliography in the toc

%-------------------- end preamble ----------------------

\begin{document}

% matching end for #ifdef PREAMBLE
% #endif

\newcommand{\exercisesection}[1]{\subsection*{#1}}

\input{newcommands_bfmath}
\input{newcommands_replace}

% ------------------- main content ----------------------



% ----------------- title -------------------------

\title{A Document for Testing DocOnce}

% ----------------- author(s) -------------------------

\author{Hans Petter Langtangen\footnote{Email: \texttt{hpl@simula.no}. Center for Biomedical Computing, Simula Research Laboratory and Department of Informatics, University of Oslo.}
\and Kaare Dump\footnote{Segfault, Cyberspace.}
\and A. Dummy Author
\and I. S. Overworked and Outburned\footnote{Inst1; Inst2, Somewhere; Third Inst, Elsewhere; and Fourth Inst.}
\and J. Doe\footnote{Email: \texttt{j\_doe@cyberspace.com}.}}

% ----------------- end author(s) -------------------------

\date{Jan 32, 2100}
\maketitle

\tableofcontents


\vspace{1cm} % after toc





% !split




The format of this document is
plain, homemade {\LaTeX} (from DocOnce).

\begin{abstract}
This is a document with many test constructions for doconce syntax.
It was used heavily for the development and kept for testing
numerous constructions, also special and less common cases.

And exactly for test purposes we have an extra line here, which
is part of the abstract.

% Cannot demonstrate chapter headings since abstract and chapter
% are mutually exclusive in {\LaTeX}
\end{abstract}

\section{Section 1}
\label{sec1}

Here is a nested list:

\begin{itemize}
  \item item1

  \item item2

  \item item3 which continues
    on the next line to test that feature

  \item and a sublist
\begin{itemize}

    \item with indented subitem1

    \item and a subitem2

\end{itemize}

\noindent
  \item and perhaps an ordered sublist
\begin{enumerate}

   \item first item

   \item second item,
      continuing on a new line
\end{enumerate}

\noindent
\end{itemize}

\noindent
\paragraph{Here is a list with paragraph heading.}

\begin{itemize}
  \item item1

  \item item2
\end{itemize}

\noindent
\paragraph{Here is a list with subsubsection heading.}
\begin{itemize}
  \item item1

  \item item2
\end{itemize}

\noindent

\begin{quote}
Here are two lines that make up
a block quote for testing \emph{emphasized words} and \textbf{boldface words},
also with hypens:
\emph{pre}-fix, post-\emph{fix}, \textbf{pre}-fix, post-\textbf{fix}.
\end{quote}


Here are two references. Equation~(\ref{my:eq1}) is fine. Eq.~(\ref{my:eq1}) too.
Even Equation (\ref{my:eq1}) without the tilde.


\subsection{Subsection 1}
\label{subsec1}

\index{somefunc@{\rm\texttt{somefunc}} function}

% Refer to section/appendix etc. at the beginning of the line
% and other special fix situations for HTML.

More text, with a reference back to
Section~\vref{sec1} and~\vref{subsec1}, and further to the
sections~\vref{subsec1} and~\vref{subsubsec:ex}, which
encourages you to do the tasks in the
Exercises~\vref{demo:ex:1} and~\vref{exer:some:formula}.
Appendices~\vref{app1} and~\vref{app2} are also nice elements.

\paragraph{Test Section reference at beginning of line and after a sentence.}
Section~\vref{subsec1} is fine.
Section~\vref{subsubsec:ex} too.


% sphinx code-blocks: pycod=python cod=fortran cppcod=c++ sys=console

\paragraph{Computer code.}
Let's do some copying from files too. First from subroutine up to the very end,

\bfcod
      subroutine test()
      integer i
      real*8 r
      r = 0
      do i = 1, i
         r = r + i
      end do
      return
C     END1

      program testme
      call test()
      return
\efcod
and then just the subroutine,
\bfcod

      subroutine test()
      integer i
      real*8 r
      r = 0
      do i = 1, i
         r = r + i
      end do
      return
\efcod
and finally the complete file with a plain text verbatim environment
(\texttt{envir=ccq}):
\bccq
C     a comment

      subroutine test()
      integer i
      real*8 r
      r = 0
      do i = 1, i
         r = r + i
      end do
      return
C     END1

      program testme
      call test()
      return
\eccq

Testing other code environments. First Python:

\bccq
!bc pycod
def f(x):
    return x+1
!ec
\eccq
which gets rendered as

\bpycod
def f(x):
    return x+1
\epycod

Test paragraph and subsubsection headings before
before code.

\paragraph{Paragraph heading before code.}

\bpycod
import sys
sys.path.insert(0, os.pardir)
\epycod

\paragraph{Subsubsection heading before code.}
\bpycod
def h(z):
    return z+1
\epycod

Now a complete program to be shown via Python Online Tutorial:

\bpypro
class Line:
    def __init__(self, a, b):
        self.a, self.b = a, b

    def __call__(self, x):
        a, b = self.a, self.b
        return a*x + b

line = Line(2, 1)
y = line(x=3)
print(y)
\epypro
\noindent
(\href{{https://pythontutor.com/visualize.html\#code=class+Line\%3A\%0A++++def+__init__\%28self\%2C+a\%2C+b\%29\%3A\%0A++++++++self.a\%2C+self.b+\%3D+a\%2C+b\%0A\%0A++++def+__call__\%28self\%2C+x\%29\%3A\%0A++++++++a\%2C+b+\%3D+self.a\%2C+self.b\%0A++++++++return+a\%2Ax+\%2B+b\%0A\%0Aline+\%3D+Line\%282\%2C+1\%29\%0Ay+\%3D+line\%28x\%3D3\%29\%0Aprint\%28y\%29&mode=display&cumulative=false&heapPrimitives=false&drawParentPointers=false&textReferences=false&py=2&curInstr=0}}{Visualize execution}) 


Some more Python code (actually specified as a sage cell, but
such cells are not supported by this format).

\bpypro
a = 2
b = 3
print('a+b:', a + b)

# In a sage cell we can also plot
from matplotlib.pyplot import *
from numpy import *
x = linspace(0, 4*pi, 101)
y = exp(-0.1*x)*cos(x)
plot(x, y)
xlabel('x'); ylabel('y')
show()
\epypro


Then Cython (with -h option so it is hidden in html/sphinx):

\bcycod
cpdef f(double x):
    return x + 1
\ecycod

Standard Python shell sessions:

\bpyshell
>>> from numpy import linspace, sin
>>> # Some comment
>>> x = linspace(0, 2, 11)
>>> y = sin(x)
>>> y[0]
0
>>> import matplotlib.pyplot as plt
>>> plt.plot(x, y)
\epyshell

Similar IPython sessions:

\bipy
In [1]: from numpy import linspace, sin
In [2]: # Some comment
In [3]: x = linspace(0, 2, 11)
In [4]: y = sin(x)
In [5]: y[0]
Out[5]: 0
In [6]: import matplotlib.pyplot as plt
In [7]: plt.plot(x, y)
In [8]: a='multiple-\nline\noutput'
In [9]: a
Out[9]: 'multiple-\nline\noutput'
In [10]: print(a)
multiple-
line
output
\eipy

Here is the interactive session again, but with \texttt{pyshell-t}.

\bpyshell
>>> from numpy import linspace, sin
>>> # Some comment
>>> x = linspace(0, 2, 11)
>>> y = sin(x)
>>> y[0]
0
>>> import matplotlib.pyplot as plt
>>> plt.plot(x, y)
\epyshell

% This one tests a + sign before a code environment
C++:
\bcpppro
#include <iostream>

int main()
{
   std::cout << "Sample output" << std::endl;
   return 0
}
\ecpppro
% The next should get correctly typset in sphinx (cod is fcod)
% It also tests emoji before code
And a little bit of Fortran: (\Verb!dizzy_face!)

\bccq
!bc cod
      subroutine midpt(x, length, a, b)
      real*8 a, b, x
      x = (a + b)/2
      length = b - a
      return
      end
!ec
\eccq
which then is typeset as

\bcod
      subroutine midpt(x, length, a, b)
      real*8 a, b, x
      x = (a + b)/2
      length = b - a
      return
      end
\ecod

HTML:

\bhtmlcod
<table>
<tr><td>Column 1</td><td>Column 2</td></tr>
<tr><td>0.67526 </td><td>0.92871 </td></tr>
<!-- comment -->
</table>
\ehtmlcod

But inline HTML code is also important, like text that starts with
\texttt{<a href="} (which can destroy the following text if not properly
quoted).

Matlab with comments requires special typesetting:

\bmcod
% Comment on the beginning of the line can be escaped by %%
if a > b
  % Indented comment needs this trick
  c = a + b
end
\emcod

And here is a system call:

\bsys
Terminal> mkdir test
Terminal> cd test
Terminal> myprog -f
output1
output2
\esys

Any valid pygments lexer/language name can appear to, e.g.,

\bccq
!bc restructuredtext
=======
Heading
=======

Some text.
!ec
\eccq
results in

\brestructuredtext
=======
Heading
=======

Some text.
\erestructuredtext

% Here goes hidden code.
% Python can be treated by some formats, Fortran is always out.





Finally, \Verb?!bc do? supports highlighting of DocOnce source:

\bdo
======= DocOnce test file =======

===== Computer code =====

Inline verbatim code, as in `import numpy as np`, is allowed, as well as
code blocks:

!bc pycod
from math import sin

def f(x):
    """Example on a function."""
    return sin(x) + 1

print(f(0))
!ec


===== Mathematics =====

Formulas can be inline, as in $\nabla\cdot\bm{u} = 0$, or typeset
as equations:

!bt
\begin{align*}
\nabla\cdot\bm{u} &= 0,\\ 
\bm{u} &= \nabla\phi .
\end{align*}
!et

=== Subsubsection heading ===

DocOnce files can have chapters, sections, subsections, and subsubsections.

__Paragraph heading.__ Paragraphs may have headings.
\edo

It is time to test \texttt{verbatim inline font} especially with \texttt{a newline inside the text} and an exclamation mark at the end: \texttt{BEGIN}! For
spellcheck, test \texttt{a verbatim expression} in \texttt{another} in a \texttt{third}.
Also test exclamation mark as in \Verb?!bc? and \Verb?!ec? as well as \Verb?a != b?.
Also test backslashes and braces like \Verb!\begin!, \Verb!\begin{enumerate}!,
\Verb!\end{this}\end{that}!, and \Verb!{something \inside braces}!.

Here is some \textcolor{red}{red color} and an attempt to write \textcolor{green}{with
green color containing a linebreak\\
code.} Some formats will only display \\
this correctly when \texttt{html} \\
is the output format.
But here some more running text is added which is not part of
the previous blocks with line breaks.

\paragraph{Running OS commands.}
\bsys
Terminal> python -c 'print("Testing\noutput\nfrom\nPython.")'
Testing
output
from
Python.
\esys


\paragraph{Footnotes.}
Here is a test of footnotes \footnote{Typesetting of the footnote depends on the format. Plain text does nothing, {\LaTeX} removes the definition and inserts the footnote as part of the {\LaTeX} text. reStructuredText and Sphinx employ a similar type of typesetting as Extended Markdown and DocOnce, and in HTML we keep the same syntax, just displayed properly in HTML.}, which are handy in text.
They are used in different flavors, now in

\begin{itemize}
 \item list items (note below that footnotes work after math, verbatim, and URLs - bin fact old and emphasize too!)

 \item even with math $\nabla^2u$\footnote{Math footnotes can be dangerous since it interferes with an exponent.}

 \item and code \texttt{h[i] += 1}\footnote{One-line footnote.}
   (\emph{must} have space between inline code and footnote!)

 \item and \href{{https://google.com}}{links}\footnote{\href{{google.com}}{\nolinkurl{google.com}} is perhaps the most famous web site today.}
\end{itemize}

\noindent
which gives flexibility in writing.
This is the third\footnote{Not much to add here, but the footnote is at the end with only one newline.} example.





Here is some more text before a new definition of a footnote that was
used above.


\begin{notice_mdfboxadmon}[Non-breaking space character.]
This paragraph aims to test \href{{https://en.wikipedia.org/wiki/Non-breaking_space}}{non-breaking space character}, and a typical
example where this is needed is in physical units: 7.4~km is traveled
in~$7.4/5.5\approx 1.345$~s.  Also check that a~\href{{https://google.com}}{link}~is
not broken across lines (drag the browser window to test this).
(On the other hand, the tilde is used in
computer code, e.g., as in \texttt{[~x for x in y]} or in \texttt{y=~x}, and should
of course remain a tilde in those contexts.)
\end{notice_mdfboxadmon} % title: Non-breaking space character.



\subsection{Subsection 2: Testing figures}
\label{subsec:ex}
\index{figures}

Test of figures. In particular we refer to Figure~\vref{fig:impact} in which
there is a flow.


\begin{figure}[!ht]  % fig:impact
  \centerline{\includegraphics[width=0.9\linewidth]{../doc/src/manual/fig/wave1D.png}}
  \caption{
  Visualization \textbf{of} a \emph{wave}. \label{fig:impact}
  }
\end{figure}
%\clearpage % flush figures fig:impact


Figures without captions are allowed and will be inlined.



\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=0.9\linewidth]{../doc/src/manual/fig/wave1D.png}}

\vspace{6mm}



\index{movies}


% Test multi-line caption in figure with sidecap=True

Here is figure~\vref{myfig} with a long (illegal) multi-line caption
containing inline verbatim text:


\begin{SCfigure}
  \centering
  \includegraphics[width=0.9\linewidth]{../doc/src/manual/fig/wave1D.png}
  \caption{
  A long caption spanning several lines and containing verbatim words like \protect \Verb!my\_file\_v1! and \protect \Verb!my\_file\_v2! as well as math with subscript as in $t_{i+1}$. \label{myfig}
  }
\end{SCfigure}
%\clearpage % flush figures myfig


% Must be a blank line after MOVIE or FIGURE to detect this problem

Test URL as figure name:



\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=0.8\linewidth]{downloaded_figures/f_plot.png}}

\vspace{6mm}




% Test wikimedia type of files that otherwise reside in subdirs


\paragraph{Remark.}
Movies are tested in separate file \texttt{movies.do.txt}.


% Somewhat challenging heading with latex math, \t, \n, ? and parenthesis

\subsection{The $\theta$ parameter (not $\nabla$?)}
\label{decay:sec:theta}

Functions do not always need to be advanced, here is one
involving $\theta$:
\bccq
def f(theta):
    return theta**2
\eccq

\paragraph{More on $\theta$.}
Here is more text following headline with math.

Newcommands must also be tested in this \report:
$\half$, $\halfi$, $\x$, $\Ddt{u}$,
both inline and in block:

\begin{align}
\Ddt{u} &= 0\nonumber
\\ 
\half &= \halfi\\ 
\half\x &= \normalvec
\end{align}

Or with align with label and numbers:

\begin{align}
\Ddt{u} &= 0
\label{aligneq1}
\\ 
\half &= \halfi\\ 
\half\x &= \normalvec
\label{aligneq2}
\end{align}


% Must test more complicated align and matrix compositions
% where DocOnce inserts auto-numbered labels etc.

First one numbered (automatically):

\begin{align}
\begin{pmatrix}
G_2 + G_3 & -G_3 & -G_2 & 0 \\ 
-G_3 & G_3 + G_4 & 0 & -G_4 \\ 
-G_2 & 0 & G_1 + G_2 & 0 \\ 
0 & -G_4 & 0 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
 v_1 \\ 
 v_2 \\ 
 v_3 \\ 
 v_4
\end{pmatrix}
+ \cdots \\ 
\begin{pmatrix}
 C_5 + C_6 & -C_6 & 0 & 0 \\ 
 -C_6 & C_6 & 0 & 0 \\ 
 0 & 0 & 0 & 0 \\ 
 0 & 0 & 0 & 0
\end{pmatrix}
  &= \frac{d}{dt}\begin{pmatrix}
 v_1 \\ 
 v_2 \\ 
 v_3 \\ 
 v_4
\end{pmatrix} +
\begin{pmatrix}
 0 \\ 
 0 \\ 
 0 \\ 
 -i_0
\end{pmatrix}
\nonumber
\end{align}

Second numbered (automatically):

\begin{align}
\begin{pmatrix}
G_1 + G_2\\ 
-G_3 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
 v_1 \\ 
 v_2
\end{pmatrix}
+ \cdots\nonumber
\\ 
\left(\begin{array}{ll}
y & 2\\ 
2 & 1
\end{array}\right)
\left(\begin{array}{ll}
0 \\ x
\end{array}\right)
&= \begin{pmatrix}
A \\ B
\end{pmatrix}
\end{align}

Both numbered, with label by the user:

\begin{align}
\begin{pmatrix}
G_1 + G_2\\ 
-G_3 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
 v_1 \\ 
 v_2
\end{pmatrix}
+ \cdots \label{mymatrix:eq1}
\\ 
\label{mymatrix:eq2}
\left(\begin{array}{ll}
y & 2\\ 
2 & 1
\end{array}\right)
\left(\begin{array}{ll}
0 \\ x
\end{array}\right)
&= \begin{pmatrix}
A \\ B
\end{pmatrix}
\end{align}
Now we refer to (\ref{mymatrix:eq1})-(\ref{mymatrix:eq2}).

\subsection{Custom Environments}

Here is an attempt to create a theorem environment via Mako
(for counting theorems) and comment lines to help replacing lines in
the \texttt{.tex} by proper begin-end {\LaTeX} environments for theorems.
Should look nice in most formats!



% begin theorem
\label{theorem:fundamental1}


\paragraph{Theorem 5.}
Let $a=1$ and $b=2$. Then $c=3$.
% end theorem

% begin proof
\paragraph{Proof.}
Since $c=a+b$, the result follows from straightforward addition.
$\Diamond$
% end proof

As we see, the proof of Theorem 5 is a modest
achievement.


\subsection{Tables}
\label{subsec:table}

\index{test index with verbatim text@test index with {\rm\texttt{verbatim text}} which is possible}
\index{test two@test {\rm\texttt{two}} (separate) {\rm\texttt{verbatim expressions}} which is also possible}
\index{index with!subindex}
\index{\textbf{boldface word} in index}
\index{index with \textbf{boldface word}}
\index{index with!\textbf{boldface word} in subentry}
\index{double \textbf{boldface word}! \textbf{boldface word} in subentry too}

% index with comma could fool sphinx
\index{index, with comma, and one more}

Let us take this table from the manual:

\begin{table}
\caption{
Testing table environment in {\LaTeX}, enabled by testing on the "latex" format
with the preprocessor.
\label{mytab}
}



\begin{quote}
\begin{tabular}{lrr}
\hline
\multicolumn{1}{c}{ time } & \multicolumn{1}{c}{ velocity } & \multicolumn{1}{c}{ acceleration } \\
\hline
0.0  & 1.4186   & -5.01        \\
2.0  & 1.376512 & 11.919       \\
4.0  & 1.1E+1   & 14.717624    \\
\hline
\end{tabular}
\end{quote}

\noindent
\end{table}

The DocOnce source code reads
\bccq

  |--------------------------------|
  |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

Here is yet another table to test that we can handle more than
one table:


\begin{quote}
\begin{tabular}{lll}
\hline
\multicolumn{1}{l}{ time } & \multicolumn{1}{l}{ velocity } & \multicolumn{1}{l}{ acceleration } \\
\hline
0.0  & 1.4186   & -5.01        \\
1.0  & 1.376512 & 11.919       \\
3.0  & 1.1E+1   & 14.717624    \\
\hline
\end{tabular}
\end{quote}

\noindent
And one with math headings (that are expanded and must be treated
accordingly), verbatim heading and entry, and no space around the pipe
symbol:


\begin{quote}
\begin{tabular}{lrrr}
\hline
\multicolumn{1}{c}{ $i$ } & \multicolumn{1}{c}{ $h_i$ } & \multicolumn{1}{c}{ $\bar T_i$ } & \multicolumn{1}{c}{ \Verb!L\_i! } \\
\hline
0   & 0      & 288        & -0.0065    \\
1   & 11,000 & 216        & 0.0        \\
2   & 20,000 & 216        & 0.001      \\
3   & 32,000 & 228        & 0.0028     \\
4   & 47,000 & 270        & 0.0        \\
5   & 51,000 & 270        & -0.0028    \\
6   & 71,000 & 214        & \texttt{NaN} \\
\hline
\end{tabular}
\end{quote}

\noindent
And add one with verbatim headings (with underscores),
and rows starting with \texttt{|-} because of a negative number,
and \texttt{|} right before and after verbatim word (with no space):


\begin{quote}
\begin{tabular}{rrrr}
\hline
\multicolumn{1}{c}{ exact } & \multicolumn{1}{c}{ \Verb!v\_1! } & \multicolumn{1}{c}{ $a_i$ + \Verb!v\_2! } & \multicolumn{1}{c}{ \Verb!verb\_3\_! } \\
\hline
9     & 9.62       & 5.57               & 8.98           \\
-20   & -23.39     & -7.65              & -19.93         \\
10    & 17.74      & -4.50              & 9.96           \\
0     & -9.19      & 4.13               & -0.26          \\
\hline
\end{tabular}
\end{quote}

\noindent
Pipe symbols in verbatim and math text in tables used to pose difficulties,
but not
anymore:


\begin{quote}
\begin{tabular}{lr}
\hline
\multicolumn{1}{c}{ $S$ } & \multicolumn{1}{c}{ command } \\
\hline
$ ||a_0|| $ & \texttt{norm|length} \\
$x\cap y$   & \texttt{x|y}         \\
\hline
\end{tabular}
\end{quote}

\noindent

Here is a table with X alignment:


\begin{quote}
\begin{tabularx}{\linewidth}{cX}
\hline
\multicolumn{1}{c}{ Type } & \multicolumn{1}{c}{ Description } \\
\hline
X     & Alignment character that is used for specifying a potentially very long text in a column in a table. It makes use of the \texttt{tabularx} package in {\LaTeX}, otherwise (for other formats) it means \texttt{l} (centered alignment). \\
l,r,c & standard alignment characters                                                                                                                                                                                                       \\
\hline
\end{tabularx}
\end{quote}

\noindent
Finally, a table with math
and URLs.

% Mako code to expand URLs in the table
% (These types of tables did not work before Jan 2014)



\begin{quote}
\begin{tabular}{ccc}
\hline
 \\
\hline
$\mathcal{L}=0$         & \includegraphics[width=2cm]{../doc/src/manual/mov/wave_frames/frame_0080.png} & \includegraphics[width=2cm]{../doc/src/manual/mov/wave_frames/frame_0085.png} \\
$a=b$                   & \includegraphics[width=2cm]{../doc/src/manual/mov/wave_frames/frame_0090.png} & \includegraphics[width=2cm]{../doc/src/manual/mov/wave_frames/frame_0095.png} \\
$\nabla\cdot\bm{u} =0 $ & \includegraphics[width=2cm]{../doc/src/manual/mov/wave_frames/frame_0100.png} & \includegraphics[width=2cm]{../doc/src/manual/mov/wave_frames/frame_0105.png} \\
\hline
\end{tabular}
\end{quote}

\noindent

\subsection{A test of verbatim words in heading with subscript $a_i$: \protect\Verb!my\_file\_v1! and \protect\Verb!my\_file\_v2! }

\paragraph{Paragraph with verbatim and math: \protect\Verb!my\_file\_v1.py! and \protect\Verb!my\_file\_v2.py! define some math $a_{i-1}$.}
Here is more \Verb!__verbatim__! code and
some plain text on a new line.

% Test various types of headlines
\subsection{\textbf{Just bold}}

Some text.

\subsection{\emph{Just emphasize}}

Some text.

\subsection{\texttt{Just verbatim} }

Some text.

\subsection{\textbf{Bold} beginning}

Some text.

\subsection{\emph{Emphasize} beginning}

Some text.

\subsection{\texttt{Verbatim} beginning}

Some text.

\subsection{Maybe \textbf{bold end}}

Some text.

\subsection{Maybe \emph{emphasize end}}

Some text.

\subsection{Maybe \texttt{verbatim end} }

Some text.

\subsection{The middle has \textbf{bold} word}

Some text.

\subsection{The middle has \emph{emphasize} word}

Some text.

\subsection{The middle has \texttt{verbatim} word}

Some text.


\paragraph{\emph{Just emphasize}.}
Some text.


\paragraph{\texttt{Just verbatim}.}
Some text.


\paragraph{\emph{Emphasize} beginning.}
Some text.


\paragraph{\texttt{Verbatim beginning}.}
Some text.


\paragraph{Maybe \emph{emphasize end}.}
Some text.


\paragraph{Maybe \texttt{verbatim end}.}
Some text.


\paragraph{The middle has \emph{emphasize} word.}
Some text.


\paragraph{The middle has \texttt{verbatim} word.}
Some text.


\paragraph{Ampersand.}
We can test Hennes {\&} Mauritz, often abbreviated H{\&}M, but written
as \Verb!Hennes & Mauritz! and \Verb!H & M!.
A sole \Verb!&! must also work.
% Note: substitutions must not occur inside verbatim, just in ordinary text.

\bccq
# Just to check that ampersand works in code blocks:
c = a & b
\eccq

\paragraph{Quotes.}
Let us also add a test of quotes such as ``double quotes, with numbers
like 3.14 and newline/comma and hyphen (as in double-quote)''; written
in the standard LaTeX-style that gives correct {\LaTeX} formatting and
ordinary double quotes for all non-LaTeX formats.  Here is another
sentence that ``caused'' a bug in the past because double backtick
quotes could imply verbatim text up to a verbatim word starting with
period, like \texttt{.txt}.

More quotes to be tested for spellcheck:
(``with parenthesis''), ``with newline''
and ``with comma'', ``hyphen''-wise, and ``period''.


\subsection{Bibliography test}

Here is an example: \cite{Langtangen_Pedersen_2002} discussed propagation of
large destructive water waves, \cite{Langtangen_et_al_2002} gave
an overview of numerical methods for solving the Navier--Stokes equations,
while the use of Backward Kolmogorov equations for analyzing
random vibrations was investigated in \cite{Langtangen_1994a}.
The book chapter \cite{Mardal_et_al_2003a} contains information on
C++ software tools for programming multigrid methods. A real retro
reference is \cite{Langtangen_1988d} about a big FORTRAN package.
Multiple references are also possible, e.g., see
\cite{Langtangen_Pedersen_2002,Mardal_et_al_2003a}.

We need to cite more than 10 papers to reproduce an old formatting
problem with blanks in the keys in reST format:
\cite{Langtangen_1992c,Langtangen_1994a,Mortensen_et_al_2011,Langtangen_Pedersen_2002}
and
\cite{Langtangen_et_al_2002,Glimsdal_et_al_20006,Rahman_et_al_2006b,Haga_et_al_2011a,Langtangen_2003a,Langtangen_2008a,Langtangen:95}
and all the work of
\cite{Langtangen_2012,Mardal_et_al_2003a,Jeberg_et_al_2004} as well as
old work \cite{Langtangen_1988d} and \cite{Langtangen_1989e}, and the
talk \cite{Langtangen_talk_2007a}.
Langtangen also had two thesis \cite{Langtangen:85,Langtangen_1989e}
back in the days.
More retro citations are
the old ME-IN323 book \cite{Langtangen:91} and the
\cite{Langtangen:94b} OONSKI '94 paper.




% --- begin exercise ---
\begin{doconceexercise}
\refstepcounter{doconceexercisecounter}

\exercisesection{Example \thedoconceexercisecounter: Examples can be typeset as exercises}
                             
\label{Example}

Examples can start with a subsection heading starting with \texttt{Example:}
and then, with the command-line option \Verb!--examples_as_exercises! be
typeset as exercises. This is useful if one has solution
environments as part of the example.


\subex{a)}
State some problem.

\paragraph{Solution.}
The answer to this subproblem can be written here.

\subex{b)}
State some other problem.

\paragraph{Hint 1.}
A hint can be given.

\paragraph{Hint 2.}
Maybe even another hint?

\paragraph{Solution.}
The answer to this other subproblem goes here,
maybe over multiple doconce input lines.

\end{doconceexercise}
% --- end exercise ---


\subsection{User-defined environments}



Example~\vref{ex:test:1p1} demonstrates how to write a test function.
That is, a special test function for a function \texttt{add} appears in
Example~\vref{ex:test:1p1}.


\begin{example}
\label{ex:test:1p1}

\noindent\emph{A test function}.

Suppose we want to write a test function for checking the
implementation of a Python function for addition.

\bpycod
def add(a, b):
    return a + b

def test_add():
    a = 1; b = 1
    expected = a + b
    computed = add(a, b)
    assert expected == computed
\epycod
\end{example}



\begin{example}
\label{ex:math:1p1}

\noindent\emph{Addition}.

We have

\[ 1 + 1 = 2 \]
or in tabular form:


\begin{quote}
\begin{tabular}{cc}
\hline
\multicolumn{1}{c}{ Problem } & \multicolumn{1}{c}{ Result } \\
\hline
$1+1$   & $2$    \\
\hline
\end{tabular}
\end{quote}

\noindent
\end{example}



\begin{tcolorbox}[%skin=widget,
boxrule=1mm,
coltitle=black,
colframe=blue!45!white,
colback=blue!15!white,
width=(.9\linewidth),before=\hfill,after=\hfill,
adjusted title={Highlight box!}]
This environment is used to highlight something:

\[ E = mc^2 \]
\end{tcolorbox}



\subsection{URLs}
\label{subsubsec:ex}

Testing of URLs: hpl's home page \href{{https://folk.uio.no/hpl}}{hpl}, or
the entire URL if desired, \href{{https://folk.uio.no/hpl}}{\nolinkurl{https://folk.uio.no/hpl}}.  Here is a
plain file link \href{{testdoc.do.txt}}{\nolinkurl{testdoc.do.txt}}, or \href{{testdoc.do.txt}}{\nolinkurl{testdoc.do.txt}}, or
\href{{testdoc.do.txt}}{\nolinkurl{testdoc.do.txt}} or \href{{testdoc.do.txt}}{\nolinkurl{testdoc.do.txt}} or \href{{testdoc.do.txt}}{a link with
newline}. Can test spaces with the link with word
too: \href{{https://folk.uio.no/hpl}}{hpl} or \href{{https://folk.uio.no/hpl}}{hpl}. Also \texttt{file:///} works: \href{{file:///home/hpl/vc/doconce/doc/demos/manual/manual.html}}{link to a
file} is
fine to have. Moreover, ``loose'' URLs work, i.e., no quotes, just
the plain URL as in \href{{https://folk.uio.no/hpl}}{\nolinkurl{https://folk.uio.no/hpl}}, if followed by space, comma,
colon, semi-colon, question mark, exclamation mark, but not a period
(which gets confused with the periods inside the URL).

Mail addresses can also be used: \href{{mailto:hpl@simula.no}}{\nolinkurl{hpl@simula.no}}, or just a \href{{mailto:hpl@simula.no}}{mail link}, or a raw \href{{mailto:hpl@simula.no}}{\nolinkurl{mailto:hpl@simula.no}}.

Here are some tough tests of URLs, especially for the \texttt{latex} format:
\href{{https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas}}{Newton-Cotes} formulas
and a \href{{https://www.springer.com/mathematics/computational+science+%26+engineering/book/978-3-642-23098-1}}{good book}. Need to test
Newton-Cotes with percentage in URL too:
\href{{https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas}}{\nolinkurl{https://en.wikipedia.org/wiki/Newton\%E2\%80\%93Cotes_formulas}}
and \href{{https://en.wikipedia.org/wiki/Newton-Cotes#Open_Newton.E2.80.93Cotes_formulae}}{\nolinkurl{https://en.wikipedia.org/wiki/Newton-Cotes\#Open_Newton.E2.80.93Cotes_formulae}} which has a shebang.

For the \texttt{--device=paper} option it is important to test that URLs with
monospace font link text get a footnote
(unless the \Verb!--latex_no_program_footnotelink!
is used), as in this reference to
\href{{https://github.com/hplgit/INF5620/tree/gh-pages/src/decay/experiments/decay_mod.py}}{\nolinkurl{decay_mod}}, \href{{https://tinyurl.com/pwyasaa/formulas.ball1.py}}{\nolinkurl{ball1.py}},
and \href{{https://tinyurl.com/pwyasaa/formulas.ball2.py}}{\nolinkurl{ball2.py}}.


% Comments should be inserted outside paragraphs (because in the rst
% format extra blanks make a paragraph break).

% Note that when there is no https: or file:, it can be a file link
% if the link name is URL, url, "URL", or "url". Such files should,
% if rst output is desired, but placed in a \Verb!_static*! folder.

More tough tests: repeated URLs whose footnotes when using the
\texttt{--device=paper} option must be correct. We have
\href{{https://google.com}}{google}, \href{{https://google.com}}{google}, and
\href{{https://google.com}}{google}, which should result in exactly three
footnotes.



\subsection{Test of Some {\LaTeX} Fixes}

Let's check abbr.~of some common kind, e.g.~the well-known i.e.
expression as an example, and 1 vs.~2 which is also often used.
Dr.~Tang and Prof.~Monsen, or maybe also prof.~Ting,
will go to the Dept.~of Science to test how Mr.~Hansen is doing together
with Ms.~Larsen. A reference like Sec.~\vref{subsubsec:ex} or
Ch.~\vref{subsubsec:ex}, or even App.~\vref{subsubsec:ex}, must also be
handled. Likewise, this is test no.~$i$ of DocOnce features.
Also, look at Fig.~4 to see how the data compares with Tab.~\vref{mytab}.
Percentage must be fixed: 7\%,  87.65\% and
50\% at the beginning of the line.


% !split and check if these extra words are included properly in the comment

\section{{\LaTeX} Mathematics}

Here is an equation without label using backslash-bracket environment:
\[ a = b + c \]

or with number and label, as in (\ref{my:eq1}), using the equation environment:

\begin{equation}
{\partial u\over\partial t} = \nabla^2 u \label{my:eq1}
\end{equation}

We can refer to this equation by (\ref{my:eq1}).

Here is a system without equation numbers, using the align-asterisk environment:

\begin{align*}
\pmb{a} &= \pmb{q}\times\pmb{n} \\ 
b &= \nabla^2 u + \nabla^4 v
\end{align*}


And here is a system of equations with labels in an align environment:

\begin{align}
a &= q + 4 + 5+ 6 \label{eq1} \\ 
b &= \nabla^2 u + \nabla^4 x \label{eq2}
\end{align}

We can refer to (\ref{eq1})-(\ref{eq2}). They are a bit simpler than
the Navier--Stokes equations. And test {\LaTeX} hyphen in \texttt{CG-2}.
Also test $a_{i-j}$ as well as $kx-wt$.

Testing \texttt{alignat} environment:

\begin{alignat}{2}
a &= q + 4 + 5+ 6\qquad & \mbox{for } q\geq 0 \label{eq1a} \\ 
b &= \nabla^2 u + \nabla^4 x & x\in\Omega \label{eq2a}
\end{alignat}

Many of the next environments will fail in non-latex formats.
Testing multiline:

\begin{multline}
a = b = q + \\ 
  f + \nabla\cdot\nabla u
\label{multiline:eq1}
\end{multline}

Testing split:

\begin{equation}
\label{split:envir:eq}
\begin{split}
a = b = q &+ \\ 
  & f + \nabla\cdot\nabla u
\end{split}
\end{equation}
We can refer to the last equation by (\ref{split:envir:eq}).

Testing gather:
\begin{gather}
a = b \\ 
c = d + 7 + 9
\end{gather}

Let us refer to (\ref{eq1})-(\ref{eq2}) again, and to the
alignat variant (\ref{eq1a})-(\ref{eq2a}), and to (\ref{my:eq1}).

Testing eqnarray:
\begin{eqnarray}
{\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{eqnarray}

More mathematical typesetting is demonstrated in the coming exercises.

Below, we have Problem~\vref{demo:ex:1} and Project~\vref{demo:ex:2},
as well as Projects~\vref{proj:circle1} and~\vref{exer:you}, and in
between there we have Exercise~\vref{exer:some:formula}.


\section{Exercises}



% --- begin exercise ---
\begin{doconceexercise}
\refstepcounter{doconceexercisecounter}

\exercisesection{Problem \thedoconceexercisecounter: Flip a Coin}
                             
\label{demo:ex:1}
% keywords = random numbers; Monte Carlo simulation; ipynb

% Torture tests


\subex{a)}
Make a program that simulates flipping a coin $N$ times.
Print out ``tail'' or ``head'' for each flip and
let the program count the number of heads.

% --- begin hint in exercise ---

\paragraph{Hint 1.}
Use \texttt{r = random.random()} and define head as \texttt{r <= 0.5}.

% --- end hint in exercise ---

% --- begin hint in exercise ---

\paragraph{Hint 2.}
Draw an integer among $\{1,2\}$ with
\texttt{r = random.randint(1,2)} and define head when \texttt{r} is 1.

% --- end hint in exercise ---


% --- begin answer of exercise ---
\paragraph{Answer.}
If the \texttt{random.random()} function returns a number $<1/2$, let it be
head, otherwise tail. Repeat this $N$ number of times.
% --- end answer of exercise ---


% --- begin solution of exercise ---
\paragraph{Solution.}
\bpycod
import sys, random
N = int(sys.argv[1])
heads = 0
for i in range(N):
    r = random.random()
    if r <= 0.5:
        heads += 1
print('Flipping a coin %d times gave %d heads' % (N, heads))
\epycod
% --- end solution of exercise ---

\subex{b)}
Vectorize the code in a) using boolean indexing.

Vectorized code can be written in many ways.
Sometimes the code is less intuitive, sometimes not.
At least there is not much to find in Section~\vref{sec1}.

\subex{c)}
Vectorize the code in a) using \texttt{numpy.sum}.


% --- begin answer of exercise ---
\paragraph{Answer.}
\texttt{np.sum(np.where(r <= 0.5, 1, 0))} or \texttt{np.sum(r <= 0.5)}.
% --- end answer of exercise ---

In this latter subexercise, we have an
example where the code is easy to read.


\paragraph{My remarks.}
Remarks with such a subsubsection is treated as more text
after the last subexercise. Test a list too:

\begin{enumerate}
\item Mark 1.

\item Mark 2.
\end{enumerate}

\noindent
\noindent Filenames: \Verb!flip_coin.py!, \Verb!flip_coin.pdf!.

% Closing remarks for this Problem

\paragraph{Remarks.}
These are the exercise remarks, appearing at the very end.

% solution files: mysol.txt, mysol_flip_coin.py, yet_another.file

\end{doconceexercise}
% --- end exercise ---


\subsection{Not an exercise}

Should be possible to stick a normal section in the middle of many
exercises.



% --- begin exercise ---
\begin{doconceexercise}
\refstepcounter{doconceexercisecounter}

\exercisesection{Exercise \thedoconceexercisecounter: Test of plain text exercise}
                             
\label{my:exer1}

Very short exercise. What is the capital
of Norway?
\noindent Filename: \texttt{myexer1}.

\end{doconceexercise}
% --- end exercise ---




% --- begin exercise ---
\begin{doconceexercise}
\refstepcounter{doconceexercisecounter}

\exercisesection{Project \thedoconceexercisecounter: Compute a Probability}
                             
\label{demo:ex:2}

% Minimalistic exercise


What is the probability of getting a number between 0.5 and 0.6 when
drawing uniformly distributed random numbers from the interval $[0,1)$?


At the end we have a list because that caused problems in {\LaTeX}
in previous DocOnce versions:

\begin{enumerate}
\item item1

\item item2
\end{enumerate}

\noindent
% --- begin hint in exercise ---

\paragraph{Hint.}
To answer this question empirically, let a program
draw $N$ such random numbers using Python's standard \texttt{random} module,
count how many of them, $M$, that fall in the interval $(0.5,0.6)$, and
compute the probability as $M/N$.

% --- end hint in exercise ---

\end{doconceexercise}
% --- end exercise ---




% --- begin exercise ---
\begin{doconceexercise}
\refstepcounter{doconceexercisecounter}

\exercisesection{Project \thedoconceexercisecounter: Explore Distributions of Random Circles}
                             
\label{proj:circle1}
% keywords = ipynb

The formula for a circle is given by

\begin{align}
x &= x_0 + R\cos 2\pi t,
\label{circle:x}\\ 
y &= y_0 + R\sin 2\pi t,
\label{circle:y}
\end{align}
where $R$ is the radius of the circle, $(x_0,y_0)$ is the
center point, and $t$ is a parameter in the unit interval $[0,1]$.
For any $t$, $(x,y)$ computed from (\ref{circle:x})-(\ref{circle:y})
is a point on the circle.
The formula can be used to generate \texttt{n} points on a circle:

\bpypro
import numpy as np

def circle(R, x0, y0, n=501):
    t = np.linspace(0, 1, n)
    x = x0 + R*np.cos(2*np.pi*t)
    y = y0 + R*np.sin(2*np.pi*t)
    return x, y

x, y = circle(2.0, 0, 0)
\epypro

% Often in an exercise we have some comments about the solution
% which we normally want to keep where they are.

The goal of this project is to draw $N$ circles with random
center and radius. Plot each circle using the \texttt{circle} function
above.


\subex{a)}
Let $R$ be normally distributed and $(x_0,y_0)$ uniformly distributed.

% --- begin hint in exercise ---

\paragraph{Hint.}
Use the \texttt{numpy.random} module to draw the
$x_0$, $y_0$, and $R$ quantities.

% --- end hint in exercise ---


% --- begin answer of exercise ---
\paragraph{Answer.}
Here goes the short answer to part a).
% --- end answer of exercise ---


% --- begin solution of exercise ---
\paragraph{Solution.}
Here goes a full solution to part a).
% --- end solution of exercise ---

\subex{b)}
Let $R$ be uniformly distributed and $(x_0,y_0)$ normally distributed.
\noindent Filename: \texttt{norm}.

\subex{c)}
Let $R$ and $(x_0,y_0)$ be normally distributed.


\noindent Filename: \texttt{circles}.

% Closing remarks for this Project

\paragraph{Remarks.}
At the very end of the exercise it may be appropriate to summarize
and give some perspectives.


\end{doconceexercise}
% --- end exercise ---




% --- begin exercise ---
\begin{doconceexercise}
\refstepcounter{doconceexercisecounter}

\exercisesection{Exercise \thedoconceexercisecounter: Determine some Distance}
                             
\label{exer:dist}

Intro to this exercise. Questions are in subexercises below.


% --- begin solution of exercise ---
\paragraph{Solution.}
Here goes a full solution of the whole exercise.
With some math $a=b$ in this solution:
\[ \hbox{math in solution: } a = b \]
And code \texttt{a=b} in this solution:
\bccq
a = b  # code in solution
\eccq
End of solution is here.

% --- end solution of exercise ---


\subex{a)}
Subexercises are numbered a), b), etc.

% --- begin hint in exercise ---

\paragraph{Hint 1.}
First hint to subexercise a).
With math $a=b$ in hint:

\[ a=b. \]
And with code (in plain verbatim) returning $x+1$ in hint:

\bccq
def func(x):
    return x + 1  # with code in hint
\eccq

% --- end hint in exercise ---

% --- begin hint in exercise ---

\paragraph{Hint 2.}
Second hint to subexercise a).

Test list in hint:

\begin{enumerate}
\item item1

\item item2
\end{enumerate}

\noindent
% --- end hint in exercise ---
\noindent Filename: \Verb!subexer_a.pdf!.


% --- begin answer of exercise ---
\paragraph{Answer.}
Short answer to subexercise a).
With math in answer: $a=b$.
% --- end answer of exercise ---

\subex{b)}
Here goes the text for subexercise b).


Some math $\cos^2 x + \sin^2 x = 1$ written one a single line:

\[ \cos^2 x + \sin^2 x = 1 \thinspace .\]

% --- begin hint in exercise ---

\paragraph{Hint.}
A hint for this subexercise.

% --- end hint in exercise ---
\noindent Filename: \Verb!subexer_b.pdf!.


% --- begin solution of exercise ---
\paragraph{Solution.}
Here goes the solution of this subexercise.
% --- end solution of exercise ---



% No meaning in this weired test example:
The text here belongs to the main (intro) part of the exercise. Need
closing remarks to have text after subexercises.

Test list in exercise:

\begin{enumerate}
\item item1

\item item2
% Closing remarks for this Exercise
\end{enumerate}

\noindent
\paragraph{Remarks.}
Some final closing remarks, e.g., summarizing the main findings
and their implications in other problems can be made. These
remarks will appear at the end of the typeset exercise.


\end{doconceexercise}
% --- end exercise ---




% --- begin exercise ---
\begin{doconceexercise}

\exercisesection{Some exercise without the "Exercise:" prefix}

% Another minimalistic exercise

Just some text. And some math saying that $e^0=1$ on a single line,
to test that math block insertion is correct:

\[ \exp{(0)} = 1 \]

And a test that the code \texttt{lambda x: x+2} is correctly placed here:

\bccq
lambda x: x+2
\eccq


% Have some comments at the end of the exercise to see that
% the Filename: ... is written correctly.
\end{doconceexercise}
% --- end exercise ---




% --- begin exercise ---
\begin{doconceexercise}
\refstepcounter{doconceexercisecounter}

\exercisesection{Exercise \thedoconceexercisecounter: Solution of differential equation}
                             
\label{sec:this:exer:de}


\begin{doconcequiz}
\refstepcounter{doconcequizcounter}
\label{quiz:diff:eq1}


\noindent\textbf{\large SOlution of differential equation}

\noindent
Given

\[ \frac{dy}{dx} = -y(x),\quad y(0)=1 \]
What is the solution of this equation?

\vspace{2mm}

\textbf{A}. 
$y=e^{-y}$

\textbf{B}. 
$y=e^{y}$

\textbf{C}. 
\bpycod
from math import exp
def f(x):
    return exp(x)
\epycod

\textbf{D}. 
The solution cannot be found because there is a derivative in the equation.

\textbf{E}. 
The equation is meaningless: an equation must be an equation
for $x$ or $y$, not a function $y(x)$.


% --- begin answer of exercise ---
\paragraph{Answer:} A.
% --- end answer of exercise ---

% --- begin solution of exercise ---
\noindent {\bf Solution:}\\


\textbf{A}: Right. 

\textbf{B}: Wrong. Almost, but the sign is wrong (note the minus!).

\textbf{C}: Wrong. Ooops, forgot a minus: \texttt{exp(-x)}, otherwise this Python code
must be considered as a good answer. It is more natural,
though, to write the solution to the problem
in mathematical notation:

\[ y(x) = e^{-y}.\]

\textbf{D}: Wrong. Equations with derivatives can be solved;
they are termed \emph{differential
equations}.

\textbf{E}: Wrong. Equations where the unknown is a function, as $y(x)$
here, are called \emph{differential equations}, and are solved by
special techniques.


% --- end solution of exercise ---


\vspace{3mm}

\end{doconcequiz}



\end{doconceexercise}
% --- end exercise ---




% --- begin exercise ---
\begin{doconceexercise}
\refstepcounter{doconceexercisecounter}

\exercisesection{Example \thedoconceexercisecounter: Just an example}
                             

% This example needs the --examples_as_exercises option, otherwise
% it is just typeset as it is written.


\subex{a)}
What is the capital of Norway?

\paragraph{Answer.}
Oslo.

\end{doconceexercise}
% --- end exercise ---


\section{Here goes another section}

With some text, before we continue with exercises.

\section{More Exercises}



% --- begin exercise ---
\begin{doconceexercise}
\refstepcounter{doconceexercisecounter}

\exercisesection{Exercise \thedoconceexercisecounter: Make references to projects and problems}
                             
\label{exer:some:formula}

% Test comments not at the end only
Pick a statement from Project~\vref{proj:circle1} or Problem~\vref{demo:ex:1}
and verify it.

Test list at the end of an exercise without other elements (like subexercise,
hint, etc.):

\begin{enumerate}
\item item1

\item item2
\end{enumerate}

\noindent
\noindent Filename: \Verb!verify_formula.py!.

\end{doconceexercise}
% --- end exercise ---




% --- begin exercise ---
\begin{doconceexercise}
\refstepcounter{doconceexercisecounter}

\exercisesection{Project \thedoconceexercisecounter: References to Project~\vref{demo:ex:2} in a heading works for latex}
                             
\label{exer:you}

Refer to the previous exercise as Exercise~\vref{exer:some:formula},
the two before that as Projects~\vref{demo:ex:2} and~\vref{proj:circle1},
and this one as Project~\vref{exer:you}.
\noindent Filename: \Verb!selc_composed.pdf!.

\end{doconceexercise}
% --- end exercise ---




\bibliographystyle{plain}
\bibliography{papers}





\appendix

\section{Just for testing; part I}
\label{app1}

This is the first appendix.

\subsection{A subsection within an appendix}

Some text.

\section{Just for testing; part II}
\label{app2}

This is more stuff for an appendix.

\subsection{Appendix: Testing identical titles}

Without label.


\subsection{Appendix: Testing identical titles}
\label{test:title:id1}

With label.

\subsection{Appendix: Testing identical titles}
\label{test:title:id2}

What about inserting a quiz?


\begin{doconcequiz}
\refstepcounter{doconcequizcounter}
\label{quiz:2}


\noindent\textbf{\large Capital of Norway}
\paragraph{Fundamental test:}
What is the capital of Norway?

\vspace{2mm}

\textbf{A}. 
Stockholm

\textbf{B}. 
London

\textbf{C}. 
Oslo

\textbf{D}. 
Bergen


% --- begin answer of exercise ---
\paragraph{Answer:} C.
% --- end answer of exercise ---

% --- begin solution of exercise ---
\noindent {\bf Solution:}\\


\textbf{A}: Wrong. Stockholm is the capital of Sweden.

\textbf{B}: Wrong. 

\textbf{C}: Right. 

\textbf{D}: Wrong. Those from Bergen would claim so, but nobody else.


% --- end solution of exercise ---


\vspace{3mm}

\end{doconcequiz}




\subsection{Appendix: Testing identical titles}

Without label.


\begin{notice_mdfboxadmon}[Tip.]
Here is a tip or hint box, typeset as a notice box.
\end{notice_mdfboxadmon} % title: Tip.




\clearpage

Need a lot of text to surround the summary box.
Version control systems allow you to record the history of files
and share files among several computers and collaborators in a
professional way. File changes on one computer are updated or
merged with changes on another computer. Especially when working
with programs or technical reports it is essential
to have changes documented and to
ensure that every computer and person involved in the project
have the latest updates of the files.
Greg Wilson' excellent \href{{https://software-carpentry.org/2010/07/script-for-introduction-to-version-control/}}{Script for Introduction to Version Control} provides a more detailed motivation why you will benefit greatly
from using version control systems.


\begin{summary_mdfboxadmon}[Summary.]
\textbf{Bold remark:} Make some text with this summary.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
\end{summary_mdfboxadmon} % title: Summary.



Projects that you want to share among several computers or project
workers are today most conveniently stored at some web site "in the
cloud" and updated through communication with that site. I strongly
recommend you to use such sites for all serious programming and
scientific writing work - and all other important files.

The simplest services for hosting project files are \href{{https://dropbox.com}}{Dropbox} and \href{{https://drive.google.com}}{Google Drive}.
It is very easy to get started with these systems, and they allow you
to share files among laptops and mobile units with as many users as
you want. The systems offer a kind of version control in that the
files are stored frequently (several times per minute), and you can go
back to previous versions for the last 30 days. However, it is
challenging  to find the right version from the past when there are
so many of them.

More seriously, when several people may edit files simultaneously, it
can be difficult detect who did what when, roll back to previous
versions, and to manually merge the edits when these are
incompatible. Then one needs more sophisticated tools than Dropbox or
Google Drive: project hosting services with true version control
systems.  The following text aims at providing you with the minimum
information to started with such systems. Numerous other tutorials
contain more comprehensive material and in-depth explanations of the
concepts and tools.

The idea with project hosting services is that you have the files
associated with a project in the cloud. Many people may share these
files.  Every time you want to work on the project you explicitly
update your version of the files, edit the files as you like, and
synchronize the files with the "master version" at the site where the
project is hosted.  If you at some point need to go back to a
version of the files at some particular point in the past,
this is an easy operation. You can also use tools to see
what various people have done with the files in the various versions.

All these services are very similar. Below we describe how you get
started with Bitbucket, GitHub, and Googlecode. Launchpad works very
similarly to the latter three. All the project hosting services have
excellent introductions available at their web sites, but the recipes
below are much shorter and aim at getting you started as quickly as
possible by concentrating on the most important need-to-know steps.
The Git tutorials we refer to later in this document contain more
detailed information and constitute of course very valuable readings
when you use version control systems every day. The point now is
to get started.


\subsection{Appendix: Testing inline comments}

% Names can be [ A-Za-z0-9_'+-]+

Projects that you want to share among several computers or project
workers are today most conveniently stored at some web site "in the
cloud" and updated through communication with that
site. \shortinlinecomment{hpl's semi opinion 1}{ not sure if in the cloud is understood by all. }{ not sure if in } I strongly recommend you to use such sites for all serious
programming and scientific writing work - and all other important
files.

The simplest services for hosting project files is Dropbox. \longinlinecomment{mp 2}{ Simply go to \href{{https://dropbox.com}}{\nolinkurl{https://dropbox.com}} and watch the video. It explains how files, like \texttt{myfile.py}, perhaps containing much math, like $\partial u/\partial t$, are easily communicated between machines. }{ Simply go to \href{{https://dropbox.com}}{\nolinkurl{https://dropbox.com}} } It
is very easy to get started with Dropbox, and it allows you to share
files among \textcolor{red}{(hpl 3:)} \replace{laptops and mobile units}{computers, tablets, and phones}.

% Test horizontal rule

------

% Coments for editing

First\textcolor{red}{, (\textbf{edit 4}: add comma)} consider a quantity $Q$. \textcolor{red}{(edit 5:)} \replace{To this end,}{We note that}
$Q>0$, because (\textbf{edit 6}:) \remove{a} negative \textcolor{red}{(edit 7:)} \replace{quantity is}{quantities are} (\textbf{edit 8}:) \remove{just} negative.  \textcolor{red}{ (\textbf{edit 9}:) This comes as no surprise.}

% Test tailored latex figure references with page number
Let us refer to Figure~\vref{fig:impact} again.

Test references in a list:

\begin{itemize}
 \item \vref{sec1}

 \item \vref{subsec1}

 \item \vref{fig:impact}
\end{itemize}

\noindent
\subsection{Appendix: Testing headings ending with \texttt{verbatim inline} }

The point here is to test 1) \texttt{verbatim} code in headings, and 2)
ending a heading with verbatim code as this triggers a special
case in {\LaTeX}.

We also test mdash---used as alternative to hyphen without spaces around,
or in quotes:


\begin{quote}
\emph{Fun is fun}.---Unknown.
\end{quote}


The ndash should also be tested -- as in the Hanson--Nilson equations
on page 277--278.

And finally, what about admons, quotes, and boxes? They are tested
in a separate document: \texttt{admon.do.txt}.


% ------------------- end of main content ---------------

% #ifdef PREAMBLE
\cleardoublepage\phantomsection  % trick to get correct link to Index
\printindex

\end{document}
% #endif

************** File: testdoc_bigex.tex *****************
%%
%% Automatically generated file from DocOnce source
%% (https://github.com/hplgit/doconce/)
%%

% #define PREAMBLE

% #ifdef PREAMBLE
%-------------------- begin preamble ----------------------

\documentclass[%
oneside,                 % oneside: electronic viewing, twoside: printing
final,                   % draft: marks overfull hboxes, figures with paths
10pt]{article}

\listfiles               %  print all files needed to compile this document

\usepackage{relsize,makeidx,color,setspace,amsmath,amsfonts,amssymb}
\usepackage[table]{xcolor}
\usepackage{bm,ltablex,microtype}

\usepackage[pdftex]{graphicx}
\usepackage{sidecap}

% user-provided packages: --latex_packages=varioref
\usepackage{varioref}

% 'on page ...' reference with \vref{} and varioref package
\renewcommand\reftextfaceafter{on page~\thevpagerefnum}
\renewcommand\reftextfacebefore{on page~\thevpagerefnum}
\renewcommand\reftextafter{on page~\thevpagerefnum}
\renewcommand\reftextbefore{on page~\thevpagerefnum}

% Tools for marking corrections
\usepackage{soul}
\newcommand{\replace}[2]{{\color{red}\text{\st{#1} #2}}}
\newcommand{\remove}[1]{{\color{red}\st{#1}}}

% Packages for typesetting blocks of computer code
\usepackage{fancyvrb,framed,moreverb}

% Define colors
\definecolor{orange}{cmyk}{0,0.4,0.8,0.2}
\definecolor{tucorange}{rgb}{1.0,0.64,0}
\definecolor{darkorange}{rgb}{.71,0.21,0.01}
\definecolor{darkgreen}{rgb}{.12,.54,.11}
\definecolor{myteal}{rgb}{.26, .44, .56}
\definecolor{gray}{gray}{0.45}
\definecolor{mediumgray}{gray}{.8}
\definecolor{lightgray}{gray}{.95}
\definecolor{brown}{rgb}{0.54,0.27,0.07}
\definecolor{purple}{rgb}{0.5,0.0,0.5}
\definecolor{darkgray}{gray}{0.25}
\definecolor{darkblue}{rgb}{0,0.08,0.45}
\definecolor{darkblue2}{rgb}{0,0,0.8}
\definecolor{lightred}{rgb}{1.0,0.39,0.28}
\definecolor{lightgreen}{rgb}{0.48,0.99,0.0}
\definecolor{lightblue}{rgb}{0.53,0.81,0.92}
\definecolor{lightblue2}{rgb}{0.3,0.3,1.0}
\definecolor{lightpurple}{rgb}{0.87,0.63,0.87}
\definecolor{lightcyan}{rgb}{0.5,1.0,0.83}

\colorlet{comment_green}{green!50!black}
\colorlet{string_red}{red!60!black}
\colorlet{keyword_pink}{magenta!70!black}
\colorlet{indendifier_green}{green!70!white}

% Backgrounds for code
\definecolor{cbg_gray}{rgb}{.95, .95, .95}
\definecolor{bar_gray}{rgb}{.92, .92, .92}

\definecolor{cbg_yellowgray}{rgb}{.95, .95, .85}
\definecolor{bar_yellowgray}{rgb}{.95, .95, .65}

\colorlet{cbg_yellow2}{yellow!10}
\colorlet{bar_yellow2}{yellow!20}

\definecolor{cbg_yellow1}{rgb}{.98, .98, 0.8}
\definecolor{bar_yellow1}{rgb}{.98, .98, 0.4}

\definecolor{cbg_red1}{rgb}{1, 0.85, 0.85}
\definecolor{bar_red1}{rgb}{1, 0.75, 0.85}

\definecolor{cbg_blue1}{rgb}{0.87843, 0.95686, 1.0}
\definecolor{bar_blue1}{rgb}{0.7,     0.95686, 1}

%\setlength{\fboxsep}{2mm}  % adjust cod_vpad/pro_vpad background box

%% Background for code blocks (parameter is color name)

%% pro/cod_vpad: gives some vertical padding before and after the text
%% (but has more simplistic code than _cod/pro_tight+cod/pro).
%% pro/cod_vpad can be used to enclose Verbatim or lst begin/end for code.
%% pro/cod calls _pro/cod_tight and has very little vertical padding,
%% used to enclose Verbatim and other begin/end for code.
%% (pro/cod is what the ptex2tex program could produce with the
%% Blue/BlueBar definitions in .ptex2tex.cfg.)

\newenvironment{cod_vpad}[1]{
   \def\FrameCommand{\colorbox{#1}}
   \MakeFramed{\FrameRestore}}
   {\endMakeFramed}

\newenvironment{_cod_tight}[1]{
   \def\FrameCommand{\colorbox{#1}}
   \FrameRule0.6pt\MakeFramed {\FrameRestore}\vskip3mm}
   {\vskip0mm\endMakeFramed}

\newenvironment{cod}[1]{
\bgroup\rmfamily
\fboxsep=0mm\relax
\begin{_cod_tight}{#1}
\list{}{\parsep=-2mm\parskip=0mm\topsep=0pt\leftmargin=2mm
\rightmargin=2\leftmargin\leftmargin=4pt\relax}
\item\relax}
{\endlist\end{_cod_tight}\egroup}

%% Background for complete program blocks (parameter 1 is color name
%% for background, parameter 2 is color for left bar)
\newenvironment{pro_vpad}[2]{
   \def\FrameCommand{\color{#2}\vrule width 1mm\normalcolor\colorbox{#1}}
   \MakeFramed{\FrameRestore}}
   {\endMakeFramed}

\newenvironment{_pro_tight}[2]{
   \def\FrameCommand{\color{#2}\vrule width 1mm\normalcolor\colorbox{#1}}
   \FrameRule0.6pt\MakeFramed {\advance\hsize-2mm\FrameRestore}\vskip3mm}
   {\vskip0mm\endMakeFramed}

\newenvironment{pro}[2]{
\bgroup\rmfamily
\fboxsep=0mm\relax
\begin{_pro_tight}{#1}{#2}
\list{}{\parsep=-2mm\parskip=0mm\topsep=0pt\leftmargin=2mm
\rightmargin=2\leftmargin\leftmargin=4pt\relax}
\item\relax}
{\endlist\end{_pro_tight}\egroup}

\usepackage{listingsutf8}

% Common lstlisting parameters

\usepackage{calc}
\newlength{\lstboxwidth}  % width of lst box
\newlength{\framethickness}
\setlength{\framethickness}{0.5mm}
% for frame=trbl and a framerule that has significant size, set
% xleftmargin=5mm and xrightmargin=5mm.

\lstset{
  basicstyle=\small \ttfamily,
  breaklines=false,          % break/wrap lines
  breakatwhitespace=true,    % let linebreaks happen at whitespace
  breakindent=40pt,
  tab=,
  tabsize=4,                 % tab means 4 spaces
  %belowskip=\smallskipamount,  % space between code and text below
  xleftmargin=2mm,           % indentation of code frame
  xrightmargin=0mm,
  framexleftmargin=2mm,      % add frame space to the left of the code box
  %numbers=left,             % put line numbers on the left
  %stepnumber=2,             % stepnumber=1 numbers each line, =n every n lines
  framerule=\framethickness, % thickness of frame
  aboveskip=2ex,             % vertical space above code frame
  showstringspaces=false,    % show spaces in strings with an underscore
  showspaces=false,          % show spaces with an underscore
  showtabs=false,
  keepspaces=true,
  columns=fullflexible,      % tighter character kerning, like verb
  escapeinside={(*@}{@*)},   % (*@ \pause @*) in slides and math in code blocks
  extendedchars=\true,       % allows non-ascii chars, does not work with utf-8
}

% Internally defined styles for lstlisting

\lstdefinestyle{simple}{
commentstyle={},
}

% user-defined lst styles in file "mylststyles":
\lstdefinestyle{myspeciallststyle}{
keywordstyle=\color{blue}\bfseries,
commentstyle=\color{myteal},
stringstyle=\color{darkgreen},
identifierstyle=\color{darkorange},
}

% end of custom lstdefinestyles

\usepackage[T1]{fontenc}
%\usepackage[latin1]{inputenc}
\usepackage{ucs}
\usepackage[utf8x]{inputenc}

\usepackage{lmodern}         % Latin Modern fonts derived from Computer Modern

\newenvironment{doconcequiz}{}{}
\newcounter{doconcequizcounter}

% Hyperlinks in PDF:
\definecolor{linkcolor}{rgb}{0,0,0.4}
\usepackage{hyperref}
\hypersetup{
    breaklinks=true,
    colorlinks=true,
    linkcolor=linkcolor,
    urlcolor=linkcolor,
    citecolor=black,
    filecolor=black,
    %filecolor=blue,
    pdfmenubar=true,
    pdftoolbar=true,
    bookmarksdepth=3   % Uncomment (and tweak) for PDF bookmarks with more levels than the TOC
    }
%\hyperbaseurl{}   % hyperlinks are relative to this root

\setcounter{tocdepth}{2}  % levels in table of contents

%\VerbatimFootnotes must come after hyperref and footmisc packages
\VerbatimFootnotes

% Tricks for having figures close to where they are defined:
% 1. define less restrictive rules for where to put figures
\setcounter{topnumber}{2}
\setcounter{bottomnumber}{2}
\setcounter{totalnumber}{4}
\renewcommand{\topfraction}{0.95}
\renewcommand{\bottomfraction}{0.95}
\renewcommand{\textfraction}{0}
\renewcommand{\floatpagefraction}{0.75}
% floatpagefraction must always be less than topfraction!
% 2. ensure all figures are flushed before next section
\usepackage[section]{placeins}
% 3. enable begin{figure}[H] (often leads to ugly pagebreaks)
%\usepackage{float}\restylefloat{figure}

% newcommands for typesetting inline (doconce) comments
\newcommand{\shortinlinecomment}[3]{{\color{red}{\bf #1}: #2}}
\newcommand{\longinlinecomment}[3]{{\color{red}{\bf #1}: #2}}

\usepackage[framemethod=TikZ]{mdframed}

% --- begin definitions of admonition environments ---

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "notice" admon
\colorlet{mdfbox_notice_background}{gray!5}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_notice_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=mdfbox_notice_background,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{notice_mdfboxmdframed}

\newenvironment{notice_mdfboxadmon}[1][]{
\begin{notice_mdfboxmdframed}[frametitle=#1]
}
{
\end{notice_mdfboxmdframed}
}

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "summary" admon
\colorlet{mdfbox_summary_background}{gray!5}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_summary_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=mdfbox_summary_background,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{summary_mdfboxmdframed}

\newenvironment{summary_mdfboxadmon}[1][]{
\begin{summary_mdfboxmdframed}[frametitle=#1]
}
{
\end{summary_mdfboxmdframed}
}

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "warning" admon
\colorlet{mdfbox_warning_background}{gray!5}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_warning_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=mdfbox_warning_background,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{warning_mdfboxmdframed}

\newenvironment{warning_mdfboxadmon}[1][]{
\begin{warning_mdfboxmdframed}[frametitle=#1]
}
{
\end{warning_mdfboxmdframed}
}

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "question" admon
\colorlet{mdfbox_question_background}{gray!5}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_question_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=mdfbox_question_background,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{question_mdfboxmdframed}

\newenvironment{question_mdfboxadmon}[1][]{
\begin{question_mdfboxmdframed}[frametitle=#1]
}
{
\end{question_mdfboxmdframed}
}

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "block" admon
\colorlet{mdfbox_block_background}{gray!5}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_block_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=mdfbox_block_background,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{block_mdfboxmdframed}

\newenvironment{block_mdfboxadmon}[1][]{
\begin{block_mdfboxmdframed}[frametitle=#1]
}
{
\end{block_mdfboxmdframed}
}

% --- end of definitions of admonition environments ---

% prevent orhpans and widows
\clubpenalty = 10000
\widowpenalty = 10000

\usepackage{calc}

\newenvironment{doconceexercise}{}{}
\newcounter{doconceexercisecounter}
% --- begin definition of \listofexercises command ---
\makeatletter
\newcommand\listofexercises{\section*{List of Examples, Exercises, Problems, and Projects}
\@starttoc{loe}
}
\newcommand*{\l@doconceexercise}{\@dottedtocline{0}{0pt}{6.5em}}
\makeatother
% --- end definition of \listofexercises command ---



% ------ header in subexercises ------
%\newcommand{\subex}[1]{\paragraph{#1}}
%\newcommand{\subex}[1]{\par\vspace{1.7mm}\noindent{\bf #1}\ \ }
\makeatletter
% 1.5ex is the spacing above the header, 0.5em the spacing after subex title
\newcommand\subex{\@startsection{paragraph}{4}{\z@}%
                  {1.5ex\@plus1ex \@minus.2ex}%
                  {-0.5em}%
                  {\normalfont\normalsize\bfseries}}
\makeatother


% --- end of standard preamble for documents ---


\usepackage{amsthm,tcolorbox}
\theoremstyle{definition}
\newtheorem{example}{Example}[section]



% insert custom LaTeX commands...

\raggedbottom
\makeindex
\usepackage[totoc]{idxlayout}   % for index in the toc
\usepackage[nottoc]{tocbibind}  % for references/bibliography in the toc

%-------------------- end preamble ----------------------

\begin{document}

% matching end for #ifdef PREAMBLE
% #endif

\newcommand{\exercisesection}[1]{\subsection*{#1}}

\input{newcommands_bfmath}
\input{newcommands_replace}

% ------------------- main content ----------------------



% ----------------- title -------------------------

\thispagestyle{empty}

\begin{center}
{\LARGE\bf
\begin{spacing}{1.25}
A Document for Testing DocOnce
\end{spacing}
}
\end{center}

% ----------------- author(s) -------------------------

\begin{center}
{\bf Hans Petter Langtangen${}^{1, 2}$ (\texttt{hpl@simula.no})} \\ [0mm]
\end{center}


\begin{center}
{\bf Kaare Dump${}^{3}$} \\ [0mm]
\end{center}


\begin{center}
{\bf A. Dummy Author${}^{}$} \\ [0mm]
\end{center}


\begin{center}
{\bf I. S. Overworked and Outburned${}^{4, 5, 6, 7}$} \\ [0mm]
\end{center}


\begin{center}
{\bf J. Doe${}^{}$ (\texttt{j\_doe@cyberspace.com})} \\ [0mm]
\end{center}

\begin{center}
% List of all institutions:
\centerline{{\small ${}^1$Center for Biomedical Computing, Simula Research Laboratory}}
\centerline{{\small ${}^2$Department of Informatics, University of Oslo}}
\centerline{{\small ${}^3$Segfault, Cyberspace}}
\centerline{{\small ${}^4$Inst1}}
\centerline{{\small ${}^5$Inst2, Somewhere}}
\centerline{{\small ${}^6$Third Inst, Elsewhere}}
\centerline{{\small ${}^7$Fourth Inst}}
\end{center}
    
% ----------------- end author(s) -------------------------

% --- begin date ---
\begin{center}
Jan 32, 2100
\end{center}
% --- end date ---

\vspace{1cm}


\tableofcontents


\vspace{1cm} % after toc





% !split




The format of this document is
plain, homemade \textsc{pdf}{\LaTeX} (from DocOnce).

\begin{abstract}
This is a document with many test constructions for doconce syntax.
It was used heavily for the development and kept for testing
numerous constructions, also special and less common cases.

And exactly for test purposes we have an extra line here, which
is part of the abstract.

% Cannot demonstrate chapter headings since abstract and chapter
% are mutually exclusive in {\LaTeX}
\end{abstract}

\section{Section 1}
\label{sec1}

Here is a nested list:

\begin{itemize}
  \item item1

  \item item2

  \item item3 which continues
    on the next line to test that feature

  \item and a sublist
\begin{itemize}

    \item with indented subitem1

    \item and a subitem2

\end{itemize}

\noindent
  \item and perhaps an ordered sublist
\begin{enumerate}

   \item first item

   \item second item,
      continuing on a new line
\end{enumerate}

\noindent
\end{itemize}

\noindent
\paragraph{Here is a list with paragraph heading.}

\begin{itemize}
  \item item1

  \item item2
\end{itemize}

\noindent
\paragraph{Here is a list with subsubsection heading.}
\begin{itemize}
  \item item1

  \item item2
\end{itemize}

\noindent

\begin{quote}
Here are two lines that make up
a block quote for testing \emph{emphasized words} and \textbf{boldface words},
also with hypens:
\emph{pre}-fix, post-\emph{fix}, \textbf{pre}-fix, post-\textbf{fix}.
\end{quote}


Here are two references. Equation~(\ref{my:eq1}) is fine. Eq.~(\ref{my:eq1}) too.
Even Equation (\ref{my:eq1}) without the tilde.


\subsection{Subsection 1}
\label{subsec1}

\index{somefunc@{\rm\texttt{somefunc}} function}

% Refer to section/appendix etc. at the beginning of the line
% and other special fix situations for HTML.

More text, with a reference back to
Section~\vref{sec1} and~\vref{subsec1}, and further to the
sections~\vref{subsec1} and~\vref{subsubsec:ex}, which
encourages you to do the tasks in the
Exercises~\vref{demo:ex:1} and~\vref{exer:some:formula}.
Appendices~\vref{app1} and~\vref{app2} are also nice elements.

\paragraph{Test Section reference at beginning of line and after a sentence.}
Section~\vref{subsec1} is fine.
Section~\vref{subsubsec:ex} too.


% sphinx code-blocks: pycod=python cod=fortran cppcod=c++ sys=console

\paragraph{Computer code.}
Let's do some copying from files too. First from subroutine up to the very end,

\begin{cod}{cbg_gray}\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=2mm]
      subroutine test()
      integer i
      real*8 r
      r = 0
      do i = 1, i
         r = r + i
      end do
      return
C     END1

      program testme
      call test()
      return
\end{Verbatim}
\end{cod}
\noindent
and then just the subroutine,
\begin{cod}{cbg_gray}\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=2mm]

      subroutine test()
      integer i
      real*8 r
      r = 0
      do i = 1, i
         r = r + i
      end do
      return
\end{Verbatim}
\end{cod}
\noindent
and finally the complete file with a plain text verbatim environment
(\texttt{envir=ccq}):
\begin{cod}{cbg_blue1}\begin{lstlisting}[language=Python,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
C     a comment

      subroutine test()
      integer i
      real*8 r
      r = 0
      do i = 1, i
         r = r + i
      end do
      return
C     END1

      program testme
      call test()
      return
\end{lstlisting}\end{cod}
\noindent

Testing other code environments. First Python:

\begin{cod}{cbg_blue1}\begin{lstlisting}[language=Python,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
!bc pycod
def f(x):
    return x+1
!ec
\end{lstlisting}\end{cod}
\noindent
which gets rendered as

\begin{cod}{cbg_blue1}\begin{lstlisting}[language=Python,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
def f(x):
    return x+1
\end{lstlisting}\end{cod}
\noindent

Test paragraph and subsubsection headings before
before code.

\paragraph{Paragraph heading before code.}

\begin{cod}{cbg_blue1}\begin{lstlisting}[language=Python,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
import sys
sys.path.insert(0, os.pardir)
\end{lstlisting}\end{cod}
\noindent

\paragraph{Subsubsection heading before code.}
\begin{cod}{cbg_blue1}\begin{lstlisting}[language=Python,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
def h(z):
    return z+1
\end{lstlisting}\end{cod}
\noindent

Now a complete program to be shown via Python Online Tutorial:

\begin{pro}{cbg_blue1}{bar_blue1}\begin{lstlisting}[language=Python,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
class Line:
    def __init__(self, a, b):
        self.a, self.b = a, b

    def __call__(self, x):
        a, b = self.a, self.b
        return a*x + b

line = Line(2, 1)
y = line(x=3)
print(y)
\end{lstlisting}\end{pro}
\noindent
\noindent
(\href{{https://pythontutor.com/visualize.html\#code=class+Line\%3A\%0A++++def+__init__\%28self\%2C+a\%2C+b\%29\%3A\%0A++++++++self.a\%2C+self.b+\%3D+a\%2C+b\%0A\%0A++++def+__call__\%28self\%2C+x\%29\%3A\%0A++++++++a\%2C+b+\%3D+self.a\%2C+self.b\%0A++++++++return+a\%2Ax+\%2B+b\%0A\%0Aline+\%3D+Line\%282\%2C+1\%29\%0Ay+\%3D+line\%28x\%3D3\%29\%0Aprint\%28y\%29&mode=display&cumulative=false&heapPrimitives=false&drawParentPointers=false&textReferences=false&py=2&curInstr=0}}{Visualize execution}) 


Some more Python code (actually specified as a sage cell, but
such cells are not supported by this format).

\begin{pro}{cbg_blue1}{bar_blue1}\begin{lstlisting}[language=Python,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
a = 2
b = 3
print('a+b:', a + b)

# In a sage cell we can also plot
from matplotlib.pyplot import *
from numpy import *
x = linspace(0, 4*pi, 101)
y = exp(-0.1*x)*cos(x)
plot(x, y)
xlabel('x'); ylabel('y')
show()
\end{lstlisting}\end{pro}
\noindent


Then Cython (with -h option so it is hidden in html/sphinx):

\begin{cod}{cbg_blue1}\begin{lstlisting}[language=Python,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
cpdef f(double x):
    return x + 1
\end{lstlisting}\end{cod}
\noindent

Standard Python shell sessions:

\begin{cod}{cbg_blue1}\begin{lstlisting}[language=Python,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
>>> from numpy import linspace, sin
>>> # Some comment
>>> x = linspace(0, 2, 11)
>>> y = sin(x)
>>> y[0]
0
>>> import matplotlib.pyplot as plt
>>> plt.plot(x, y)
\end{lstlisting}\end{cod}
\noindent

Similar IPython sessions:

\begin{cod}{cbg_blue1}\begin{lstlisting}[language=Python,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
In [1]: from numpy import linspace, sin
In [2]: # Some comment
In [3]: x = linspace(0, 2, 11)
In [4]: y = sin(x)
In [5]: y[0]
Out[5]: 0
In [6]: import matplotlib.pyplot as plt
In [7]: plt.plot(x, y)
In [8]: a='multiple-\nline\noutput'
In [9]: a
Out[9]: 'multiple-\nline\noutput'
In [10]: print(a)
multiple-
line
output
\end{lstlisting}\end{cod}
\noindent

Here is the interactive session again, but with \texttt{pyshell-t}.

\begin{cod}{cbg_blue1}\begin{lstlisting}[language=Python,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
>>> from numpy import linspace, sin
>>> # Some comment
>>> x = linspace(0, 2, 11)
>>> y = sin(x)
>>> y[0]
0
>>> import matplotlib.pyplot as plt
>>> plt.plot(x, y)
\end{lstlisting}\end{cod}
\noindent

% This one tests a + sign before a code environment
C++:
\begin{pro}{cbg_blue1}{bar_blue1}\begin{lstlisting}[language=C++,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
#include <iostream>

int main()
{
   std::cout << "Sample output" << std::endl;
   return 0
}
\end{lstlisting}\end{pro}
\noindent
% The next should get correctly typset in sphinx (cod is fcod)
% It also tests emoji before code
And a little bit of Fortran: \raisebox{-\height+\ht\strutbox}{\includegraphics[height=1.5em]{latex_figs/dizzy_face.png}}

\begin{cod}{cbg_blue1}\begin{lstlisting}[language=Python,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
!bc cod
      subroutine midpt(x, length, a, b)
      real*8 a, b, x
      x = (a + b)/2
      length = b - a
      return
      end
!ec
\end{lstlisting}\end{cod}
\noindent
which then is typeset as

\begin{cod}{cbg_blue1}\begin{lstlisting}[language=Python,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
      subroutine midpt(x, length, a, b)
      real*8 a, b, x
      x = (a + b)/2
      length = b - a
      return
      end
\end{lstlisting}\end{cod}
\noindent

HTML:

\begin{cod}{cbg_blue1}\begin{lstlisting}[language=HTML,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
<table>
<tr><td>Column 1</td><td>Column 2</td></tr>
<tr><td>0.67526 </td><td>0.92871 </td></tr>
<!-- comment -->
</table>
\end{lstlisting}\end{cod}
\noindent

But inline HTML code is also important, like text that starts with
\texttt{<a href="} (which can destroy the following text if not properly
quoted).

Matlab with comments requires special typesetting:

\begin{cod}{cbg_blue1}\begin{lstlisting}[language=Matlab,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
% Comment on the beginning of the line can be escaped by %%
if a > b
  % Indented comment needs this trick
  c = a + b
end
\end{lstlisting}\end{cod}
\noindent

And here is a system call:

\begin{Verbatim}[frame=lines,label=\fbox{{\tiny Terminal}},framesep=2.5mm,framerule=0.7pt]
Terminal> mkdir test
Terminal> cd test
Terminal> myprog -f
output1
output2
\end{Verbatim}

Any valid pygments lexer/language name can appear to, e.g.,

\begin{cod}{cbg_blue1}\begin{lstlisting}[language=Python,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
!bc restructuredtext
=======
Heading
=======

Some text.
!ec
\end{lstlisting}\end{cod}
\noindent
results in

\begin{cod}{cbg_blue1}\begin{lstlisting}[language=Python,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
=======
Heading
=======

Some text.
\end{lstlisting}\end{cod}
\noindent

% Here goes hidden code.
% Python can be treated by some formats, Fortran is always out.





Finally, \Verb?!bc do? supports highlighting of DocOnce source:

\begin{cod}{cbg_blue1}\begin{lstlisting}[language=Python,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
======= DocOnce test file =======

===== Computer code =====

Inline verbatim code, as in `import numpy as np`, is allowed, as well as
code blocks:

!bc pycod
from math import sin

def f(x):
    """Example on a function."""
    return sin(x) + 1

print(f(0))
!ec


===== Mathematics =====

Formulas can be inline, as in $\nabla\cdot\bm{u} = 0$, or typeset
as equations:

!bt
\begin{align*}
\nabla\cdot\bm{u} &= 0,\\ 
\bm{u} &= \nabla\phi .
\end{align*}
!et

=== Subsubsection heading ===

DocOnce files can have chapters, sections, subsections, and subsubsections.

__Paragraph heading.__ Paragraphs may have headings.
\end{lstlisting}\end{cod}
\noindent

It is time to test \texttt{verbatim inline font} especially with \texttt{a newline inside the text} and an exclamation mark at the end: \texttt{BEGIN}! For
spellcheck, test \texttt{a verbatim expression} in \texttt{another} in a \texttt{third}.
Also test exclamation mark as in \Verb?!bc? and \Verb?!ec? as well as \Verb?a != b?.
Also test backslashes and braces like \Verb!\begin!, \Verb!\begin{enumerate}!,
\Verb!\end{this}\end{that}!, and \Verb!{something \inside braces}!.

Here is some \textcolor{red}{red color} and an attempt to write \textcolor{green}{with
green color containing a linebreak\\
code.} Some formats will only display \\
this correctly when \texttt{html} \\
is the output format.
But here some more running text is added which is not part of
the previous blocks with line breaks.

\paragraph{Running OS commands.}
\begin{Verbatim}[frame=lines,label=\fbox{{\tiny Terminal}},framesep=2.5mm,framerule=0.7pt]
Terminal> python -c 'print("Testing\noutput\nfrom\nPython.")'
Testing
output
from
Python.
\end{Verbatim}


\paragraph{Footnotes.}
Here is a test of footnotes \footnote{Typesetting of the footnote depends on the format. Plain text does nothing, {\LaTeX} removes the definition and inserts the footnote as part of the {\LaTeX} text. reStructuredText and Sphinx employ a similar type of typesetting as Extended Markdown and DocOnce, and in HTML we keep the same syntax, just displayed properly in HTML.}, which are handy in text.
They are used in different flavors, now in

\begin{itemize}
 \item list items (note below that footnotes work after math, verbatim, and URLs - bin fact old and emphasize too!)

 \item even with math $\nabla^2u$\footnote{Math footnotes can be dangerous since it interferes with an exponent.}

 \item and code \texttt{h[i] += 1}\footnote{One-line footnote.}
   (\emph{must} have space between inline code and footnote!)

 \item and \href{{https://google.com}}{links}\footnote{\href{{google.com}}{\nolinkurl{google.com}} is perhaps the most famous web site today.}
\end{itemize}

\noindent
which gives flexibility in writing.
This is the third\footnote{Not much to add here, but the footnote is at the end with only one newline.} example.





Here is some more text before a new definition of a footnote that was
used above.


\begin{notice_mdfboxadmon}[Non-breaking space character.]
This paragraph aims to test \href{{https://en.wikipedia.org/wiki/Non-breaking_space}}{non-breaking space character}, and a typical
example where this is needed is in physical units: 7.4~km is traveled
in~$7.4/5.5\approx 1.345$~s.  Also check that a~\href{{https://google.com}}{link}~is
not broken across lines (drag the browser window to test this).
(On the other hand, the tilde is used in
computer code, e.g., as in \texttt{[~x for x in y]} or in \texttt{y=~x}, and should
of course remain a tilde in those contexts.)
\end{notice_mdfboxadmon} % title: Non-breaking space character.



\subsection{Subsection 2: Testing figures}
\label{subsec:ex}
\index{figures}

Test of figures. In particular we refer to Figure~\vref{fig:impact} in which
there is a flow.


\begin{figure}[!ht]  % fig:impact
  \centerline{\includegraphics[width=0.9\linewidth]{../doc/src/manual/fig/wave1D.pdf}}
  \caption{
  Visualization \textbf{of} a \emph{wave}. \label{fig:impact}
  }
\end{figure}
%\clearpage % flush figures fig:impact


Figures without captions are allowed and will be inlined.



\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=0.9\linewidth]{../doc/src/manual/fig/wave1D.pdf}}

\vspace{6mm}



\index{movies}


% Test multi-line caption in figure with sidecap=True

Here is figure~\vref{myfig} with a long (illegal) multi-line caption
containing inline verbatim text:


\begin{SCfigure}
  \centering
  \includegraphics[width=0.9\linewidth]{../doc/src/manual/fig/wave1D.png}
  \caption{
  A long caption spanning several lines and containing verbatim words like \protect \Verb!my\_file\_v1! and \protect \Verb!my\_file\_v2! as well as math with subscript as in $t_{i+1}$. \label{myfig}
  }
\end{SCfigure}
%\clearpage % flush figures myfig


% Must be a blank line after MOVIE or FIGURE to detect this problem

Test URL as figure name:



\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=0.8\linewidth]{downloaded_figures/f_plot.png}}

\vspace{6mm}




% Test wikimedia type of files that otherwise reside in subdirs


\paragraph{Remark.}
Movies are tested in separate file \texttt{movies.do.txt}.


% Somewhat challenging heading with latex math, \t, \n, ? and parenthesis

\subsection{The $\theta$ parameter (not $\nabla$?)}
\label{decay:sec:theta}

Functions do not always need to be advanced, here is one
involving $\theta$:
\begin{cod}{cbg_blue1}\begin{lstlisting}[language=Python,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
def f(theta):
    return theta**2
\end{lstlisting}\end{cod}
\noindent

\paragraph{More on $\theta$.}
Here is more text following headline with math.

Newcommands must also be tested in this \report:
$\half$, $\halfi$, $\x$, $\Ddt{u}$,
both inline and in block:

\begin{align}
\Ddt{u} &= 0\nonumber
\\ 
\half &= \halfi\\ 
\half\x &= \normalvec
\end{align}

Or with align with label and numbers:

\begin{align}
\Ddt{u} &= 0
\label{aligneq1}
\\ 
\half &= \halfi\\ 
\half\x &= \normalvec
\label{aligneq2}
\end{align}


% Must test more complicated align and matrix compositions
% where DocOnce inserts auto-numbered labels etc.

First one numbered (automatically):

\begin{align}
\begin{pmatrix}
G_2 + G_3 & -G_3 & -G_2 & 0 \\ 
-G_3 & G_3 + G_4 & 0 & -G_4 \\ 
-G_2 & 0 & G_1 + G_2 & 0 \\ 
0 & -G_4 & 0 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
 v_1 \\ 
 v_2 \\ 
 v_3 \\ 
 v_4
\end{pmatrix}
+ \cdots \\ 
\begin{pmatrix}
 C_5 + C_6 & -C_6 & 0 & 0 \\ 
 -C_6 & C_6 & 0 & 0 \\ 
 0 & 0 & 0 & 0 \\ 
 0 & 0 & 0 & 0
\end{pmatrix}
  &= \frac{d}{dt}\begin{pmatrix}
 v_1 \\ 
 v_2 \\ 
 v_3 \\ 
 v_4
\end{pmatrix} +
\begin{pmatrix}
 0 \\ 
 0 \\ 
 0 \\ 
 -i_0
\end{pmatrix}
\nonumber
\end{align}

Second numbered (automatically):

\begin{align}
\begin{pmatrix}
G_1 + G_2\\ 
-G_3 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
 v_1 \\ 
 v_2
\end{pmatrix}
+ \cdots\nonumber
\\ 
\left(\begin{array}{ll}
y & 2\\ 
2 & 1
\end{array}\right)
\left(\begin{array}{ll}
0 \\ x
\end{array}\right)
&= \begin{pmatrix}
A \\ B
\end{pmatrix}
\end{align}

Both numbered, with label by the user:

\begin{align}
\begin{pmatrix}
G_1 + G_2\\ 
-G_3 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
 v_1 \\ 
 v_2
\end{pmatrix}
+ \cdots \label{mymatrix:eq1}
\\ 
\label{mymatrix:eq2}
\left(\begin{array}{ll}
y & 2\\ 
2 & 1
\end{array}\right)
\left(\begin{array}{ll}
0 \\ x
\end{array}\right)
&= \begin{pmatrix}
A \\ B
\end{pmatrix}
\end{align}
Now we refer to (\ref{mymatrix:eq1})-(\ref{mymatrix:eq2}).

\subsection{Custom Environments}

Here is an attempt to create a theorem environment via Mako
(for counting theorems) and comment lines to help replacing lines in
the \texttt{.tex} by proper begin-end {\LaTeX} environments for theorems.
Should look nice in most formats!



% begin theorem
\label{theorem:fundamental1}


\paragraph{Theorem 5.}
Let $a=1$ and $b=2$. Then $c=3$.
% end theorem

% begin proof
\paragraph{Proof.}
Since $c=a+b$, the result follows from straightforward addition.
$\Diamond$
% end proof

As we see, the proof of Theorem 5 is a modest
achievement.


\subsection{Tables}
\label{subsec:table}

\index{test index with verbatim text@test index with {\rm\texttt{verbatim text}} which is possible}
\index{test two@test {\rm\texttt{two}} (separate) {\rm\texttt{verbatim expressions}} which is also possible}
\index{index with!subindex}
\index{\textbf{boldface word} in index}
\index{index with \textbf{boldface word}}
\index{index with!\textbf{boldface word} in subentry}
\index{double \textbf{boldface word}! \textbf{boldface word} in subentry too}

% index with comma could fool sphinx
\index{index, with comma, and one more}

Let us take this table from the manual:

\begin{table}
\caption{
Testing table environment in {\LaTeX}, enabled by testing on the "latex" format
with the preprocessor.
\label{mytab}
}



\begin{quote}
\begin{tabular}{lrr}
\hline
\multicolumn{1}{c}{ time } & \multicolumn{1}{c}{ velocity } & \multicolumn{1}{c}{ acceleration } \\
\hline
0.0  & 1.4186   & -5.01        \\
2.0  & 1.376512 & 11.919       \\
4.0  & 1.1E+1   & 14.717624    \\
\hline
\end{tabular}
\end{quote}

\noindent
\end{table}

The DocOnce source code reads
\begin{cod}{cbg_blue1}\begin{lstlisting}[language=Python,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]

  |--------------------------------|
  |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{lstlisting}\end{cod}
\noindent

Here is yet another table to test that we can handle more than
one table:


\begin{quote}
\begin{tabular}{lll}
\hline
\multicolumn{1}{l}{ time } & \multicolumn{1}{l}{ velocity } & \multicolumn{1}{l}{ acceleration } \\
\hline
0.0  & 1.4186   & -5.01        \\
1.0  & 1.376512 & 11.919       \\
3.0  & 1.1E+1   & 14.717624    \\
\hline
\end{tabular}
\end{quote}

\noindent
And one with math headings (that are expanded and must be treated
accordingly), verbatim heading and entry, and no space around the pipe
symbol:


\begin{quote}
\begin{tabular}{lrrr}
\hline
\multicolumn{1}{c}{ $i$ } & \multicolumn{1}{c}{ $h_i$ } & \multicolumn{1}{c}{ $\bar T_i$ } & \multicolumn{1}{c}{ \Verb!L\_i! } \\
\hline
0   & 0      & 288        & -0.0065    \\
1   & 11,000 & 216        & 0.0        \\
2   & 20,000 & 216        & 0.001      \\
3   & 32,000 & 228        & 0.0028     \\
4   & 47,000 & 270        & 0.0        \\
5   & 51,000 & 270        & -0.0028    \\
6   & 71,000 & 214        & \texttt{NaN} \\
\hline
\end{tabular}
\end{quote}

\noindent
And add one with verbatim headings (with underscores),
and rows starting with \texttt{|-} because of a negative number,
and \texttt{|} right before and after verbatim word (with no space):


\begin{quote}
\begin{tabular}{rrrr}
\hline
\multicolumn{1}{c}{ exact } & \multicolumn{1}{c}{ \Verb!v\_1! } & \multicolumn{1}{c}{ $a_i$ + \Verb!v\_2! } & \multicolumn{1}{c}{ \Verb!verb\_3\_! } \\
\hline
9     & 9.62       & 5.57               & 8.98           \\
-20   & -23.39     & -7.65              & -19.93         \\
10    & 17.74      & -4.50              & 9.96           \\
0     & -9.19      & 4.13               & -0.26          \\
\hline
\end{tabular}
\end{quote}

\noindent
Pipe symbols in verbatim and math text in tables used to pose difficulties,
but not
anymore:


\begin{quote}
\begin{tabular}{lr}
\hline
\multicolumn{1}{c}{ $S$ } & \multicolumn{1}{c}{ command } \\
\hline
$ ||a_0|| $ & \texttt{norm|length} \\
$x\cap y$   & \texttt{x|y}         \\
\hline
\end{tabular}
\end{quote}

\noindent

Here is a table with X alignment:


\begin{quote}
\begin{tabularx}{\linewidth}{cX}
\hline
\multicolumn{1}{c}{ Type } & \multicolumn{1}{c}{ Description } \\
\hline
X     & Alignment character that is used for specifying a potentially very long text in a column in a table. It makes use of the \texttt{tabularx} package in {\LaTeX}, otherwise (for other formats) it means \texttt{l} (centered alignment). \\
l,r,c & standard alignment characters                                                                                                                                                                                                       \\
\hline
\end{tabularx}
\end{quote}

\noindent
Finally, a table with math
and URLs.

% Mako code to expand URLs in the table
% (These types of tables did not work before Jan 2014)



\begin{quote}
\begin{tabular}{ccc}
\hline
 \\
\hline
$\mathcal{L}=0$         & \includegraphics[width=2cm]{../doc/src/manual/mov/wave_frames/frame_0080.png} & \includegraphics[width=2cm]{../doc/src/manual/mov/wave_frames/frame_0085.png} \\
$a=b$                   & \includegraphics[width=2cm]{../doc/src/manual/mov/wave_frames/frame_0090.png} & \includegraphics[width=2cm]{../doc/src/manual/mov/wave_frames/frame_0095.png} \\
$\nabla\cdot\bm{u} =0 $ & \includegraphics[width=2cm]{../doc/src/manual/mov/wave_frames/frame_0100.png} & \includegraphics[width=2cm]{../doc/src/manual/mov/wave_frames/frame_0105.png} \\
\hline
\end{tabular}
\end{quote}

\noindent

\subsection{A test of verbatim words in heading with subscript $a_i$: \protect\Verb!my\_file\_v1! and \protect\Verb!my\_file\_v2! }

\paragraph{Paragraph with verbatim and math: \protect\Verb!my\_file\_v1.py! and \protect\Verb!my\_file\_v2.py! define some math $a_{i-1}$.}
Here is more \Verb!__verbatim__! code and
some plain text on a new line.

% Test various types of headlines
\subsection{\textbf{Just bold}}

Some text.

\subsection{\emph{Just emphasize}}

Some text.

\subsection{\texttt{Just verbatim} }

Some text.

\subsection{\textbf{Bold} beginning}

Some text.

\subsection{\emph{Emphasize} beginning}

Some text.

\subsection{\texttt{Verbatim} beginning}

Some text.

\subsection{Maybe \textbf{bold end}}

Some text.

\subsection{Maybe \emph{emphasize end}}

Some text.

\subsection{Maybe \texttt{verbatim end} }

Some text.

\subsection{The middle has \textbf{bold} word}

Some text.

\subsection{The middle has \emph{emphasize} word}

Some text.

\subsection{The middle has \texttt{verbatim} word}

Some text.


\paragraph{\emph{Just emphasize}.}
Some text.


\paragraph{\texttt{Just verbatim}.}
Some text.


\paragraph{\emph{Emphasize} beginning.}
Some text.


\paragraph{\texttt{Verbatim beginning}.}
Some text.


\paragraph{Maybe \emph{emphasize end}.}
Some text.


\paragraph{Maybe \texttt{verbatim end}.}
Some text.


\paragraph{The middle has \emph{emphasize} word.}
Some text.


\paragraph{The middle has \texttt{verbatim} word.}
Some text.


\paragraph{Ampersand.}
We can test Hennes {\&} Mauritz, often abbreviated H{\&}M, but written
as \Verb!Hennes & Mauritz! and \Verb!H & M!.
A sole \Verb!&! must also work.
% Note: substitutions must not occur inside verbatim, just in ordinary text.

\begin{cod}{cbg_blue1}\begin{lstlisting}[language=Python,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
# Just to check that ampersand works in code blocks:
c = a & b
\end{lstlisting}\end{cod}
\noindent

\paragraph{Quotes.}
Let us also add a test of quotes such as ``double quotes, with numbers
like 3.14 and newline/comma and hyphen (as in double-quote)''; written
in the standard LaTeX-style that gives correct {\LaTeX} formatting and
ordinary double quotes for all non-LaTeX formats.  Here is another
sentence that ``caused'' a bug in the past because double backtick
quotes could imply verbatim text up to a verbatim word starting with
period, like \texttt{.txt}.

More quotes to be tested for spellcheck:
(``with parenthesis''), ``with newline''
and ``with comma'', ``hyphen''-wise, and ``period''.


\subsection{Bibliography test}

Here is an example: \cite{Langtangen_Pedersen_2002} discussed propagation of
large destructive water waves, \cite{Langtangen_et_al_2002} gave
an overview of numerical methods for solving the Navier--Stokes equations,
while the use of Backward Kolmogorov equations for analyzing
random vibrations was investigated in \cite{Langtangen_1994a}.
The book chapter \cite{Mardal_et_al_2003a} contains information on
C++ software tools for programming multigrid methods. A real retro
reference is \cite{Langtangen_1988d} about a big FORTRAN package.
Multiple references are also possible, e.g., see
\cite{Langtangen_Pedersen_2002,Mardal_et_al_2003a}.

We need to cite more than 10 papers to reproduce an old formatting
problem with blanks in the keys in reST format:
\cite{Langtangen_1992c,Langtangen_1994a,Mortensen_et_al_2011,Langtangen_Pedersen_2002}
and
\cite{Langtangen_et_al_2002,Glimsdal_et_al_20006,Rahman_et_al_2006b,Haga_et_al_2011a,Langtangen_2003a,Langtangen_2008a,Langtangen:95}
and all the work of
\cite{Langtangen_2012,Mardal_et_al_2003a,Jeberg_et_al_2004} as well as
old work \cite{Langtangen_1988d} and \cite{Langtangen_1989e}, and the
talk \cite{Langtangen_talk_2007a}.
Langtangen also had two thesis \cite{Langtangen:85,Langtangen_1989e}
back in the days.
More retro citations are
the old ME-IN323 book \cite{Langtangen:91} and the
\cite{Langtangen:94b} OONSKI '94 paper.




% --- begin exercise ---
\begin{doconceexercise}
\refstepcounter{doconceexercisecounter}

\exercisesection{Example \thedoconceexercisecounter: Examples can be typeset as exercises}
                             
\label{Example}

Examples can start with a subsection heading starting with \texttt{Example:}
and then, with the command-line option \Verb!--examples_as_exercises! be
typeset as exercises. This is useful if one has solution
environments as part of the example.


\subex{a)}
State some problem.

\paragraph{Solution.}
The answer to this subproblem can be written here.

\subex{b)}
State some other problem.

\paragraph{Hint 1.}
A hint can be given.

\paragraph{Hint 2.}
Maybe even another hint?

\paragraph{Solution.}
The answer to this other subproblem goes here,
maybe over multiple doconce input lines.

\end{doconceexercise}
% --- end exercise ---


\subsection{User-defined environments}



Example~\vref{ex:test:1p1} demonstrates how to write a test function.
That is, a special test function for a function \texttt{add} appears in
Example~\vref{ex:test:1p1}.


\begin{example}
\label{ex:test:1p1}

\noindent\emph{A test function}.

Suppose we want to write a test function for checking the
implementation of a Python function for addition.

\begin{cod}{cbg_blue1}\begin{lstlisting}[language=Python,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
def add(a, b):
    return a + b

def test_add():
    a = 1; b = 1
    expected = a + b
    computed = add(a, b)
    assert expected == computed
\end{lstlisting}\end{cod}
\noindent
\end{example}



\begin{example}
\label{ex:math:1p1}

\noindent\emph{Addition}.

We have

\[ 1 + 1 = 2 \]
or in tabular form:


\begin{quote}
\begin{tabular}{cc}
\hline
\multicolumn{1}{c}{ Problem } & \multicolumn{1}{c}{ Result } \\
\hline
$1+1$   & $2$    \\
\hline
\end{tabular}
\end{quote}

\noindent
\end{example}



\begin{tcolorbox}[%skin=widget,
boxrule=1mm,
coltitle=black,
colframe=blue!45!white,
colback=blue!15!white,
width=(.9\linewidth),before=\hfill,after=\hfill,
adjusted title={Highlight box!}]
This environment is used to highlight something:

\[ E = mc^2 \]
\end{tcolorbox}



\subsection{URLs}
\label{subsubsec:ex}

Testing of URLs: hpl's home page \href{{https://folk.uio.no/hpl}}{hpl}, or
the entire URL if desired, \href{{https://folk.uio.no/hpl}}{\nolinkurl{https://folk.uio.no/hpl}}.  Here is a
plain file link \href{{testdoc.do.txt}}{\nolinkurl{testdoc.do.txt}}, or \href{{testdoc.do.txt}}{\nolinkurl{testdoc.do.txt}}, or
\href{{testdoc.do.txt}}{\nolinkurl{testdoc.do.txt}} or \href{{testdoc.do.txt}}{\nolinkurl{testdoc.do.txt}} or \href{{testdoc.do.txt}}{a link with
newline}. Can test spaces with the link with word
too: \href{{https://folk.uio.no/hpl}}{hpl} or \href{{https://folk.uio.no/hpl}}{hpl}. Also \texttt{file:///} works: \href{{file:///home/hpl/vc/doconce/doc/demos/manual/manual.html}}{link to a
file} is
fine to have. Moreover, ``loose'' URLs work, i.e., no quotes, just
the plain URL as in \href{{https://folk.uio.no/hpl}}{\nolinkurl{https://folk.uio.no/hpl}}, if followed by space, comma,
colon, semi-colon, question mark, exclamation mark, but not a period
(which gets confused with the periods inside the URL).

Mail addresses can also be used: \href{{mailto:hpl@simula.no}}{\nolinkurl{hpl@simula.no}}, or just a \href{{mailto:hpl@simula.no}}{mail link}, or a raw \href{{mailto:hpl@simula.no}}{\nolinkurl{mailto:hpl@simula.no}}.

Here are some tough tests of URLs, especially for the \texttt{latex} format:
\href{{https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas}}{Newton-Cotes} formulas
and a \href{{https://www.springer.com/mathematics/computational+science+%26+engineering/book/978-3-642-23098-1}}{good book}. Need to test
Newton-Cotes with percentage in URL too:
\href{{https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas}}{\nolinkurl{https://en.wikipedia.org/wiki/Newton\%E2\%80\%93Cotes_formulas}}
and \href{{https://en.wikipedia.org/wiki/Newton-Cotes#Open_Newton.E2.80.93Cotes_formulae}}{\nolinkurl{https://en.wikipedia.org/wiki/Newton-Cotes\#Open_Newton.E2.80.93Cotes_formulae}} which has a shebang.

For the \texttt{--device=paper} option it is important to test that URLs with
monospace font link text get a footnote
(unless the \Verb!--latex_no_program_footnotelink!
is used), as in this reference to
\href{{https://github.com/hplgit/INF5620/tree/gh-pages/src/decay/experiments/decay_mod.py}}{\nolinkurl{decay_mod}}, \href{{https://tinyurl.com/pwyasaa/formulas.ball1.py}}{\nolinkurl{ball1.py}},
and \href{{https://tinyurl.com/pwyasaa/formulas.ball2.py}}{\nolinkurl{ball2.py}}.


% Comments should be inserted outside paragraphs (because in the rst
% format extra blanks make a paragraph break).

% Note that when there is no https: or file:, it can be a file link
% if the link name is URL, url, "URL", or "url". Such files should,
% if rst output is desired, but placed in a \Verb!_static*! folder.

More tough tests: repeated URLs whose footnotes when using the
\texttt{--device=paper} option must be correct. We have
\href{{https://google.com}}{google}, \href{{https://google.com}}{google}, and
\href{{https://google.com}}{google}, which should result in exactly three
footnotes.



\subsection{Test of Some {\LaTeX} Fixes}

Let's check abbr.~of some common kind, e.g.~the well-known i.e.
expression as an example, and 1 vs.~2 which is also often used.
Dr.~Tang and Prof.~Monsen, or maybe also prof.~Ting,
will go to the Dept.~of Science to test how Mr.~Hansen is doing together
with Ms.~Larsen. A reference like Sec.~\vref{subsubsec:ex} or
Ch.~\vref{subsubsec:ex}, or even App.~\vref{subsubsec:ex}, must also be
handled. Likewise, this is test no.~$i$ of DocOnce features.
Also, look at Fig.~4 to see how the data compares with Tab.~\vref{mytab}.
Percentage must be fixed: 7\%,  87.65\% and
50\% at the beginning of the line.


% !split and check if these extra words are included properly in the comment

\section{{\LaTeX} Mathematics}

Here is an equation without label using backslash-bracket environment:
\[ a = b + c \]

or with number and label, as in (\ref{my:eq1}), using the equation environment:

\begin{equation}
{\partial u\over\partial t} = \nabla^2 u \label{my:eq1}
\end{equation}

We can refer to this equation by (\ref{my:eq1}).

Here is a system without equation numbers, using the align-asterisk environment:

\begin{align*}
\pmb{a} &= \pmb{q}\times\pmb{n} \\ 
b &= \nabla^2 u + \nabla^4 v
\end{align*}


And here is a system of equations with labels in an align environment:

\begin{align}
a &= q + 4 + 5+ 6 \label{eq1} \\ 
b &= \nabla^2 u + \nabla^4 x \label{eq2}
\end{align}

We can refer to (\ref{eq1})-(\ref{eq2}). They are a bit simpler than
the Navier--Stokes equations. And test {\LaTeX} hyphen in \texttt{CG-2}.
Also test $a_{i-j}$ as well as $kx-wt$.

Testing \texttt{alignat} environment:

\begin{alignat}{2}
a &= q + 4 + 5+ 6\qquad & \mbox{for } q\geq 0 \label{eq1a} \\ 
b &= \nabla^2 u + \nabla^4 x & x\in\Omega \label{eq2a}
\end{alignat}

Many of the next environments will fail in non-latex formats.
Testing multiline:

\begin{multline}
a = b = q + \\ 
  f + \nabla\cdot\nabla u
\label{multiline:eq1}
\end{multline}

Testing split:

\begin{equation}
\label{split:envir:eq}
\begin{split}
a = b = q &+ \\ 
  & f + \nabla\cdot\nabla u
\end{split}
\end{equation}
We can refer to the last equation by (\ref{split:envir:eq}).

Testing gather:
\begin{gather}
a = b \\ 
c = d + 7 + 9
\end{gather}

Let us refer to (\ref{eq1})-(\ref{eq2}) again, and to the
alignat variant (\ref{eq1a})-(\ref{eq2a}), and to (\ref{my:eq1}).

Testing eqnarray:
\begin{eqnarray}
{\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{eqnarray}

More mathematical typesetting is demonstrated in the coming exercises.

Below, we have Problem~\vref{demo:ex:1} and Project~\vref{demo:ex:2},
as well as Projects~\vref{proj:circle1} and~\vref{exer:you}, and in
between there we have Exercise~\vref{exer:some:formula}.


\section{Exercises}



% --- begin exercise ---
\begin{doconceexercise}
\refstepcounter{doconceexercisecounter}

\exercisesection{Problem \thedoconceexercisecounter: Flip a Coin}
                             
\label{demo:ex:1}
% keywords = random numbers; Monte Carlo simulation; ipynb

% Torture tests


\subex{a)}
Make a program that simulates flipping a coin $N$ times.
Print out ``tail'' or ``head'' for each flip and
let the program count the number of heads.

% --- begin hint in exercise ---

\paragraph{Hint 1.}
Use \texttt{r = random.random()} and define head as \texttt{r <= 0.5}.

% --- end hint in exercise ---

% --- begin hint in exercise ---

\paragraph{Hint 2.}
Draw an integer among $\{1,2\}$ with
\texttt{r = random.randint(1,2)} and define head when \texttt{r} is 1.

% --- end hint in exercise ---


% --- begin answer of exercise ---
\paragraph{Answer.}
If the \texttt{random.random()} function returns a number $<1/2$, let it be
head, otherwise tail. Repeat this $N$ number of times.
% --- end answer of exercise ---


% --- begin solution of exercise ---
\paragraph{Solution.}
\begin{cod}{cbg_blue1}\begin{lstlisting}[language=Python,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
import sys, random
N = int(sys.argv[1])
heads = 0
for i in range(N):
    r = random.random()
    if r <= 0.5:
        heads += 1
print('Flipping a coin %d times gave %d heads' % (N, heads))
\end{lstlisting}\end{cod}
\noindent
% --- end solution of exercise ---

\subex{b)}
Vectorize the code in a) using boolean indexing.

Vectorized code can be written in many ways.
Sometimes the code is less intuitive, sometimes not.
At least there is not much to find in Section~\vref{sec1}.

\subex{c)}
Vectorize the code in a) using \texttt{numpy.sum}.


% --- begin answer of exercise ---
\paragraph{Answer.}
\texttt{np.sum(np.where(r <= 0.5, 1, 0))} or \texttt{np.sum(r <= 0.5)}.
% --- end answer of exercise ---

In this latter subexercise, we have an
example where the code is easy to read.


\paragraph{My remarks.}
Remarks with such a subsubsection is treated as more text
after the last subexercise. Test a list too:

\begin{enumerate}
\item Mark 1.

\item Mark 2.
\end{enumerate}

\noindent
\noindent Filenames: \Verb!flip_coin.py!, \Verb!flip_coin.pdf!.

% Closing remarks for this Problem

\paragraph{Remarks.}
These are the exercise remarks, appearing at the very end.

% solution files: mysol.txt, mysol_flip_coin.py, yet_another.file

\end{doconceexercise}
% --- end exercise ---


\subsection{Not an exercise}

Should be possible to stick a normal section in the middle of many
exercises.



% --- begin exercise ---
\begin{doconceexercise}
\refstepcounter{doconceexercisecounter}

\exercisesection{Exercise \thedoconceexercisecounter: Test of plain text exercise}
                             
\label{my:exer1}

Very short exercise. What is the capital
of Norway?
\noindent Filename: \texttt{myexer1}.

\end{doconceexercise}
% --- end exercise ---




% --- begin exercise ---
\begin{doconceexercise}
\refstepcounter{doconceexercisecounter}

\exercisesection{Project \thedoconceexercisecounter: Compute a Probability}
                             
\label{demo:ex:2}

% Minimalistic exercise


What is the probability of getting a number between 0.5 and 0.6 when
drawing uniformly distributed random numbers from the interval $[0,1)$?


At the end we have a list because that caused problems in {\LaTeX}
in previous DocOnce versions:

\begin{enumerate}
\item item1

\item item2
\end{enumerate}

\noindent
% --- begin hint in exercise ---

\paragraph{Hint.}
To answer this question empirically, let a program
draw $N$ such random numbers using Python's standard \texttt{random} module,
count how many of them, $M$, that fall in the interval $(0.5,0.6)$, and
compute the probability as $M/N$.

% --- end hint in exercise ---

\end{doconceexercise}
% --- end exercise ---




% --- begin exercise ---
\begin{doconceexercise}
\refstepcounter{doconceexercisecounter}

\exercisesection{Project \thedoconceexercisecounter: Explore Distributions of Random Circles}
                             
\label{proj:circle1}
% keywords = ipynb

The formula for a circle is given by

\begin{align}
x &= x_0 + R\cos 2\pi t,
\label{circle:x}\\ 
y &= y_0 + R\sin 2\pi t,
\label{circle:y}
\end{align}
where $R$ is the radius of the circle, $(x_0,y_0)$ is the
center point, and $t$ is a parameter in the unit interval $[0,1]$.
For any $t$, $(x,y)$ computed from (\ref{circle:x})-(\ref{circle:y})
is a point on the circle.
The formula can be used to generate \texttt{n} points on a circle:

\begin{pro}{cbg_blue1}{bar_blue1}\begin{lstlisting}[language=Python,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
import numpy as np

def circle(R, x0, y0, n=501):
    t = np.linspace(0, 1, n)
    x = x0 + R*np.cos(2*np.pi*t)
    y = y0 + R*np.sin(2*np.pi*t)
    return x, y

x, y = circle(2.0, 0, 0)
\end{lstlisting}\end{pro}
\noindent

% Often in an exercise we have some comments about the solution
% which we normally want to keep where they are.

The goal of this project is to draw $N$ circles with random
center and radius. Plot each circle using the \texttt{circle} function
above.


\subex{a)}
Let $R$ be normally distributed and $(x_0,y_0)$ uniformly distributed.

% --- begin hint in exercise ---

\paragraph{Hint.}
Use the \texttt{numpy.random} module to draw the
$x_0$, $y_0$, and $R$ quantities.

% --- end hint in exercise ---


% --- begin answer of exercise ---
\paragraph{Answer.}
Here goes the short answer to part a).
% --- end answer of exercise ---


% --- begin solution of exercise ---
\paragraph{Solution.}
Here goes a full solution to part a).
% --- end solution of exercise ---

\subex{b)}
Let $R$ be uniformly distributed and $(x_0,y_0)$ normally distributed.
\noindent Filename: \texttt{norm}.

\subex{c)}
Let $R$ and $(x_0,y_0)$ be normally distributed.


\noindent Filename: \texttt{circles}.

% Closing remarks for this Project

\paragraph{Remarks.}
At the very end of the exercise it may be appropriate to summarize
and give some perspectives.


\end{doconceexercise}
% --- end exercise ---




% --- begin exercise ---
\begin{doconceexercise}
\refstepcounter{doconceexercisecounter}

\exercisesection{Exercise \thedoconceexercisecounter: Determine some Distance}
                             
\label{exer:dist}

Intro to this exercise. Questions are in subexercises below.


% --- begin solution of exercise ---
\paragraph{Solution.}
Here goes a full solution of the whole exercise.
With some math $a=b$ in this solution:
\[ \hbox{math in solution: } a = b \]
And code \texttt{a=b} in this solution:
\begin{cod}{cbg_blue1}\begin{lstlisting}[language=Python,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
a = b  # code in solution
\end{lstlisting}\end{cod}
\noindent
End of solution is here.

% --- end solution of exercise ---


\subex{a)}
Subexercises are numbered a), b), etc.

% --- begin hint in exercise ---

\paragraph{Hint 1.}
First hint to subexercise a).
With math $a=b$ in hint:

\[ a=b. \]
And with code (in plain verbatim) returning $x+1$ in hint:

\begin{cod}{cbg_blue1}\begin{lstlisting}[language=Python,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
def func(x):
    return x + 1  # with code in hint
\end{lstlisting}\end{cod}
\noindent

% --- end hint in exercise ---

% --- begin hint in exercise ---

\paragraph{Hint 2.}
Second hint to subexercise a).

Test list in hint:

\begin{enumerate}
\item item1

\item item2
\end{enumerate}

\noindent
% --- end hint in exercise ---
\noindent Filename: \Verb!subexer_a.pdf!.


% --- begin answer of exercise ---
\paragraph{Answer.}
Short answer to subexercise a).
With math in answer: $a=b$.
% --- end answer of exercise ---

\subex{b)}
Here goes the text for subexercise b).


Some math $\cos^2 x + \sin^2 x = 1$ written one a single line:

\[ \cos^2 x + \sin^2 x = 1 \thinspace .\]

% --- begin hint in exercise ---

\paragraph{Hint.}
A hint for this subexercise.

% --- end hint in exercise ---
\noindent Filename: \Verb!subexer_b.pdf!.


% --- begin solution of exercise ---
\paragraph{Solution.}
Here goes the solution of this subexercise.
% --- end solution of exercise ---



% No meaning in this weired test example:
The text here belongs to the main (intro) part of the exercise. Need
closing remarks to have text after subexercises.

Test list in exercise:

\begin{enumerate}
\item item1

\item item2
% Closing remarks for this Exercise
\end{enumerate}

\noindent
\paragraph{Remarks.}
Some final closing remarks, e.g., summarizing the main findings
and their implications in other problems can be made. These
remarks will appear at the end of the typeset exercise.


\end{doconceexercise}
% --- end exercise ---




% --- begin exercise ---
\begin{doconceexercise}

\exercisesection{Some exercise without the "Exercise:" prefix}

% Another minimalistic exercise

Just some text. And some math saying that $e^0=1$ on a single line,
to test that math block insertion is correct:

\[ \exp{(0)} = 1 \]

And a test that the code \texttt{lambda x: x+2} is correctly placed here:

\begin{cod}{cbg_blue1}\begin{lstlisting}[language=Python,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
lambda x: x+2
\end{lstlisting}\end{cod}
\noindent


% Have some comments at the end of the exercise to see that
% the Filename: ... is written correctly.
\end{doconceexercise}
% --- end exercise ---




% --- begin exercise ---
\begin{doconceexercise}
\refstepcounter{doconceexercisecounter}

\exercisesection{Exercise \thedoconceexercisecounter: Solution of differential equation}
                             
\label{sec:this:exer:de}


\begin{doconcequiz}
\refstepcounter{doconcequizcounter}
\label{quiz:diff:eq1}


\noindent\textbf{\large SOlution of differential equation}

\noindent
Given

\[ \frac{dy}{dx} = -y(x),\quad y(0)=1 \]
What is the solution of this equation?

\vspace{2mm}

\textbf{A}. 
$y=e^{-y}$

\textbf{B}. 
$y=e^{y}$

\textbf{C}. 
\begin{cod}{cbg_blue1}\begin{lstlisting}[language=Python,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
from math import exp
def f(x):
    return exp(x)
\end{lstlisting}\end{cod}
\noindent

\textbf{D}. 
The solution cannot be found because there is a derivative in the equation.

\textbf{E}. 
The equation is meaningless: an equation must be an equation
for $x$ or $y$, not a function $y(x)$.


% --- begin answer of exercise ---
\paragraph{Answer:} A.
% --- end answer of exercise ---

% --- begin solution of exercise ---
\noindent {\bf Solution:}\\


\textbf{A}: Right. 

\textbf{B}: Wrong. Almost, but the sign is wrong (note the minus!).

\textbf{C}: Wrong. Ooops, forgot a minus: \texttt{exp(-x)}, otherwise this Python code
must be considered as a good answer. It is more natural,
though, to write the solution to the problem
in mathematical notation:

\[ y(x) = e^{-y}.\]

\textbf{D}: Wrong. Equations with derivatives can be solved;
they are termed \emph{differential
equations}.

\textbf{E}: Wrong. Equations where the unknown is a function, as $y(x)$
here, are called \emph{differential equations}, and are solved by
special techniques.


% --- end solution of exercise ---


\vspace{3mm}

\end{doconcequiz}



\end{doconceexercise}
% --- end exercise ---




% --- begin exercise ---
\begin{doconceexercise}
\refstepcounter{doconceexercisecounter}

\exercisesection{Example \thedoconceexercisecounter: Just an example}
                             

% This example needs the --examples_as_exercises option, otherwise
% it is just typeset as it is written.


\subex{a)}
What is the capital of Norway?

\paragraph{Answer.}
Oslo.

\end{doconceexercise}
% --- end exercise ---


\section{Here goes another section}

With some text, before we continue with exercises.

\section{More Exercises}



% --- begin exercise ---
\begin{doconceexercise}
\refstepcounter{doconceexercisecounter}

\exercisesection{Exercise \thedoconceexercisecounter: Make references to projects and problems}
                             
\label{exer:some:formula}

% Test comments not at the end only
Pick a statement from Project~\vref{proj:circle1} or Problem~\vref{demo:ex:1}
and verify it.

Test list at the end of an exercise without other elements (like subexercise,
hint, etc.):

\begin{enumerate}
\item item1

\item item2
\end{enumerate}

\noindent
\noindent Filename: \Verb!verify_formula.py!.

\end{doconceexercise}
% --- end exercise ---




% --- begin exercise ---
\begin{doconceexercise}
\refstepcounter{doconceexercisecounter}

\exercisesection{Project \thedoconceexercisecounter: References to Project~\vref{demo:ex:2} in a heading works for pdflatex}
                             
\label{exer:you}

Refer to the previous exercise as Exercise~\vref{exer:some:formula},
the two before that as Projects~\vref{demo:ex:2} and~\vref{proj:circle1},
and this one as Project~\vref{exer:you}.
\noindent Filename: \Verb!selc_composed.pdf!.

\end{doconceexercise}
% --- end exercise ---




\bibliographystyle{plain}
\bibliography{papers}





\appendix

\section{Just for testing; part I}
\label{app1}

This is the first appendix.

\subsection{A subsection within an appendix}

Some text.

\section{Just for testing; part II}
\label{app2}

This is more stuff for an appendix.

\subsection{Appendix: Testing identical titles}

Without label.


\subsection{Appendix: Testing identical titles}
\label{test:title:id1}

With label.

\subsection{Appendix: Testing identical titles}
\label{test:title:id2}

What about inserting a quiz?


\begin{doconcequiz}
\refstepcounter{doconcequizcounter}
\label{quiz:2}


\noindent\textbf{\large Capital of Norway}
\paragraph{Fundamental test:}
What is the capital of Norway?

\vspace{2mm}

\textbf{A}. 
Stockholm

\textbf{B}. 
London

\textbf{C}. 
Oslo

\textbf{D}. 
Bergen


% --- begin answer of exercise ---
\paragraph{Answer:} C.
% --- end answer of exercise ---

% --- begin solution of exercise ---
\noindent {\bf Solution:}\\


\textbf{A}: Wrong. Stockholm is the capital of Sweden.

\textbf{B}: Wrong. 

\textbf{C}: Right. 

\textbf{D}: Wrong. Those from Bergen would claim so, but nobody else.


% --- end solution of exercise ---


\vspace{3mm}

\end{doconcequiz}




\subsection{Appendix: Testing identical titles}

Without label.


\begin{notice_mdfboxadmon}[Tip.]
Here is a tip or hint box, typeset as a notice box.
\end{notice_mdfboxadmon} % title: Tip.




\clearpage

Need a lot of text to surround the summary box.
Version control systems allow you to record the history of files
and share files among several computers and collaborators in a
professional way. File changes on one computer are updated or
merged with changes on another computer. Especially when working
with programs or technical reports it is essential
to have changes documented and to
ensure that every computer and person involved in the project
have the latest updates of the files.
Greg Wilson' excellent \href{{https://software-carpentry.org/2010/07/script-for-introduction-to-version-control/}}{Script for Introduction to Version Control} provides a more detailed motivation why you will benefit greatly
from using version control systems.


\begin{summary_mdfboxadmon}[Summary.]
\textbf{Bold remark:} Make some text with this summary.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
\end{summary_mdfboxadmon} % title: Summary.



Projects that you want to share among several computers or project
workers are today most conveniently stored at some web site "in the
cloud" and updated through communication with that site. I strongly
recommend you to use such sites for all serious programming and
scientific writing work - and all other important files.

The simplest services for hosting project files are \href{{https://dropbox.com}}{Dropbox} and \href{{https://drive.google.com}}{Google Drive}.
It is very easy to get started with these systems, and they allow you
to share files among laptops and mobile units with as many users as
you want. The systems offer a kind of version control in that the
files are stored frequently (several times per minute), and you can go
back to previous versions for the last 30 days. However, it is
challenging  to find the right version from the past when there are
so many of them.

More seriously, when several people may edit files simultaneously, it
can be difficult detect who did what when, roll back to previous
versions, and to manually merge the edits when these are
incompatible. Then one needs more sophisticated tools than Dropbox or
Google Drive: project hosting services with true version control
systems.  The following text aims at providing you with the minimum
information to started with such systems. Numerous other tutorials
contain more comprehensive material and in-depth explanations of the
concepts and tools.

The idea with project hosting services is that you have the files
associated with a project in the cloud. Many people may share these
files.  Every time you want to work on the project you explicitly
update your version of the files, edit the files as you like, and
synchronize the files with the "master version" at the site where the
project is hosted.  If you at some point need to go back to a
version of the files at some particular point in the past,
this is an easy operation. You can also use tools to see
what various people have done with the files in the various versions.

All these services are very similar. Below we describe how you get
started with Bitbucket, GitHub, and Googlecode. Launchpad works very
similarly to the latter three. All the project hosting services have
excellent introductions available at their web sites, but the recipes
below are much shorter and aim at getting you started as quickly as
possible by concentrating on the most important need-to-know steps.
The Git tutorials we refer to later in this document contain more
detailed information and constitute of course very valuable readings
when you use version control systems every day. The point now is
to get started.


\subsection{Appendix: Testing inline comments}

% Names can be [ A-Za-z0-9_'+-]+

Projects that you want to share among several computers or project
workers are today most conveniently stored at some web site "in the
cloud" and updated through communication with that
site. \shortinlinecomment{hpl's semi opinion 1}{ not sure if in the cloud is understood by all. }{ not sure if in } I strongly recommend you to use such sites for all serious
programming and scientific writing work - and all other important
files.

The simplest services for hosting project files is Dropbox. \longinlinecomment{mp 2}{ Simply go to \href{{https://dropbox.com}}{\nolinkurl{https://dropbox.com}} and watch the video. It explains how files, like \texttt{myfile.py}, perhaps containing much math, like $\partial u/\partial t$, are easily communicated between machines. }{ Simply go to \href{{https://dropbox.com}}{\nolinkurl{https://dropbox.com}} } It
is very easy to get started with Dropbox, and it allows you to share
files among \textcolor{red}{(hpl 3:)} \replace{laptops and mobile units}{computers, tablets, and phones}.

% Test horizontal rule

------

% Coments for editing

First\textcolor{red}{, (\textbf{edit 4}: add comma)} consider a quantity $Q$. \textcolor{red}{(edit 5:)} \replace{To this end,}{We note that}
$Q>0$, because (\textbf{edit 6}:) \remove{a} negative \textcolor{red}{(edit 7:)} \replace{quantity is}{quantities are} (\textbf{edit 8}:) \remove{just} negative.  \textcolor{red}{ (\textbf{edit 9}:) This comes as no surprise.}

% Test tailored latex figure references with page number
Let us refer to Figure~\vref{fig:impact} again.

Test references in a list:

\begin{itemize}
 \item \vref{sec1}

 \item \vref{subsec1}

 \item \vref{fig:impact}
\end{itemize}

\noindent
\subsection{Appendix: Testing headings ending with \texttt{verbatim inline} }

The point here is to test 1) \texttt{verbatim} code in headings, and 2)
ending a heading with verbatim code as this triggers a special
case in {\LaTeX}.

We also test mdash---used as alternative to hyphen without spaces around,
or in quotes:


\begin{quote}
\emph{Fun is fun}.---Unknown.
\end{quote}


The ndash should also be tested -- as in the Hanson--Nilson equations
on page 277--278.

And finally, what about admons, quotes, and boxes? They are tested
in a separate document: \texttt{admon.do.txt}.


% ------------------- end of main content ---------------

% #ifdef PREAMBLE
\cleardoublepage\phantomsection  % trick to get correct link to Index
\printindex

\end{document}
% #endif

************** File: testdoc.tex_doconce_ptex2tex *****************
\bsys (!bc sys) -> \begin{Verbatim}[frame=lines]

\bpypro (!bc pypro) -> \begin{python:nt}

\bpyshell (!bc pyshell) -> \begin{minted}[fontsize=\fontsize{9pt}{9pt},linenos=false,mathescape,baselinestretch=1.0,fontfamily=tt,xleftmargin=7mm]{python}

\bpycod (!bc py) -> \begin{minted}[fontsize=\fontsize{9pt}{9pt},linenos=false,mathescape,baselinestretch=1.0,fontfamily=tt,xleftmargin=7mm]{python}

\bcycod (!bc cy) -> \begin{minted}[fontsize=\fontsize{9pt}{9pt},linenos=false,mathescape,baselinestretch=1.0,fontfamily=tt,xleftmargin=7mm]{cython}

\bfcod (!bc f) -> \begin{minted}[fontsize=\fontsize{9pt}{9pt},linenos=false,mathescape,baselinestretch=1.0,fontfamily=tt,xleftmargin=7mm]{fortran}

\bcpppro (!bc cpp) -> \begin{minted}[fontsize=\fontsize{9pt}{9pt},linenos=false,mathescape,baselinestretch=1.0,fontfamily=tt,xleftmargin=7mm]{c++}

\bmcod (!bc m) -> \begin{minted}[fontsize=\fontsize{9pt}{9pt},linenos=false,mathescape,baselinestretch=1.0,fontfamily=tt,xleftmargin=7mm]{matlab}

\bhtmlcod (!bc html) -> \begin{minted}[fontsize=\fontsize{9pt}{9pt},linenos=false,mathescape,baselinestretch=1.0,fontfamily=tt,xleftmargin=7mm]{html}

\bipy (!bc ipy) -> \begin{minted}[fontsize=\fontsize{9pt}{9pt},linenos=false,mathescape,baselinestretch=1.0,fontfamily=tt,xleftmargin=7mm]{ipy}

\bdo (!bc do) -> \begin{minted}[fontsize=\fontsize{9pt}{9pt},linenos=false,mathescape,baselinestretch=1.0,fontfamily=tt,xleftmargin=7mm]{doconce}

\brestructuredtext (!bc restructuredtext) -> \begin{minted}[fontsize=\fontsize{9pt}{9pt},linenos=false,mathescape,baselinestretch=1.0,fontfamily=tt,xleftmargin=7mm]{restructuredtext}

\bccq (!bc ccq) -> \begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95] ("ccq" is unsupported so we use Verbatim)

\bcod (!bc cod) -> \begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95] ("cod" is unsupported so we use Verbatim)

output in testdoc.tex
----------- end of doconce ptex2tex output ----------------
%%
%% Automatically generated file from DocOnce source
%% (https://github.com/hplgit/doconce/)
%%
%%


%-------------------- begin preamble ----------------------

\documentclass[%
twoside,                 % oneside: electronic viewing, twoside: printing
draft,                   % draft: marks overfull hboxes, figures with paths
10pt]{article}

\listfiles               %  print all files needed to compile this document

\usepackage[a4paper]{geometry}

\usepackage{relsize,makeidx,color,setspace,amsmath,amsfonts,amssymb}
\usepackage[table]{xcolor}
\usepackage{bm,ltablex,microtype}

\usepackage[pdftex]{graphicx}
\usepackage{sidecap}

% user--provided packages: --latex_packages=varioref
\usepackage{varioref}

% 'on page ...' reference with \vref{} and varioref package
\renewcommand\reftextfaceafter{on page~\thevpagerefnum}
\renewcommand\reftextfacebefore{on page~\thevpagerefnum}
\renewcommand\reftextafter{on page~\thevpagerefnum}
\renewcommand\reftextbefore{on page~\thevpagerefnum}

% Tools for marking corrections
\usepackage{soul}
\newcommand{\replace}[2]{{\color{red}\text{\st{#1} #2}}}
\newcommand{\remove}[1]{{\color{red}\st{#1}}}

\usepackage{fancyvrb,anslistings} % packages needed for verbatim environments
\usepackage{minted}
\usemintedstyle{default}
\usepackage{fancyvrb}

\usepackage[T1]{fontenc}
%\usepackage[latin1]{inputenc}
\usepackage{ucs}
\usepackage[utf8x]{inputenc}

% Set palatino as the default font family:
\usepackage[sc]{mathpazo}    % Palatino fonts
\linespread{1.05}            % Palatino needs extra line spread to look nice

\usepackage{lmodern}         % Latin Modern fonts derived from Computer Modern

\newenvironment{doconcequiz}{}{}
\newcounter{doconcequizcounter}

% Hyperlinks in PDF:
\colorlet{linkcolor}{blue!90}
\usepackage{hyperref}
\hypersetup{
    breaklinks=true,
    colorlinks=true,
    linkcolor=linkcolor,
    urlcolor=linkcolor,
    citecolor=black,
    filecolor=black,
    %filecolor=blue,
    pdfmenubar=true,
    pdftoolbar=true,
    bookmarksdepth=3   % Uncomment (and tweak) for PDF bookmarks with more levels than the TOC
    }
%\hyperbaseurl{}   % hyperlinks are relative to this root

\setcounter{tocdepth}{2}  % levels in table of contents

%\VerbatimFootnotes must come after hyperref and footmisc packages
\VerbatimFootnotes

% Tricks for having figures close to where they are defined:
% 1. define less restrictive rules for where to put figures
\setcounter{topnumber}{2}
\setcounter{bottomnumber}{2}
\setcounter{totalnumber}{4}
\renewcommand{\topfraction}{0.95}
\renewcommand{\bottomfraction}{0.95}
\renewcommand{\textfraction}{0}
\renewcommand{\floatpagefraction}{0.75}
% floatpagefraction must always be less than topfraction!
% 2. ensure all figures are flushed before next section
\usepackage[section]{placeins}
% 3. enable begin{figure}[H] (often leads to ugly pagebreaks)
%\usepackage{float}\restylefloat{figure}

% enable inline (doconce) comments to be typeset with the todonotes package
\usepackage{ifthen,xkeyval,tikz,calc,graphicx}
\usepackage[shadow]{todonotes}
\newcommand{\shortinlinecomment}[3]{%
\todo[size=\normalsize,fancyline,color=orange!40,caption={#3}]{%
 \begin{spacing}{0.75}{\bf #1}: #2\end{spacing}}}
\newcommand{\longinlinecomment}[3]{%
\todo[inline,color=orange!40,caption={#3}]{{\bf #1}: #2}}

% Display labels for sections, equations, and citations in the margin
\usepackage{showlabels}
\showlabels{cite}

\onehalfspacing    % from setspace package
%\doublespacing

% --- fancyhdr package for fancy headers ---
\usepackage{fancyhdr}
\fancyhf{} % sets both header and footer to nothing
\renewcommand{\headrulewidth}{1pt}
% section name to the left (L) and page number to the right (R)
% on even (E) pages, the other way around on odd pages
% (switch twoside to onside in documentclass to just have odd pages)
\fancyhead[LE,RO]{\rightmark} % section
\fancyhead[RE,LO]{\thepage}
\pagestyle{fancy}


\usepackage[framemethod=TikZ]{mdframed}

% --- begin definitions of admonition environments ---

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "notice" admon
\colorlet{mdfbox_notice_background}{gray!5}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_notice_background,
  linecolor=seccolor,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=seccolor!20,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{notice_mdfboxmdframed}

\newenvironment{notice_mdfboxadmon}[1][]{
\begin{notice_mdfboxmdframed}[frametitle=#1]
}
{
\end{notice_mdfboxmdframed}
}

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "summary" admon
\colorlet{mdfbox_summary_background}{gray!5}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_summary_background,
  linecolor=seccolor,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=seccolor!20,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{summary_mdfboxmdframed}

\newenvironment{summary_mdfboxadmon}[1][]{
\begin{summary_mdfboxmdframed}[frametitle=#1]
}
{
\end{summary_mdfboxmdframed}
}

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "warning" admon
\colorlet{mdfbox_warning_background}{gray!5}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_warning_background,
  linecolor=seccolor,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=seccolor!20,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{warning_mdfboxmdframed}

\newenvironment{warning_mdfboxadmon}[1][]{
\begin{warning_mdfboxmdframed}[frametitle=#1]
}
{
\end{warning_mdfboxmdframed}
}

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "question" admon
\colorlet{mdfbox_question_background}{gray!5}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_question_background,
  linecolor=seccolor,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=seccolor!20,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{question_mdfboxmdframed}

\newenvironment{question_mdfboxadmon}[1][]{
\begin{question_mdfboxmdframed}[frametitle=#1]
}
{
\end{question_mdfboxmdframed}
}

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "block" admon
\colorlet{mdfbox_block_background}{gray!5}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_block_background,
  linecolor=seccolor,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=seccolor!20,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{block_mdfboxmdframed}

\newenvironment{block_mdfboxadmon}[1][]{
\begin{block_mdfboxmdframed}[frametitle=#1]
}
{
\end{block_mdfboxmdframed}
}

% --- end of definitions of admonition environments ---

% prevent orhpans and widows
\clubpenalty = 10000
\widowpenalty = 10000

% https://www.ctex.org/documents/packages/layout/titlesec.pdf
\usepackage{titlesec}  % needed for colored section headings
%\usepackage[compact]{titlesec}  % reduce the spacing around section headings

% --- section/subsection headings with blue color ---
\definecolor{seccolor}{cmyk}{.9,.5,0,.35}  % siamltexmm.sty section color
\titleformat{name=\section}
{\color{seccolor}\normalfont\Large\bfseries}
{\color{seccolor}\thesection}{1em}{}
\titleformat{name=\subsection}
{\color{seccolor}\normalfont\large\bfseries}
{\color{seccolor}\thesubsection}{1em}{}
\titleformat{name=\paragraph}[runin]
{\color{seccolor}\normalfont\normalsize\bfseries}
{}{}{\indent}

% let the header have a thick gray hrule with section and page in blue above
\renewcommand{\headrulewidth}{1pt}
\renewcommand{\headrule}{{\color{gray!50}%
\hrule width\headwidth height\headrulewidth \vskip-\headrulewidth}}
% replace \rightmark and \thepage by bfseries everwyhere to get bold headings
\fancyhead[LE,RO]{{\color{seccolor}\nouppercase{\rightmark}}} %section
\fancyhead[RE,LO]{{\color{seccolor}\thepage}}


% --- color every two table rows ---
\let\oldtabular\tabular
\let\endoldtabular\endtabular
\definecolor{appleblue}{rgb}{0.93,0.95,1.0}  % Apple blue
\renewenvironment{tabular}{\rowcolors{2}{white}{appleblue}%
\oldtabular}{\endoldtabular}


\newenvironment{doconceexercise}{}{}
\newcounter{doconceexercisecounter}
% --- begin definition of \listofexercises command ---
\makeatletter
\newcommand\listofexercises{\section*{List of Examples, Exercises, Problems, and Projects}
\@starttoc{loe}
}
\newcommand*{\l@doconceexercise}{\@dottedtocline{0}{0pt}{6.5em}}
\makeatother
% --- end definition of \listofexercises command ---



% ------ header in subexercises ------
%\newcommand{\subex}[1]{\paragraph{#1}}
%\newcommand{\subex}[1]{\par\vspace{1.7mm}\noindent{\bf #1}\ \ }
\makeatletter
% 1.5ex is the spacing above the header, 0.5em the spacing after subex title
\newcommand\subex{\@startsection{paragraph}{4}{\z@}%
                  {1.5ex\@plus1ex \@minus.2ex}%
                  {-0.5em}%
                  {\normalfont\normalsize\bfseries}}
\makeatother


% --- end of standard preamble for documents ---


\usepackage{amsthm,tcolorbox}
\theoremstyle{definition}
\newtheorem{example}{Example}[section]
\newtheorem{theorem}{Theorem}[section]



% insert custom LaTeX commands...

\raggedbottom
\makeindex
\usepackage[totoc]{idxlayout}   % for index in the toc
\usepackage[nottoc]{tocbibind}  % for references/bibliography in the toc

%-------------------- end preamble ----------------------

\begin{document}

% matching end for #ifdef PREAMBLE

\newcommand{\exercisesection}[1]{\subsection*{#1}}

\input{newcommands_bfmath}
\input{newcommands_replace}

% ------------------- main content ----------------------



% ----------------- title -------------------------

\thispagestyle{empty}
\hbox{\ \ }
\vfill
\begin{center}
{\huge{\bfseries{
\begin{spacing}{1.25}
{\color{seccolor}\rule{\linewidth}{0.5mm}} \\[0.4cm]
{\color{seccolor}A Document for Testing DocOnce}
\\[0.4cm] {\color{seccolor}\rule{\linewidth}{0.5mm}} \\[1.5cm]
\end{spacing}
}}}

% ----------------- author(s) -------------------------

\vspace{0.5cm}

{\Large\textsf{Hans Petter Langtangen${}^{1, 2}$ (\texttt{hpl@simula.no})}}\\ [3mm]

{\Large\textsf{Kaare Dump${}^{3}$}}\\ [3mm]

{\Large\textsf{A. Dummy Author${}^{}$}}\\ [3mm]

{\Large\textsf{I. S. Overworked and Outburned${}^{4, 5, 6, 7}$}}\\ [3mm]

{\Large\textsf{J. Doe${}^{}$ (\texttt{j\_doe@cyberspace.com})}}\\ [3mm]

\ \\ [2mm]

{\large\textsf{${}^1$Center for Biomedical Computing, Simula Research Laboratory} \\ [1.5mm]}
{\large\textsf{${}^2$Department of Informatics, University of Oslo} \\ [1.5mm]}
{\large\textsf{${}^3$Segfault, Cyberspace} \\ [1.5mm]}
{\large\textsf{${}^4$Inst1} \\ [1.5mm]}
{\large\textsf{${}^5$Inst2, Somewhere} \\ [1.5mm]}
{\large\textsf{${}^6$Third Inst, Elsewhere} \\ [1.5mm]}
{\large\textsf{${}^7$Fourth Inst} \\ [1.5mm]}
% ----------------- end author(s) -------------------------

% --- begin date ---
\ \\ [10mm]
{\large\textsf{Jan 32, 2100}}
\end{center}
% --- end date ---
\vfill
\clearpage

\tableofcontents
\listofexercises


\listoftodos[List of inline comments]


\clearpage % after toc





% !split




The format of this document is
plain, homemade \textsc{pdf}{\LaTeX} (from DocOnce).

% --- begin abstract ---
\ \\ [13mm]
\begin{center}
\begin{minipage}{0.9\linewidth}
\small
This is a document with many test constructions for doconce syntax.
It was used heavily for the development and kept for testing
numerous constructions, also special and less common cases.

And exactly for test purposes we have an extra line here, which
is part of the abstract.

% Cannot demonstrate chapter headings since abstract and chapter
% are mutually exclusive in {\LaTeX}
\end{minipage}
\end{center}
% --- end abstract ---

\section{Section 1}
\label{sec1}

Here is a nested list:

\begin{itemize}
  \item item1

  \item item2

  \item item3 which continues
    on the next line to test that feature

  \item and a sublist
\begin{itemize}

    \item with indented subitem1

    \item and a subitem2

\end{itemize}

\noindent
  \item and perhaps an ordered sublist
\begin{enumerate}

   \item first item

   \item second item,
      continuing on a new line
\end{enumerate}

\noindent
\end{itemize}

\noindent
\paragraph{Here is a list with paragraph heading.}

\begin{itemize}
  \item item1

  \item item2
\end{itemize}

\noindent
\paragraph{Here is a list with subsubsection heading.}
\begin{itemize}
  \item item1

  \item item2
\end{itemize}

\noindent

\begin{quote}
Here are two lines that make up
a block quote for testing \emph{emphasized words} and \textbf{boldface words},
also with hypens:
\emph{pre}-fix, post-\emph{fix}, \textbf{pre}-fix, post-\textbf{fix}.
\end{quote}


Here are two references. Equation~(\ref{my:eq1}) is fine. Eq.~(\ref{my:eq1}) too.
Even Equation (\ref{my:eq1}) without the tilde.


\subsection{Subsection 1}
\label{subsec1}

\index{somefunc@{\rm\texttt{somefunc}} function}\marginpar{\footnotesize {\rm\texttt{somefunc}} function}

% Refer to section/appendix etc. at the beginning of the line
% and other special fix situations for HTML.

More text, with a reference back to
Section~\vref{sec1} and~\vref{subsec1}, and further to the
sections~\vref{subsec1} and~\vref{subsubsec:ex}, which
encourages you to do the tasks in the
Exercises~\vref{demo:ex:1} and~\vref{exer:some:formula}.
Appendices~\vref{app1} and~\vref{app2} are also nice elements.

\paragraph{Test Section reference at beginning of line and after a sentence.}
Section~\vref{subsec1} is fine.
Section~\vref{subsubsec:ex} too.


% sphinx code--blocks: pycod=python cod=fortran cppcod=c++ sys=console

\paragraph{Computer code.}
Let's do some copying from files too. First from subroutine up to the very end,

\begin{minted}[fontsize=\fontsize{9pt}{9pt},linenos=false,mathescape,baselinestretch=1.0,fontfamily=tt,xleftmargin=7mm]{fortran}
      subroutine test()
      integer i
      real*8 r
      r = 0
      do i = 1, i
         r = r + i
      end do
      return
C     END1

      program testme
      call test()
      return
\end{minted}
and then just the subroutine,
\begin{minted}[fontsize=\fontsize{9pt}{9pt},linenos=false,mathescape,baselinestretch=1.0,fontfamily=tt,xleftmargin=7mm]{fortran}

      subroutine test()
      integer i
      real*8 r
      r = 0
      do i = 1, i
         r = r + i
      end do
      return
\end{minted}
and finally the complete file with a plain text verbatim environment
(\texttt{envir=ccq}):
\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95]
C     a comment

      subroutine test()
      integer i
      real*8 r
      r = 0
      do i = 1, i
         r = r + i
      end do
      return
C     END1

      program testme
      call test()
      return
\end{Verbatim}

Testing other code environments. First Python:

\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95]
!bc pycod
def f(x):
    return x+1
!ec
\end{Verbatim}
which gets rendered as

\begin{minted}[fontsize=\fontsize{9pt}{9pt},linenos=false,mathescape,baselinestretch=1.0,fontfamily=tt,xleftmargin=7mm]{python}
def f(x):
    return x+1
\end{minted}

Test paragraph and subsubsection headings before
before code.

\paragraph{Paragraph heading before code.}

\begin{minted}[fontsize=\fontsize{9pt}{9pt},linenos=false,mathescape,baselinestretch=1.0,fontfamily=tt,xleftmargin=7mm]{python}
import sys
sys.path.insert(0, os.pardir)
\end{minted}

\paragraph{Subsubsection heading before code.}
\begin{minted}[fontsize=\fontsize{9pt}{9pt},linenos=false,mathescape,baselinestretch=1.0,fontfamily=tt,xleftmargin=7mm]{python}
def h(z):
    return z+1
\end{minted}

Now a complete program to be shown via Python Online Tutorial:

\begin{python:nt}
class Line:
    def __init__(self, a, b):
        self.a, self.b = a, b

    def __call__(self, x):
        a, b = self.a, self.b
        return a*x + b

line = Line(2, 1)
y = line(x=3)
print(y)
\end{python:nt}

Some more Python code (actually specified as a sage cell, but
such cells are not supported by this format).

\begin{python:nt}
a = 2
b = 3
print('a+b:', a + b)

# In a sage cell we can also plot
from matplotlib.pyplot import *
from numpy import *
x = linspace(0, 4*pi, 101)
y = exp(-0.1*x)*cos(x)
plot(x, y)
xlabel('x'); ylabel('y')
show()
\end{python:nt}


Then Cython (with -h option so it is hidden in html/sphinx):

\begin{minted}[fontsize=\fontsize{9pt}{9pt},linenos=false,mathescape,baselinestretch=1.0,fontfamily=tt,xleftmargin=7mm]{cython}
cpdef f(double x):
    return x + 1
\end{minted}

Standard Python shell sessions:

\begin{minted}[fontsize=\fontsize{9pt}{9pt},linenos=false,mathescape,baselinestretch=1.0,fontfamily=tt,xleftmargin=7mm]{python}
>>> from numpy import linspace, sin
>>> # Some comment
>>> x = linspace(0, 2, 11)
>>> y = sin(x)
>>> y[0]
0
>>> import matplotlib.pyplot as plt
>>> plt.plot(x, y)
\end{minted}

Similar IPython sessions:

\begin{minted}[fontsize=\fontsize{9pt}{9pt},linenos=false,mathescape,baselinestretch=1.0,fontfamily=tt,xleftmargin=7mm]{ipy}
In [1]: from numpy import linspace, sin
In [2]: # Some comment
In [3]: x = linspace(0, 2, 11)
In [4]: y = sin(x)
In [5]: y[0]
Out[5]: 0
In [6]: import matplotlib.pyplot as plt
In [7]: plt.plot(x, y)
In [8]: a='multiple-\nline\noutput'
In [9]: a
Out[9]: 'multiple-\nline\noutput'
In [10]: print(a)
multiple-
line
output
\end{minted}

Here is the interactive session again, but with \texttt{pyshell-t}.

\begin{minted}[fontsize=\fontsize{9pt}{9pt},linenos=false,mathescape,baselinestretch=1.0,fontfamily=tt,xleftmargin=7mm]{python}
>>> from numpy import linspace, sin
>>> # Some comment
>>> x = linspace(0, 2, 11)
>>> y = sin(x)
>>> y[0]
0
>>> import matplotlib.pyplot as plt
>>> plt.plot(x, y)
\end{minted}

% This one tests a + sign before a code environment
C++:
\begin{minted}[fontsize=\fontsize{9pt}{9pt},linenos=false,mathescape,baselinestretch=1.0,fontfamily=tt,xleftmargin=7mm]{c++}
#include <iostream>

int main()
{
   std::cout << "Sample output" << std::endl;
   return 0
}
\end{minted}
% The next should get correctly typset in sphinx (cod is fcod)
% It also tests emoji before code
And a little bit of Fortran: \raisebox{-\height+\ht\strutbox}{\includegraphics[height=1.5em]{latex_figs/dizzy_face.png}}

\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95]
!bc cod
      subroutine midpt(x, length, a, b)
      real*8 a, b, x
      x = (a + b)/2
      length = b - a
      return
      end
!ec
\end{Verbatim}
which then is typeset as

\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95]
      subroutine midpt(x, length, a, b)
      real*8 a, b, x
      x = (a + b)/2
      length = b - a
      return
      end
\end{Verbatim}

HTML:

\begin{minted}[fontsize=\fontsize{9pt}{9pt},linenos=false,mathescape,baselinestretch=1.0,fontfamily=tt,xleftmargin=7mm]{html}
<table>
<tr><td>Column 1</td><td>Column 2</td></tr>
<tr><td>0.67526 </td><td>0.92871 </td></tr>
<!-- comment -->
</table>
\end{minted}

But inline HTML code is also important, like text that starts with
\texttt{<a href="} (which can destroy the following text if not properly
quoted).

Matlab with comments requires special typesetting:

\begin{minted}[fontsize=\fontsize{9pt}{9pt},linenos=false,mathescape,baselinestretch=1.0,fontfamily=tt,xleftmargin=7mm]{matlab}
% Comment on the beginning of the line can be escaped by %%
if a > b
  % Indented comment needs this trick
  c = a + b
end
\end{minted}

And here is a system call:

\begin{Verbatim}[frame=lines]
Terminal> mkdir test
Terminal> cd test
Terminal> myprog -f
output1
output2
\end{Verbatim}

Any valid pygments lexer/language name can appear to, e.g.,

\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95]
!bc restructuredtext
=======
Heading
=======

Some text.
!ec
\end{Verbatim}
results in

\begin{minted}[fontsize=\fontsize{9pt}{9pt},linenos=false,mathescape,baselinestretch=1.0,fontfamily=tt,xleftmargin=7mm]{restructuredtext}
=======
Heading
=======

Some text.
\end{minted}

% Here goes hidden code.
% Python can be treated by some formats, Fortran is always out.





Finally, \Verb?!bc do? supports highlighting of DocOnce source:

\begin{minted}[fontsize=\fontsize{9pt}{9pt},linenos=false,mathescape,baselinestretch=1.0,fontfamily=tt,xleftmargin=7mm]{doconce}
======= DocOnce test file =======

===== Computer code =====

Inline verbatim code, as in `import numpy as np`, is allowed, as well as
code blocks:

!bc pycod
from math import sin

def f(x):
    """Example on a function."""
    return sin(x) + 1

print(f(0))
!ec


===== Mathematics =====

Formulas can be inline, as in $\nabla\cdot\bm{u} = 0$, or typeset
as equations:

!bt
\begin{align*}
\nabla\cdot\bm{u} &= 0,\\ 
\bm{u} &= \nabla\phi .
\end{align*}
!et

=== Subsubsection heading ===

DocOnce files can have chapters, sections, subsections, and subsubsections.

__Paragraph heading.__ Paragraphs may have headings.
\end{minted}

It is time to test \texttt{verbatim inline font} especially with \texttt{a newline inside the text} and an exclamation mark at the end: \texttt{BEGIN}! For
spellcheck, test \texttt{a verbatim expression} in \texttt{another} in a \texttt{third}.
Also test exclamation mark as in \Verb?!bc? and \Verb?!ec? as well as \Verb?a != b?.
Also test backslashes and braces like \Verb!\begin!, \Verb!\begin{enumerate}!,
\Verb!\end{this}\end{that}!, and \Verb!{something \inside braces}!.

Here is some \textcolor{red}{red color} and an attempt to write \textcolor{green}{with
green color containing a linebreak\\
code.} Some formats will only display \\
this correctly when \texttt{html} \\
is the output format.
But here some more running text is added which is not part of
the previous blocks with line breaks.

\paragraph{Running OS commands.}
\begin{Verbatim}[frame=lines]
Terminal> python -c 'print("Testing\noutput\nfrom\nPython.")'
Testing
output
from
Python.
\end{Verbatim}


\paragraph{Footnotes.}
Here is a test of footnotes \footnote{Typesetting of the footnote depends on the format. Plain text does nothing, {\LaTeX} removes the definition and inserts the footnote as part of the {\LaTeX} text. reStructuredText and Sphinx employ a similar type of typesetting as Extended Markdown and DocOnce, and in HTML we keep the same syntax, just displayed properly in HTML.}, which are handy in text.
They are used in different flavors, now in

\begin{itemize}
 \item list items (note below that footnotes work after math, verbatim, and URLs - bin fact old and emphasize too!)

 \item even with math $\nabla^2u$\footnote{Math footnotes can be dangerous since it interferes with an exponent.}

 \item and code \texttt{h[i] += 1}\footnote{One--line footnote.}
   (\emph{must} have space between inline code and footnote!)

 \item and \href{{https://google.com}}{links}\footnote{\texttt{https://google.com}}\footnote{\href{{google.com}}{\nolinkurl{google.com}\footnote{\texttt{google.com}}} is perhaps the most famous web site today.}
\end{itemize}

\noindent
which gives flexibility in writing.
This is the third\footnote{Not much to add here, but the footnote is at the end with only one newline.} example.





Here is some more text before a new definition of a footnote that was
used above.


\begin{notice_mdfboxadmon}[Non--breaking space character.]
This paragraph aims to test \href{{https://en.wikipedia.org/wiki/Non--breaking_space}}{non--breaking space character}\footnote{\texttt{https://en.wikipedia.org/wiki/Non--breaking\_space}}, and a typical
example where this is needed is in physical units: 7.4~km is traveled
in~$7.4/5.5\approx 1.345$~s.  Also check that a~\href{{https://google.com}}{link}\footnote{\texttt{https://google.com}}~is
not broken across lines (drag the browser window to test this).
(On the other hand, the tilde is used in
computer code, e.g., as in \texttt{[~x for x in y]} or in \texttt{y=~x}, and should
of course remain a tilde in those contexts.)
\end{notice_mdfboxadmon} % title: Non--breaking space character.



\subsection{Subsection 2: Testing figures}
\label{subsec:ex}
\index{figures}\marginpar{\footnotesize figures}

Test of figures. In particular we refer to Figure~\vref{fig:impact} in which
there is a flow.


\begin{figure}[!ht]  % fig:impact
  \centerline{\includegraphics[width=0.9\linewidth]{../doc/src/manual/fig/wave1D.pdf}}
  \caption{
  Visualization \textbf{of} a \emph{wave}. \label{fig:impact}
  }
\end{figure}
%\clearpage % flush figures fig:impact


Figures without captions are allowed and will be inlined.



\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=0.9\linewidth]{../doc/src/manual/fig/wave1D.pdf}}

\vspace{6mm}



\index{movies}\marginpar{\footnotesize movies}


% Test multi--line caption in figure with sidecap=True

Here is figure~\vref{myfig} with a long (illegal) multi--line caption
containing inline verbatim text:


\begin{SCfigure}
  \centering
  \includegraphics[width=0.9\linewidth]{../doc/src/manual/fig/wave1D.png}
  \caption{
  A long caption spanning several lines and containing verbatim words like \protect \Verb!my\_file\_v1! and \protect \Verb!my\_file\_v2! as well as math with subscript as in $t_{i+1}$. \label{myfig}
  }
\end{SCfigure}
%\clearpage % flush figures myfig


% Must be a blank line after MOVIE or FIGURE to detect this problem

Test URL as figure name:



\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=0.8\linewidth]{downloaded_figures/f_plot.png}}

\vspace{6mm}




% Test wikimedia type of files that otherwise reside in subdirs


\paragraph{Remark.}
Movies are tested in separate file \texttt{movies.do.txt}.


% Somewhat challenging heading with latex math, \t, \n, ? and parenthesis

\subsection{The $\theta$ parameter (not $\nabla$?)}
\label{decay:sec:theta}

Functions do not always need to be advanced, here is one
involving $\theta$:
\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95]
def f(theta):
    return theta**2
\end{Verbatim}

\paragraph{More on $\theta$.}
Here is more text following headline with math.

Newcommands must also be tested in this \report:
$\half$, $\halfi$, $\x$, $\Ddt{u}$,
both inline and in block:

\begin{align}
\Ddt{u} &= 0\nonumber
\\ 
\half &= \halfi\\ 
\half\x &= \normalvec
\end{align}

Or with align with label and numbers:

\begin{align}
\Ddt{u} &= 0
\label{aligneq1}
\\ 
\half &= \halfi\\ 
\half\x &= \normalvec
\label{aligneq2}
\end{align}


% Must test more complicated align and matrix compositions
% where DocOnce inserts auto--numbered labels etc.

First one numbered (automatically):

\begin{align}
\begin{pmatrix}
G_2 + G_3 & -G_3 & -G_2 & 0 \\ 
-G_3 & G_3 + G_4 & 0 & -G_4 \\ 
-G_2 & 0 & G_1 + G_2 & 0 \\ 
0 & -G_4 & 0 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
 v_1 \\ 
 v_2 \\ 
 v_3 \\ 
 v_4
\end{pmatrix}
+ \cdots \\ 
\begin{pmatrix}
 C_5 + C_6 & -C_6 & 0 & 0 \\ 
 -C_6 & C_6 & 0 & 0 \\ 
 0 & 0 & 0 & 0 \\ 
 0 & 0 & 0 & 0
\end{pmatrix}
  &= \frac{d}{dt}\begin{pmatrix}
 v_1 \\ 
 v_2 \\ 
 v_3 \\ 
 v_4
\end{pmatrix} +
\begin{pmatrix}
 0 \\ 
 0 \\ 
 0 \\ 
 -i_0
\end{pmatrix}
\nonumber
\end{align}

Second numbered (automatically):

\begin{align}
\begin{pmatrix}
G_1 + G_2\\ 
-G_3 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
 v_1 \\ 
 v_2
\end{pmatrix}
+ \cdots\nonumber
\\ 
\left(\begin{array}{ll}
y & 2\\ 
2 & 1
\end{array}\right)
\left(\begin{array}{ll}
0 \\ x
\end{array}\right)
&= \begin{pmatrix}
A \\ B
\end{pmatrix}
\end{align}

Both numbered, with label by the user:

\begin{align}
\begin{pmatrix}
G_1 + G_2\\ 
-G_3 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
 v_1 \\ 
 v_2
\end{pmatrix}
+ \cdots \label{mymatrix:eq1}
\\ 
\label{mymatrix:eq2}
\left(\begin{array}{ll}
y & 2\\ 
2 & 1
\end{array}\right)
\left(\begin{array}{ll}
0 \\ x
\end{array}\right)
&= \begin{pmatrix}
A \\ B
\end{pmatrix}
\end{align}
Now we refer to (\ref{mymatrix:eq1})-(\ref{mymatrix:eq2}).

\subsection{Custom Environments}

Here is an attempt to create a theorem environment via Mako
(for counting theorems) and comment lines to help replacing lines in
the \texttt{.tex} by proper begin--end {\LaTeX} environments for theorems.
Should look nice in most formats!



\begin{theorem}
\label{theorem:fundamental1}



Let $a=1$ and $b=2$. Then $c=3$.
\end{theorem}

% begin proof
\paragraph{Proof.}
Since $c=a+b$, the result follows from straightforward addition.
$\Diamond$
% end proof

As we see, the proof of Theorem 5 is a modest
achievement.


\subsection{Tables}
\label{subsec:table}

\index{test index with verbatim text@test index with {\rm\texttt{verbatim text}} which is possible}\marginpar{\footnotesize test index with {\rm\texttt{verbatim text}} which is possible}
\index{test two@test {\rm\texttt{two}} (separate) {\rm\texttt{verbatim expressions}} which is also possible}\marginpar{\footnotesize test {\rm\texttt{two}} (separate) {\rm\texttt{verbatim expressions}} which is also possible}
\index{index with!subindex}\marginpar{\footnotesize index with!subindex}
\index{\textbf{boldface word} in index}\marginpar{\footnotesize \textbf{boldface word} in index}
\index{index with \textbf{boldface word}}\marginpar{\footnotesize index with \textbf{boldface word}}
\index{index with!\textbf{boldface word} in subentry}\marginpar{\footnotesize index with!\textbf{boldface word} in subentry}
\index{double \textbf{boldface word}! \textbf{boldface word} in subentry too}\marginpar{\footnotesize double \textbf{boldface word}! \textbf{boldface word} in subentry too}

% index with comma could fool sphinx
\index{index, with comma, and one more}\marginpar{\footnotesize index, with comma, and one more}

Let us take this table from the manual:

\begin{table}
\caption{
Testing table environment in {\LaTeX}, enabled by testing on the "latex" format
with the preprocessor.
\label{mytab}
}



\begin{quote}
\begin{tabular}{lrr}
\hline
\multicolumn{1}{c}{ time } & \multicolumn{1}{c}{ velocity } & \multicolumn{1}{c}{ acceleration } \\
\hline
0.0  & 1.4186   & -5.01        \\
2.0  & 1.376512 & 11.919       \\
4.0  & 1.1E+1   & 14.717624    \\
\hline
\end{tabular}
\end{quote}

\noindent
\end{table}

The DocOnce source code reads
\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95]

  |--------------------------------|
  |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}

Here is yet another table to test that we can handle more than
one table:


\begin{quote}
\begin{tabular}{lll}
\hline
\multicolumn{1}{l}{ time } & \multicolumn{1}{l}{ velocity } & \multicolumn{1}{l}{ acceleration } \\
\hline
0.0  & 1.4186   & -5.01        \\
1.0  & 1.376512 & 11.919       \\
3.0  & 1.1E+1   & 14.717624    \\
\hline
\end{tabular}
\end{quote}

\noindent
And one with math headings (that are expanded and must be treated
accordingly), verbatim heading and entry, and no space around the pipe
symbol:


\begin{quote}
\begin{tabular}{lrrr}
\hline
\multicolumn{1}{c}{ $i$ } & \multicolumn{1}{c}{ $h_i$ } & \multicolumn{1}{c}{ $\bar T_i$ } & \multicolumn{1}{c}{ \Verb!L\_i! } \\
\hline
0   & 0      & 288        & -0.0065    \\
1   & 11,000 & 216        & 0.0        \\
2   & 20,000 & 216        & 0.001      \\
3   & 32,000 & 228        & 0.0028     \\
4   & 47,000 & 270        & 0.0        \\
5   & 51,000 & 270        & -0.0028    \\
6   & 71,000 & 214        & \texttt{NaN} \\
\hline
\end{tabular}
\end{quote}

\noindent
And add one with verbatim headings (with underscores),
and rows starting with \texttt{|-} because of a negative number,
and \texttt{|} right before and after verbatim word (with no space):


\begin{quote}
\begin{tabular}{rrrr}
\hline
\multicolumn{1}{c}{ exact } & \multicolumn{1}{c}{ \Verb!v\_1! } & \multicolumn{1}{c}{ $a_i$ + \Verb!v\_2! } & \multicolumn{1}{c}{ \Verb!verb\_3\_! } \\
\hline
9     & 9.62       & 5.57               & 8.98           \\
-20   & -23.39     & -7.65              & -19.93         \\
10    & 17.74      & -4.50              & 9.96           \\
0     & -9.19      & 4.13               & -0.26          \\
\hline
\end{tabular}
\end{quote}

\noindent
Pipe symbols in verbatim and math text in tables used to pose difficulties,
but not
anymore:


\begin{quote}
\begin{tabular}{lr}
\hline
\multicolumn{1}{c}{ $S$ } & \multicolumn{1}{c}{ command } \\
\hline
$ ||a_0|| $ & \texttt{norm|length} \\
$x\cap y$   & \texttt{x|y}         \\
\hline
\end{tabular}
\end{quote}

\noindent

Here is a table with X alignment:


\begin{quote}
\begin{tabularx}{\linewidth}{cX}
\hline
\multicolumn{1}{c}{ Type } & \multicolumn{1}{c}{ Description } \\
\hline
X     & Alignment character that is used for specifying a potentially very long text in a column in a table. It makes use of the \texttt{tabularx} package in {\LaTeX}, otherwise (for other formats) it means \texttt{l} (centered alignment). \\
l,r,c & standard alignment characters                                                                                                                                                                                                       \\
\hline
\end{tabularx}
\end{quote}

\noindent
Finally, a table with math
and URLs.

% Mako code to expand URLs in the table
% (These types of tables did not work before Jan 2014)



\begin{quote}
\begin{tabular}{ccc}
\hline
 \\
\hline
$\mathcal{L}=0$         & \includegraphics[width=2cm]{../doc/src/manual/mov/wave_frames/frame_0080.png} & \includegraphics[width=2cm]{../doc/src/manual/mov/wave_frames/frame_0085.png} \\
$a=b$                   & \includegraphics[width=2cm]{../doc/src/manual/mov/wave_frames/frame_0090.png} & \includegraphics[width=2cm]{../doc/src/manual/mov/wave_frames/frame_0095.png} \\
$\nabla\cdot\bm{u} =0 $ & \includegraphics[width=2cm]{../doc/src/manual/mov/wave_frames/frame_0100.png} & \includegraphics[width=2cm]{../doc/src/manual/mov/wave_frames/frame_0105.png} \\
\hline
\end{tabular}
\end{quote}

\noindent

\subsection{A test of verbatim words in heading with subscript $a_i$: \protect\Verb!my\_file\_v1! and \protect\Verb!my\_file\_v2! }

\paragraph{Paragraph with verbatim and math: \protect\Verb!my\_file\_v1.py! and \protect\Verb!my\_file\_v2.py! define some math $a_{i-1}$.}
Here is more \Verb!__verbatim__! code and
some plain text on a new line.

% Test various types of headlines
\subsection{\textbf{Just bold}}

Some text.

\subsection{\emph{Just emphasize}}

Some text.

\subsection{\texttt{Just verbatim} }

Some text.

\subsection{\textbf{Bold} beginning}

Some text.

\subsection{\emph{Emphasize} beginning}

Some text.

\subsection{\texttt{Verbatim} beginning}

Some text.

\subsection{Maybe \textbf{bold end}}

Some text.

\subsection{Maybe \emph{emphasize end}}

Some text.

\subsection{Maybe \texttt{verbatim end} }

Some text.

\subsection{The middle has \textbf{bold} word}

Some text.

\subsection{The middle has \emph{emphasize} word}

Some text.

\subsection{The middle has \texttt{verbatim} word}

Some text.


\paragraph{\emph{Just emphasize}.}
Some text.


\paragraph{\texttt{Just verbatim}.}
Some text.


\paragraph{\emph{Emphasize} beginning.}
Some text.


\paragraph{\texttt{Verbatim beginning}.}
Some text.


\paragraph{Maybe \emph{emphasize end}.}
Some text.


\paragraph{Maybe \texttt{verbatim end}.}
Some text.


\paragraph{The middle has \emph{emphasize} word.}
Some text.


\paragraph{The middle has \texttt{verbatim} word.}
Some text.


\paragraph{Ampersand.}
We can test Hennes {\&} Mauritz, often abbreviated H{\&}M, but written
as \Verb!Hennes & Mauritz! and \Verb!H & M!.
A sole \Verb!&! must also work.
% Note: substitutions must not occur inside verbatim, just in ordinary text.

\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95]
# Just to check that ampersand works in code blocks:
c = a & b
\end{Verbatim}

\paragraph{Quotes.}
Let us also add a test of quotes such as ``double quotes, with numbers
like 3.14 and newline/comma and hyphen (as in double--quote)''; written
in the standard LaTeX--style that gives correct {\LaTeX} formatting and
ordinary double quotes for all non--LaTeX formats.  Here is another
sentence that ``caused'' a bug in the past because double backtick
quotes could imply verbatim text up to a verbatim word starting with
period, like \texttt{.txt}.

More quotes to be tested for spellcheck:
(``with parenthesis''), ``with newline''
and ``with comma'', ``hyphen''-wise, and ``period''.


\subsection{Bibliography test}

Here is an example: \cite{Langtangen_Pedersen_2002} discussed propagation of
large destructive water waves, \cite{Langtangen_et_al_2002} gave
an overview of numerical methods for solving the Navier---Stokes equations,
while the use of Backward Kolmogorov equations for analyzing
random vibrations was investigated in \cite{Langtangen_1994a}.
The book chapter \cite{Mardal_et_al_2003a} contains information on
C++ software tools for programming multigrid methods. A real retro
reference is \cite{Langtangen_1988d} about a big FORTRAN package.
Multiple references are also possible, e.g., see
\cite{Langtangen_Pedersen_2002,Mardal_et_al_2003a}.

We need to cite more than 10 papers to reproduce an old formatting
problem with blanks in the keys in reST format:
\cite{Langtangen_1992c,Langtangen_1994a,Mortensen_et_al_2011,Langtangen_Pedersen_2002}
and
\cite{Langtangen_et_al_2002,Glimsdal_et_al_20006,Rahman_et_al_2006b,Haga_et_al_2011a,Langtangen_2003a,Langtangen_2008a,Langtangen:95}
and all the work of
\cite{Langtangen_2012,Mardal_et_al_2003a,Jeberg_et_al_2004} as well as
old work \cite{Langtangen_1988d} and \cite{Langtangen_1989e}, and the
talk \cite{Langtangen_talk_2007a}.
Langtangen also had two thesis \cite{Langtangen:85,Langtangen_1989e}
back in the days.
More retro citations are
the old ME-IN323 book \cite{Langtangen:91} and the
\cite{Langtangen:94b} OONSKI '94 paper.




% --- begin exercise ---
\begin{doconceexercise}
\refstepcounter{doconceexercisecounter}

\exercisesection{Example \thedoconceexercisecounter: Examples can be typeset as exercises}
                \addcontentsline{loe}{doconceexercise}{Example \thedoconceexercisecounter: Examples can be typeset as exercises}
                
\label{Example}

Examples can start with a subsection heading starting with \texttt{Example:}
and then, with the command--line option \Verb!--examples_as_exercises! be
typeset as exercises. This is useful if one has solution
environments as part of the example.


\subex{a)}
State some problem.

\paragraph{Solution.}
The answer to this subproblem can be written here.

\subex{b)}
State some other problem.

\paragraph{Hint 1.}
A hint can be given.

\paragraph{Hint 2.}
Maybe even another hint?

\paragraph{Solution.}
The answer to this other subproblem goes here,
maybe over multiple doconce input lines.

\end{doconceexercise}
% --- end exercise ---


\subsection{User--defined environments}



Example~\vref{ex:test:1p1} demonstrates how to write a test function.
That is, a special test function for a function \texttt{add} appears in
Example~\vref{ex:test:1p1}.


\begin{example}
\label{ex:test:1p1}

\noindent\emph{A test function}.

Suppose we want to write a test function for checking the
implementation of a Python function for addition.

\begin{minted}[fontsize=\fontsize{9pt}{9pt},linenos=false,mathescape,baselinestretch=1.0,fontfamily=tt,xleftmargin=7mm]{python}
def add(a, b):
    return a + b

def test_add():
    a = 1; b = 1
    expected = a + b
    computed = add(a, b)
    assert expected == computed
\end{minted}
\end{example}



\begin{example}
\label{ex:math:1p1}

\noindent\emph{Addition}.

We have

\[ 1 + 1 = 2 \]
or in tabular form:


\begin{quote}
\begin{tabular}{cc}
\hline
\multicolumn{1}{c}{ Problem } & \multicolumn{1}{c}{ Result } \\
\hline
$1+1$   & $2$    \\
\hline
\end{tabular}
\end{quote}

\noindent
\end{example}



\begin{tcolorbox}[%skin=widget,
boxrule=1mm,
coltitle=black,
colframe=blue!45!white,
colback=blue!15!white,
width=(.9\linewidth),before=\hfill,after=\hfill,
adjusted title={Highlight box!}]
This environment is used to highlight something:

\[ E = mc^2 \]
\end{tcolorbox}



\subsection{URLs}
\label{subsubsec:ex}

Testing of URLs: hpl's home page \href{{https://folk.uio.no/hpl}}{hpl}\footnote{\texttt{https://folk.uio.no/hpl}}, or
the entire URL if desired, \href{{https://folk.uio.no/hpl}}{\nolinkurl{https://folk.uio.no/hpl}}.  Here is a
plain file link \href{{testdoc.do.txt}}{\nolinkurl{testdoc.do.txt}\footnote{\texttt{testdoc.do.txt}}}, or \href{{testdoc.do.txt}}{\nolinkurl{testdoc.do.txt}\footnote{\texttt{testdoc.do.txt}}}, or
\href{{testdoc.do.txt}}{\nolinkurl{testdoc.do.txt}\footnote{\texttt{testdoc.do.txt}}} or \href{{testdoc.do.txt}}{\nolinkurl{testdoc.do.txt}\footnote{\texttt{testdoc.do.txt}}} or \href{{testdoc.do.txt}}{a link with
newline}\footnote{\texttt{testdoc.do.txt}}. Can test spaces with the link with word
too: \href{{https://folk.uio.no/hpl}}{hpl}\footnote{\texttt{https://folk.uio.no/hpl}} or \href{{https://folk.uio.no/hpl}}{hpl}\footnote{\texttt{https://folk.uio.no/hpl}}. Also \texttt{file:///} works: \href{{file:///home/hpl/vc/doconce/doc/demos/manual/manual.html}}{link to a
file}\footnote{\texttt{file:///home/hpl/vc/doconce/doc/demos/manual/manual.html}} is
fine to have. Moreover, ``loose'' URLs work, i.e., no quotes, just
the plain URL as in \href{{https://folk.uio.no/hpl}}{\nolinkurl{https://folk.uio.no/hpl}}, if followed by space, comma,
colon, semi--colon, question mark, exclamation mark, but not a period
(which gets confused with the periods inside the URL).

Mail addresses can also be used: \href{{mailto:hpl@simula.no}}{\nolinkurl{hpl@simula.no}\footnote{\texttt{mailto:hpl@simula.no}}}, or just a \href{{mailto:hpl@simula.no}}{mail link}\footnote{\texttt{mailto:hpl@simula.no}}, or a raw \href{{mailto:hpl@simula.no}}{\nolinkurl{mailto:hpl@simula.no}\footnote{\texttt{mailto:hpl@simula.no}}}.

Here are some tough tests of URLs, especially for the \texttt{latex} format:
\href{{https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas}}{Newton-Cotes}\footnote{\texttt{https://en.wikipedia.org/wiki/Newton\%E2\%80\%93Cotes\_formulas}} formulas
and a \href{{https://www.springer.com/mathematics/computational+science+%26+engineering/book/978-3-642-23098-1}}{good book}\footnote{\texttt{https://www.springer.com/mathematics/computational+science+\%26+engineering/book/978-3-642-23098-1}}. Need to test
Newton-Cotes with percentage in URL too:
\href{{https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas}}{\nolinkurl{https://en.wikipedia.org/wiki/Newton\%E2\%80\%93Cotes_formulas}}
and \href{{https://en.wikipedia.org/wiki/Newton-Cotes#Open_Newton.E2.80.93Cotes_formulae}}{\nolinkurl{https://en.wikipedia.org/wiki/Newton-Cotes\#Open_Newton.E2.80.93Cotes_formulae}} which has a shebang.

For the \texttt{--device=paper} option it is important to test that URLs with
monospace font link text get a footnote
(unless the \Verb!--latex_no_program_footnotelink!
is used), as in this reference to
\href{{https://github.com/hplgit/INF5620/tree/gh-pages/src/decay/experiments/decay_mod.py}}{\nolinkurl{decay_mod}}, \href{{https://tinyurl.com/pwyasaa/formulas.ball1.py}}{\nolinkurl{ball1.py}},
and \href{{https://tinyurl.com/pwyasaa/formulas.ball2.py}}{\nolinkurl{ball2.py}}.


% Comments should be inserted outside paragraphs (because in the rst
% format extra blanks make a paragraph break).

% Note that when there is no https: or file:, it can be a file link
% if the link name is URL, url, "URL", or "url". Such files should,
% if rst output is desired, but placed in a \Verb!_static*! folder.

More tough tests: repeated URLs whose footnotes when using the
\texttt{--device=paper} option must be correct. We have
\href{{https://google.com}}{google}\footnote{\texttt{https://google.com}}, \href{{https://google.com}}{google}\footnote{\texttt{https://google.com}}, and
\href{{https://google.com}}{google}\footnote{\texttt{https://google.com}}, which should result in exactly three
footnotes.



\subsection{Test of Some {\LaTeX} Fixes}

Let's check abbr.~of some common kind, e.g.~the well--known i.e.
expression as an example, and 1 vs.~2 which is also often used.
Dr.~Tang and Prof.~Monsen, or maybe also prof.~Ting,
will go to the Dept.~of Science to test how Mr.~Hansen is doing together
with Ms.~Larsen. A reference like Sec.~\vref{subsubsec:ex} or
Ch.~\vref{subsubsec:ex}, or even App.~\vref{subsubsec:ex}, must also be
handled. Likewise, this is test no.~$i$ of DocOnce features.
Also, look at Fig.~4 to see how the data compares with Tab.~\vref{mytab}.
Percentage must be fixed: 7\%,  87.65\% and
50\% at the beginning of the line.


% !split and check if these extra words are included properly in the comment

\section{{\LaTeX} Mathematics}

Here is an equation without label using backslash--bracket environment:
\[ a = b + c \]

or with number and label, as in (\ref{my:eq1}), using the equation environment:

\begin{equation}
{\partial u\over\partial t} = \nabla^2 u \label{my:eq1}
\end{equation}

We can refer to this equation by (\ref{my:eq1}).

Here is a system without equation numbers, using the align--asterisk environment:

\begin{align*}
\pmb{a} &= \pmb{q}\times\pmb{n} \\ 
b &= \nabla^2 u + \nabla^4 v
\end{align*}


And here is a system of equations with labels in an align environment:

\begin{align}
a &= q + 4 + 5+ 6 \label{eq1} \\ 
b &= \nabla^2 u + \nabla^4 x \label{eq2}
\end{align}

We can refer to (\ref{eq1})-(\ref{eq2}). They are a bit simpler than
the Navier---Stokes equations. And test {\LaTeX} hyphen in \texttt{CG-2}.
Also test $a_{i-j}$ as well as $kx-wt$.

Testing \texttt{alignat} environment:

\begin{alignat}{2}
a &= q + 4 + 5+ 6\qquad & \mbox{for } q\geq 0 \label{eq1a} \\ 
b &= \nabla^2 u + \nabla^4 x & x\in\Omega \label{eq2a}
\end{alignat}

Many of the next environments will fail in non--latex formats.
Testing multiline:

\begin{multline}
a = b = q + \\ 
  f + \nabla\cdot\nabla u
\label{multiline:eq1}
\end{multline}

Testing split:

\begin{equation}
\label{split:envir:eq}
\begin{split}
a = b = q &+ \\ 
  & f + \nabla\cdot\nabla u
\end{split}
\end{equation}
We can refer to the last equation by (\ref{split:envir:eq}).

Testing gather:
\begin{gather}
a = b \\ 
c = d + 7 + 9
\end{gather}

Let us refer to (\ref{eq1})-(\ref{eq2}) again, and to the
alignat variant (\ref{eq1a})-(\ref{eq2a}), and to (\ref{my:eq1}).

Testing eqnarray:
\begin{eqnarray}
{\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{eqnarray}

More mathematical typesetting is demonstrated in the coming exercises.

Below, we have Problem~\vref{demo:ex:1} and Project~\vref{demo:ex:2},
as well as Projects~\vref{proj:circle1} and~\vref{exer:you}, and in
between there we have Exercise~\vref{exer:some:formula}.


\section{Exercises}



% --- begin exercise ---
\begin{doconceexercise}
\refstepcounter{doconceexercisecounter}

\exercisesection{Problem \thedoconceexercisecounter: Flip a Coin}
                \addcontentsline{loe}{doconceexercise}{Problem \thedoconceexercisecounter: Flip a Coin}
                
\label{demo:ex:1}
% keywords = random numbers; Monte Carlo simulation; ipynb

% Torture tests


\subex{a)}
Make a program that simulates flipping a coin $N$ times.
Print out ``tail'' or ``head'' for each flip and
let the program count the number of heads.

% --- begin hint in exercise ---

\paragraph{Hint 1.}
Use \texttt{r = random.random()} and define head as \texttt{r <= 0.5}.

% --- end hint in exercise ---

% --- begin hint in exercise ---

\paragraph{Hint 2.}
Draw an integer among $\{1,2\}$ with
\texttt{r = random.randint(1,2)} and define head when \texttt{r} is 1.

% --- end hint in exercise ---


% --- begin answer of exercise ---
\paragraph{Answer.}
If the \texttt{random.random()} function returns a number $<1/2$, let it be
head, otherwise tail. Repeat this $N$ number of times.
% --- end answer of exercise ---


% --- begin solution of exercise ---
\paragraph{Solution.}
\begin{minted}[fontsize=\fontsize{9pt}{9pt},linenos=false,mathescape,baselinestretch=1.0,fontfamily=tt,xleftmargin=7mm]{python}
import sys, random
N = int(sys.argv[1])
heads = 0
for i in range(N):
    r = random.random()
    if r <= 0.5:
        heads += 1
print('Flipping a coin %d times gave %d heads' % (N, heads))
\end{minted}
% --- end solution of exercise ---

\subex{b)}
Vectorize the code in a) using boolean indexing.

Vectorized code can be written in many ways.
Sometimes the code is less intuitive, sometimes not.
At least there is not much to find in Section~\vref{sec1}.

\subex{c)}
Vectorize the code in a) using \texttt{numpy.sum}.


% --- begin answer of exercise ---
\paragraph{Answer.}
\texttt{np.sum(np.where(r <= 0.5, 1, 0))} or \texttt{np.sum(r <= 0.5)}.
% --- end answer of exercise ---

In this latter subexercise, we have an
example where the code is easy to read.


\paragraph{My remarks.}
Remarks with such a subsubsection is treated as more text
after the last subexercise. Test a list too:

\begin{enumerate}
\item Mark 1.

\item Mark 2.
\end{enumerate}

\noindent
\noindent Filenames: \Verb!flip_coin.py!, \Verb!flip_coin.pdf!.

% Closing remarks for this Problem

\paragraph{Remarks.}
These are the exercise remarks, appearing at the very end.

% solution files: mysol.txt, mysol_flip_coin.py, yet_another.file

\end{doconceexercise}
% --- end exercise ---


\subsection{Not an exercise}

Should be possible to stick a normal section in the middle of many
exercises.



% --- begin exercise ---
\begin{doconceexercise}
\refstepcounter{doconceexercisecounter}

\exercisesection{Exercise \thedoconceexercisecounter: Test of plain text exercise}
                \addcontentsline{loe}{doconceexercise}{Exercise \thedoconceexercisecounter: Test of plain text exercise}
                
\label{my:exer1}

Very short exercise. What is the capital
of Norway?
\noindent Filename: \texttt{myexer1}.

\end{doconceexercise}
% --- end exercise ---




% --- begin exercise ---
\begin{doconceexercise}
\refstepcounter{doconceexercisecounter}

\exercisesection{Project \thedoconceexercisecounter: Compute a Probability}
                \addcontentsline{loe}{doconceexercise}{Project \thedoconceexercisecounter: Compute a Probability}
                
\label{demo:ex:2}

% Minimalistic exercise


What is the probability of getting a number between 0.5 and 0.6 when
drawing uniformly distributed random numbers from the interval $[0,1)$?


At the end we have a list because that caused problems in {\LaTeX}
in previous DocOnce versions:

\begin{enumerate}
\item item1

\item item2
\end{enumerate}

\noindent
% --- begin hint in exercise ---

\paragraph{Hint.}
To answer this question empirically, let a program
draw $N$ such random numbers using Python's standard \texttt{random} module,
count how many of them, $M$, that fall in the interval $(0.5,0.6)$, and
compute the probability as $M/N$.

% --- end hint in exercise ---

\end{doconceexercise}
% --- end exercise ---




% --- begin exercise ---
\begin{doconceexercise}
\refstepcounter{doconceexercisecounter}

\exercisesection{Project \thedoconceexercisecounter: Explore Distributions of Random Circles}
                \addcontentsline{loe}{doconceexercise}{Project \thedoconceexercisecounter: Explore Distributions of Random Circles}
                
\label{proj:circle1}
% keywords = ipynb

The formula for a circle is given by

\begin{align}
x &= x_0 + R\cos 2\pi t,
\label{circle:x}\\ 
y &= y_0 + R\sin 2\pi t,
\label{circle:y}
\end{align}
where $R$ is the radius of the circle, $(x_0,y_0)$ is the
center point, and $t$ is a parameter in the unit interval $[0,1]$.
For any $t$, $(x,y)$ computed from (\ref{circle:x})-(\ref{circle:y})
is a point on the circle.
The formula can be used to generate \texttt{n} points on a circle:

\begin{python:nt}
import numpy as np

def circle(R, x0, y0, n=501):
    t = np.linspace(0, 1, n)
    x = x0 + R*np.cos(2*np.pi*t)
    y = y0 + R*np.sin(2*np.pi*t)
    return x, y

x, y = circle(2.0, 0, 0)
\end{python:nt}

% Often in an exercise we have some comments about the solution
% which we normally want to keep where they are.

The goal of this project is to draw $N$ circles with random
center and radius. Plot each circle using the \texttt{circle} function
above.


\subex{a)}
Let $R$ be normally distributed and $(x_0,y_0)$ uniformly distributed.

% --- begin hint in exercise ---

\paragraph{Hint.}
Use the \texttt{numpy.random} module to draw the
$x_0$, $y_0$, and $R$ quantities.

% --- end hint in exercise ---


% --- begin answer of exercise ---
\paragraph{Answer.}
Here goes the short answer to part a).
% --- end answer of exercise ---


% --- begin solution of exercise ---
\paragraph{Solution.}
Here goes a full solution to part a).
% --- end solution of exercise ---

\subex{b)}
Let $R$ be uniformly distributed and $(x_0,y_0)$ normally distributed.
\noindent Filename: \texttt{norm}.

\subex{c)}
Let $R$ and $(x_0,y_0)$ be normally distributed.


\noindent Filename: \texttt{circles}.

% Closing remarks for this Project

\paragraph{Remarks.}
At the very end of the exercise it may be appropriate to summarize
and give some perspectives.


\end{doconceexercise}
% --- end exercise ---




% --- begin exercise ---
\begin{doconceexercise}
\refstepcounter{doconceexercisecounter}

\exercisesection{Exercise \thedoconceexercisecounter: Determine some Distance}
                \addcontentsline{loe}{doconceexercise}{Exercise \thedoconceexercisecounter: Determine some Distance}
                
\label{exer:dist}

Intro to this exercise. Questions are in subexercises below.


% --- begin solution of exercise ---
\paragraph{Solution.}
Here goes a full solution of the whole exercise.
With some math $a=b$ in this solution:
\[ \hbox{math in solution: } a = b \]
And code \texttt{a=b} in this solution:
\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95]
a = b  # code in solution
\end{Verbatim}
End of solution is here.

% --- end solution of exercise ---


\subex{a)}
Subexercises are numbered a), b), etc.

% --- begin hint in exercise ---

\paragraph{Hint 1.}
First hint to subexercise a).
With math $a=b$ in hint:

\[ a=b. \]
And with code (in plain verbatim) returning $x+1$ in hint:

\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95]
def func(x):
    return x + 1  # with code in hint
\end{Verbatim}

% --- end hint in exercise ---

% --- begin hint in exercise ---

\paragraph{Hint 2.}
Second hint to subexercise a).

Test list in hint:

\begin{enumerate}
\item item1

\item item2
\end{enumerate}

\noindent
% --- end hint in exercise ---
\noindent Filename: \Verb!subexer_a.pdf!.


% --- begin answer of exercise ---
\paragraph{Answer.}
Short answer to subexercise a).
With math in answer: $a=b$.
% --- end answer of exercise ---

\subex{b)}
Here goes the text for subexercise b).


Some math $\cos^2 x + \sin^2 x = 1$ written one a single line:

\[ \cos^2 x + \sin^2 x = 1 \thinspace .\]

% --- begin hint in exercise ---

\paragraph{Hint.}
A hint for this subexercise.

% --- end hint in exercise ---
\noindent Filename: \Verb!subexer_b.pdf!.


% --- begin solution of exercise ---
\paragraph{Solution.}
Here goes the solution of this subexercise.
% --- end solution of exercise ---



% No meaning in this weired test example:
The text here belongs to the main (intro) part of the exercise. Need
closing remarks to have text after subexercises.

Test list in exercise:

\begin{enumerate}
\item item1

\item item2
% Closing remarks for this Exercise
\end{enumerate}

\noindent
\paragraph{Remarks.}
Some final closing remarks, e.g., summarizing the main findings
and their implications in other problems can be made. These
remarks will appear at the end of the typeset exercise.


\end{doconceexercise}
% --- end exercise ---




% --- begin exercise ---
\begin{doconceexercise}

\exercisesection{Some exercise without the "Exercise:" prefix}
\addcontentsline{loe}{doconceexercise}{Some exercise without the "Exercise:" prefix}


% Another minimalistic exercise

Just some text. And some math saying that $e^0=1$ on a single line,
to test that math block insertion is correct:

\[ \exp{(0)} = 1 \]

And a test that the code \texttt{lambda x: x+2} is correctly placed here:

\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95]
lambda x: x+2
\end{Verbatim}


% Have some comments at the end of the exercise to see that
% the Filename: ... is written correctly.
\end{doconceexercise}
% --- end exercise ---




% --- begin exercise ---
\begin{doconceexercise}
\refstepcounter{doconceexercisecounter}

\exercisesection{Exercise \thedoconceexercisecounter: Solution of differential equation}
                \addcontentsline{loe}{doconceexercise}{Exercise \thedoconceexercisecounter: Solution of differential equation}
                
\label{sec:this:exer:de}


\begin{doconcequiz}
\refstepcounter{doconcequizcounter}
\label{quiz:diff:eq1}


\noindent\textbf{\large SOlution of differential equation}

\noindent
Given

\[ \frac{dy}{dx} = -y(x),\quad y(0)=1 \]
What is the solution of this equation?

\vspace{2mm}

\textbf{A}. 
$y=e^{-y}$

\textbf{B}. 
$y=e^{y}$

\textbf{C}. 
\begin{minted}[fontsize=\fontsize{9pt}{9pt},linenos=false,mathescape,baselinestretch=1.0,fontfamily=tt,xleftmargin=7mm]{python}
from math import exp
def f(x):
    return exp(x)
\end{minted}

\textbf{D}. 
The solution cannot be found because there is a derivative in the equation.

\textbf{E}. 
The equation is meaningless: an equation must be an equation
for $x$ or $y$, not a function $y(x)$.


% --- begin answer of exercise ---
\paragraph{Answer:} A.
% --- end answer of exercise ---

% --- begin solution of exercise ---
\noindent {\bf Solution:}\\


\textbf{A}: Right. 

\textbf{B}: Wrong. Almost, but the sign is wrong (note the minus!).

\textbf{C}: Wrong. Ooops, forgot a minus: \texttt{exp(-x)}, otherwise this Python code
must be considered as a good answer. It is more natural,
though, to write the solution to the problem
in mathematical notation:

\[ y(x) = e^{-y}.\]

\textbf{D}: Wrong. Equations with derivatives can be solved;
they are termed \emph{differential
equations}.

\textbf{E}: Wrong. Equations where the unknown is a function, as $y(x)$
here, are called \emph{differential equations}, and are solved by
special techniques.


% --- end solution of exercise ---


\vspace{3mm}

\end{doconcequiz}



\end{doconceexercise}
% --- end exercise ---




% --- begin exercise ---
\begin{doconceexercise}
\refstepcounter{doconceexercisecounter}

\exercisesection{Example \thedoconceexercisecounter: Just an example}
                \addcontentsline{loe}{doconceexercise}{Example \thedoconceexercisecounter: Just an example}
                

% This example needs the --examples_as_exercises option, otherwise
% it is just typeset as it is written.


\subex{a)}
What is the capital of Norway?

\paragraph{Answer.}
Oslo.

\end{doconceexercise}
% --- end exercise ---


\section{Here goes another section}

With some text, before we continue with exercises.

\section{More Exercises}



% --- begin exercise ---
\begin{doconceexercise}
\refstepcounter{doconceexercisecounter}

\exercisesection{Exercise \thedoconceexercisecounter: Make references to projects and problems}
                \addcontentsline{loe}{doconceexercise}{Exercise \thedoconceexercisecounter: Make references to projects and problems}
                
\label{exer:some:formula}

% Test comments not at the end only
Pick a statement from Project~\vref{proj:circle1} or Problem~\vref{demo:ex:1}
and verify it.

Test list at the end of an exercise without other elements (like subexercise,
hint, etc.):

\begin{enumerate}
\item item1

\item item2
\end{enumerate}

\noindent
\noindent Filename: \Verb!verify_formula.py!.

\end{doconceexercise}
% --- end exercise ---




% --- begin exercise ---
\begin{doconceexercise}
\refstepcounter{doconceexercisecounter}

\exercisesection{Project \thedoconceexercisecounter: References to Project~\vref{demo:ex:2} in a heading works for pdflatex}
                \addcontentsline{loe}{doconceexercise}{Project \thedoconceexercisecounter: References to Project~\vref{demo:ex:2} in a heading works for pdflatex}
                
\label{exer:you}

Refer to the previous exercise as Exercise~\vref{exer:some:formula},
the two before that as Projects~\vref{demo:ex:2} and~\vref{proj:circle1},
and this one as Project~\vref{exer:you}.
\noindent Filename: \Verb!selc_composed.pdf!.

\end{doconceexercise}
% --- end exercise ---




\bibliographystyle{plain}
\bibliography{papers}





\appendix

\section{Just for testing; part I}
\label{app1}

This is the first appendix.

\subsection{A subsection within an appendix}

Some text.

\section{Just for testing; part II}
\label{app2}

This is more stuff for an appendix.

\subsection{Appendix: Testing identical titles}

Without label.


\subsection{Appendix: Testing identical titles}
\label{test:title:id1}

With label.

\subsection{Appendix: Testing identical titles}
\label{test:title:id2}

What about inserting a quiz?


\begin{doconcequiz}
\refstepcounter{doconcequizcounter}
\label{quiz:2}


\noindent\textbf{\large Capital of Norway}
\paragraph{Fundamental test:}
What is the capital of Norway?

\vspace{2mm}

\textbf{A}. 
Stockholm

\textbf{B}. 
London

\textbf{C}. 
Oslo

\textbf{D}. 
Bergen


% --- begin answer of exercise ---
\paragraph{Answer:} C.
% --- end answer of exercise ---

% --- begin solution of exercise ---
\noindent {\bf Solution:}\\


\textbf{A}: Wrong. Stockholm is the capital of Sweden.

\textbf{B}: Wrong. 

\textbf{C}: Right. 

\textbf{D}: Wrong. Those from Bergen would claim so, but nobody else.


% --- end solution of exercise ---


\vspace{3mm}

\end{doconcequiz}




\subsection{Appendix: Testing identical titles}

Without label.


\begin{notice_mdfboxadmon}[Tip.]
Here is a tip or hint box, typeset as a notice box.
\end{notice_mdfboxadmon} % title: Tip.




\clearpage

Need a lot of text to surround the summary box.
Version control systems allow you to record the history of files
and share files among several computers and collaborators in a
professional way. File changes on one computer are updated or
merged with changes on another computer. Especially when working
with programs or technical reports it is essential
to have changes documented and to
ensure that every computer and person involved in the project
have the latest updates of the files.
Greg Wilson' excellent \href{{https://software--carpentry.org/2010/07/script--for-introduction-to--version-control/}}{Script for Introduction to Version Control}\footnote{\texttt{https://software--carpentry.org/2010/07/script--for-introduction-to--version-control/}} provides a more detailed motivation why you will benefit greatly
from using version control systems.


\begin{summary_mdfboxadmon}[Summary.]
\textbf{Bold remark:} Make some text with this summary.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
\end{summary_mdfboxadmon} % title: Summary.



Projects that you want to share among several computers or project
workers are today most conveniently stored at some web site "in the
cloud" and updated through communication with that site. I strongly
recommend you to use such sites for all serious programming and
scientific writing work - and all other important files.

The simplest services for hosting project files are \href{{https://dropbox.com}}{Dropbox}\footnote{\texttt{https://dropbox.com}} and \href{{https://drive.google.com}}{Google Drive}\footnote{\texttt{https://drive.google.com}}.
It is very easy to get started with these systems, and they allow you
to share files among laptops and mobile units with as many users as
you want. The systems offer a kind of version control in that the
files are stored frequently (several times per minute), and you can go
back to previous versions for the last 30 days. However, it is
challenging  to find the right version from the past when there are
so many of them.

More seriously, when several people may edit files simultaneously, it
can be difficult detect who did what when, roll back to previous
versions, and to manually merge the edits when these are
incompatible. Then one needs more sophisticated tools than Dropbox or
Google Drive: project hosting services with true version control
systems.  The following text aims at providing you with the minimum
information to started with such systems. Numerous other tutorials
contain more comprehensive material and in--depth explanations of the
concepts and tools.

The idea with project hosting services is that you have the files
associated with a project in the cloud. Many people may share these
files.  Every time you want to work on the project you explicitly
update your version of the files, edit the files as you like, and
synchronize the files with the "master version" at the site where the
project is hosted.  If you at some point need to go back to a
version of the files at some particular point in the past,
this is an easy operation. You can also use tools to see
what various people have done with the files in the various versions.

All these services are very similar. Below we describe how you get
started with Bitbucket, GitHub, and Googlecode. Launchpad works very
similarly to the latter three. All the project hosting services have
excellent introductions available at their web sites, but the recipes
below are much shorter and aim at getting you started as quickly as
possible by concentrating on the most important need-to--know steps.
The Git tutorials we refer to later in this document contain more
detailed information and constitute of course very valuable readings
when you use version control systems every day. The point now is
to get started.


\subsection{Appendix: Testing inline comments}

% Names can be [ A-Za-z0-9_'+-]+

Projects that you want to share among several computers or project
workers are today most conveniently stored at some web site "in the
cloud" and updated through communication with that
site. \shortinlinecomment{hpl's semi opinion 1}{ not sure if in the cloud is understood by all. }{ not sure if in } I strongly recommend you to use such sites for all serious
programming and scientific writing work - and all other important
files.

The simplest services for hosting project files is Dropbox. \longinlinecomment{mp 2}{ Simply go to \href{{https://dropbox.com}}{\nolinkurl{https://dropbox.com}} and watch the video. It explains how files, like \texttt{myfile.py}, perhaps containing much math, like $\partial u/\partial t$, are easily communicated between machines. }{ Simply go to \href{{https://dropbox.com}}{\nolinkurl{https://dropbox.com}} } It
is very easy to get started with Dropbox, and it allows you to share
files among \textcolor{red}{(hpl 3:)} \replace{laptops and mobile units}{computers, tablets, and phones}.

% Test horizontal rule

------

% Coments for editing

First\textcolor{red}{, (\textbf{edit 4}: add comma)} consider a quantity $Q$. \textcolor{red}{(edit 5:)} \replace{To this end,}{We note that}
$Q>0$, because (\textbf{edit 6}:) \remove{a} negative \textcolor{red}{(edit 7:)} \replace{quantity is}{quantities are} (\textbf{edit 8}:) \remove{just} negative.  \textcolor{red}{ (\textbf{edit 9}:) This comes as no surprise.}

% Test tailored latex figure references with page number
Let us refer to Figure~\vref{fig:impact} again.

Test references in a list:

\begin{itemize}
 \item \vref{sec1}

 \item \vref{subsec1}

 \item \vref{fig:impact}
\end{itemize}

\noindent
\subsection{Appendix: Testing headings ending with \texttt{verbatim inline} }

The point here is to test 1) \texttt{verbatim} code in headings, and 2)
ending a heading with verbatim code as this triggers a special
case in {\LaTeX}.

We also test mdash---used as alternative to hyphen without spaces around,
or in quotes:


\begin{quote}
\emph{Fun is fun}.---Unknown.
\end{quote}


The ndash should also be tested -- as in the Hanson---Nilson equations
on page 277--278.

And finally, what about admons, quotes, and boxes? They are tested
in a separate document: \texttt{admon.do.txt}.


% ------------------- end of main content ---------------

\cleardoublepage\phantomsection  % trick to get correct link to Index
\printindex

\end{document}

************** File: testdoc.tex_direct *****************
%%
%% Automatically generated file from DocOnce source
%% (https://github.com/hplgit/doconce/)
%%

% #define PREAMBLE

% #ifdef PREAMBLE
%-------------------- begin preamble ----------------------

\documentclass[%
oneside,                 % oneside: electronic viewing, twoside: printing
final,                   % draft: marks overfull hboxes, figures with paths
10pt]{article}

\listfiles               %  print all files needed to compile this document

\usepackage{relsize,makeidx,color,setspace,amsmath,amsfonts,amssymb}
\usepackage[table]{xcolor}
\usepackage{bm,ltablex,microtype}

\usepackage[pdftex]{graphicx}
\usepackage{sidecap}

% user-provided packages: --latex_packages=varioref
\usepackage{varioref}

% 'on page ...' reference with \vref{} and varioref package
\renewcommand\reftextfaceafter{on page~\thevpagerefnum}
\renewcommand\reftextfacebefore{on page~\thevpagerefnum}
\renewcommand\reftextafter{on page~\thevpagerefnum}
\renewcommand\reftextbefore{on page~\thevpagerefnum}

% Tools for marking corrections
\usepackage{soul}
\newcommand{\replace}[2]{{\color{red}\text{\st{#1} #2}}}
\newcommand{\remove}[1]{{\color{red}\st{#1}}}

% Packages for typesetting blocks of computer code
\usepackage{fancyvrb,framed,moreverb}

% Define colors
\definecolor{orange}{cmyk}{0,0.4,0.8,0.2}
\definecolor{tucorange}{rgb}{1.0,0.64,0}
\definecolor{darkorange}{rgb}{.71,0.21,0.01}
\definecolor{darkgreen}{rgb}{.12,.54,.11}
\definecolor{myteal}{rgb}{.26, .44, .56}
\definecolor{gray}{gray}{0.45}
\definecolor{mediumgray}{gray}{.8}
\definecolor{lightgray}{gray}{.95}
\definecolor{brown}{rgb}{0.54,0.27,0.07}
\definecolor{purple}{rgb}{0.5,0.0,0.5}
\definecolor{darkgray}{gray}{0.25}
\definecolor{darkblue}{rgb}{0,0.08,0.45}
\definecolor{darkblue2}{rgb}{0,0,0.8}
\definecolor{lightred}{rgb}{1.0,0.39,0.28}
\definecolor{lightgreen}{rgb}{0.48,0.99,0.0}
\definecolor{lightblue}{rgb}{0.53,0.81,0.92}
\definecolor{lightblue2}{rgb}{0.3,0.3,1.0}
\definecolor{lightpurple}{rgb}{0.87,0.63,0.87}
\definecolor{lightcyan}{rgb}{0.5,1.0,0.83}

\colorlet{comment_green}{green!50!black}
\colorlet{string_red}{red!60!black}
\colorlet{keyword_pink}{magenta!70!black}
\colorlet{indendifier_green}{green!70!white}

% Backgrounds for code
\definecolor{cbg_gray}{rgb}{.95, .95, .95}
\definecolor{bar_gray}{rgb}{.92, .92, .92}

\definecolor{cbg_yellowgray}{rgb}{.95, .95, .85}
\definecolor{bar_yellowgray}{rgb}{.95, .95, .65}

\colorlet{cbg_yellow2}{yellow!10}
\colorlet{bar_yellow2}{yellow!20}

\definecolor{cbg_yellow1}{rgb}{.98, .98, 0.8}
\definecolor{bar_yellow1}{rgb}{.98, .98, 0.4}

\definecolor{cbg_red1}{rgb}{1, 0.85, 0.85}
\definecolor{bar_red1}{rgb}{1, 0.75, 0.85}

\definecolor{cbg_blue1}{rgb}{0.87843, 0.95686, 1.0}
\definecolor{bar_blue1}{rgb}{0.7,     0.95686, 1}

%\setlength{\fboxsep}{2mm}  % adjust cod_vpad/pro_vpad background box

%% Background for code blocks (parameter is color name)

%% pro/cod_vpad: gives some vertical padding before and after the text
%% (but has more simplistic code than _cod/pro_tight+cod/pro).
%% pro/cod_vpad can be used to enclose Verbatim or lst begin/end for code.
%% pro/cod calls _pro/cod_tight and has very little vertical padding,
%% used to enclose Verbatim and other begin/end for code.
%% (pro/cod is what the ptex2tex program could produce with the
%% Blue/BlueBar definitions in .ptex2tex.cfg.)

\newenvironment{cod_vpad}[1]{
   \def\FrameCommand{\colorbox{#1}}
   \MakeFramed{\FrameRestore}}
   {\endMakeFramed}

\newenvironment{_cod_tight}[1]{
   \def\FrameCommand{\colorbox{#1}}
   \FrameRule0.6pt\MakeFramed {\FrameRestore}\vskip3mm}
   {\vskip0mm\endMakeFramed}

\newenvironment{cod}[1]{
\bgroup\rmfamily
\fboxsep=0mm\relax
\begin{_cod_tight}{#1}
\list{}{\parsep=-2mm\parskip=0mm\topsep=0pt\leftmargin=2mm
\rightmargin=2\leftmargin\leftmargin=4pt\relax}
\item\relax}
{\endlist\end{_cod_tight}\egroup}

%% Background for complete program blocks (parameter 1 is color name
%% for background, parameter 2 is color for left bar)
\newenvironment{pro_vpad}[2]{
   \def\FrameCommand{\color{#2}\vrule width 1mm\normalcolor\colorbox{#1}}
   \MakeFramed{\FrameRestore}}
   {\endMakeFramed}

\newenvironment{_pro_tight}[2]{
   \def\FrameCommand{\color{#2}\vrule width 1mm\normalcolor\colorbox{#1}}
   \FrameRule0.6pt\MakeFramed {\advance\hsize-2mm\FrameRestore}\vskip3mm}
   {\vskip0mm\endMakeFramed}

\newenvironment{pro}[2]{
\bgroup\rmfamily
\fboxsep=0mm\relax
\begin{_pro_tight}{#1}{#2}
\list{}{\parsep=-2mm\parskip=0mm\topsep=0pt\leftmargin=2mm
\rightmargin=2\leftmargin\leftmargin=4pt\relax}
\item\relax}
{\endlist\end{_pro_tight}\egroup}

\usepackage{listingsutf8}

% Common lstlisting parameters

\usepackage{calc}
\newlength{\lstboxwidth}  % width of lst box
\newlength{\framethickness}
\setlength{\framethickness}{0.5mm}
% for frame=trbl and a framerule that has significant size, set
% xleftmargin=5mm and xrightmargin=5mm.

\lstset{
  basicstyle=\small \ttfamily,
  breaklines=false,          % break/wrap lines
  breakatwhitespace=true,    % let linebreaks happen at whitespace
  breakindent=40pt,
  tab=,
  tabsize=4,                 % tab means 4 spaces
  %belowskip=\smallskipamount,  % space between code and text below
  xleftmargin=2mm,           % indentation of code frame
  xrightmargin=0mm,
  framexleftmargin=2mm,      % add frame space to the left of the code box
  %numbers=left,             % put line numbers on the left
  %stepnumber=2,             % stepnumber=1 numbers each line, =n every n lines
  framerule=\framethickness, % thickness of frame
  aboveskip=2ex,             % vertical space above code frame
  showstringspaces=false,    % show spaces in strings with an underscore
  showspaces=false,          % show spaces with an underscore
  showtabs=false,
  keepspaces=true,
  columns=fullflexible,      % tighter character kerning, like verb
  escapeinside={(*@}{@*)},   % (*@ \pause @*) in slides and math in code blocks
  extendedchars=\true,       % allows non-ascii chars, does not work with utf-8
}

% Internally defined styles for lstlisting

\lstdefinestyle{simple}{
commentstyle={},
}

% user-defined lst styles in file "mylststyles":
\lstdefinestyle{myspeciallststyle}{
keywordstyle=\color{blue}\bfseries,
commentstyle=\color{myteal},
stringstyle=\color{darkgreen},
identifierstyle=\color{darkorange},
}

% end of custom lstdefinestyles

\usepackage[T1]{fontenc}
%\usepackage[latin1]{inputenc}
\usepackage{ucs}
\usepackage[utf8x]{inputenc}

\usepackage{lmodern}         % Latin Modern fonts derived from Computer Modern

\newenvironment{doconcequiz}{}{}
\newcounter{doconcequizcounter}

% Hyperlinks in PDF:
\definecolor{linkcolor}{rgb}{0,0,0.4}
\usepackage{hyperref}
\hypersetup{
    breaklinks=true,
    colorlinks=true,
    linkcolor=linkcolor,
    urlcolor=linkcolor,
    citecolor=black,
    filecolor=black,
    %filecolor=blue,
    pdfmenubar=true,
    pdftoolbar=true,
    bookmarksdepth=3   % Uncomment (and tweak) for PDF bookmarks with more levels than the TOC
    }
%\hyperbaseurl{}   % hyperlinks are relative to this root

\setcounter{tocdepth}{2}  % levels in table of contents

%\VerbatimFootnotes must come after hyperref and footmisc packages
\VerbatimFootnotes

% Tricks for having figures close to where they are defined:
% 1. define less restrictive rules for where to put figures
\setcounter{topnumber}{2}
\setcounter{bottomnumber}{2}
\setcounter{totalnumber}{4}
\renewcommand{\topfraction}{0.95}
\renewcommand{\bottomfraction}{0.95}
\renewcommand{\textfraction}{0}
\renewcommand{\floatpagefraction}{0.75}
% floatpagefraction must always be less than topfraction!
% 2. ensure all figures are flushed before next section
\usepackage[section]{placeins}
% 3. enable begin{figure}[H] (often leads to ugly pagebreaks)
%\usepackage{float}\restylefloat{figure}

% newcommands for typesetting inline (doconce) comments
\newcommand{\shortinlinecomment}[3]{{\color{red}{\bf #1}: #2}}
\newcommand{\longinlinecomment}[3]{{\color{red}{\bf #1}: #2}}

\usepackage[framemethod=TikZ]{mdframed}

% --- begin definitions of admonition environments ---

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "notice" admon
\colorlet{mdfbox_notice_background}{gray!5}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_notice_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=mdfbox_notice_background,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{notice_mdfboxmdframed}

\newenvironment{notice_mdfboxadmon}[1][]{
\begin{notice_mdfboxmdframed}[frametitle=#1]
}
{
\end{notice_mdfboxmdframed}
}

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "summary" admon
\colorlet{mdfbox_summary_background}{gray!5}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_summary_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=mdfbox_summary_background,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{summary_mdfboxmdframed}

\newenvironment{summary_mdfboxadmon}[1][]{
\begin{summary_mdfboxmdframed}[frametitle=#1]
}
{
\end{summary_mdfboxmdframed}
}

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "warning" admon
\colorlet{mdfbox_warning_background}{gray!5}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_warning_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=mdfbox_warning_background,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{warning_mdfboxmdframed}

\newenvironment{warning_mdfboxadmon}[1][]{
\begin{warning_mdfboxmdframed}[frametitle=#1]
}
{
\end{warning_mdfboxmdframed}
}

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "question" admon
\colorlet{mdfbox_question_background}{gray!5}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_question_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=mdfbox_question_background,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{question_mdfboxmdframed}

\newenvironment{question_mdfboxadmon}[1][]{
\begin{question_mdfboxmdframed}[frametitle=#1]
}
{
\end{question_mdfboxmdframed}
}

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "block" admon
\colorlet{mdfbox_block_background}{gray!5}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_block_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=mdfbox_block_background,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{block_mdfboxmdframed}

\newenvironment{block_mdfboxadmon}[1][]{
\begin{block_mdfboxmdframed}[frametitle=#1]
}
{
\end{block_mdfboxmdframed}
}

% --- end of definitions of admonition environments ---

% prevent orhpans and widows
\clubpenalty = 10000
\widowpenalty = 10000

\usepackage{calc}

\newenvironment{doconceexercise}{}{}
\newcounter{doconceexercisecounter}
% --- begin definition of \listofexercises command ---
\makeatletter
\newcommand\listofexercises{\section*{List of Examples, Exercises, Problems, and Projects}
\@starttoc{loe}
}
\newcommand*{\l@doconceexercise}{\@dottedtocline{0}{0pt}{6.5em}}
\makeatother
% --- end definition of \listofexercises command ---



% ------ header in subexercises ------
%\newcommand{\subex}[1]{\paragraph{#1}}
%\newcommand{\subex}[1]{\par\vspace{1.7mm}\noindent{\bf #1}\ \ }
\makeatletter
% 1.5ex is the spacing above the header, 0.5em the spacing after subex title
\newcommand\subex{\@startsection{paragraph}{4}{\z@}%
                  {1.5ex\@plus1ex \@minus.2ex}%
                  {-0.5em}%
                  {\normalfont\normalsize\bfseries}}
\makeatother


% --- end of standard preamble for documents ---


\usepackage{amsthm,tcolorbox}
\theoremstyle{definition}
\newtheorem{example}{Example}[section]



% insert custom LaTeX commands...

\raggedbottom
\makeindex
\usepackage[totoc]{idxlayout}   % for index in the toc
\usepackage[nottoc]{tocbibind}  % for references/bibliography in the toc

%-------------------- end preamble ----------------------

\begin{document}

% matching end for #ifdef PREAMBLE
% #endif

\newcommand{\exercisesection}[1]{\subsection*{#1}}

\input{newcommands_bfmath}
\input{newcommands_replace}

% ------------------- main content ----------------------



% ----------------- title -------------------------

\thispagestyle{empty}

\begin{center}
{\LARGE\bf
\begin{spacing}{1.25}
A Document for Testing DocOnce
\end{spacing}
}
\end{center}

% ----------------- author(s) -------------------------

\begin{center}
{\bf Hans Petter Langtangen${}^{1, 2}$ (\texttt{hpl@simula.no})} \\ [0mm]
\end{center}


\begin{center}
{\bf Kaare Dump${}^{3}$} \\ [0mm]
\end{center}


\begin{center}
{\bf A. Dummy Author${}^{}$} \\ [0mm]
\end{center}


\begin{center}
{\bf I. S. Overworked and Outburned${}^{4, 5, 6, 7}$} \\ [0mm]
\end{center}


\begin{center}
{\bf J. Doe${}^{}$ (\texttt{j\_doe@cyberspace.com})} \\ [0mm]
\end{center}

\begin{center}
% List of all institutions:
\centerline{{\small ${}^1$Center for Biomedical Computing, Simula Research Laboratory}}
\centerline{{\small ${}^2$Department of Informatics, University of Oslo}}
\centerline{{\small ${}^3$Segfault, Cyberspace}}
\centerline{{\small ${}^4$Inst1}}
\centerline{{\small ${}^5$Inst2, Somewhere}}
\centerline{{\small ${}^6$Third Inst, Elsewhere}}
\centerline{{\small ${}^7$Fourth Inst}}
\end{center}
    
% ----------------- end author(s) -------------------------

% --- begin date ---
\begin{center}
Jan 32, 2100
\end{center}
% --- end date ---

\vspace{1cm}


\tableofcontents


\vspace{1cm} % after toc





% !split




The format of this document is
plain, homemade \textsc{pdf}{\LaTeX} (from DocOnce).

\begin{abstract}
This is a document with many test constructions for doconce syntax.
It was used heavily for the development and kept for testing
numerous constructions, also special and less common cases.

And exactly for test purposes we have an extra line here, which
is part of the abstract.

% Cannot demonstrate chapter headings since abstract and chapter
% are mutually exclusive in {\LaTeX}
\end{abstract}

\section{Section 1}
\label{sec1}

Here is a nested list:

\begin{itemize}
  \item item1

  \item item2

  \item item3 which continues
    on the next line to test that feature

  \item and a sublist
\begin{itemize}

    \item with indented subitem1

    \item and a subitem2

\end{itemize}

\noindent
  \item and perhaps an ordered sublist
\begin{enumerate}

   \item first item

   \item second item,
      continuing on a new line
\end{enumerate}

\noindent
\end{itemize}

\noindent
\paragraph{Here is a list with paragraph heading.}

\begin{itemize}
  \item item1

  \item item2
\end{itemize}

\noindent
\paragraph{Here is a list with subsubsection heading.}
\begin{itemize}
  \item item1

  \item item2
\end{itemize}

\noindent

\begin{quote}
Here are two lines that make up
a block quote for testing \emph{emphasized words} and \textbf{boldface words},
also with hypens:
\emph{pre}-fix, post-\emph{fix}, \textbf{pre}-fix, post-\textbf{fix}.
\end{quote}


Here are two references. Equation~(\ref{my:eq1}) is fine. Eq.~(\ref{my:eq1}) too.
Even Equation (\ref{my:eq1}) without the tilde.


\subsection{Subsection 1}
\label{subsec1}

\index{somefunc@{\rm\texttt{somefunc}} function}

% Refer to section/appendix etc. at the beginning of the line
% and other special fix situations for HTML.

More text, with a reference back to
Section~\vref{sec1} and~\vref{subsec1}, and further to the
sections~\vref{subsec1} and~\vref{subsubsec:ex}, which
encourages you to do the tasks in the
Exercises~\vref{demo:ex:1} and~\vref{exer:some:formula}.
Appendices~\vref{app1} and~\vref{app2} are also nice elements.

\paragraph{Test Section reference at beginning of line and after a sentence.}
Section~\vref{subsec1} is fine.
Section~\vref{subsubsec:ex} too.


% sphinx code-blocks: pycod=python cod=fortran cppcod=c++ sys=console

\paragraph{Computer code.}
Let's do some copying from files too. First from subroutine up to the very end,

\begin{cod}{cbg_gray}\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=2mm]
      subroutine test()
      integer i
      real*8 r
      r = 0
      do i = 1, i
         r = r + i
      end do
      return
C     END1

      program testme
      call test()
      return
\end{Verbatim}
\end{cod}
\noindent
and then just the subroutine,
\begin{cod}{cbg_gray}\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=2mm]

      subroutine test()
      integer i
      real*8 r
      r = 0
      do i = 1, i
         r = r + i
      end do
      return
\end{Verbatim}
\end{cod}
\noindent
and finally the complete file with a plain text verbatim environment
(\texttt{envir=ccq}):
\begin{cod}{cbg_blue1}\begin{lstlisting}[language=Python,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
C     a comment

      subroutine test()
      integer i
      real*8 r
      r = 0
      do i = 1, i
         r = r + i
      end do
      return
C     END1

      program testme
      call test()
      return
\end{lstlisting}\end{cod}
\noindent

Testing other code environments. First Python:

\begin{cod}{cbg_blue1}\begin{lstlisting}[language=Python,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
!bc pycod
def f(x):
    return x+1
!ec
\end{lstlisting}\end{cod}
\noindent
which gets rendered as

\begin{cod}{cbg_blue1}\begin{lstlisting}[language=Python,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
def f(x):
    return x+1
\end{lstlisting}\end{cod}
\noindent

Test paragraph and subsubsection headings before
before code.

\paragraph{Paragraph heading before code.}

\begin{cod}{cbg_blue1}\begin{lstlisting}[language=Python,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
import sys
sys.path.insert(0, os.pardir)
\end{lstlisting}\end{cod}
\noindent

\paragraph{Subsubsection heading before code.}
\begin{cod}{cbg_blue1}\begin{lstlisting}[language=Python,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
def h(z):
    return z+1
\end{lstlisting}\end{cod}
\noindent

Now a complete program to be shown via Python Online Tutorial:

\begin{pro}{cbg_blue1}{bar_blue1}\begin{lstlisting}[language=Python,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
class Line:
    def __init__(self, a, b):
        self.a, self.b = a, b

    def __call__(self, x):
        a, b = self.a, self.b
        return a*x + b

line = Line(2, 1)
y = line(x=3)
print(y)
\end{lstlisting}\end{pro}
\noindent
\noindent
(\href{{https://pythontutor.com/visualize.html\#code=class+Line\%3A\%0A++++def+__init__\%28self\%2C+a\%2C+b\%29\%3A\%0A++++++++self.a\%2C+self.b+\%3D+a\%2C+b\%0A\%0A++++def+__call__\%28self\%2C+x\%29\%3A\%0A++++++++a\%2C+b+\%3D+self.a\%2C+self.b\%0A++++++++return+a\%2Ax+\%2B+b\%0A\%0Aline+\%3D+Line\%282\%2C+1\%29\%0Ay+\%3D+line\%28x\%3D3\%29\%0Aprint\%28y\%29&mode=display&cumulative=false&heapPrimitives=false&drawParentPointers=false&textReferences=false&py=2&curInstr=0}}{Visualize execution}) 


Some more Python code (actually specified as a sage cell, but
such cells are not supported by this format).

\begin{pro}{cbg_blue1}{bar_blue1}\begin{lstlisting}[language=Python,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
a = 2
b = 3
print('a+b:', a + b)

# In a sage cell we can also plot
from matplotlib.pyplot import *
from numpy import *
x = linspace(0, 4*pi, 101)
y = exp(-0.1*x)*cos(x)
plot(x, y)
xlabel('x'); ylabel('y')
show()
\end{lstlisting}\end{pro}
\noindent


Then Cython (with -h option so it is hidden in html/sphinx):

\begin{cod}{cbg_blue1}\begin{lstlisting}[language=Python,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
cpdef f(double x):
    return x + 1
\end{lstlisting}\end{cod}
\noindent

Standard Python shell sessions:

\begin{cod}{cbg_blue1}\begin{lstlisting}[language=Python,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
>>> from numpy import linspace, sin
>>> # Some comment
>>> x = linspace(0, 2, 11)
>>> y = sin(x)
>>> y[0]
0
>>> import matplotlib.pyplot as plt
>>> plt.plot(x, y)
\end{lstlisting}\end{cod}
\noindent

Similar IPython sessions:

\begin{cod}{cbg_blue1}\begin{lstlisting}[language=Python,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
In [1]: from numpy import linspace, sin
In [2]: # Some comment
In [3]: x = linspace(0, 2, 11)
In [4]: y = sin(x)
In [5]: y[0]
Out[5]: 0
In [6]: import matplotlib.pyplot as plt
In [7]: plt.plot(x, y)
In [8]: a='multiple-\nline\noutput'
In [9]: a
Out[9]: 'multiple-\nline\noutput'
In [10]: print(a)
multiple-
line
output
\end{lstlisting}\end{cod}
\noindent

Here is the interactive session again, but with \texttt{pyshell-t}.

\begin{cod}{cbg_blue1}\begin{lstlisting}[language=Python,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
>>> from numpy import linspace, sin
>>> # Some comment
>>> x = linspace(0, 2, 11)
>>> y = sin(x)
>>> y[0]
0
>>> import matplotlib.pyplot as plt
>>> plt.plot(x, y)
\end{lstlisting}\end{cod}
\noindent

% This one tests a + sign before a code environment
C++:
\begin{pro}{cbg_blue1}{bar_blue1}\begin{lstlisting}[language=C++,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
#include <iostream>

int main()
{
   std::cout << "Sample output" << std::endl;
   return 0
}
\end{lstlisting}\end{pro}
\noindent
% The next should get correctly typset in sphinx (cod is fcod)
% It also tests emoji before code
And a little bit of Fortran: \raisebox{-\height+\ht\strutbox}{\includegraphics[height=1.5em]{latex_figs/dizzy_face.png}}

\begin{cod}{cbg_blue1}\begin{lstlisting}[language=Python,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
!bc cod
      subroutine midpt(x, length, a, b)
      real*8 a, b, x
      x = (a + b)/2
      length = b - a
      return
      end
!ec
\end{lstlisting}\end{cod}
\noindent
which then is typeset as

\begin{cod}{cbg_blue1}\begin{lstlisting}[language=Python,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
      subroutine midpt(x, length, a, b)
      real*8 a, b, x
      x = (a + b)/2
      length = b - a
      return
      end
\end{lstlisting}\end{cod}
\noindent

HTML:

\begin{cod}{cbg_blue1}\begin{lstlisting}[language=HTML,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
<table>
<tr><td>Column 1</td><td>Column 2</td></tr>
<tr><td>0.67526 </td><td>0.92871 </td></tr>
<!-- comment -->
</table>
\end{lstlisting}\end{cod}
\noindent

But inline HTML code is also important, like text that starts with
\texttt{<a href="} (which can destroy the following text if not properly
quoted).

Matlab with comments requires special typesetting:

\begin{cod}{cbg_blue1}\begin{lstlisting}[language=Matlab,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
% Comment on the beginning of the line can be escaped by %%
if a > b
  % Indented comment needs this trick
  c = a + b
end
\end{lstlisting}\end{cod}
\noindent

And here is a system call:

\begin{Verbatim}[frame=lines,label=\fbox{{\tiny Terminal}},framesep=2.5mm,framerule=0.7pt]
Terminal> mkdir test
Terminal> cd test
Terminal> myprog -f
output1
output2
\end{Verbatim}

Any valid pygments lexer/language name can appear to, e.g.,

\begin{cod}{cbg_blue1}\begin{lstlisting}[language=Python,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
!bc restructuredtext
=======
Heading
=======

Some text.
!ec
\end{lstlisting}\end{cod}
\noindent
results in

\begin{cod}{cbg_blue1}\begin{lstlisting}[language=Python,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
=======
Heading
=======

Some text.
\end{lstlisting}\end{cod}
\noindent

% Here goes hidden code.
% Python can be treated by some formats, Fortran is always out.





Finally, \Verb?!bc do? supports highlighting of DocOnce source:

\begin{cod}{cbg_blue1}\begin{lstlisting}[language=Python,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
======= DocOnce test file =======

===== Computer code =====

Inline verbatim code, as in `import numpy as np`, is allowed, as well as
code blocks:

!bc pycod
from math import sin

def f(x):
    """Example on a function."""
    return sin(x) + 1

print(f(0))
!ec


===== Mathematics =====

Formulas can be inline, as in $\nabla\cdot\bm{u} = 0$, or typeset
as equations:

!bt
\begin{align*}
\nabla\cdot\bm{u} &= 0,\\ 
\bm{u} &= \nabla\phi .
\end{align*}
!et

=== Subsubsection heading ===

DocOnce files can have chapters, sections, subsections, and subsubsections.

__Paragraph heading.__ Paragraphs may have headings.
\end{lstlisting}\end{cod}
\noindent

It is time to test \texttt{verbatim inline font} especially with \texttt{a newline inside the text} and an exclamation mark at the end: \texttt{BEGIN}! For
spellcheck, test \texttt{a verbatim expression} in \texttt{another} in a \texttt{third}.
Also test exclamation mark as in \Verb?!bc? and \Verb?!ec? as well as \Verb?a != b?.
Also test backslashes and braces like \Verb!\begin!, \Verb!\begin{enumerate}!,
\Verb!\end{this}\end{that}!, and \Verb!{something \inside braces}!.

Here is some \textcolor{red}{red color} and an attempt to write \textcolor{green}{with
green color containing a linebreak\\
code.} Some formats will only display \\
this correctly when \texttt{html} \\
is the output format.
But here some more running text is added which is not part of
the previous blocks with line breaks.

\paragraph{Running OS commands.}
\begin{Verbatim}[frame=lines,label=\fbox{{\tiny Terminal}},framesep=2.5mm,framerule=0.7pt]
Terminal> python -c 'print("Testing\noutput\nfrom\nPython.")'
Testing
output
from
Python.
\end{Verbatim}


\paragraph{Footnotes.}
Here is a test of footnotes \footnote{Typesetting of the footnote depends on the format. Plain text does nothing, {\LaTeX} removes the definition and inserts the footnote as part of the {\LaTeX} text. reStructuredText and Sphinx employ a similar type of typesetting as Extended Markdown and DocOnce, and in HTML we keep the same syntax, just displayed properly in HTML.}, which are handy in text.
They are used in different flavors, now in

\begin{itemize}
 \item list items (note below that footnotes work after math, verbatim, and URLs - bin fact old and emphasize too!)

 \item even with math $\nabla^2u$\footnote{Math footnotes can be dangerous since it interferes with an exponent.}

 \item and code \texttt{h[i] += 1}\footnote{One-line footnote.}
   (\emph{must} have space between inline code and footnote!)

 \item and \href{{https://google.com}}{links}\footnote{\href{{google.com}}{\nolinkurl{google.com}} is perhaps the most famous web site today.}
\end{itemize}

\noindent
which gives flexibility in writing.
This is the third\footnote{Not much to add here, but the footnote is at the end with only one newline.} example.





Here is some more text before a new definition of a footnote that was
used above.


\begin{notice_mdfboxadmon}[Non-breaking space character.]
This paragraph aims to test \href{{https://en.wikipedia.org/wiki/Non-breaking_space}}{non-breaking space character}, and a typical
example where this is needed is in physical units: 7.4~km is traveled
in~$7.4/5.5\approx 1.345$~s.  Also check that a~\href{{https://google.com}}{link}~is
not broken across lines (drag the browser window to test this).
(On the other hand, the tilde is used in
computer code, e.g., as in \texttt{[~x for x in y]} or in \texttt{y=~x}, and should
of course remain a tilde in those contexts.)
\end{notice_mdfboxadmon} % title: Non-breaking space character.



\subsection{Subsection 2: Testing figures}
\label{subsec:ex}
\index{figures}

Test of figures. In particular we refer to Figure~\vref{fig:impact} in which
there is a flow.


\begin{figure}[!ht]  % fig:impact
  \centerline{\includegraphics[width=0.9\linewidth]{../doc/src/manual/fig/wave1D.pdf}}
  \caption{
  Visualization \textbf{of} a \emph{wave}. \label{fig:impact}
  }
\end{figure}
%\clearpage % flush figures fig:impact


Figures without captions are allowed and will be inlined.



\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=0.9\linewidth]{../doc/src/manual/fig/wave1D.pdf}}

\vspace{6mm}



\index{movies}


% Test multi-line caption in figure with sidecap=True

Here is figure~\vref{myfig} with a long (illegal) multi-line caption
containing inline verbatim text:


\begin{SCfigure}
  \centering
  \includegraphics[width=0.9\linewidth]{../doc/src/manual/fig/wave1D.png}
  \caption{
  A long caption spanning several lines and containing verbatim words like \protect \Verb!my\_file\_v1! and \protect \Verb!my\_file\_v2! as well as math with subscript as in $t_{i+1}$. \label{myfig}
  }
\end{SCfigure}
%\clearpage % flush figures myfig


% Must be a blank line after MOVIE or FIGURE to detect this problem

Test URL as figure name:



\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=0.8\linewidth]{downloaded_figures/f_plot.png}}

\vspace{6mm}




% Test wikimedia type of files that otherwise reside in subdirs


\paragraph{Remark.}
Movies are tested in separate file \texttt{movies.do.txt}.


% Somewhat challenging heading with latex math, \t, \n, ? and parenthesis

\subsection{The $\theta$ parameter (not $\nabla$?)}
\label{decay:sec:theta}

Functions do not always need to be advanced, here is one
involving $\theta$:
\begin{cod}{cbg_blue1}\begin{lstlisting}[language=Python,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
def f(theta):
    return theta**2
\end{lstlisting}\end{cod}
\noindent

\paragraph{More on $\theta$.}
Here is more text following headline with math.

Newcommands must also be tested in this \report:
$\half$, $\halfi$, $\x$, $\Ddt{u}$,
both inline and in block:

\begin{align}
\Ddt{u} &= 0\nonumber
\\ 
\half &= \halfi\\ 
\half\x &= \normalvec
\end{align}

Or with align with label and numbers:

\begin{align}
\Ddt{u} &= 0
\label{aligneq1}
\\ 
\half &= \halfi\\ 
\half\x &= \normalvec
\label{aligneq2}
\end{align}


% Must test more complicated align and matrix compositions
% where DocOnce inserts auto-numbered labels etc.

First one numbered (automatically):

\begin{align}
\begin{pmatrix}
G_2 + G_3 & -G_3 & -G_2 & 0 \\ 
-G_3 & G_3 + G_4 & 0 & -G_4 \\ 
-G_2 & 0 & G_1 + G_2 & 0 \\ 
0 & -G_4 & 0 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
 v_1 \\ 
 v_2 \\ 
 v_3 \\ 
 v_4
\end{pmatrix}
+ \cdots \\ 
\begin{pmatrix}
 C_5 + C_6 & -C_6 & 0 & 0 \\ 
 -C_6 & C_6 & 0 & 0 \\ 
 0 & 0 & 0 & 0 \\ 
 0 & 0 & 0 & 0
\end{pmatrix}
  &= \frac{d}{dt}\begin{pmatrix}
 v_1 \\ 
 v_2 \\ 
 v_3 \\ 
 v_4
\end{pmatrix} +
\begin{pmatrix}
 0 \\ 
 0 \\ 
 0 \\ 
 -i_0
\end{pmatrix}
\nonumber
\end{align}

Second numbered (automatically):

\begin{align}
\begin{pmatrix}
G_1 + G_2\\ 
-G_3 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
 v_1 \\ 
 v_2
\end{pmatrix}
+ \cdots\nonumber
\\ 
\left(\begin{array}{ll}
y & 2\\ 
2 & 1
\end{array}\right)
\left(\begin{array}{ll}
0 \\ x
\end{array}\right)
&= \begin{pmatrix}
A \\ B
\end{pmatrix}
\end{align}

Both numbered, with label by the user:

\begin{align}
\begin{pmatrix}
G_1 + G_2\\ 
-G_3 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
 v_1 \\ 
 v_2
\end{pmatrix}
+ \cdots \label{mymatrix:eq1}
\\ 
\label{mymatrix:eq2}
\left(\begin{array}{ll}
y & 2\\ 
2 & 1
\end{array}\right)
\left(\begin{array}{ll}
0 \\ x
\end{array}\right)
&= \begin{pmatrix}
A \\ B
\end{pmatrix}
\end{align}
Now we refer to (\ref{mymatrix:eq1})-(\ref{mymatrix:eq2}).

\subsection{Custom Environments}

Here is an attempt to create a theorem environment via Mako
(for counting theorems) and comment lines to help replacing lines in
the \texttt{.tex} by proper begin-end {\LaTeX} environments for theorems.
Should look nice in most formats!



% begin theorem
\label{theorem:fundamental1}


\paragraph{Theorem 5.}
Let $a=1$ and $b=2$. Then $c=3$.
% end theorem

% begin proof
\paragraph{Proof.}
Since $c=a+b$, the result follows from straightforward addition.
$\Diamond$
% end proof

As we see, the proof of Theorem 5 is a modest
achievement.


\subsection{Tables}
\label{subsec:table}

\index{test index with verbatim text@test index with {\rm\texttt{verbatim text}} which is possible}
\index{test two@test {\rm\texttt{two}} (separate) {\rm\texttt{verbatim expressions}} which is also possible}
\index{index with!subindex}
\index{\textbf{boldface word} in index}
\index{index with \textbf{boldface word}}
\index{index with!\textbf{boldface word} in subentry}
\index{double \textbf{boldface word}! \textbf{boldface word} in subentry too}

% index with comma could fool sphinx
\index{index, with comma, and one more}

Let us take this table from the manual:

\begin{table}
\caption{
Testing table environment in {\LaTeX}, enabled by testing on the "latex" format
with the preprocessor.
\label{mytab}
}



\begin{quote}
\begin{tabular}{lrr}
\hline
\multicolumn{1}{c}{ time } & \multicolumn{1}{c}{ velocity } & \multicolumn{1}{c}{ acceleration } \\
\hline
0.0  & 1.4186   & -5.01        \\
2.0  & 1.376512 & 11.919       \\
4.0  & 1.1E+1   & 14.717624    \\
\hline
\end{tabular}
\end{quote}

\noindent
\end{table}

The DocOnce source code reads
\begin{cod}{cbg_blue1}\begin{lstlisting}[language=Python,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]

  |--------------------------------|
  |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{lstlisting}\end{cod}
\noindent

Here is yet another table to test that we can handle more than
one table:


\begin{quote}
\begin{tabular}{lll}
\hline
\multicolumn{1}{l}{ time } & \multicolumn{1}{l}{ velocity } & \multicolumn{1}{l}{ acceleration } \\
\hline
0.0  & 1.4186   & -5.01        \\
1.0  & 1.376512 & 11.919       \\
3.0  & 1.1E+1   & 14.717624    \\
\hline
\end{tabular}
\end{quote}

\noindent
And one with math headings (that are expanded and must be treated
accordingly), verbatim heading and entry, and no space around the pipe
symbol:


\begin{quote}
\begin{tabular}{lrrr}
\hline
\multicolumn{1}{c}{ $i$ } & \multicolumn{1}{c}{ $h_i$ } & \multicolumn{1}{c}{ $\bar T_i$ } & \multicolumn{1}{c}{ \Verb!L\_i! } \\
\hline
0   & 0      & 288        & -0.0065    \\
1   & 11,000 & 216        & 0.0        \\
2   & 20,000 & 216        & 0.001      \\
3   & 32,000 & 228        & 0.0028     \\
4   & 47,000 & 270        & 0.0        \\
5   & 51,000 & 270        & -0.0028    \\
6   & 71,000 & 214        & \texttt{NaN} \\
\hline
\end{tabular}
\end{quote}

\noindent
And add one with verbatim headings (with underscores),
and rows starting with \texttt{|-} because of a negative number,
and \texttt{|} right before and after verbatim word (with no space):


\begin{quote}
\begin{tabular}{rrrr}
\hline
\multicolumn{1}{c}{ exact } & \multicolumn{1}{c}{ \Verb!v\_1! } & \multicolumn{1}{c}{ $a_i$ + \Verb!v\_2! } & \multicolumn{1}{c}{ \Verb!verb\_3\_! } \\
\hline
9     & 9.62       & 5.57               & 8.98           \\
-20   & -23.39     & -7.65              & -19.93         \\
10    & 17.74      & -4.50              & 9.96           \\
0     & -9.19      & 4.13               & -0.26          \\
\hline
\end{tabular}
\end{quote}

\noindent
Pipe symbols in verbatim and math text in tables used to pose difficulties,
but not
anymore:


\begin{quote}
\begin{tabular}{lr}
\hline
\multicolumn{1}{c}{ $S$ } & \multicolumn{1}{c}{ command } \\
\hline
$ ||a_0|| $ & \texttt{norm|length} \\
$x\cap y$   & \texttt{x|y}         \\
\hline
\end{tabular}
\end{quote}

\noindent

Here is a table with X alignment:


\begin{quote}
\begin{tabularx}{\linewidth}{cX}
\hline
\multicolumn{1}{c}{ Type } & \multicolumn{1}{c}{ Description } \\
\hline
X     & Alignment character that is used for specifying a potentially very long text in a column in a table. It makes use of the \texttt{tabularx} package in {\LaTeX}, otherwise (for other formats) it means \texttt{l} (centered alignment). \\
l,r,c & standard alignment characters                                                                                                                                                                                                       \\
\hline
\end{tabularx}
\end{quote}

\noindent
Finally, a table with math
and URLs.

% Mako code to expand URLs in the table
% (These types of tables did not work before Jan 2014)



\begin{quote}
\begin{tabular}{ccc}
\hline
 \\
\hline
$\mathcal{L}=0$         & \includegraphics[width=2cm]{../doc/src/manual/mov/wave_frames/frame_0080.png} & \includegraphics[width=2cm]{../doc/src/manual/mov/wave_frames/frame_0085.png} \\
$a=b$                   & \includegraphics[width=2cm]{../doc/src/manual/mov/wave_frames/frame_0090.png} & \includegraphics[width=2cm]{../doc/src/manual/mov/wave_frames/frame_0095.png} \\
$\nabla\cdot\bm{u} =0 $ & \includegraphics[width=2cm]{../doc/src/manual/mov/wave_frames/frame_0100.png} & \includegraphics[width=2cm]{../doc/src/manual/mov/wave_frames/frame_0105.png} \\
\hline
\end{tabular}
\end{quote}

\noindent

\subsection{A test of verbatim words in heading with subscript $a_i$: \protect\Verb!my\_file\_v1! and \protect\Verb!my\_file\_v2! }

\paragraph{Paragraph with verbatim and math: \protect\Verb!my\_file\_v1.py! and \protect\Verb!my\_file\_v2.py! define some math $a_{i-1}$.}
Here is more \Verb!__verbatim__! code and
some plain text on a new line.

% Test various types of headlines
\subsection{\textbf{Just bold}}

Some text.

\subsection{\emph{Just emphasize}}

Some text.

\subsection{\texttt{Just verbatim} }

Some text.

\subsection{\textbf{Bold} beginning}

Some text.

\subsection{\emph{Emphasize} beginning}

Some text.

\subsection{\texttt{Verbatim} beginning}

Some text.

\subsection{Maybe \textbf{bold end}}

Some text.

\subsection{Maybe \emph{emphasize end}}

Some text.

\subsection{Maybe \texttt{verbatim end} }

Some text.

\subsection{The middle has \textbf{bold} word}

Some text.

\subsection{The middle has \emph{emphasize} word}

Some text.

\subsection{The middle has \texttt{verbatim} word}

Some text.


\paragraph{\emph{Just emphasize}.}
Some text.


\paragraph{\texttt{Just verbatim}.}
Some text.


\paragraph{\emph{Emphasize} beginning.}
Some text.


\paragraph{\texttt{Verbatim beginning}.}
Some text.


\paragraph{Maybe \emph{emphasize end}.}
Some text.


\paragraph{Maybe \texttt{verbatim end}.}
Some text.


\paragraph{The middle has \emph{emphasize} word.}
Some text.


\paragraph{The middle has \texttt{verbatim} word.}
Some text.


\paragraph{Ampersand.}
We can test Hennes {\&} Mauritz, often abbreviated H{\&}M, but written
as \Verb!Hennes & Mauritz! and \Verb!H & M!.
A sole \Verb!&! must also work.
% Note: substitutions must not occur inside verbatim, just in ordinary text.

\begin{cod}{cbg_blue1}\begin{lstlisting}[language=Python,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
# Just to check that ampersand works in code blocks:
c = a & b
\end{lstlisting}\end{cod}
\noindent

\paragraph{Quotes.}
Let us also add a test of quotes such as ``double quotes, with numbers
like 3.14 and newline/comma and hyphen (as in double-quote)''; written
in the standard LaTeX-style that gives correct {\LaTeX} formatting and
ordinary double quotes for all non-LaTeX formats.  Here is another
sentence that ``caused'' a bug in the past because double backtick
quotes could imply verbatim text up to a verbatim word starting with
period, like \texttt{.txt}.

More quotes to be tested for spellcheck:
(``with parenthesis''), ``with newline''
and ``with comma'', ``hyphen''-wise, and ``period''.


\subsection{Bibliography test}

Here is an example: \cite{Langtangen_Pedersen_2002} discussed propagation of
large destructive water waves, \cite{Langtangen_et_al_2002} gave
an overview of numerical methods for solving the Navier--Stokes equations,
while the use of Backward Kolmogorov equations for analyzing
random vibrations was investigated in \cite{Langtangen_1994a}.
The book chapter \cite{Mardal_et_al_2003a} contains information on
C++ software tools for programming multigrid methods. A real retro
reference is \cite{Langtangen_1988d} about a big FORTRAN package.
Multiple references are also possible, e.g., see
\cite{Langtangen_Pedersen_2002,Mardal_et_al_2003a}.

We need to cite more than 10 papers to reproduce an old formatting
problem with blanks in the keys in reST format:
\cite{Langtangen_1992c,Langtangen_1994a,Mortensen_et_al_2011,Langtangen_Pedersen_2002}
and
\cite{Langtangen_et_al_2002,Glimsdal_et_al_20006,Rahman_et_al_2006b,Haga_et_al_2011a,Langtangen_2003a,Langtangen_2008a,Langtangen:95}
and all the work of
\cite{Langtangen_2012,Mardal_et_al_2003a,Jeberg_et_al_2004} as well as
old work \cite{Langtangen_1988d} and \cite{Langtangen_1989e}, and the
talk \cite{Langtangen_talk_2007a}.
Langtangen also had two thesis \cite{Langtangen:85,Langtangen_1989e}
back in the days.
More retro citations are
the old ME-IN323 book \cite{Langtangen:91} and the
\cite{Langtangen:94b} OONSKI '94 paper.




% --- begin exercise ---
\begin{doconceexercise}
\refstepcounter{doconceexercisecounter}

\exercisesection{Example \thedoconceexercisecounter: Examples can be typeset as exercises}
                             
\label{Example}

Examples can start with a subsection heading starting with \texttt{Example:}
and then, with the command-line option \Verb!--examples_as_exercises! be
typeset as exercises. This is useful if one has solution
environments as part of the example.


\subex{a)}
State some problem.

\paragraph{Solution.}
The answer to this subproblem can be written here.

\subex{b)}
State some other problem.

\paragraph{Hint 1.}
A hint can be given.

\paragraph{Hint 2.}
Maybe even another hint?

\paragraph{Solution.}
The answer to this other subproblem goes here,
maybe over multiple doconce input lines.

\end{doconceexercise}
% --- end exercise ---


\subsection{User-defined environments}



Example~\vref{ex:test:1p1} demonstrates how to write a test function.
That is, a special test function for a function \texttt{add} appears in
Example~\vref{ex:test:1p1}.


\begin{example}
\label{ex:test:1p1}

\noindent\emph{A test function}.

Suppose we want to write a test function for checking the
implementation of a Python function for addition.

\begin{cod}{cbg_blue1}\begin{lstlisting}[language=Python,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
def add(a, b):
    return a + b

def test_add():
    a = 1; b = 1
    expected = a + b
    computed = add(a, b)
    assert expected == computed
\end{lstlisting}\end{cod}
\noindent
\end{example}



\begin{example}
\label{ex:math:1p1}

\noindent\emph{Addition}.

We have

\[ 1 + 1 = 2 \]
or in tabular form:


\begin{quote}
\begin{tabular}{cc}
\hline
\multicolumn{1}{c}{ Problem } & \multicolumn{1}{c}{ Result } \\
\hline
$1+1$   & $2$    \\
\hline
\end{tabular}
\end{quote}

\noindent
\end{example}



\begin{tcolorbox}[%skin=widget,
boxrule=1mm,
coltitle=black,
colframe=blue!45!white,
colback=blue!15!white,
width=(.9\linewidth),before=\hfill,after=\hfill,
adjusted title={Highlight box!}]
This environment is used to highlight something:

\[ E = mc^2 \]
\end{tcolorbox}



\subsection{URLs}
\label{subsubsec:ex}

Testing of URLs: hpl's home page \href{{https://folk.uio.no/hpl}}{hpl}, or
the entire URL if desired, \href{{https://folk.uio.no/hpl}}{\nolinkurl{https://folk.uio.no/hpl}}.  Here is a
plain file link \href{{testdoc.do.txt}}{\nolinkurl{testdoc.do.txt}}, or \href{{testdoc.do.txt}}{\nolinkurl{testdoc.do.txt}}, or
\href{{testdoc.do.txt}}{\nolinkurl{testdoc.do.txt}} or \href{{testdoc.do.txt}}{\nolinkurl{testdoc.do.txt}} or \href{{testdoc.do.txt}}{a link with
newline}. Can test spaces with the link with word
too: \href{{https://folk.uio.no/hpl}}{hpl} or \href{{https://folk.uio.no/hpl}}{hpl}. Also \texttt{file:///} works: \href{{file:///home/hpl/vc/doconce/doc/demos/manual/manual.html}}{link to a
file} is
fine to have. Moreover, ``loose'' URLs work, i.e., no quotes, just
the plain URL as in \href{{https://folk.uio.no/hpl}}{\nolinkurl{https://folk.uio.no/hpl}}, if followed by space, comma,
colon, semi-colon, question mark, exclamation mark, but not a period
(which gets confused with the periods inside the URL).

Mail addresses can also be used: \href{{mailto:hpl@simula.no}}{\nolinkurl{hpl@simula.no}}, or just a \href{{mailto:hpl@simula.no}}{mail link}, or a raw \href{{mailto:hpl@simula.no}}{\nolinkurl{mailto:hpl@simula.no}}.

Here are some tough tests of URLs, especially for the \texttt{latex} format:
\href{{https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas}}{Newton-Cotes} formulas
and a \href{{https://www.springer.com/mathematics/computational+science+%26+engineering/book/978-3-642-23098-1}}{good book}. Need to test
Newton-Cotes with percentage in URL too:
\href{{https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas}}{\nolinkurl{https://en.wikipedia.org/wiki/Newton\%E2\%80\%93Cotes_formulas}}
and \href{{https://en.wikipedia.org/wiki/Newton-Cotes#Open_Newton.E2.80.93Cotes_formulae}}{\nolinkurl{https://en.wikipedia.org/wiki/Newton-Cotes\#Open_Newton.E2.80.93Cotes_formulae}} which has a shebang.

For the \texttt{--device=paper} option it is important to test that URLs with
monospace font link text get a footnote
(unless the \Verb!--latex_no_program_footnotelink!
is used), as in this reference to
\href{{https://github.com/hplgit/INF5620/tree/gh-pages/src/decay/experiments/decay_mod.py}}{\nolinkurl{decay_mod}}, \href{{https://tinyurl.com/pwyasaa/formulas.ball1.py}}{\nolinkurl{ball1.py}},
and \href{{https://tinyurl.com/pwyasaa/formulas.ball2.py}}{\nolinkurl{ball2.py}}.


% Comments should be inserted outside paragraphs (because in the rst
% format extra blanks make a paragraph break).

% Note that when there is no https: or file:, it can be a file link
% if the link name is URL, url, "URL", or "url". Such files should,
% if rst output is desired, but placed in a \Verb!_static*! folder.

More tough tests: repeated URLs whose footnotes when using the
\texttt{--device=paper} option must be correct. We have
\href{{https://google.com}}{google}, \href{{https://google.com}}{google}, and
\href{{https://google.com}}{google}, which should result in exactly three
footnotes.



\subsection{Test of Some {\LaTeX} Fixes}

Let's check abbr.~of some common kind, e.g.~the well-known i.e.
expression as an example, and 1 vs.~2 which is also often used.
Dr.~Tang and Prof.~Monsen, or maybe also prof.~Ting,
will go to the Dept.~of Science to test how Mr.~Hansen is doing together
with Ms.~Larsen. A reference like Sec.~\vref{subsubsec:ex} or
Ch.~\vref{subsubsec:ex}, or even App.~\vref{subsubsec:ex}, must also be
handled. Likewise, this is test no.~$i$ of DocOnce features.
Also, look at Fig.~4 to see how the data compares with Tab.~\vref{mytab}.
Percentage must be fixed: 7\%,  87.65\% and
50\% at the beginning of the line.


% !split and check if these extra words are included properly in the comment

\section{{\LaTeX} Mathematics}

Here is an equation without label using backslash-bracket environment:
\[ a = b + c \]

or with number and label, as in (\ref{my:eq1}), using the equation environment:

\begin{equation}
{\partial u\over\partial t} = \nabla^2 u \label{my:eq1}
\end{equation}

We can refer to this equation by (\ref{my:eq1}).

Here is a system without equation numbers, using the align-asterisk environment:

\begin{align*}
\pmb{a} &= \pmb{q}\times\pmb{n} \\ 
b &= \nabla^2 u + \nabla^4 v
\end{align*}


And here is a system of equations with labels in an align environment:

\begin{align}
a &= q + 4 + 5+ 6 \label{eq1} \\ 
b &= \nabla^2 u + \nabla^4 x \label{eq2}
\end{align}

We can refer to (\ref{eq1})-(\ref{eq2}). They are a bit simpler than
the Navier--Stokes equations. And test {\LaTeX} hyphen in \texttt{CG-2}.
Also test $a_{i-j}$ as well as $kx-wt$.

Testing \texttt{alignat} environment:

\begin{alignat}{2}
a &= q + 4 + 5+ 6\qquad & \mbox{for } q\geq 0 \label{eq1a} \\ 
b &= \nabla^2 u + \nabla^4 x & x\in\Omega \label{eq2a}
\end{alignat}

Many of the next environments will fail in non-latex formats.
Testing multiline:

\begin{multline}
a = b = q + \\ 
  f + \nabla\cdot\nabla u
\label{multiline:eq1}
\end{multline}

Testing split:

\begin{equation}
\label{split:envir:eq}
\begin{split}
a = b = q &+ \\ 
  & f + \nabla\cdot\nabla u
\end{split}
\end{equation}
We can refer to the last equation by (\ref{split:envir:eq}).

Testing gather:
\begin{gather}
a = b \\ 
c = d + 7 + 9
\end{gather}

Let us refer to (\ref{eq1})-(\ref{eq2}) again, and to the
alignat variant (\ref{eq1a})-(\ref{eq2a}), and to (\ref{my:eq1}).

Testing eqnarray:
\begin{eqnarray}
{\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{eqnarray}

More mathematical typesetting is demonstrated in the coming exercises.

Below, we have Problem~\vref{demo:ex:1} and Project~\vref{demo:ex:2},
as well as Projects~\vref{proj:circle1} and~\vref{exer:you}, and in
between there we have Exercise~\vref{exer:some:formula}.


\section{Exercises}



% --- begin exercise ---
\begin{doconceexercise}
\refstepcounter{doconceexercisecounter}

\exercisesection{Problem \thedoconceexercisecounter: Flip a Coin}
                             
\label{demo:ex:1}
% keywords = random numbers; Monte Carlo simulation; ipynb

% Torture tests


\subex{a)}
Make a program that simulates flipping a coin $N$ times.
Print out ``tail'' or ``head'' for each flip and
let the program count the number of heads.

% --- begin hint in exercise ---

\paragraph{Hint 1.}
Use \texttt{r = random.random()} and define head as \texttt{r <= 0.5}.

% --- end hint in exercise ---

% --- begin hint in exercise ---

\paragraph{Hint 2.}
Draw an integer among $\{1,2\}$ with
\texttt{r = random.randint(1,2)} and define head when \texttt{r} is 1.

% --- end hint in exercise ---


% --- begin answer of exercise ---
\paragraph{Answer.}
If the \texttt{random.random()} function returns a number $<1/2$, let it be
head, otherwise tail. Repeat this $N$ number of times.
% --- end answer of exercise ---


% --- begin solution of exercise ---
\paragraph{Solution.}
\begin{cod}{cbg_blue1}\begin{lstlisting}[language=Python,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
import sys, random
N = int(sys.argv[1])
heads = 0
for i in range(N):
    r = random.random()
    if r <= 0.5:
        heads += 1
print('Flipping a coin %d times gave %d heads' % (N, heads))
\end{lstlisting}\end{cod}
\noindent
% --- end solution of exercise ---

\subex{b)}
Vectorize the code in a) using boolean indexing.

Vectorized code can be written in many ways.
Sometimes the code is less intuitive, sometimes not.
At least there is not much to find in Section~\vref{sec1}.

\subex{c)}
Vectorize the code in a) using \texttt{numpy.sum}.


% --- begin answer of exercise ---
\paragraph{Answer.}
\texttt{np.sum(np.where(r <= 0.5, 1, 0))} or \texttt{np.sum(r <= 0.5)}.
% --- end answer of exercise ---

In this latter subexercise, we have an
example where the code is easy to read.


\paragraph{My remarks.}
Remarks with such a subsubsection is treated as more text
after the last subexercise. Test a list too:

\begin{enumerate}
\item Mark 1.

\item Mark 2.
\end{enumerate}

\noindent
\noindent Filenames: \Verb!flip_coin.py!, \Verb!flip_coin.pdf!.

% Closing remarks for this Problem

\paragraph{Remarks.}
These are the exercise remarks, appearing at the very end.

% solution files: mysol.txt, mysol_flip_coin.py, yet_another.file

\end{doconceexercise}
% --- end exercise ---


\subsection{Not an exercise}

Should be possible to stick a normal section in the middle of many
exercises.



% --- begin exercise ---
\begin{doconceexercise}
\refstepcounter{doconceexercisecounter}

\exercisesection{Exercise \thedoconceexercisecounter: Test of plain text exercise}
                             
\label{my:exer1}

Very short exercise. What is the capital
of Norway?
\noindent Filename: \texttt{myexer1}.

\end{doconceexercise}
% --- end exercise ---




% --- begin exercise ---
\begin{doconceexercise}
\refstepcounter{doconceexercisecounter}

\exercisesection{Project \thedoconceexercisecounter: Compute a Probability}
                             
\label{demo:ex:2}

% Minimalistic exercise


What is the probability of getting a number between 0.5 and 0.6 when
drawing uniformly distributed random numbers from the interval $[0,1)$?


At the end we have a list because that caused problems in {\LaTeX}
in previous DocOnce versions:

\begin{enumerate}
\item item1

\item item2
\end{enumerate}

\noindent
% --- begin hint in exercise ---

\paragraph{Hint.}
To answer this question empirically, let a program
draw $N$ such random numbers using Python's standard \texttt{random} module,
count how many of them, $M$, that fall in the interval $(0.5,0.6)$, and
compute the probability as $M/N$.

% --- end hint in exercise ---

\end{doconceexercise}
% --- end exercise ---




% --- begin exercise ---
\begin{doconceexercise}
\refstepcounter{doconceexercisecounter}

\exercisesection{Project \thedoconceexercisecounter: Explore Distributions of Random Circles}
                             
\label{proj:circle1}
% keywords = ipynb

The formula for a circle is given by

\begin{align}
x &= x_0 + R\cos 2\pi t,
\label{circle:x}\\ 
y &= y_0 + R\sin 2\pi t,
\label{circle:y}
\end{align}
where $R$ is the radius of the circle, $(x_0,y_0)$ is the
center point, and $t$ is a parameter in the unit interval $[0,1]$.
For any $t$, $(x,y)$ computed from (\ref{circle:x})-(\ref{circle:y})
is a point on the circle.
The formula can be used to generate \texttt{n} points on a circle:

\begin{pro}{cbg_blue1}{bar_blue1}\begin{lstlisting}[language=Python,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
import numpy as np

def circle(R, x0, y0, n=501):
    t = np.linspace(0, 1, n)
    x = x0 + R*np.cos(2*np.pi*t)
    y = y0 + R*np.sin(2*np.pi*t)
    return x, y

x, y = circle(2.0, 0, 0)
\end{lstlisting}\end{pro}
\noindent

% Often in an exercise we have some comments about the solution
% which we normally want to keep where they are.

The goal of this project is to draw $N$ circles with random
center and radius. Plot each circle using the \texttt{circle} function
above.


\subex{a)}
Let $R$ be normally distributed and $(x_0,y_0)$ uniformly distributed.

% --- begin hint in exercise ---

\paragraph{Hint.}
Use the \texttt{numpy.random} module to draw the
$x_0$, $y_0$, and $R$ quantities.

% --- end hint in exercise ---


% --- begin answer of exercise ---
\paragraph{Answer.}
Here goes the short answer to part a).
% --- end answer of exercise ---


% --- begin solution of exercise ---
\paragraph{Solution.}
Here goes a full solution to part a).
% --- end solution of exercise ---

\subex{b)}
Let $R$ be uniformly distributed and $(x_0,y_0)$ normally distributed.
\noindent Filename: \texttt{norm}.

\subex{c)}
Let $R$ and $(x_0,y_0)$ be normally distributed.


\noindent Filename: \texttt{circles}.

% Closing remarks for this Project

\paragraph{Remarks.}
At the very end of the exercise it may be appropriate to summarize
and give some perspectives.


\end{doconceexercise}
% --- end exercise ---




% --- begin exercise ---
\begin{doconceexercise}
\refstepcounter{doconceexercisecounter}

\exercisesection{Exercise \thedoconceexercisecounter: Determine some Distance}
                             
\label{exer:dist}

Intro to this exercise. Questions are in subexercises below.


% --- begin solution of exercise ---
\paragraph{Solution.}
Here goes a full solution of the whole exercise.
With some math $a=b$ in this solution:
\[ \hbox{math in solution: } a = b \]
And code \texttt{a=b} in this solution:
\begin{cod}{cbg_blue1}\begin{lstlisting}[language=Python,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
a = b  # code in solution
\end{lstlisting}\end{cod}
\noindent
End of solution is here.

% --- end solution of exercise ---


\subex{a)}
Subexercises are numbered a), b), etc.

% --- begin hint in exercise ---

\paragraph{Hint 1.}
First hint to subexercise a).
With math $a=b$ in hint:

\[ a=b. \]
And with code (in plain verbatim) returning $x+1$ in hint:

\begin{cod}{cbg_blue1}\begin{lstlisting}[language=Python,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
def func(x):
    return x + 1  # with code in hint
\end{lstlisting}\end{cod}
\noindent

% --- end hint in exercise ---

% --- begin hint in exercise ---

\paragraph{Hint 2.}
Second hint to subexercise a).

Test list in hint:

\begin{enumerate}
\item item1

\item item2
\end{enumerate}

\noindent
% --- end hint in exercise ---
\noindent Filename: \Verb!subexer_a.pdf!.


% --- begin answer of exercise ---
\paragraph{Answer.}
Short answer to subexercise a).
With math in answer: $a=b$.
% --- end answer of exercise ---

\subex{b)}
Here goes the text for subexercise b).


Some math $\cos^2 x + \sin^2 x = 1$ written one a single line:

\[ \cos^2 x + \sin^2 x = 1 \thinspace .\]

% --- begin hint in exercise ---

\paragraph{Hint.}
A hint for this subexercise.

% --- end hint in exercise ---
\noindent Filename: \Verb!subexer_b.pdf!.


% --- begin solution of exercise ---
\paragraph{Solution.}
Here goes the solution of this subexercise.
% --- end solution of exercise ---



% No meaning in this weired test example:
The text here belongs to the main (intro) part of the exercise. Need
closing remarks to have text after subexercises.

Test list in exercise:

\begin{enumerate}
\item item1

\item item2
% Closing remarks for this Exercise
\end{enumerate}

\noindent
\paragraph{Remarks.}
Some final closing remarks, e.g., summarizing the main findings
and their implications in other problems can be made. These
remarks will appear at the end of the typeset exercise.


\end{doconceexercise}
% --- end exercise ---




% --- begin exercise ---
\begin{doconceexercise}

\exercisesection{Some exercise without the "Exercise:" prefix}

% Another minimalistic exercise

Just some text. And some math saying that $e^0=1$ on a single line,
to test that math block insertion is correct:

\[ \exp{(0)} = 1 \]

And a test that the code \texttt{lambda x: x+2} is correctly placed here:

\begin{cod}{cbg_blue1}\begin{lstlisting}[language=Python,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
lambda x: x+2
\end{lstlisting}\end{cod}
\noindent


% Have some comments at the end of the exercise to see that
% the Filename: ... is written correctly.
\end{doconceexercise}
% --- end exercise ---




% --- begin exercise ---
\begin{doconceexercise}
\refstepcounter{doconceexercisecounter}

\exercisesection{Exercise \thedoconceexercisecounter: Solution of differential equation}
                             
\label{sec:this:exer:de}


\begin{doconcequiz}
\refstepcounter{doconcequizcounter}
\label{quiz:diff:eq1}


\noindent\textbf{\large SOlution of differential equation}

\noindent
Given

\[ \frac{dy}{dx} = -y(x),\quad y(0)=1 \]
What is the solution of this equation?

\vspace{2mm}

\textbf{A}. 
$y=e^{-y}$

\textbf{B}. 
$y=e^{y}$

\textbf{C}. 
\begin{cod}{cbg_blue1}\begin{lstlisting}[language=Python,style=myspeciallststyle,numbers=left,numberstyle=\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]
from math import exp
def f(x):
    return exp(x)
\end{lstlisting}\end{cod}
\noindent

\textbf{D}. 
The solution cannot be found because there is a derivative in the equation.

\textbf{E}. 
The equation is meaningless: an equation must be an equation
for $x$ or $y$, not a function $y(x)$.


% --- begin answer of exercise ---
\paragraph{Answer:} A.
% --- end answer of exercise ---

% --- begin solution of exercise ---
\noindent {\bf Solution:}\\


\textbf{A}: Right. 

\textbf{B}: Wrong. Almost, but the sign is wrong (note the minus!).

\textbf{C}: Wrong. Ooops, forgot a minus: \texttt{exp(-x)}, otherwise this Python code
must be considered as a good answer. It is more natural,
though, to write the solution to the problem
in mathematical notation:

\[ y(x) = e^{-y}.\]

\textbf{D}: Wrong. Equations with derivatives can be solved;
they are termed \emph{differential
equations}.

\textbf{E}: Wrong. Equations where the unknown is a function, as $y(x)$
here, are called \emph{differential equations}, and are solved by
special techniques.


% --- end solution of exercise ---


\vspace{3mm}

\end{doconcequiz}



\end{doconceexercise}
% --- end exercise ---




% --- begin exercise ---
\begin{doconceexercise}
\refstepcounter{doconceexercisecounter}

\exercisesection{Example \thedoconceexercisecounter: Just an example}
                             

% This example needs the --examples_as_exercises option, otherwise
% it is just typeset as it is written.


\subex{a)}
What is the capital of Norway?

\paragraph{Answer.}
Oslo.

\end{doconceexercise}
% --- end exercise ---


\section{Here goes another section}

With some text, before we continue with exercises.

\section{More Exercises}



% --- begin exercise ---
\begin{doconceexercise}
\refstepcounter{doconceexercisecounter}

\exercisesection{Exercise \thedoconceexercisecounter: Make references to projects and problems}
                             
\label{exer:some:formula}

% Test comments not at the end only
Pick a statement from Project~\vref{proj:circle1} or Problem~\vref{demo:ex:1}
and verify it.

Test list at the end of an exercise without other elements (like subexercise,
hint, etc.):

\begin{enumerate}
\item item1

\item item2
\end{enumerate}

\noindent
\noindent Filename: \Verb!verify_formula.py!.

\end{doconceexercise}
% --- end exercise ---




% --- begin exercise ---
\begin{doconceexercise}
\refstepcounter{doconceexercisecounter}

\exercisesection{Project \thedoconceexercisecounter: References to Project~\vref{demo:ex:2} in a heading works for pdflatex}
                             
\label{exer:you}

Refer to the previous exercise as Exercise~\vref{exer:some:formula},
the two before that as Projects~\vref{demo:ex:2} and~\vref{proj:circle1},
and this one as Project~\vref{exer:you}.
\noindent Filename: \Verb!selc_composed.pdf!.

\end{doconceexercise}
% --- end exercise ---




\bibliographystyle{plain}
\bibliography{papers}





\appendix

\section{Just for testing; part I}
\label{app1}

This is the first appendix.

\subsection{A subsection within an appendix}

Some text.

\section{Just for testing; part II}
\label{app2}

This is more stuff for an appendix.

\subsection{Appendix: Testing identical titles}

Without label.


\subsection{Appendix: Testing identical titles}
\label{test:title:id1}

With label.

\subsection{Appendix: Testing identical titles}
\label{test:title:id2}

What about inserting a quiz?


\begin{doconcequiz}
\refstepcounter{doconcequizcounter}
\label{quiz:2}


\noindent\textbf{\large Capital of Norway}
\paragraph{Fundamental test:}
What is the capital of Norway?

\vspace{2mm}

\textbf{A}. 
Stockholm

\textbf{B}. 
London

\textbf{C}. 
Oslo

\textbf{D}. 
Bergen


% --- begin answer of exercise ---
\paragraph{Answer:} C.
% --- end answer of exercise ---

% --- begin solution of exercise ---
\noindent {\bf Solution:}\\


\textbf{A}: Wrong. Stockholm is the capital of Sweden.

\textbf{B}: Wrong. 

\textbf{C}: Right. 

\textbf{D}: Wrong. Those from Bergen would claim so, but nobody else.


% --- end solution of exercise ---


\vspace{3mm}

\end{doconcequiz}




\subsection{Appendix: Testing identical titles}

Without label.


\begin{notice_mdfboxadmon}[Tip.]
Here is a tip or hint box, typeset as a notice box.
\end{notice_mdfboxadmon} % title: Tip.




\clearpage

Need a lot of text to surround the summary box.
Version control systems allow you to record the history of files
and share files among several computers and collaborators in a
professional way. File changes on one computer are updated or
merged with changes on another computer. Especially when working
with programs or technical reports it is essential
to have changes documented and to
ensure that every computer and person involved in the project
have the latest updates of the files.
Greg Wilson' excellent \href{{https://software-carpentry.org/2010/07/script-for-introduction-to-version-control/}}{Script for Introduction to Version Control} provides a more detailed motivation why you will benefit greatly
from using version control systems.


\begin{summary_mdfboxadmon}[Summary.]
\textbf{Bold remark:} Make some text with this summary.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
\end{summary_mdfboxadmon} % title: Summary.



Projects that you want to share among several computers or project
workers are today most conveniently stored at some web site "in the
cloud" and updated through communication with that site. I strongly
recommend you to use such sites for all serious programming and
scientific writing work - and all other important files.

The simplest services for hosting project files are \href{{https://dropbox.com}}{Dropbox} and \href{{https://drive.google.com}}{Google Drive}.
It is very easy to get started with these systems, and they allow you
to share files among laptops and mobile units with as many users as
you want. The systems offer a kind of version control in that the
files are stored frequently (several times per minute), and you can go
back to previous versions for the last 30 days. However, it is
challenging  to find the right version from the past when there are
so many of them.

More seriously, when several people may edit files simultaneously, it
can be difficult detect who did what when, roll back to previous
versions, and to manually merge the edits when these are
incompatible. Then one needs more sophisticated tools than Dropbox or
Google Drive: project hosting services with true version control
systems.  The following text aims at providing you with the minimum
information to started with such systems. Numerous other tutorials
contain more comprehensive material and in-depth explanations of the
concepts and tools.

The idea with project hosting services is that you have the files
associated with a project in the cloud. Many people may share these
files.  Every time you want to work on the project you explicitly
update your version of the files, edit the files as you like, and
synchronize the files with the "master version" at the site where the
project is hosted.  If you at some point need to go back to a
version of the files at some particular point in the past,
this is an easy operation. You can also use tools to see
what various people have done with the files in the various versions.

All these services are very similar. Below we describe how you get
started with Bitbucket, GitHub, and Googlecode. Launchpad works very
similarly to the latter three. All the project hosting services have
excellent introductions available at their web sites, but the recipes
below are much shorter and aim at getting you started as quickly as
possible by concentrating on the most important need-to-know steps.
The Git tutorials we refer to later in this document contain more
detailed information and constitute of course very valuable readings
when you use version control systems every day. The point now is
to get started.


\subsection{Appendix: Testing inline comments}

% Names can be [ A-Za-z0-9_'+-]+

Projects that you want to share among several computers or project
workers are today most conveniently stored at some web site "in the
cloud" and updated through communication with that
site. \shortinlinecomment{hpl's semi opinion 1}{ not sure if in the cloud is understood by all. }{ not sure if in } I strongly recommend you to use such sites for all serious
programming and scientific writing work - and all other important
files.

The simplest services for hosting project files is Dropbox. \longinlinecomment{mp 2}{ Simply go to \href{{https://dropbox.com}}{\nolinkurl{https://dropbox.com}} and watch the video. It explains how files, like \texttt{myfile.py}, perhaps containing much math, like $\partial u/\partial t$, are easily communicated between machines. }{ Simply go to \href{{https://dropbox.com}}{\nolinkurl{https://dropbox.com}} } It
is very easy to get started with Dropbox, and it allows you to share
files among \textcolor{red}{(hpl 3:)} \replace{laptops and mobile units}{computers, tablets, and phones}.

% Test horizontal rule

------

% Coments for editing

First\textcolor{red}{, (\textbf{edit 4}: add comma)} consider a quantity $Q$. \textcolor{red}{(edit 5:)} \replace{To this end,}{We note that}
$Q>0$, because (\textbf{edit 6}:) \remove{a} negative \textcolor{red}{(edit 7:)} \replace{quantity is}{quantities are} (\textbf{edit 8}:) \remove{just} negative.  \textcolor{red}{ (\textbf{edit 9}:) This comes as no surprise.}

% Test tailored latex figure references with page number
Let us refer to Figure~\vref{fig:impact} again.

Test references in a list:

\begin{itemize}
 \item \vref{sec1}

 \item \vref{subsec1}

 \item \vref{fig:impact}
\end{itemize}

\noindent
\subsection{Appendix: Testing headings ending with \texttt{verbatim inline} }

The point here is to test 1) \texttt{verbatim} code in headings, and 2)
ending a heading with verbatim code as this triggers a special
case in {\LaTeX}.

We also test mdash---used as alternative to hyphen without spaces around,
or in quotes:


\begin{quote}
\emph{Fun is fun}.---Unknown.
\end{quote}


The ndash should also be tested -- as in the Hanson--Nilson equations
on page 277--278.

And finally, what about admons, quotes, and boxes? They are tested
in a separate document: \texttt{admon.do.txt}.


% ------------------- end of main content ---------------

% #ifdef PREAMBLE
\cleardoublepage\phantomsection  % trick to get correct link to Index
\printindex

\end{document}
% #endif

************** File: testdoc.rst *****************

.. raw:: html

        <script type="text/x-mathjax-config">
        MathJax.Hub.Config({
          TeX: {
             equationNumbers: {  autoNumber: "AMS"  },
             extensions: ["AMSmath.js", "AMSsymbols.js", "autobold.js", "color.js"]
          }
        });
        </script>
        <script type="text/javascript" async
         src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
        </script>
        
        

.. Automatically generated reStructuredText file from DocOnce source
   (https://github.com/hplgit/doconce/)

.. |nbsp| unicode:: 0xA0
   :trim:

.. Document title:

A Document for Testing DocOnce
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

:Authors: Hans Petter Langtangen (hpl at simula.no), Kaare Dump, A. Dummy Author, I. S. Overworked and Outburned, J. Doe (j_doe at cyberspace.com)
:Date: Jan 32, 2100

Made with DocOnce

.. contents:: Table of contents
   :depth: 2

.. !split

The format of this document is
rst

*Abstract.* This is a document with many test constructions for doconce syntax.
It was used heavily for the development and kept for testing
numerous constructions, also special and less common cases.

And exactly for test purposes we have an extra line here, which
is part of the abstract.

.. Cannot demonstrate chapter headings since abstract and chapter

.. are mutually exclusive in LaTeX

.. _sec1:

Section 1
=========

Here is a nested list:

  * item1

  * item2

  * item3 which continues
    on the next line to test that feature

  * and a sublist

    * with indented subitem1

    * and a subitem2

  * and perhaps an ordered sublist

   a. first item

   b. second item,
      continuing on a new line

**Here is a list with paragraph heading.**

  * item1

  * item2

Here is a list with subsubsection heading
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  * item1

  * item2


..

    Here are two lines that make up
    a block quote for testing *emphasized words* and **boldface words**,
    also with hypens:
    *pre*-fix, post-*fix*, **pre**-fix, post-**fix**.



Here are two references. Equation |nbsp| (`my:eq1`_) is fine. Eq. |nbsp| (`my:eq1`_) too.
Even Equation (`my:eq1`_) without the tilde.

.. _subsec1:

Subsection 1
------------

.. Refer to section/appendix etc. at the beginning of the line

.. and other special fix situations for HTML.

More text, with a reference back to
the section `Section 1`_ and `Subsection 1`_, and further to the
the sections `Subsection 1`_ and `URLs`_, which
encourages you to do the tasks in `Problem 2: Flip a Coin`_ and `Exercise 10: Make references to projects and problems`_.
 `Appendix: Just for testing; part I`_ and `Appendix: Just for testing; part II`_ are also nice elements.

Test Section reference at beginning of line and after a sentence
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The section `Subsection 1`_ is fine.
The section `URLs`_ too.

.. sphinx code-blocks: pycod=python cod=fortran cppcod=c++ sys=console

Computer code
~~~~~~~~~~~~~

Let's do some copying from files too. First from subroutine up to the very end::

              subroutine test()
              integer i
              real*8 r
              r = 0
              do i = 1, i
                 r = r + i
              end do
              return
        C     END1
        
              program testme
              call test()
              return

and then just the subroutine::

        
              subroutine test()
              integer i
              real*8 r
              r = 0
              do i = 1, i
                 r = r + i
              end do
              return

and finally the complete file with a plain text verbatim environment
(``envir=ccq``)::

        C     a comment
        
              subroutine test()
              integer i
              real*8 r
              r = 0
              do i = 1, i
                 r = r + i
              end do
              return
        C     END1
        
              program testme
              call test()
              return

Testing other code environments. First Python::

        !bc pycod
        def f(x):
            return x+1
        !ec

which gets rendered as::

        def f(x):
            return x+1

Here is a program that is supposed to be interactive via
Python Online Tutorial, but that service is not accessible
for the present format::

        class Line:
            def __init__(self, a, b):
                self.a, self.b = a, b
        
            def __call__(self, x):
                a, b = self.a, self.b
                return a*x + b
        
        line = Line(2, 1)
        y = line(x=3)
        print(y)

Some more Python code (actually specified as a sage cell, but
such cells are not supported by this format)::

        a = 2
        b = 3
        print('a+b:', a + b)
        
        # In a sage cell we can also plot
        from matplotlib.pyplot import *
        from numpy import *
        x = linspace(0, 4*pi, 101)
        y = exp(-0.1*x)*cos(x)
        plot(x, y)
        xlabel('x'); ylabel('y')
        show()

Then Cython (with -h option so it is hidden in html/sphinx)::

        cpdef f(double x):
            return x + 1

Standard Python shell sessions::

        >>> from numpy import linspace, sin
        >>> # Some comment
        >>> x = linspace(0, 2, 11)
        >>> y = sin(x)
        >>> y[0]
        0
        >>> import matplotlib.pyplot as plt
        >>> plt.plot(x, y)

Similar IPython sessions::

        In [1]: from numpy import linspace, sin
        In [2]: # Some comment
        In [3]: x = linspace(0, 2, 11)
        In [4]: y = sin(x)
        In [5]: y[0]
        Out[5]: 0
        In [6]: import matplotlib.pyplot as plt
        In [7]: plt.plot(x, y)
        In [8]: a='multiple-\nline\noutput'
        In [9]: a
        Out[9]: 'multiple-\nline\noutput'
        In [10]: print(a)
        multiple-
        line
        output

Here is the interactive session again, but with ``pyshell-t``::

        >>> from numpy import linspace, sin
        >>> # Some comment
        >>> x = linspace(0, 2, 11)
        >>> y = sin(x)
        >>> y[0]
        0
        >>> import matplotlib.pyplot as plt
        >>> plt.plot(x, y)

.. This one tests a + sign before a code environment

C++::

        #include <iostream>
        
        int main()
        {
           std::cout << "Sample output" << std::endl;
           return 0
        }

.. The next should get correctly typset in sphinx (cod is fcod)

.. It also tests emoji before code

And a little bit of Fortran: :dizzy_face::

        !bc cod
              subroutine midpt(x, length, a, b)
              real*8 a, b, x
              x = (a + b)/2
              length = b - a
              return
              end
        !ec

which then is typeset as::

              subroutine midpt(x, length, a, b)
              real*8 a, b, x
              x = (a + b)/2
              length = b - a
              return
              end

HTML::

        <table>
        <tr><td>Column 1</td><td>Column 2</td></tr>
        <tr><td>0.67526 </td><td>0.92871 </td></tr>
        <!-- comment -->
        </table>

But inline HTML code is also important, like text that starts with
``<a href="`` (which can destroy the following text if not properly
quoted).

Matlab with comments requires special typesetting::

        % Comment on the beginning of the line can be escaped by %%
        if a > b
          % Indented comment needs this trick
          c = a + b
        end

And here is a system call::

        Terminal> mkdir test
        Terminal> cd test
        Terminal> myprog -f
        output1
        output2

Any valid pygments lexer/language name can appear to, e.g.::

        !bc restructuredtext
        =======
        Heading
        =======
        
        Some text.
        !ec

results in::

        =======
        Heading
        =======
        
        Some text.

.. Here goes hidden code.

.. Python can be treated by some formats, Fortran is always out.

Finally, ``!bc do`` supports highlighting of DocOnce source::

        ======= DocOnce test file =======
        
        ===== Computer code =====
        
        Inline verbatim code, as in `import numpy as np`, is allowed, as well as
        code blocks:
        
        !bc pycod
        from math import sin
        
        def f(x):
            """Example on a function."""
            return sin(x) + 1
        
        print(f(0))
        !ec
        
        
        ===== Mathematics =====
        
        Formulas can be inline, as in $\nabla\cdot\bm{u} = 0$, or typeset
        as equations:
        
        !bt
        \begin{align*}
        \nabla\cdot\bm{u} &= 0,\\ 
        \bm{u} &= \nabla\phi .
        \end{align*}
        !et
        
        === Subsubsection heading ===
        
        DocOnce files can have chapters, sections, subsections, and subsubsections.
        
        __Paragraph heading.__ Paragraphs may have headings.

It is time to test ``verbatim inline font`` especially with ``a newline
inside the text`` and an exclamation mark at the end: ``BEGIN``! For
spellcheck, test ``a verbatim expression`` in ``another`` in a ``third``.
Also test exclamation mark as in ``!bc`` and ``!ec`` as well as ``a != b``.
Also test backslashes and braces like ``\begin``, ``\begin{enumerate}``,
``\end{this}\end{that}``, and ``{something \inside braces}``.

The following attempt to exemplify colored text does not work in
format rst.
Here is some **red color** and an attempt to write **with
green color containing a linebreak

| code.** Some formats will only display 
| this correctly when ``html`` 
| is the output format.

But here some more running text is added which is not part of
the previous blocks with line breaks.

Running OS commands
~~~~~~~~~~~~~~~~~~~

        Terminal> python -c 'print("Testing\noutput\nfrom\nPython.")'
        Testing
        output
        from
        Python.

Footnotes
~~~~~~~~~

Here is a test of footnotes [#footnote]_, which are handy in text.
They are used in different flavors, now in

 * list items (note below that footnotes work after math, verbatim, and URLs - bin fact old and emphasize too!)

 * even with math \\( \nabla^2u \\) [#math1]_

 * and code ``h[i] += 1`` [#code]_
   (*must* have space between inline code and footnote!)

 * and `links <https://google.com>`__ [#google-search]_

which gives flexibility in writing.
This is the third [#example-of-the-third-footnote]_ example.

.. [#footnote] Typesetting of the footnote depends on the format.
   Plain text does nothing, LaTeX removes the
   definition and inserts the footnote as part of the LaTeX text.
   reStructuredText and Sphinx employ a similar type of typesetting
   as Extended Markdown and DocOnce, and in HTML we keep the same
   syntax, just displayed properly in HTML.

.. [#math1] Math footnotes can be dangerous since it
   interferes with an exponent.

.. [#code] One-line footnote.

.. [#google-search] `<google.com>`_ is perhaps the most famous
   web site today.

Here is some more text before a new definition of a footnote that was
used above.


.. admonition:: Non-breaking space character

   This paragraph aims to test `non-breaking space character <https://en.wikipedia.org/wiki/Non-breaking_space>`__, and a typical
   example where this is needed is in physical units: 7.4 |nbsp| km is traveled
   in |nbsp| \\( 7.4/5.5\approx 1.345 \\) |nbsp| s.  Also check that a |nbsp| `link <https://google.com>`__ |nbsp| is
   not broken across lines (drag the browser window to test this).
   (On the other hand, the tilde is used in
   computer code, e.g., as in ``[~x for x in y]`` or in ``y=~x``, and should
   of course remain a tilde in those contexts.)




.. _subsec:ex:

Subsection 2: Testing figures
-----------------------------

Test of figures. In particular we refer to Figure `fig:impact`_ in which
there is a flow.

.. _fig:impact:

.. figure:: ../doc/src/manual/fig/wave1D.png
   :width: 200

   *Visualization **of** a *wave**  (fig:impact)

Figures without captions are allowed and will be inlined.

.. figure:: ../doc/src/manual/fig/wave1D.png
   :width: 200

.. Test multi-line caption in figure with sidecap=True

Here is figure `myfig`_ with a long (illegal) multi-line caption
containing inline verbatim text:

.. _myfig:

.. figure:: ../doc/src/manual/fig/wave1D.png
   :width: 500

   *A long caption spanning several lines and containing verbatim words like ``my_file_v1`` and ``my_file_v2`` as well as math with subscript as in $t_{i+1}$*  (myfig)

.. Must be a blank line after MOVIE or FIGURE to detect this problem

Test URL as figure name:

.. figure:: https://raw.github.com/doconce/doconce/master/doc/src/blog/f_plot.png
   :width: 500

.. Test wikimedia type of files that otherwise reside in subdirs

**Remark.**
Movies are tested in separate file ``movies.do.txt``.

.. Somewhat challenging heading with latex math, \t, \n, ? and parenthesis

.. _decay:sec:theta:

The \\( \theta \\) parameter (not \\( \nabla \\)?)
--------------------------------------------------

Functions do not always need to be advanced, here is one
involving \\( \theta \\)::

        def f(theta):
            return theta**2

**More on \\( \theta \\).**
Here is more text following headline with math.

Newcommands must also be tested in this test report:
\\( \frac{1}{2} \\), \\( {1/2} \\), \\( \pmb{x} \\), \\( \frac{Du}{dt} \\),
both inline and in block

.. raw:: html

        $$
        \begin{align}
        \frac{Du}{dt} &= 0\nonumber
        \\ 
        \frac{1}{2} &= {1/2}\\ 
        \frac{1}{2}\pmb{x} &= \pmb{n}
        \end{align}
        $$

Or with align with label and numbers

.. raw:: html

        $$
        \begin{align}
        \frac{Du}{dt} &= 0
        \label{aligneq1}
        \\ 
        \frac{1}{2} &= {1/2}\\ 
        \frac{1}{2}\pmb{x} &= \pmb{n}
        \label{aligneq2}
        \end{align}
        $$

.. Must test more complicated align and matrix compositions

.. where DocOnce inserts auto-numbered labels etc.

First one numbered (automatically)

.. raw:: html

        $$
        \begin{align}
        \begin{pmatrix}
        G_2 + G_3 & -G_3 & -G_2 & 0 \\ 
        -G_3 & G_3 + G_4 & 0 & -G_4 \\ 
        -G_2 & 0 & G_1 + G_2 & 0 \\ 
        0 & -G_4 & 0 & G_4
        \end{pmatrix}
        &=
        \begin{pmatrix}
         v_1 \\ 
         v_2 \\ 
         v_3 \\ 
         v_4
        \end{pmatrix}
        + \cdots \\ 
        \begin{pmatrix}
         C_5 + C_6 & -C_6 & 0 & 0 \\ 
         -C_6 & C_6 & 0 & 0 \\ 
         0 & 0 & 0 & 0 \\ 
         0 & 0 & 0 & 0
        \end{pmatrix}
          &= \frac{d}{dt}\begin{pmatrix}
         v_1 \\ 
         v_2 \\ 
         v_3 \\ 
         v_4
        \end{pmatrix} +
        \begin{pmatrix}
         0 \\ 
         0 \\ 
         0 \\ 
         -i_0
        \end{pmatrix}
        \nonumber
        \end{align}
        $$

Second numbered (automatically)

.. raw:: html

        $$
        \begin{align}
        \begin{pmatrix}
        G_1 + G_2\\ 
        -G_3 & G_4
        \end{pmatrix}
        &=
        \begin{pmatrix}
         v_1 \\ 
         v_2
        \end{pmatrix}
        + \cdots\nonumber
        \\ 
        \left(\begin{array}{ll}
        y & 2\\ 
        2 & 1
        \end{array}\right)
        \left(\begin{array}{ll}
        0 \\ x
        \end{array}\right)
        &= \begin{pmatrix}
        A \\ B
        \end{pmatrix}
        \end{align}
        $$

Both numbered, with label by the user

.. raw:: html

        $$
        \begin{align}
        \begin{pmatrix}
        G_1 + G_2\\ 
        -G_3 & G_4
        \end{pmatrix}
        &=
        \begin{pmatrix}
         v_1 \\ 
         v_2
        \end{pmatrix}
        + \cdots \label{mymatrix:eq1}
        \\ 
        \label{mymatrix:eq2}
        \left(\begin{array}{ll}
        y & 2\\ 
        2 & 1
        \end{array}\right)
        \left(\begin{array}{ll}
        0 \\ x
        \end{array}\right)
        &= \begin{pmatrix}
        A \\ B
        \end{pmatrix}
        \end{align}
        $$

Now we refer to Equations (mymatrix:eq1)-(mymatrix:eq2).

Custom Environments
-------------------

Here is an attempt to create a theorem environment via Mako
(for counting theorems) and comment lines to help replacing lines in
the ``.tex`` by proper begin-end LaTeX environments for theorems.
Should look nice in most formats!

.. begin theorem

**Theorem 5.**
Let \\( a=1 \\) and \\( b=2 \\). Then \\( c=3 \\).

.. end theorem

.. begin proof

**Proof.**
Since \\( c=a+b \\), the result follows from straightforward addition.
\\( \Diamond \\)

.. end proof

As we see, the proof of Theorem 5 is a modest
achievement.

.. _subsec:table:

Tables
------

.. index with comma could fool sphinx

Let us take this table from the manual:

====  ========  ============  
time  velocity  acceleration  
====  ========  ============  
0.0     1.4186         -5.01  
2.0   1.376512        11.919  
4.0     1.1E+1     14.717624  
====  ========  ============  

The DocOnce source code reads::

        
          |--------------------------------|
          |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    |
          |--------------------------------|
        

Here is yet another table to test that we can handle more than
one table:

====  ========  ============  
time  velocity  acceleration  
====  ========  ============  
0.0   1.4186    -5.01         
1.0   1.376512  11.919        
3.0   1.1E+1    14.717624     
====  ========  ============  

And one with math headings (that are expanded and must be treated
accordingly), verbatim heading and entry, and no space around the pipe
symbol:

=========  ===========  ================  =======  
\\( i \\)  \\( h_i \\)  \\( \bar T_i \\)  ``L_i``  
=========  ===========  ================  =======  
0                    0               288  -0.0065  
1               11,000               216      0.0  
2               20,000               216    0.001  
3               32,000               228   0.0028  
4               47,000               270      0.0  
5               51,000               270  -0.0028  
6               71,000               214  ``NaN``  
=========  ===========  ================  =======  

And add one with verbatim headings (with underscores),
and rows starting with ``|-`` because of a negative number,
and ``|`` right before and after verbatim word (with no space):

=====  =======  =====================  ===========  
exact  ``v_1``  \\( a_i \\) + ``v_2``  ``verb_3_``  
=====  =======  =====================  ===========  
    9     9.62                   5.57         8.98  
  -20   -23.39                  -7.65       -19.93  
   10    17.74                  -4.50         9.96  
    0    -9.19                   4.13        -0.26  
=====  =======  =====================  ===========  

Pipe symbols in verbatim and math text in tables used to pose difficulties,
but not
anymore:

===============  ===============  
   \\( S \\)         command      
===============  ===============  
$ ||a_0|| $      ``norm|length``  
\\( x\cap y \\)          ``x|y``  
===============  ===============  

Here is a table with X alignment:

=====  ==========================================================================================================================================================================================================================  
 Type                                                                                                         Description                                                                                                          
=====  ==========================================================================================================================================================================================================================  
  X    Alignment character that is used for specifying a potentially very long text in a column in a table. It makes use of the ``tabularx`` package in LaTeX, otherwise (for other formats) it means ``l`` (centered alignment).  
l,r,c  standard alignment characters                                                                                                                                                                                               
=====  ==========================================================================================================================================================================================================================  

Finally, a table with math
(``bm`` that expands to ``boldsymbol``, was tricky, but
cleanly handled now)
and URLs.

.. Mako code to expand URLs in the table

.. (These types of tables did not work before Jan 2014)

=============================  ==========================================================  ==========================================================  
                                                                                                                                                       
=============================  ==========================================================  ==========================================================  
    \\( \mathcal{L}=0 \\)      `080 <../doc/src/manual/mov/wave_frames/frame_0080.png>`__  `085 <../doc/src/manual/mov/wave_frames/frame_0085.png>`__  
         \\( a=b \\)           `090 <../doc/src/manual/mov/wave_frames/frame_0090.png>`__  `095 <../doc/src/manual/mov/wave_frames/frame_0095.png>`__  
\\( \nabla\cdot\bm{u} =0  \\)  `100 <../doc/src/manual/mov/wave_frames/frame_0100.png>`__  `105 <../doc/src/manual/mov/wave_frames/frame_0105.png>`__  
=============================  ==========================================================  ==========================================================  

A test of verbatim words in heading with subscript \\( a_i \\): ``my_file_v1`` and ``my_file_v2``
-------------------------------------------------------------------------------------------------

**Paragraph with verbatim and math: ``my_file_v1.py`` and ``my_file_v2.py`` define some math \\( a_{i-1} \\).**
Here is more ``__verbatim__`` code and
some plain text on a new line.

.. Test various types of headlines

**Just bold**
-------------

Some text.

*Just emphasize*
----------------

Some text.

``Just verbatim``
-----------------

Some text.

**Bold** beginning
------------------

Some text.

*Emphasize* beginning
---------------------

Some text.

``Verbatim`` beginning
----------------------

Some text.

Maybe **bold end**
------------------

Some text.

Maybe *emphasize end*
---------------------

Some text.

Maybe ``verbatim end``
----------------------

Some text.

The middle has **bold** word
----------------------------

Some text.

The middle has *emphasize* word
-------------------------------

Some text.

The middle has ``verbatim`` word
--------------------------------

Some text.

***Just emphasize*.**
Some text.

**``Just verbatim``.**
Some text.

***Emphasize* beginning.**
Some text.

**``Verbatim beginning``.**
Some text.

**Maybe *emphasize end*.**
Some text.

**Maybe ``verbatim end``.**
Some text.

**The middle has *emphasize* word.**
Some text.

**The middle has ``verbatim`` word.**
Some text.

**Ampersand.**
We can test Hennes & Mauritz, often abbreviated H&M, but written
as ``Hennes & Mauritz`` and ``H & M``.
A sole ``&`` must also work.

.. Note: substitutions must not occur inside verbatim, just in ordinary text::

        # Just to check that ampersand works in code blocks:
        c = a & b

**Quotes.**
Let us also add a test of quotes such as "double quotes, with numbers
like 3.14 and newline/comma and hyphen (as in double-quote)"; written
in the standard LaTeX-style that gives correct LaTeX formatting and
ordinary double quotes for all non-LaTeX formats.  Here is another
sentence that "caused" a bug in the past because double backtick
quotes could imply verbatim text up to a verbatim word starting with
period, like ``.txt``.

More quotes to be tested for spellcheck:
("with parenthesis"), "with newline"
and "with comma", "hyphen"-wise, and "period".

Bibliography test
-----------------

Here is an example: [Ref01]_ discussed propagation of
large destructive water waves, [Ref02]_ gave
an overview of numerical methods for solving the Navier - Stokes equations,
while the use of Backward Kolmogorov equations for analyzing
random vibrations was investigated in [Ref03]_.
The book chapter [Ref04]_ contains information on
C++ software tools for programming multigrid methods. A real retro
reference is [Ref05]_ about a big FORTRAN package.
Multiple references are also possible, e.g., see
[Ref01]_ [Ref04]_.

We need to cite more than 10 papers to reproduce an old formatting
problem with blanks in the keys in reST format:
[Ref06]_ [Ref03]_ [Ref07]_ [Ref01]_
and
[Ref02]_ [Ref08]_ [Ref09]_ [Ref10]_ [Ref11]_ [Ref12]_ [Ref13]_
and all the work of
[Ref14]_ [Ref04]_ [Ref15]_ as well as
old work [Ref05]_ and [Ref16]_, and the
talk [Ref17]_.
Langtangen also had two thesis [Ref18]_ [Ref16]_
back in the days.
More retro citations are
the old ME-IN323 book [Ref19]_ and the
[Ref20]_ OONSKI '94 paper.

.. --- begin exercise ---

.. _Example:

Example 1: Examples can be typeset as exercises
-----------------------------------------------

Examples can start with a subsection heading starting with ``Example:``
and then, with the command-line option ``--examples_as_exercises`` be
typeset as exercises. This is useful if one has solution
environments as part of the example.

**a)**
State some problem.

**Solution.**
The answer to this subproblem can be written here.

**b)**
State some other problem.

**Hint 1.**
A hint can be given.

**Hint 2.**
Maybe even another hint?

**Solution.**
The answer to this other subproblem goes here,
maybe over multiple doconce input lines.

.. --- end exercise ---

User-defined environments
-------------------------

The example in the section `Example 1: A test function`_ demonstrates how to write a test function.
That is, a special test function for a function ``add`` appears in
the example in the section `Example 1: A test function`_.

.. _ex:test:1p1:

Example 1: A test function
--------------------------

Suppose we want to write a test function for checking the
implementation of a Python function for addition::

        def add(a, b):
            return a + b
        
        def test_add():
            a = 1; b = 1
            expected = a + b
            computed = add(a, b)
            assert expected == computed

.. _ex:math:1p1:

Example 2: Addition
-------------------

We have

.. raw:: html

        $$ 1 + 1 = 2 $$

or in tabular form:

===========  =========  
  Problem      Result   
===========  =========  
\\( 1+1 \\)  \\( 2 \\)  
===========  =========  


.. admonition:: Highlight box

   This environment is used to highlight something
   
   .. raw:: html
   
           $$ E = mc^2 $$




.. _subsubsec:ex:

URLs
----

Testing of URLs: hpl's home page `hpl <https://folk.uio.no/hpl>`__, or
the entire URL if desired, `<https://folk.uio.no/hpl>`_.  Here is a
plain file link `<testdoc.do.txt>`_, or `<testdoc.do.txt>`_, or
`<testdoc.do.txt>`_ or `<testdoc.do.txt>`_ or `a link with
newline <testdoc.do.txt>`__. Can test spaces with the link with word
too: `hpl <https://folk.uio.no/hpl>`__ or `hpl <https://folk.uio.no/hpl>`__. Also ``file:///`` works: `link to a
file <file:///home/hpl/vc/doconce/doc/demos/manual/manual.html>`__ is
fine to have. Moreover, "loose" URLs work, i.e., no quotes, just
the plain URL as in `<https://folk.uio.no/hpl>`_, if followed by space, comma,
colon, semi-colon, question mark, exclamation mark, but not a period
(which gets confused with the periods inside the URL).

Mail addresses can also be used: `hpl@simula.no <mailto:hpl@simula.no>`__, or just a `mail link <mailto:hpl@simula.no>`__, or a raw `<mailto:hpl@simula.no>`_.

Here are some tough tests of URLs, especially for the ``latex`` format:
`Newton-Cotes <https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas>`__ formulas
and a `good book <https://www.springer.com/mathematics/computational+science+%26+engineering/book/978-3-642-23098-1>`__. Need to test
Newton-Cotes with percentage in URL too:
`<https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas>`_
and `<https://en.wikipedia.org/wiki/Newton-Cotes#Open_Newton.E2.80.93Cotes_formulae>`_ which has a shebang.

For the ``--device=paper`` option it is important to test that URLs with
monospace font link text get a footnote
(unless the ``--latex_no_program_footnotelink``
is used), as in this reference to
`decay_mod <https://github.com/hplgit/INF5620/tree/gh-pages/src/decay/experiments/decay_mod.py>`__, `ball1.py <https://tinyurl.com/pwyasaa/formulas.ball1.py>`__,
and `ball2.py <https://tinyurl.com/pwyasaa/formulas.ball2.py>`__.

.. Comments should be inserted outside paragraphs (because in the rst

.. format extra blanks make a paragraph break).

.. Note that when there is no https: or file:, it can be a file link

.. if the link name is URL, url, "URL", or "url". Such files should,

.. if rst output is desired, but placed in a ``_static*`` folder.

More tough tests: repeated URLs whose footnotes when using the
``--device=paper`` option must be correct. We have
`google <https://google.com>`__, `google <https://google.com>`__, and
`google <https://google.com>`__, which should result in exactly three
footnotes.

.. !split and check if these extra words are included properly in the comment

LaTeX Mathematics
=================

Here is an equation without label using backslash-bracket environment

.. raw:: html

        $$ a = b + c $$

or with number and label, as in Equation (my:eq1), using the equation environment

.. raw:: html

        $$
        \begin{equation}
        {\partial u\over\partial t} = \nabla^2 u \label{my:eq1}
        \end{equation}
        $$

We can refer to this equation by Equation (my:eq1).

Here is a system without equation numbers, using the align-asterisk environment

.. raw:: html

        $$
        \begin{align*}
        \pmb{a} &= \pmb{q}\times\pmb{n} \\ 
        b &= \nabla^2 u + \nabla^4 v
        \end{align*}
        $$

More mathematical typesetting is demonstrated in the coming exercises.

Below, we have `Problem 2: Flip a Coin`_ and `Project 4: Compute a Probability`_,
as well as `Project 5: Explore Distributions of Random Circles`_ and `Project 11: References in a headings do not work well in rst`_, and in
between there we have `Exercise 10: Make references to projects and problems`_.

Exercises
=========

.. --- begin exercise ---

.. _demo:ex:1:

Problem 2: Flip a Coin
----------------------

.. keywords = random numbers; Monte Carlo simulation; ipynb

.. Torture tests

**a)**
Make a program that simulates flipping a coin \\( N \\) times.
Print out "tail" or "head" for each flip and
let the program count the number of heads.

.. --- begin hint in exercise ---

**Hint 1.**
Use ``r = random.random()`` and define head as ``r <= 0.5``.

.. --- end hint in exercise ---

.. --- begin hint in exercise ---

**Hint 2.**
Draw an integer among \\( \{1,2\} \\) with
``r = random.randint(1,2)`` and define head when ``r`` is 1.

.. --- end hint in exercise ---

.. --- begin answer of exercise ---

**Answer.**
If the ``random.random()`` function returns a number \\( <1/2 \\), let it be
head, otherwise tail. Repeat this \\( N \\) number of times.

.. --- end answer of exercise ---

.. --- begin solution of exercise ---

**Solution.**::

        import sys, random
        N = int(sys.argv[1])
        heads = 0
        for i in range(N):
            r = random.random()
            if r <= 0.5:
                heads += 1
        print('Flipping a coin %d times gave %d heads' % (N, heads))

.. --- end solution of exercise ---

**b)**
Vectorize the code in a) using boolean indexing.

Vectorized code can be written in many ways.
Sometimes the code is less intuitive, sometimes not.
At least there is not much to find in the section `Section 1`_.

**c)**
Vectorize the code in a) using ``numpy.sum``.

.. --- begin answer of exercise ---

**Answer.**
``np.sum(np.where(r <= 0.5, 1, 0))`` or ``np.sum(r <= 0.5)``.

.. --- end answer of exercise ---

In this latter subexercise, we have an
example where the code is easy to read.

My remarks
~~~~~~~~~~

Remarks with such a subsubsection is treated as more text
after the last subexercise. Test a list too:

1. Mark 1.

2. Mark 2.

Filenames: ``flip_coin.py``, ``flip_coin.pdf``.

.. Closing remarks for this Problem

Remarks          (1)
~~~~~~~~~~~~~~~~~~~~

These are the exercise remarks, appearing at the very end.

.. solution files: mysol.txt, mysol_flip_coin.py, yet_another.file

.. --- end exercise ---

Not an exercise
---------------

Should be possible to stick a normal section in the middle of many
exercises.

.. --- begin exercise ---

.. _my:exer1:

Exercise 3: Test of plain text exercise
---------------------------------------

Very short exercise. What is the capital
of Norway?
Filename: ``myexer1``.

.. --- end exercise ---

.. --- begin exercise ---

.. _demo:ex:2:

Project 4: Compute a Probability
--------------------------------

.. Minimalistic exercise

What is the probability of getting a number between 0.5 and 0.6 when
drawing uniformly distributed random numbers from the interval \\( [0,1) \\)?

At the end we have a list because that caused problems in LaTeX
in previous DocOnce versions:

1. item1

2. item2

.. --- begin hint in exercise ---

**Hint.**
To answer this question empirically, let a program
draw \\( N \\) such random numbers using Python's standard ``random`` module,
count how many of them, \\( M \\), that fall in the interval \\( (0.5,0.6) \\), and
compute the probability as \\( M/N \\).

.. --- end hint in exercise ---

.. --- end exercise ---

.. --- begin exercise ---

.. _proj:circle1:

Project 5: Explore Distributions of Random Circles
--------------------------------------------------

.. keywords = ipynb

The formula for a circle is given by

.. raw:: html

        $$
        \begin{align}
        x &= x_0 + R\cos 2\pi t,
        \label{circle:x}\\ 
        y &= y_0 + R\sin 2\pi t,
        \label{circle:y}
        \end{align}
        $$

where \\( R \\) is the radius of the circle, \\( (x_0,y_0) \\) is the
center point, and \\( t \\) is a parameter in the unit interval \\( [0,1] \\).
For any \\( t \\), \\( (x,y) \\) computed from Equations (circle:x)-(circle:y)
is a point on the circle.
The formula can be used to generate ``n`` points on a circle::

        import numpy as np
        
        def circle(R, x0, y0, n=501):
            t = np.linspace(0, 1, n)
            x = x0 + R*np.cos(2*np.pi*t)
            y = y0 + R*np.sin(2*np.pi*t)
            return x, y
        
        x, y = circle(2.0, 0, 0)

.. Often in an exercise we have some comments about the solution

.. which we normally want to keep where they are.

The goal of this project is to draw \\( N \\) circles with random
center and radius. Plot each circle using the ``circle`` function
above.

**a)**
Let \\( R \\) be normally distributed and \\( (x_0,y_0) \\) uniformly distributed.

.. --- begin hint in exercise ---

**Hint.**
Use the ``numpy.random`` module to draw the
\\( x_0 \\), \\( y_0 \\), and \\( R \\) quantities.

.. --- end hint in exercise ---

.. --- begin answer of exercise ---

**Answer.**
Here goes the short answer to part a).

.. --- end answer of exercise ---

.. --- begin solution of exercise ---

**Solution.**
Here goes a full solution to part a).

.. --- end solution of exercise ---

**b)**
Let \\( R \\) be uniformly distributed and \\( (x_0,y_0) \\) normally distributed.
Filename: ``norm``.

**c)**
Let \\( R \\) and \\( (x_0,y_0) \\) be normally distributed.

Filename: ``circles``.

.. Closing remarks for this Project

Remarks          (2)
~~~~~~~~~~~~~~~~~~~~

At the very end of the exercise it may be appropriate to summarize
and give some perspectives.

.. --- end exercise ---

.. --- begin exercise ---

.. _exer:dist:

Exercise 6: Determine some Distance
-----------------------------------

Intro to this exercise. Questions are in subexercises below.

.. --- begin solution of exercise ---

**Solution.**
Here goes a full solution of the whole exercise.
With some math \\( a=b \\) in this solution

.. raw:: html

        $$ \hbox{math in solution: } a = b $$

And code ``a=b`` in this solution::

        a = b  # code in solution

End of solution is here.

.. --- end solution of exercise ---

**a)**
Subexercises are numbered a), b), etc.

.. --- begin hint in exercise ---

**Hint 1.**
First hint to subexercise a).
With math \\( a=b \\) in hint

.. raw:: html

        $$ a=b. $$

And with code (in plain verbatim) returning \\( x+1 \\) in hint::

        def func(x):
            return x + 1  # with code in hint

.. --- end hint in exercise ---

.. --- begin hint in exercise ---

**Hint 2.**
Second hint to subexercise a).

Test list in hint:

1. item1

2. item2

.. --- end hint in exercise ---

Filename: ``subexer_a.pdf``.

.. --- begin answer of exercise ---

**Answer.**
Short answer to subexercise a).
With math in answer: \\( a=b \\).

.. --- end answer of exercise ---

**b)**
Here goes the text for subexercise b).

Some math \\( \cos^2 x + \sin^2 x = 1 \\) written one a single line

.. raw:: html

        $$ \cos^2 x + \sin^2 x = 1 \thinspace .$$

.. --- begin hint in exercise ---

**Hint.**
A hint for this subexercise.

.. --- end hint in exercise ---

Filename: ``subexer_b.pdf``.

.. --- begin solution of exercise ---

**Solution.**
Here goes the solution of this subexercise.

.. --- end solution of exercise ---

.. No meaning in this weired test example:

The text here belongs to the main (intro) part of the exercise. Need
closing remarks to have text after subexercises.

Test list in exercise:

1. item1

2. item2

.. Closing remarks for this Exercise

Remarks          (3)
~~~~~~~~~~~~~~~~~~~~

Some final closing remarks, e.g., summarizing the main findings
and their implications in other problems can be made. These
remarks will appear at the end of the typeset exercise.

.. --- end exercise ---

.. --- begin exercise ---

Some exercise without the "Exercise:" prefix
--------------------------------------------

.. Another minimalistic exercise

Just some text. And some math saying that \\( e^0=1 \\) on a single line,
to test that math block insertion is correct

.. raw:: html

        $$ \exp{(0)} = 1 $$

And a test that the code ``lambda x: x+2`` is correctly placed here::

        lambda x: x+2

.. Have some comments at the end of the exercise to see that

.. the Filename: ... is written correctly.

.. --- end exercise ---

.. --- begin exercise ---

.. _sec:this:exer:de:

Exercise 8: Solution of differential equation
---------------------------------------------



.. begin quiz

Given

.. raw:: html

        $$ \frac{dy}{dx} = -y(x),\quad y(0)=1 $$

What is the solution of this equation?


**Choice A:** \\( y=e^{-y} \\)

:abbr:`? (Right!)`

**Choice B:** \\( y=e^{y} \\)

:abbr:`? (Wrong!)` :abbr:`# (Almost, but the sign is wrong (note the minus!).)`

**Choice C:** Code::

        from math import exp
        def f(x):
            return exp(x)

:abbr:`? (Wrong!)` :abbr:`# (Ooops, forgot a minus: exp(-x), otherwise this Python code must be considered as a good answer. It is more natural, though, to write the solution to the problem in mathematical notation  .. raw:: html          $$ y(x) = e^{-y}.$$)`

**Choice D:** The solution cannot be found because there is a derivative in the equation.

:abbr:`? (Wrong!)` :abbr:`# (Equations with derivatives can be solved; they are termed *differential equations*.)`

**Choice E:** The equation is meaningless: an equation must be an equation
for \\( x \\) or \\( y \\), not a function \\( y(x) \\).

:abbr:`? (Wrong!)` :abbr:`# (Equations where the unknown is a function, as \\( y(x) \\) here, are called *differential equations*, and are solved by special techniques.)`

.. end quiz



.. --- end exercise ---

.. --- begin exercise ---

Example 9: Just an example
--------------------------

.. This example needs the --examples_as_exercises option, otherwise

.. it is just typeset as it is written.

**a)**
What is the capital of Norway?

**Answer.**
Oslo.

.. --- end exercise ---

Here goes another section
=========================

With some text, before we continue with exercises.

More Exercises
==============

.. --- begin exercise ---

.. _exer:some:formula:

Exercise 10: Make references to projects and problems
-----------------------------------------------------

.. Test comments not at the end only

Pick a statement from `Project 5: Explore Distributions of Random Circles`_ or `Problem 2: Flip a Coin`_
and verify it.

Test list at the end of an exercise without other elements (like subexercise,
hint, etc.):

1. item1

2. item2

Filename: ``verify_formula.py``.

.. --- end exercise ---

.. --- begin exercise ---

.. _exer:you:

Project 11: References in a headings do not work well in rst
------------------------------------------------------------

Refer to the previous exercise as `Exercise 10: Make references to projects and problems`_,
the two before that as `Project 4: Compute a Probability`_ and `Project 5: Explore Distributions of Random Circles`_,
and this one as `Project 11: References in a headings do not work well in rst`_.
Filename: ``selc_composed.pdf``.

.. --- end exercise ---

References
==========

.. [Ref01]
   **H. P. Langtangen and G. Pedersen**. Propagation of Large Destructive Waves,
   *International Journal of Applied Mechanics and Engineering*,
   7(1),
   pp. 187-204,
   2002.

.. [Ref02]
   **H. P. Langtangen, K.-A. Mardal and R. Winther**. Numerical Methods for Incompressible Viscous Flow,
   *Advances in Water Resources*,
   25,
   pp. 1125-1146,
   2002.

.. [Ref03]
   **H. P. Langtangen**. Numerical Solution of First Passage Problems in Random Vibrations,
   *SIAM Journal of Scientific and Statistical Computing*,
   15,
   pp. 997-996,
   1994.

.. [Ref04]
   **K.-A. Mardal, G. W. Zumbusch and H. P. Langtangen**. Software Tools for Multigrid Methods,
   Advanced Topics in Computational Partial Differential Equations -- Numerical Methods and Diffpack Programming,
   edited by **H. P. Langtangen and A. Tveito**,
   Springer,
   2003,
   Edited book,
   `\urlhttp://some.where.org <\urlhttp://some.where.org>`_.

.. [Ref05]
   **H. P. Langtangen**. The FEMDEQS Program System,
   *Department of Mathematics, University of Oslo*,
   `http://www.math.uio.no/old/days/hpl/femdeqs.pdf <http://www.math.uio.no/old/days/hpl/femdeqs.pdf>`_,
   1989.

.. [Ref06]
   **H. P. Langtangen**. Stochastic Breakthrough Time Analysis of an Enhanced Oil Recovery Process,
   *SIAM Journal on Scientific Computing*,
   13,
   pp. 1394-1417,
   1992.

.. [Ref07]
   **M. Mortensen, H. P. Langtangen and G. N. Wells**. A FEniCS-Based Programming Framework for Modeling Turbulent Flow by the Reynolds-Averaged Navier-Stokes Equations,
   *Advances in Water Resources*,
   34(9),
   `doi: 10.1016/j.advwatres.2011.02.013 <https://dx.doi.org/10.1016/j.advwatres.2011.02.013>`__,
   2011.

.. [Ref08]
   **S. Glimsdal, G. Pedersen, K. Atakan, C. B. Harbitz, H. P. Langtangen and F. L\ovholt**. Propagation of the Dec. |nbsp| 26, 2004 Indian Ocean Tsunami: Effects of Dispersion and Source Characteristics,
   *International Journal of Fluid Mechanics Research*,
   33(1),
   pp. 15-43,
   2006.

.. [Ref09]
   **S. Rahman, J. Gorman, C. H. W. Barnes, D. A. Williams and H. P. Langtangen**. Numerical Investigation of a Piezoelectric Surface Acoustic Wave Interaction With a One-Dimensional Channel,
   *Physical Review B: Condensed Matter and Materials Physics*,
   74,
   2006,
   035308.

.. [Ref10]
   **J. B. Haga, H. Osnes and H. P. Langtangen**. On the Causes of Pressure Oscillations in Low-Permeable and Low-Compressible Porous Media,
   *International Journal of Analytical and Numerical Methods in Geomechanics*,
   `doi: 10.1002/nag.1062 <https://dx.doi.org/10.1002/nag.1062>`__,
   2011,
   `http://onlinelibrary.wiley.com/doi/10.1002/nag.1062/abstract <http://onlinelibrary.wiley.com/doi/10.1002/nag.1062/abstract>`_.

.. [Ref11]
   **H. P. Langtangen**. *Computational Partial Differential Equations - Numerical Methods and Diffpack Programming*,
   second edition,
   *Texts in Computational Science and Engineering*,
   Springer,
   2003.

.. [Ref12]
   **H. P. Langtangen**. *Python Scripting for Computational Science*,
   third edition,
   *Texts in Computational Science and Engineering*,
   Springer,
   2008.

.. [Ref13]
   **H. P. Langtangen and G. Pedersen**. Finite Elements for the Boussinesq Wave Equations,
   Waves and Non-linear Processes in Hydrodynamics,
   edited by **J. Grue, B. Gjevik and J. E. Weber**,
   Kluwer Academic Publishers,
   pp. pp. 117-126,
   1995,
   `http://www.amazon.ca/Waves-Nonlinear-Processes-Hydrodynamics-John/dp/0792340310 <http://www.amazon.ca/Waves-Nonlinear-Processes-Hydrodynamics-John/dp/0792340310>`_.

.. [Ref14]
   **H. P. Langtangen**. *A Primer on Scientific Programming With Python*,
   third edition,
   *Texts in Computational Science and Engineering*,
   Springer,
   2012.

.. [Ref15]
   **P. V. Jeberg, H. P. Langtangen and C. B. Terp**. Optimization With Diffpack: Practical Example From Welding,
   *Simula Research Laboratory*,
   Internal report,
   2004.

.. [Ref16]
   **H. P. Langtangen**. Computational Methods for Two-Phase Flow in Oil Reservoirs,
   Ph.D. Thesis,
   Mechanics Division, Department of Mathematics, University of Oslo,
   1989,
   Dr. |nbsp| Scient. |nbsp| thesis..

.. [Ref17]
   **H. P. Langtangen**. Computational Modeling of Huge Tsunamis From Asteroid Impacts,
   Invited keynote lecture at the \emphInternational conference on Computational Science 2007 (ICCS'07), Beijing, China,
   2007.

.. [Ref18]
   **H. P. Langtangen**. Solution of the Navier-Stokes Equations With the Finite Element Method in Two and Three Dimensions,
   M.Sc. Thesis,
   Mechanics Division, Department of Mathematics, University of Oslo,
   1985,
   Cand.Scient. thesis.

.. [Ref19]
   **H. P. Langtangen and A. Tveito**. Numerical Methods in Continuum Mechanics,
   *Center for Industrial Research*,
   1991,
   Lecture notes for a course (ME-IN 324). 286 pages..

.. [Ref20]
   **H. P. Langtangen**. Diffpack: Software for Partial Differential Equations,
   Proceedings of the Second Annual Object-Oriented Numerics Conference (OON-SKI'94), Sunriver, Oregon, USA,
   edited by **A. Vermeulen**,
   1994.

.. _app1:

Appendix: Just for testing; part I
==================================

This is the first appendix.

A subsection within an appendix
-------------------------------

Some text.

.. _app2:

Appendix: Just for testing; part II
===================================

This is more stuff for an appendix.

Appendix: Testing identical titles          (1)
-----------------------------------------------

Without label.

.. _test:title:id1:

Appendix: Testing identical titles          (2)
-----------------------------------------------

With label.

.. _test:title:id2:

Appendix: Testing identical titles          (3)
-----------------------------------------------

What about inserting a quiz?



.. !split
Test of quizzes
---------------.. begin quiz



**Fundamental test:** What is the capital of Norway?


**Answer 1:** Stockholm

:abbr:`? (Wrong!)` :abbr:`# (Stockholm is the capital of Sweden.)`

**Answer 2:** London

:abbr:`? (Wrong!)`

**Answer 3:** Oslo

:abbr:`? (Right!)`

**Choice D:** Bergen

:abbr:`? (Wrong!)` :abbr:`# (Those from Bergen would claim so, but nobody else.)`

.. end quiz



Appendix: Testing identical titles          (4)
-----------------------------------------------

Without label.


.. admonition:: Tip

   Here is a tip or hint box, typeset as a notice box.




Need a lot of text to surround the summary box.
Version control systems allow you to record the history of files
and share files among several computers and collaborators in a
professional way. File changes on one computer are updated or
merged with changes on another computer. Especially when working
with programs or technical reports it is essential
to have changes documented and to
ensure that every computer and person involved in the project
have the latest updates of the files.
Greg Wilson' excellent `Script for Introduction to Version Control <https://software-carpentry.org/2010/07/script-for-introduction-to-version-control/>`__ provides a more detailed motivation why you will benefit greatly
from using version control systems.


.. admonition:: Summary

   **Bold remark:** Make some text with this summary.
   Much testing in this document, otherwise stupid content.
   Much testing in this document, otherwise stupid content.
   Much testing in this document, otherwise stupid content.
   Much testing in this document, otherwise stupid content.
   Much testing in this document, otherwise stupid content.
   Much testing in this document, otherwise stupid content.
   Much testing in this document, otherwise stupid content.
   Much testing in this document, otherwise stupid content.
   Much testing in this document, otherwise stupid content.




Projects that you want to share among several computers or project
workers are today most conveniently stored at some web site "in the
cloud" and updated through communication with that site. I strongly
recommend you to use such sites for all serious programming and
scientific writing work - and all other important files.

The simplest services for hosting project files are `Dropbox <https://dropbox.com>`__ and `Google Drive <https://drive.google.com>`__.
It is very easy to get started with these systems, and they allow you
to share files among laptops and mobile units with as many users as
you want. The systems offer a kind of version control in that the
files are stored frequently (several times per minute), and you can go
back to previous versions for the last 30 days. However, it is
challenging  to find the right version from the past when there are
so many of them.

More seriously, when several people may edit files simultaneously, it
can be difficult detect who did what when, roll back to previous
versions, and to manually merge the edits when these are
incompatible. Then one needs more sophisticated tools than Dropbox or
Google Drive: project hosting services with true version control
systems.  The following text aims at providing you with the minimum
information to started with such systems. Numerous other tutorials
contain more comprehensive material and in-depth explanations of the
concepts and tools.

The idea with project hosting services is that you have the files
associated with a project in the cloud. Many people may share these
files.  Every time you want to work on the project you explicitly
update your version of the files, edit the files as you like, and
synchronize the files with the "master version" at the site where the
project is hosted.  If you at some point need to go back to a
version of the files at some particular point in the past,
this is an easy operation. You can also use tools to see
what various people have done with the files in the various versions.

All these services are very similar. Below we describe how you get
started with Bitbucket, GitHub, and Googlecode. Launchpad works very
similarly to the latter three. All the project hosting services have
excellent introductions available at their web sites, but the recipes
below are much shorter and aim at getting you started as quickly as
possible by concentrating on the most important need-to-know steps.
The Git tutorials we refer to later in this document contain more
detailed information and constitute of course very valuable readings
when you use version control systems every day. The point now is
to get started.

Appendix: Testing inline comments
---------------------------------

.. Names can be [ A-Za-z0-9_'+-]+

Projects that you want to share among several computers or project
workers are today most conveniently stored at some web site "in the
cloud" and updated through communication with that
site. **(**hpl's semi opinion 1**: not sure if in the cloud is
understood by
all.**) I strongly recommend you to use such sites for all serious
programming and scientific writing work - and all other important
files.

The simplest services for hosting project files is Dropbox. **(**mp 2**: Simply go to `<https://dropbox.com>`_ and watch the video. It explains
how files, like ``myfile.py``, perhaps containing much math, like
\\( \partial u/\partial t \\), are easily communicated between machines.**) It
is very easy to get started with Dropbox, and it allows you to share
files among **(**hpl 3**: laptops and mobile units -> computers, tablets,
and phones**).

.. Test horizontal rule

---------

.. Coments for editing

Firstcolor{red}{(**add 4**: ,}) consider a quantity \\( Q \\). **(**edit 5**: To this end, -> We note that**)
\\( Q>0 \\), because **(**del 6**: a**) negative **(**edit 7**: quantity is -> quantities
are**) **(**del 8**: just**) negative. **(**add 9**: This comes as no surprise.**)

.. Test tailored latex figure references with page number

Let us refer to Figure `fig:impact`_ again.

Test references in a list:

 * `Section 1`_

 * `Subsection 1`_

 * `fig:impact`_

Appendix: Testing headings ending with ``verbatim inline``
----------------------------------------------------------

The point here is to test 1) ``verbatim`` code in headings, and 2)
ending a heading with verbatim code as this triggers a special
case in LaTeX.

We also test mdash---used as alternative to hyphen without spaces around,
or in quotes:


..

    *Fun is fun*.---Unknown.



The ndash should also be tested - as in the Hanson - Nilson equations
on page 277 - 278.

And finally, what about admons, quotes, and boxes? They are tested
in a separate document: ``admon.do.txt``.

.. [#example-of-the-third-footnote] Not much to add here, but the footnote
   is at the end with only one newline.
************** File: testdoc.sphinx.rst *****************
.. raw:: html

        <script type="text/javascript">
        $(document).ready(function() {
            $("a[href^='http']").attr('target','_blank');
        });
        </script>

.. Automatically generated Sphinx-extended reStructuredText file from DocOnce source
   (https://github.com/hplgit/doconce/)

.. |nbsp| unicode:: 0xA0
   :trim:

.. Document title:

A Document for Testing DocOnce
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

:Authors: Hans Petter Langtangen (hpl at simula.no), Kaare Dump, A. Dummy Author, I. S. Overworked and Outburned, J. Doe (j_doe at cyberspace.com)
:Date: Jan 32, 2100

The format of this document is
sphinx

*Abstract.* This is a document with many test constructions for doconce syntax.
It was used heavily for the development and kept for testing
numerous constructions, also special and less common cases.

And exactly for test purposes we have an extra line here, which
is part of the abstract.

.. Cannot demonstrate chapter headings since abstract and chapter

.. are mutually exclusive in LaTeX

.. !split

.. _sec1:

Section 1
=========

Here is a nested list:

  * item1

  * item2

  * item3 which continues
    on the next line to test that feature

  * and a sublist

    * with indented subitem1

    * and a subitem2

  * and perhaps an ordered sublist

   a. first item

   b. second item,
      continuing on a new line

**Here is a list with paragraph heading.**

  * item1

  * item2

Here is a list with subsubsection heading
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  * item1

  * item2


..

    Here are two lines that make up
    a block quote for testing *emphasized words* and **boldface words**,
    also with hypens:
    *pre*-fix, post-*fix*, **pre**-fix, post-**fix**.



Here are two references. Equation |nbsp| :eq:`my:eq1` is fine. Eq. |nbsp| :eq:`my:eq1` too.
Even Equation :eq:`my:eq1` without the tilde.
This equation appears in another part if this document is split.

.. _subsec1:

Subsection 1
------------

.. index:: somefunc function

.. Refer to section/appendix etc. at the beginning of the line

.. and other special fix situations for HTML.

More text, with a reference back to
the section :ref:`sec1` and :ref:`subsec1`, and further to the
the sections :ref:`subsec1` and :ref:`subsubsec:ex`, which
encourages you to do the tasks in :ref:`demo:ex:1` and :ref:`exer:some:formula`.
 :ref:`app1` and :ref:`app2` are also nice elements.

Test Section reference at beginning of line and after a sentence
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The section :ref:`subsec1` is fine.
The section :ref:`subsubsec:ex` too.

.. sphinx code-blocks: pycod=python cod=fortran cppcod=c++ sys=console

Computer code
~~~~~~~~~~~~~

Let's do some copying from files too. First from subroutine up to the very end,

.. code-block:: fortran

          subroutine test()
          integer i
          real*8 r
          r = 0
          do i = 1, i
             r = r + i
          end do
          return
    C     END1
    
          program testme
          call test()
          return

and then just the subroutine,

.. code-block:: fortran

          subroutine test()
          integer i
          real*8 r
          r = 0
          do i = 1, i
             r = r + i
          end do
          return

and finally the complete file with a plain text verbatim environment
(``envir=ccq``):

.. code-block:: text

    C     a comment
    
          subroutine test()
          integer i
          real*8 r
          r = 0
          do i = 1, i
             r = r + i
          end do
          return
    C     END1
    
          program testme
          call test()
          return

Testing other code environments. First Python:

.. code-block:: text

    !bc pycod
    def f(x):
        return x+1
    !ec

which gets rendered as

.. code-block:: python

    def f(x):
        return x+1

Test paragraph and subsubsection headings before
before code.

**Paragraph heading before code.**

.. code-block:: python

    import sys
    sys.path.insert(0, os.pardir)

Subsubsection heading before code
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

    def h(z):
        return z+1

Now a complete program to be shown via Python Online Tutorial:

.. raw:: html

    <iframe width="950" height="500" frameborder="0"
            src="https://pythontutor.com/iframe-embed.html#code=class+Line%3A%0A++++def+__init__%28self%2C+a%2C+b%29%3A%0A++++++++self.a%2C+self.b+%3D+a%2C+b%0A%0A++++def+__call__%28self%2C+x%29%3A%0A++++++++a%2C+b+%3D+self.a%2C+self.b%0A++++++++return+a%2Ax+%2B+b%0A%0Aline+%3D+Line%282%2C+1%29%0Ay+%3D+line%28x%3D3%29%0Aprint%28y%29&py=2&curInstr=0&cumulative=false">
    </iframe>

Another complete program to be typeset as a sage cell:

.. code-block:: text

    a = 2
    b = 3
    print('a+b:', a + b)
    
    # In a sage cell we can also plot
    from matplotlib.pyplot import *
    from numpy import *
    x = linspace(0, 4*pi, 101)
    y = exp(-0.1*x)*cos(x)
    plot(x, y)
    xlabel('x'); ylabel('y')
    show()

Then Cython (with -h option so it is hidden in html/sphinx):

.. container:: toggle

    .. container:: header

        **Show/Hide Code**

    .. code-block:: cython

        cpdef f(double x):
            return x + 1

Standard Python shell sessions:

.. code-block:: python

    >>> from numpy import linspace, sin
    >>> # Some comment
    >>> x = linspace(0, 2, 11)
    >>> y = sin(x)
    >>> y[0]
    0
    >>> import matplotlib.pyplot as plt
    >>> plt.plot(x, y)

Similar IPython sessions:

.. code-block:: ipy

    In [1]: from numpy import linspace, sin
    In [2]: # Some comment
    In [3]: x = linspace(0, 2, 11)
    In [4]: y = sin(x)
    In [5]: y[0]
    Out[5]: 0
    In [6]: import matplotlib.pyplot as plt
    In [7]: plt.plot(x, y)
    In [8]: a='multiple-\nline\noutput'
    In [9]: a
    Out[9]: 'multiple-\nline\noutput'
    In [10]: print(a)
    multiple-
    line
    output

Here is the interactive session again, but with ``pyshell-t``.

.. code-block:: python

    >>> from numpy import linspace, sin
    >>> # Some comment
    >>> x = linspace(0, 2, 11)
    >>> y = sin(x)
    >>> y[0]
    0
    >>> import matplotlib.pyplot as plt
    >>> plt.plot(x, y)

.. This one tests a + sign before a code environment

C++:

.. code-block:: c++

    #include <iostream>
    
    int main()
    {
       std::cout << "Sample output" << std::endl;
       return 0
    }

.. The next should get correctly typset in sphinx (cod is fcod)

.. It also tests emoji before code

And a little bit of Fortran: :dizzy_face:

.. code-block:: text

    !bc cod
          subroutine midpt(x, length, a, b)
          real*8 a, b, x
          x = (a + b)/2
          length = b - a
          return
          end
    !ec

which then is typeset as

.. code-block:: fortran

          subroutine midpt(x, length, a, b)
          real*8 a, b, x
          x = (a + b)/2
          length = b - a
          return
          end

HTML:

.. code-block:: html

    <table>
    <tr><td>Column 1</td><td>Column 2</td></tr>
    <tr><td>0.67526 </td><td>0.92871 </td></tr>
    <!-- comment -->
    </table>

But inline HTML code is also important, like text that starts with
``<a href="`` (which can destroy the following text if not properly
quoted).

Matlab with comments requires special typesetting:

.. code-block:: matlab

    % Comment on the beginning of the line can be escaped by %%
    if a > b
      % Indented comment needs this trick
      c = a + b
    end

And here is a system call:

.. code-block:: console

    Terminal> mkdir test
    Terminal> cd test
    Terminal> myprog -f
    output1
    output2

Any valid pygments lexer/language name can appear to, e.g.,

.. code-block:: text

    !bc restructuredtext
    =======
    Heading
    =======
    
    Some text.
    !ec

results in

.. code-block:: restructuredtext

    =======
    Heading
    =======
    
    Some text.

.. Here goes hidden code.

.. Python can be treated by some formats, Fortran is always out.

Finally, ``!bc do`` supports highlighting of DocOnce source:

.. code-block:: doconce

    ======= DocOnce test file =======
    
    ===== Computer code =====
    
    Inline verbatim code, as in `import numpy as np`, is allowed, as well as
    code blocks:
    
    !bc pycod
    from math import sin
    
    def f(x):
        """Example on a function."""
        return sin(x) + 1
    
    print(f(0))
    !ec
    
    
    ===== Mathematics =====
    
    Formulas can be inline, as in $\nabla\cdot\boldsymbol{u} = 0$, or typeset
    as equations:
    
    !bt
    \begin{align*}
    \nabla\cdot\boldsymbol{u} &= 0,\\ 
    \boldsymbol{u} &= \nabla\phi .
    \end{align*}
    !et
    
    === Subsubsection heading ===
    
    DocOnce files can have chapters, sections, subsections, and subsubsections.
    
    __Paragraph heading.__ Paragraphs may have headings.

It is time to test ``verbatim inline font`` especially with ``a newline
inside the text`` and an exclamation mark at the end: ``BEGIN``! For
spellcheck, test ``a verbatim expression`` in ``another`` in a ``third``.
Also test exclamation mark as in ``!bc`` and ``!ec`` as well as ``a != b``.
Also test backslashes and braces like ``\begin``, ``\begin{enumerate}``,
``\end{this}\end{that}``, and ``{something \inside braces}``.

The following attempt to exemplify colored text does not work in
format sphinx.
Here is some **red color** and an attempt to write **with
green color containing a linebreak

| code.** Some formats will only display 
| this correctly when ``html`` 
| is the output format.

But here some more running text is added which is not part of
the previous blocks with line breaks.

Running OS commands
~~~~~~~~~~~~~~~~~~~

.. code-block:: console

    Terminal> python -c 'print("Testing\noutput\nfrom\nPython.")'
    Testing
    output
    from
    Python.

Footnotes
~~~~~~~~~

Here is a test of footnotes [#footnote]_, which are handy in text.
They are used in different flavors, now in

 * list items (note below that footnotes work after math, verbatim, and URLs - bin fact old and emphasize too!)

 * even with math :math:`\nabla^2u` [#math1]_

 * and code ``h[i] += 1`` [#code]_
   (*must* have space between inline code and footnote!)

 * and `links <https://google.com>`__ [#google-search]_

which gives flexibility in writing.
This is the third [#example-of-the-third-footnote]_ example.

.. [#footnote] Typesetting of the footnote depends on the format.
   Plain text does nothing, LaTeX removes the
   definition and inserts the footnote as part of the LaTeX text.
   reStructuredText and Sphinx employ a similar type of typesetting
   as Extended Markdown and DocOnce, and in HTML we keep the same
   syntax, just displayed properly in HTML.

.. [#math1] Math footnotes can be dangerous since it
   interferes with an exponent.

.. [#code] One-line footnote.

.. [#google-search] `<google.com>`_ is perhaps the most famous
   web site today.

Here is some more text before a new definition of a footnote that was
used above.


.. admonition:: Non-breaking space character

   This paragraph aims to test `non-breaking space character <https://en.wikipedia.org/wiki/Non-breaking_space>`__, and a typical
   example where this is needed is in physical units: 7.4 |nbsp| km is traveled
   in |nbsp| :math:`7.4/5.5\approx 1.345` |nbsp| s.  Also check that a |nbsp| `link <https://google.com>`__ |nbsp| is
   not broken across lines (drag the browser window to test this).
   (On the other hand, the tilde is used in
   computer code, e.g., as in ``[~x for x in y]`` or in ``y=~x``, and should
   of course remain a tilde in those contexts.)




.. _subsec:ex:

Subsection 2: Testing figures
-----------------------------

.. index:: figures

Test of figures. In particular we refer to Figure :ref:`fig:impact` in which
there is a flow.

.. _fig:impact:

.. figure:: ../doc/src/manual/fig/wave1D.png
   :width: 200

   Visualization **of** a *wave*

Figures without captions are allowed and will be inlined.

.. figure:: ../doc/src/manual/fig/wave1D.png
   :width: 200

.. index:: movies

.. Test multi-line caption in figure with sidecap=True

Here is figure :ref:`myfig` with a long (illegal) multi-line caption
containing inline verbatim text:

.. _myfig:

.. figure:: ../doc/src/manual/fig/wave1D.png
   :width: 500

   A long caption spanning several lines and containing verbatim words like ``my_file_v1`` and ``my_file_v2`` as well as math with subscript as in :math:`t_{i+1}`

.. Must be a blank line after MOVIE or FIGURE to detect this problem

Test URL as figure name:

.. figure:: https://raw.github.com/doconce/doconce/master/doc/src/blog/f_plot.png
   :width: 500

Test SVG figure:

.. figure:: https://openclipart.org/people/jpneok/junebug.svg
   :width: 200

.. Test wikimedia type of files that otherwise reside in subdirs

**Remark.**
Movies are tested in separate file ``movies.do.txt``.

.. Somewhat challenging heading with latex math, \t, \n, ? and parenthesis

.. _decay:sec:theta:

The :math:`\theta` parameter (not :math:`\nabla`?)
--------------------------------------------------

Functions do not always need to be advanced, here is one
involving :math:`\theta`:

.. code-block:: text

    def f(theta):
        return theta**2

**More on :math:`\theta`.**
Here is more text following headline with math.

Newcommands must also be tested in this test report:
:math:`\frac{1}{2}`, :math:`{1/2}`, :math:`\pmb{x}`, :math:`\frac{Du}{dt}`,
both inline and in block:

.. math::
        
        \frac{Du}{dt} = 0\nonumber
        

.. math::
   :label: _auto1

          
        \frac{1}{2} = {1/2}
        
        

.. math::
   :label: _auto2

          
        \frac{1}{2}\pmb{x} = \pmb{n}
        
        

Or with align with label and numbers:

.. math::
   :label: aligneq1

        
        \frac{Du}{dt} = 0
        
        

.. math::
   :label: _auto3

          
        \frac{1}{2} = {1/2}
        
        

.. math::
   :label: aligneq2

          
        \frac{1}{2}\pmb{x} = \pmb{n}
        
        

Sphinx makes a fix here and splits align into multiple equation
environments.

Custom Environments
-------------------

Here is an attempt to create a theorem environment via Mako
(for counting theorems) and comment lines to help replacing lines in
the ``.tex`` by proper begin-end LaTeX environments for theorems.
Should look nice in most formats!

.. begin theorem

**Theorem 5.**
Let :math:`a=1` and :math:`b=2`. Then :math:`c=3`.

.. end theorem

.. begin proof

**Proof.**
Since :math:`c=a+b`, the result follows from straightforward addition.
:math:`\Diamond`

.. end proof

As we see, the proof of Theorem 5 is a modest
achievement.

.. _subsec:table:

Tables
------

.. index:: test index with verbatim text which is possible

.. index:: test two (separate) verbatim expressions which is also possible

.. index::
   single: index with; subindex

.. index:: boldface word in index

.. index:: index with boldface word

.. index::
   single: index with; boldface word in subentry

.. index::
   single: double boldface word;  boldface word in subentry too

.. index with comma could fool sphinx

.. index::
   single: index, with comma, and one more

Let us take this table from the manual:

====  ========  ============  
time  velocity  acceleration  
====  ========  ============  
0.0     1.4186         -5.01  
2.0   1.376512        11.919  
4.0     1.1E+1     14.717624  
====  ========  ============  

The DocOnce source code reads

.. code-block:: text

      |--------------------------------|
      |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    |
      |--------------------------------|
    

Here is yet another table to test that we can handle more than
one table:

====  ========  ============  
time  velocity  acceleration  
====  ========  ============  
0.0   1.4186    -5.01         
1.0   1.376512  11.919        
3.0   1.1E+1    14.717624     
====  ========  ============  

And one with math headings (that are expanded and must be treated
accordingly), verbatim heading and entry, and no space around the pipe
symbol:

=========  ===========  ================  =======  
:math:`i`  :math:`h_i`  :math:`\bar T_i`  ``L_i``  
=========  ===========  ================  =======  
0                    0               288  -0.0065  
1               11,000               216      0.0  
2               20,000               216    0.001  
3               32,000               228   0.0028  
4               47,000               270      0.0  
5               51,000               270  -0.0028  
6               71,000               214  ``NaN``  
=========  ===========  ================  =======  

And add one with verbatim headings (with underscores),
and rows starting with ``|-`` because of a negative number,
and ``|`` right before and after verbatim word (with no space):

=====  =======  =====================  ===========  
exact  ``v_1``  :math:`a_i` + ``v_2``  ``verb_3_``  
=====  =======  =====================  ===========  
    9     9.62                   5.57         8.98  
  -20   -23.39                  -7.65       -19.93  
   10    17.74                  -4.50         9.96  
    0    -9.19                   4.13        -0.26  
=====  =======  =====================  ===========  

Pipe symbols in verbatim and math text in tables used to pose difficulties,
but not
anymore:

===============  ===============  
   :math:`S`         command      
===============  ===============  
$ ||a_0|| $      ``norm|length``  
:math:`x\cap y`          ``x|y``  
===============  ===============  

Here is a table with X alignment:

=====  ==========================================================================================================================================================================================================================  
 Type                                                                                                         Description                                                                                                          
=====  ==========================================================================================================================================================================================================================  
  X    Alignment character that is used for specifying a potentially very long text in a column in a table. It makes use of the ``tabularx`` package in LaTeX, otherwise (for other formats) it means ``l`` (centered alignment).  
l,r,c  standard alignment characters                                                                                                                                                                                               
=====  ==========================================================================================================================================================================================================================  

Finally, a table with math
(``bm`` that expands to ``boldsymbol``, was tricky, but
cleanly handled now)
and URLs.

.. Mako code to expand URLs in the table

.. (These types of tables did not work before Jan 2014)

====================================  ==========================================================  ==========================================================  
                                                                                                                                                              
====================================  ==========================================================  ==========================================================  
       :math:`\mathcal{L}=0`          `080 <../doc/src/manual/mov/wave_frames/frame_0080.png>`__  `085 <../doc/src/manual/mov/wave_frames/frame_0085.png>`__  
            :math:`a=b`               `090 <../doc/src/manual/mov/wave_frames/frame_0090.png>`__  `095 <../doc/src/manual/mov/wave_frames/frame_0095.png>`__  
:math:`\nabla\cdot\boldsymbol{u} =0`  `100 <../doc/src/manual/mov/wave_frames/frame_0100.png>`__  `105 <../doc/src/manual/mov/wave_frames/frame_0105.png>`__  
====================================  ==========================================================  ==========================================================  

A test of verbatim words in heading with subscript :math:`a_i`: ``my_file_v1`` and ``my_file_v2``
-------------------------------------------------------------------------------------------------

**Paragraph with verbatim and math: ``my_file_v1.py`` and ``my_file_v2.py`` define some math :math:`a_{i-1}`.**
Here is more ``__verbatim__`` code and
some plain text on a new line.

.. Test various types of headlines

**Just bold**
-------------

Some text.

*Just emphasize*
----------------

Some text.

``Just verbatim``
-----------------

Some text.

**Bold** beginning
------------------

Some text.

*Emphasize* beginning
---------------------

Some text.

``Verbatim`` beginning
----------------------

Some text.

Maybe **bold end**
------------------

Some text.

Maybe *emphasize end*
---------------------

Some text.

Maybe ``verbatim end``
----------------------

Some text.

The middle has **bold** word
----------------------------

Some text.

The middle has *emphasize* word
-------------------------------

Some text.

The middle has ``verbatim`` word
--------------------------------

Some text.

***Just emphasize*.**
Some text.

**``Just verbatim``.**
Some text.

***Emphasize* beginning.**
Some text.

**``Verbatim beginning``.**
Some text.

**Maybe *emphasize end*.**
Some text.

**Maybe ``verbatim end``.**
Some text.

**The middle has *emphasize* word.**
Some text.

**The middle has ``verbatim`` word.**
Some text.

**Ampersand.**
We can test Hennes & Mauritz, often abbreviated H&M, but written
as ``Hennes & Mauritz`` and ``H & M``.
A sole ``&`` must also work.

.. Note: substitutions must not occur inside verbatim, just in ordinary text.

.. code-block:: text

    # Just to check that ampersand works in code blocks:
    c = a & b

**Quotes.**
Let us also add a test of quotes such as "double quotes, with numbers
like 3.14 and newline/comma and hyphen (as in double-quote)"; written
in the standard LaTeX-style that gives correct LaTeX formatting and
ordinary double quotes for all non-LaTeX formats.  Here is another
sentence that "caused" a bug in the past because double backtick
quotes could imply verbatim text up to a verbatim word starting with
period, like ``.txt``.

More quotes to be tested for spellcheck:
("with parenthesis"), "with newline"
and "with comma", "hyphen"-wise, and "period".

Bibliography test
-----------------

Here is an example: [Ref01]_ discussed propagation of
large destructive water waves, [Ref02]_ gave
an overview of numerical methods for solving the Navier - Stokes equations,
while the use of Backward Kolmogorov equations for analyzing
random vibrations was investigated in [Ref03]_.
The book chapter [Ref04]_ contains information on
C++ software tools for programming multigrid methods. A real retro
reference is [Ref05]_ about a big FORTRAN package.
Multiple references are also possible, e.g., see
[Ref01]_ [Ref04]_.

We need to cite more than 10 papers to reproduce an old formatting
problem with blanks in the keys in reST format:
[Ref06]_ [Ref03]_ [Ref07]_ [Ref01]_
and
[Ref02]_ [Ref08]_ [Ref09]_ [Ref10]_ [Ref11]_ [Ref12]_ [Ref13]_
and all the work of
[Ref14]_ [Ref04]_ [Ref15]_ as well as
old work [Ref05]_ and [Ref16]_, and the
talk [Ref17]_.
Langtangen also had two thesis [Ref18]_ [Ref16]_
back in the days.
More retro citations are
the old ME-IN323 book [Ref19]_ and the
[Ref20]_ OONSKI '94 paper.

.. --- begin exercise ---

.. _Example:

Example 1: Examples can be typeset as exercises
-----------------------------------------------

Examples can start with a subsection heading starting with ``Example:``
and then, with the command-line option ``--examples_as_exercises`` be
typeset as exercises. This is useful if one has solution
environments as part of the example.

**a)**
State some problem.

**Solution.**
The answer to this subproblem can be written here.

**b)**
State some other problem.

**Hint 1.**
A hint can be given.

**Hint 2.**
Maybe even another hint?

**Solution.**
The answer to this other subproblem goes here,
maybe over multiple doconce input lines.

.. --- end exercise ---

User-defined environments
-------------------------

The example in the section :ref:`ex:test:1p1` demonstrates how to write a test function.
That is, a special test function for a function ``add`` appears in
the example in the section :ref:`ex:test:1p1`.

.. _ex:test:1p1:

Example 1: A test function
--------------------------

Suppose we want to write a test function for checking the
implementation of a Python function for addition.

.. code-block:: python

    def add(a, b):
        return a + b
    
    def test_add():
        a = 1; b = 1
        expected = a + b
        computed = add(a, b)
        assert expected == computed

.. _ex:math:1p1:

Example 2: Addition
-------------------

We have

.. math::
         1 + 1 = 2 

or in tabular form:

===========  =========  
  Problem      Result   
===========  =========  
:math:`1+1`  :math:`2`  
===========  =========  


.. admonition:: Highlight box

   This environment is used to highlight something:
   
   .. math::
            E = mc^2




.. _subsubsec:ex:

URLs
----

Testing of URLs: hpl's home page `hpl <https://folk.uio.no/hpl>`__, or
the entire URL if desired, `<https://folk.uio.no/hpl>`_.  Here is a
plain file link `<testdoc.do.txt>`_, or `<testdoc.do.txt>`_, or
`<testdoc.do.txt>`_ or `<testdoc.do.txt>`_ or `a link with
newline <testdoc.do.txt>`__. Can test spaces with the link with word
too: `hpl <https://folk.uio.no/hpl>`__ or `hpl <https://folk.uio.no/hpl>`__. Also ``file:///`` works: `link to a
file <file:///home/hpl/vc/doconce/doc/demos/manual/manual.html>`__ is
fine to have. Moreover, "loose" URLs work, i.e., no quotes, just
the plain URL as in `<https://folk.uio.no/hpl>`_, if followed by space, comma,
colon, semi-colon, question mark, exclamation mark, but not a period
(which gets confused with the periods inside the URL).

Mail addresses can also be used: `hpl@simula.no <mailto:hpl@simula.no>`__, or just a `mail link <mailto:hpl@simula.no>`__, or a raw `<mailto:hpl@simula.no>`_.

Here are some tough tests of URLs, especially for the ``latex`` format:
`Newton-Cotes <https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas>`__ formulas
and a `good book <https://www.springer.com/mathematics/computational+science+%26+engineering/book/978-3-642-23098-1>`__. Need to test
Newton-Cotes with percentage in URL too:
`<https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas>`_
and `<https://en.wikipedia.org/wiki/Newton-Cotes#Open_Newton.E2.80.93Cotes_formulae>`_ which has a shebang.

For the ``--device=paper`` option it is important to test that URLs with
monospace font link text get a footnote
(unless the ``--latex_no_program_footnotelink``
is used), as in this reference to
`decay_mod <https://github.com/hplgit/INF5620/tree/gh-pages/src/decay/experiments/decay_mod.py>`__, `ball1.py <https://tinyurl.com/pwyasaa/formulas.ball1.py>`__,
and `ball2.py <https://tinyurl.com/pwyasaa/formulas.ball2.py>`__.

.. Comments should be inserted outside paragraphs (because in the rst

.. format extra blanks make a paragraph break).

.. Note that when there is no https: or file:, it can be a file link

.. if the link name is URL, url, "URL", or "url". Such files should,

.. if rst output is desired, but placed in a ``_static*`` folder.

More tough tests: repeated URLs whose footnotes when using the
``--device=paper`` option must be correct. We have
`google <https://google.com>`__, `google <https://google.com>`__, and
`google <https://google.com>`__, which should result in exactly three
footnotes.

.. !split and check if these extra words are included properly in the comment

.. !split

LaTeX Mathematics
=================

Here is an equation without label using backslash-bracket environment:

.. math::
         a = b + c 

or with number and label, as in :eq:`my:eq1`, using the equation environment:

.. math::
   :label: my:eq1

        
        {\partial u\over\partial t} = \nabla^2 u 
        

We can refer to this equation by :eq:`my:eq1`.

Here is a system without equation numbers, using the align-asterisk environment:

.. math::
        \begin{align*}
        \pmb{a} &= \pmb{q}\times\pmb{n} \\ 
        b &= \nabla^2 u + \nabla^4 v
        \end{align*}

And here is a system of equations with labels in an align environment:

.. math::
   :label: eq1

        
        a = q + 4 + 5+ 6  
        

.. math::
   :label: eq2

          
        b = \nabla^2 u + \nabla^4 x 
        
        

We can refer to :eq:`eq1`-:eq:`eq2`. They are a bit simpler than
the Navier - Stokes equations. And test LaTeX hyphen in ``CG-2``.
Also test :math:`a_{i-j}` as well as :math:`kx-wt`.

Testing ``alignat`` environment:

.. math::
   :label: eq1a

        
        a = q + 4 + 5+ 6\qquad  \mbox{for } q\geq 0  
        

.. math::
   :label: eq2a

          
        b = \nabla^2 u + \nabla^4 x  x\in\Omega 
        

More mathematical typesetting is demonstrated in the coming exercises.

Below, we have :ref:`demo:ex:1` and :ref:`demo:ex:2`,
as well as :ref:`proj:circle1` and :ref:`exer:you`, and in
between there we have :ref:`exer:some:formula`.

.. !split

Exercises
=========

.. --- begin exercise ---

.. _demo:ex:1:

Problem 2: Flip a Coin
----------------------

.. keywords = random numbers; Monte Carlo simulation; ipynb

.. Torture tests

**a)**
Make a program that simulates flipping a coin :math:`N` times.
Print out "tail" or "head" for each flip and
let the program count the number of heads.

.. --- begin hint in exercise ---

**Hint 1.**
Use ``r = random.random()`` and define head as ``r <= 0.5``.

.. --- end hint in exercise ---

.. --- begin hint in exercise ---

**Hint 2.**
Draw an integer among :math:`\{1,2\}` with
``r = random.randint(1,2)`` and define head when ``r`` is 1.

.. --- end hint in exercise ---

.. --- begin answer of exercise ---

**Answer.**
If the ``random.random()`` function returns a number :math:`<1/2`, let it be
head, otherwise tail. Repeat this :math:`N` number of times.

.. --- end answer of exercise ---

.. --- begin solution of exercise ---

**Solution.**

.. code-block:: python

    import sys, random
    N = int(sys.argv[1])
    heads = 0
    for i in range(N):
        r = random.random()
        if r <= 0.5:
            heads += 1
    print('Flipping a coin %d times gave %d heads' % (N, heads))

.. --- end solution of exercise ---

**b)**
Vectorize the code in a) using boolean indexing.

Vectorized code can be written in many ways.
Sometimes the code is less intuitive, sometimes not.
At least there is not much to find in the section :ref:`sec1`.

**c)**
Vectorize the code in a) using ``numpy.sum``.

.. --- begin answer of exercise ---

**Answer.**
``np.sum(np.where(r <= 0.5, 1, 0))`` or ``np.sum(r <= 0.5)``.

.. --- end answer of exercise ---

In this latter subexercise, we have an
example where the code is easy to read.

My remarks
~~~~~~~~~~

Remarks with such a subsubsection is treated as more text
after the last subexercise. Test a list too:

1. Mark 1.

2. Mark 2.

Filenames: ``flip_coin.py``, ``flip_coin.pdf``.

.. Closing remarks for this Problem

Remarks          (1)
~~~~~~~~~~~~~~~~~~~~

These are the exercise remarks, appearing at the very end.

.. solution files: mysol.txt, mysol_flip_coin.py, yet_another.file

.. --- end exercise ---

Not an exercise
---------------

Should be possible to stick a normal section in the middle of many
exercises.

.. --- begin exercise ---

.. _my:exer1:

Exercise 3: Test of plain text exercise
---------------------------------------

Very short exercise. What is the capital
of Norway?
Filename: ``myexer1``.

.. --- end exercise ---

.. --- begin exercise ---

.. _demo:ex:2:

Project 4: Compute a Probability
--------------------------------

.. Minimalistic exercise

What is the probability of getting a number between 0.5 and 0.6 when
drawing uniformly distributed random numbers from the interval :math:`[0,1)`?

At the end we have a list because that caused problems in LaTeX
in previous DocOnce versions:

1. item1

2. item2

.. --- begin hint in exercise ---

**Hint.**
To answer this question empirically, let a program
draw :math:`N` such random numbers using Python's standard ``random`` module,
count how many of them, :math:`M`, that fall in the interval :math:`(0.5,0.6)`, and
compute the probability as :math:`M/N`.

.. --- end hint in exercise ---

.. --- end exercise ---

.. --- begin exercise ---

.. _proj:circle1:

Project 5: Explore Distributions of Random Circles
--------------------------------------------------

.. keywords = ipynb

The formula for a circle is given by

.. math::
   :label: circle:x

        
        x = x_0 + R\cos 2\pi t,
        
        

.. math::
   :label: circle:y

          
        y = y_0 + R\sin 2\pi t,
        
        

where :math:`R` is the radius of the circle, :math:`(x_0,y_0)` is the
center point, and :math:`t` is a parameter in the unit interval :math:`[0,1]`.
For any :math:`t`, :math:`(x,y)` computed from :eq:`circle:x`-:eq:`circle:y`
is a point on the circle.
The formula can be used to generate ``n`` points on a circle:

.. code-block:: python

    import numpy as np
    
    def circle(R, x0, y0, n=501):
        t = np.linspace(0, 1, n)
        x = x0 + R*np.cos(2*np.pi*t)
        y = y0 + R*np.sin(2*np.pi*t)
        return x, y
    
    x, y = circle(2.0, 0, 0)

.. Often in an exercise we have some comments about the solution

.. which we normally want to keep where they are.

The goal of this project is to draw :math:`N` circles with random
center and radius. Plot each circle using the ``circle`` function
above.

**a)**
Let :math:`R` be normally distributed and :math:`(x_0,y_0)` uniformly distributed.

.. --- begin hint in exercise ---

**Hint.**
Use the ``numpy.random`` module to draw the
:math:`x_0`, :math:`y_0`, and :math:`R` quantities.

.. --- end hint in exercise ---

.. --- begin answer of exercise ---

**Answer.**
Here goes the short answer to part a).

.. --- end answer of exercise ---

.. --- begin solution of exercise ---

**Solution.**
Here goes a full solution to part a).

.. --- end solution of exercise ---

**b)**
Let :math:`R` be uniformly distributed and :math:`(x_0,y_0)` normally distributed.
Filename: ``norm``.

**c)**
Let :math:`R` and :math:`(x_0,y_0)` be normally distributed.

Filename: ``circles``.

.. Closing remarks for this Project

Remarks          (2)
~~~~~~~~~~~~~~~~~~~~

At the very end of the exercise it may be appropriate to summarize
and give some perspectives.

.. --- end exercise ---

.. --- begin exercise ---

.. _exer:dist:

Exercise 6: Determine some Distance
-----------------------------------

Intro to this exercise. Questions are in subexercises below.

.. --- begin solution of exercise ---

**Solution.**
Here goes a full solution of the whole exercise.
With some math :math:`a=b` in this solution:

.. math::
         \hbox{math in solution: } a = b 

And code ``a=b`` in this solution:

.. code-block:: text

    a = b  # code in solution

End of solution is here.

.. --- end solution of exercise ---

**a)**
Subexercises are numbered a), b), etc.

.. --- begin hint in exercise ---

**Hint 1.**
First hint to subexercise a).
With math :math:`a=b` in hint:

.. math::
         a=b. 

And with code (in plain verbatim) returning :math:`x+1` in hint:

.. code-block:: text

    def func(x):
        return x + 1  # with code in hint

.. --- end hint in exercise ---

.. --- begin hint in exercise ---

**Hint 2.**
Second hint to subexercise a).

Test list in hint:

1. item1

2. item2

.. --- end hint in exercise ---

Filename: ``subexer_a.pdf``.

.. --- begin answer of exercise ---

**Answer.**
Short answer to subexercise a).
With math in answer: :math:`a=b`.

.. --- end answer of exercise ---

**b)**
Here goes the text for subexercise b).

Some math :math:`\cos^2 x + \sin^2 x = 1` written one a single line:

.. math::
         \cos^2 x + \sin^2 x = 1 \thinspace .

.. --- begin hint in exercise ---

**Hint.**
A hint for this subexercise.

.. --- end hint in exercise ---

Filename: ``subexer_b.pdf``.

.. --- begin solution of exercise ---

**Solution.**
Here goes the solution of this subexercise.

.. --- end solution of exercise ---

.. No meaning in this weired test example:

The text here belongs to the main (intro) part of the exercise. Need
closing remarks to have text after subexercises.

Test list in exercise:

1. item1

2. item2

.. Closing remarks for this Exercise

Remarks          (3)
~~~~~~~~~~~~~~~~~~~~

Some final closing remarks, e.g., summarizing the main findings
and their implications in other problems can be made. These
remarks will appear at the end of the typeset exercise.

.. --- end exercise ---

.. --- begin exercise ---

Some exercise without the "Exercise:" prefix
--------------------------------------------

.. Another minimalistic exercise

Just some text. And some math saying that :math:`e^0=1` on a single line,
to test that math block insertion is correct:

.. math::
         \exp{(0)} = 1 

And a test that the code ``lambda x: x+2`` is correctly placed here:

.. code-block:: text

    lambda x: x+2

.. Have some comments at the end of the exercise to see that

.. the Filename: ... is written correctly.

.. --- end exercise ---

.. --- begin exercise ---

.. _sec:this:exer:de:

Exercise 8: Solution of differential equation
---------------------------------------------



.. begin quiz

Given

.. math::
         \frac{dy}{dx} = -y(x),\quad y(0)=1 

What is the solution of this equation?


**Choice A:** :math:`y=e^{-y}`

:abbr:`? (Right!)`

**Choice B:** :math:`y=e^{y}`

:abbr:`? (Wrong!)` :abbr:`# (Almost, but the sign is wrong (note the minus!).)`

**Choice C:** .. code-block:: python

    from math import exp
    def f(x):
        return exp(x)

:abbr:`? (Wrong!)`

**Choice D:** The solution cannot be found because there is a derivative in the equation.

:abbr:`? (Wrong!)` :abbr:`# (Equations with derivatives can be solved; they are termed *differential equations*.)`

**Choice E:** The equation is meaningless: an equation must be an equation
for :math:`x` or :math:`y`, not a function :math:`y(x)`.

:abbr:`? (Wrong!)` :abbr:`# (Equations where the unknown is a function, as y(x) here, are called *differential equations*, and are solved by special techniques.)`

.. end quiz



.. --- end exercise ---

.. --- begin exercise ---

Example 9: Just an example
--------------------------

.. This example needs the --examples_as_exercises option, otherwise

.. it is just typeset as it is written.

**a)**
What is the capital of Norway?

**Answer.**
Oslo.

.. --- end exercise ---

.. !split

Here goes another section
=========================

With some text, before we continue with exercises.

.. !split

More Exercises
==============

.. --- begin exercise ---

.. _exer:some:formula:

Exercise 10: Make references to projects and problems
-----------------------------------------------------

.. Test comments not at the end only

Pick a statement from :ref:`proj:circle1` or :ref:`demo:ex:1`
and verify it.

Test list at the end of an exercise without other elements (like subexercise,
hint, etc.):

1. item1

2. item2

Filename: ``verify_formula.py``.

.. --- end exercise ---

.. --- begin exercise ---

.. _exer:you:

Project 11: References in a headings do not work well in sphinx
---------------------------------------------------------------

Refer to the previous exercise as :ref:`exer:some:formula`,
the two before that as :ref:`demo:ex:2` and :ref:`proj:circle1`,
and this one as :ref:`exer:you`.
Filename: ``selc_composed.pdf``.

.. --- end exercise ---

.. !split

References
==========

.. [Ref01]
   **H. P. Langtangen and G. Pedersen**. Propagation of Large Destructive Waves,
   *International Journal of Applied Mechanics and Engineering*,
   7(1),
   pp. 187-204,
   2002.

.. [Ref02]
   **H. P. Langtangen, K.-A. Mardal and R. Winther**. Numerical Methods for Incompressible Viscous Flow,
   *Advances in Water Resources*,
   25,
   pp. 1125-1146,
   2002.

.. [Ref03]
   **H. P. Langtangen**. Numerical Solution of First Passage Problems in Random Vibrations,
   *SIAM Journal of Scientific and Statistical Computing*,
   15,
   pp. 997-996,
   1994.

.. [Ref04]
   **K.-A. Mardal, G. W. Zumbusch and H. P. Langtangen**. Software Tools for Multigrid Methods,
   Advanced Topics in Computational Partial Differential Equations -- Numerical Methods and Diffpack Programming,
   edited by **H. P. Langtangen and A. Tveito**,
   Springer,
   2003,
   Edited book,
   `\urlhttp://some.where.org <\urlhttp://some.where.org>`_.

.. [Ref05]
   **H. P. Langtangen**. The FEMDEQS Program System,
   *Department of Mathematics, University of Oslo*,
   `http://www.math.uio.no/old/days/hpl/femdeqs.pdf <http://www.math.uio.no/old/days/hpl/femdeqs.pdf>`_,
   1989.

.. [Ref06]
   **H. P. Langtangen**. Stochastic Breakthrough Time Analysis of an Enhanced Oil Recovery Process,
   *SIAM Journal on Scientific Computing*,
   13,
   pp. 1394-1417,
   1992.

.. [Ref07]
   **M. Mortensen, H. P. Langtangen and G. N. Wells**. A FEniCS-Based Programming Framework for Modeling Turbulent Flow by the Reynolds-Averaged Navier-Stokes Equations,
   *Advances in Water Resources*,
   34(9),
   `doi: 10.1016/j.advwatres.2011.02.013 <https://dx.doi.org/10.1016/j.advwatres.2011.02.013>`__,
   2011.

.. [Ref08]
   **S. Glimsdal, G. Pedersen, K. Atakan, C. B. Harbitz, H. P. Langtangen and F. L\ovholt**. Propagation of the Dec. |nbsp| 26, 2004 Indian Ocean Tsunami: Effects of Dispersion and Source Characteristics,
   *International Journal of Fluid Mechanics Research*,
   33(1),
   pp. 15-43,
   2006.

.. [Ref09]
   **S. Rahman, J. Gorman, C. H. W. Barnes, D. A. Williams and H. P. Langtangen**. Numerical Investigation of a Piezoelectric Surface Acoustic Wave Interaction With a One-Dimensional Channel,
   *Physical Review B: Condensed Matter and Materials Physics*,
   74,
   2006,
   035308.

.. [Ref10]
   **J. B. Haga, H. Osnes and H. P. Langtangen**. On the Causes of Pressure Oscillations in Low-Permeable and Low-Compressible Porous Media,
   *International Journal of Analytical and Numerical Methods in Geomechanics*,
   `doi: 10.1002/nag.1062 <https://dx.doi.org/10.1002/nag.1062>`__,
   2011,
   `http://onlinelibrary.wiley.com/doi/10.1002/nag.1062/abstract <http://onlinelibrary.wiley.com/doi/10.1002/nag.1062/abstract>`_.

.. [Ref11]
   **H. P. Langtangen**. *Computational Partial Differential Equations - Numerical Methods and Diffpack Programming*,
   second edition,
   *Texts in Computational Science and Engineering*,
   Springer,
   2003.

.. [Ref12]
   **H. P. Langtangen**. *Python Scripting for Computational Science*,
   third edition,
   *Texts in Computational Science and Engineering*,
   Springer,
   2008.

.. [Ref13]
   **H. P. Langtangen and G. Pedersen**. Finite Elements for the Boussinesq Wave Equations,
   Waves and Non-linear Processes in Hydrodynamics,
   edited by **J. Grue, B. Gjevik and J. E. Weber**,
   Kluwer Academic Publishers,
   pp. pp. 117-126,
   1995,
   `http://www.amazon.ca/Waves-Nonlinear-Processes-Hydrodynamics-John/dp/0792340310 <http://www.amazon.ca/Waves-Nonlinear-Processes-Hydrodynamics-John/dp/0792340310>`_.

.. [Ref14]
   **H. P. Langtangen**. *A Primer on Scientific Programming With Python*,
   third edition,
   *Texts in Computational Science and Engineering*,
   Springer,
   2012.

.. [Ref15]
   **P. V. Jeberg, H. P. Langtangen and C. B. Terp**. Optimization With Diffpack: Practical Example From Welding,
   *Simula Research Laboratory*,
   Internal report,
   2004.

.. [Ref16]
   **H. P. Langtangen**. Computational Methods for Two-Phase Flow in Oil Reservoirs,
   Ph.D. Thesis,
   Mechanics Division, Department of Mathematics, University of Oslo,
   1989,
   Dr. |nbsp| Scient. |nbsp| thesis..

.. [Ref17]
   **H. P. Langtangen**. Computational Modeling of Huge Tsunamis From Asteroid Impacts,
   Invited keynote lecture at the \emphInternational conference on Computational Science 2007 (ICCS'07), Beijing, China,
   2007.

.. [Ref18]
   **H. P. Langtangen**. Solution of the Navier-Stokes Equations With the Finite Element Method in Two and Three Dimensions,
   M.Sc. Thesis,
   Mechanics Division, Department of Mathematics, University of Oslo,
   1985,
   Cand.Scient. thesis.

.. [Ref19]
   **H. P. Langtangen and A. Tveito**. Numerical Methods in Continuum Mechanics,
   *Center for Industrial Research*,
   1991,
   Lecture notes for a course (ME-IN 324). 286 pages..

.. [Ref20]
   **H. P. Langtangen**. Diffpack: Software for Partial Differential Equations,
   Proceedings of the Second Annual Object-Oriented Numerics Conference (OON-SKI'94), Sunriver, Oregon, USA,
   edited by **A. Vermeulen**,
   1994.

.. !split

.. _app1:

Appendix: Just for testing; part I
==================================

This is the first appendix.

A subsection within an appendix
-------------------------------

Some text.

.. !split

.. _app2:

Appendix: Just for testing; part II
===================================

This is more stuff for an appendix.

Appendix: Testing identical titles          (1)
-----------------------------------------------

Without label.

.. _test:title:id1:

Appendix: Testing identical titles          (2)
-----------------------------------------------

With label.

.. _test:title:id2:

Appendix: Testing identical titles          (3)
-----------------------------------------------

What about inserting a quiz?



.. !split
Test of quizzes
---------------.. begin quiz



**Fundamental test:** What is the capital of Norway?


**Answer 1:** Stockholm

:abbr:`? (Wrong!)` :abbr:`# (Stockholm is the capital of Sweden.)`

**Answer 2:** London

:abbr:`? (Wrong!)`

**Answer 3:** Oslo

:abbr:`? (Right!)`

**Choice D:** Bergen

:abbr:`? (Wrong!)` :abbr:`# (Those from Bergen would claim so, but nobody else.)`

.. end quiz



Appendix: Testing identical titles          (4)
-----------------------------------------------

Without label.


.. admonition:: Tip

   Here is a tip or hint box, typeset as a notice box.




Need a lot of text to surround the summary box.
Version control systems allow you to record the history of files
and share files among several computers and collaborators in a
professional way. File changes on one computer are updated or
merged with changes on another computer. Especially when working
with programs or technical reports it is essential
to have changes documented and to
ensure that every computer and person involved in the project
have the latest updates of the files.
Greg Wilson' excellent `Script for Introduction to Version Control <https://software-carpentry.org/2010/07/script-for-introduction-to-version-control/>`__ provides a more detailed motivation why you will benefit greatly
from using version control systems.


.. admonition:: Summary

   **Bold remark:** Make some text with this summary.
   Much testing in this document, otherwise stupid content.
   Much testing in this document, otherwise stupid content.
   Much testing in this document, otherwise stupid content.
   Much testing in this document, otherwise stupid content.
   Much testing in this document, otherwise stupid content.
   Much testing in this document, otherwise stupid content.
   Much testing in this document, otherwise stupid content.
   Much testing in this document, otherwise stupid content.
   Much testing in this document, otherwise stupid content.




Projects that you want to share among several computers or project
workers are today most conveniently stored at some web site "in the
cloud" and updated through communication with that site. I strongly
recommend you to use such sites for all serious programming and
scientific writing work - and all other important files.

The simplest services for hosting project files are `Dropbox <https://dropbox.com>`__ and `Google Drive <https://drive.google.com>`__.
It is very easy to get started with these systems, and they allow you
to share files among laptops and mobile units with as many users as
you want. The systems offer a kind of version control in that the
files are stored frequently (several times per minute), and you can go
back to previous versions for the last 30 days. However, it is
challenging  to find the right version from the past when there are
so many of them.

More seriously, when several people may edit files simultaneously, it
can be difficult detect who did what when, roll back to previous
versions, and to manually merge the edits when these are
incompatible. Then one needs more sophisticated tools than Dropbox or
Google Drive: project hosting services with true version control
systems.  The following text aims at providing you with the minimum
information to started with such systems. Numerous other tutorials
contain more comprehensive material and in-depth explanations of the
concepts and tools.

The idea with project hosting services is that you have the files
associated with a project in the cloud. Many people may share these
files.  Every time you want to work on the project you explicitly
update your version of the files, edit the files as you like, and
synchronize the files with the "master version" at the site where the
project is hosted.  If you at some point need to go back to a
version of the files at some particular point in the past,
this is an easy operation. You can also use tools to see
what various people have done with the files in the various versions.

All these services are very similar. Below we describe how you get
started with Bitbucket, GitHub, and Googlecode. Launchpad works very
similarly to the latter three. All the project hosting services have
excellent introductions available at their web sites, but the recipes
below are much shorter and aim at getting you started as quickly as
possible by concentrating on the most important need-to-know steps.
The Git tutorials we refer to later in this document contain more
detailed information and constitute of course very valuable readings
when you use version control systems every day. The point now is
to get started.

Appendix: Testing inline comments
---------------------------------

.. Names can be [ A-Za-z0-9_'+-]+

Projects that you want to share among several computers or project
workers are today most conveniently stored at some web site "in the
cloud" and updated through communication with that
site. [**hpl's semi opinion 1**: not sure if in the cloud is understood by all.] I strongly recommend you to use such sites for all serious
programming and scientific writing work - and all other important
files.

The simplest services for hosting project files is Dropbox. [**mp 2**: Simply go to `<https://dropbox.com>`_ and watch the video. It explains how files, like ``myfile.py``, perhaps containing much math, like :math:`\partial u/\partial t`, are easily communicated between machines.] It
is very easy to get started with Dropbox, and it allows you to share
files among (**hpl 3: remove** laptops and mobile units) (**insert:**)computers, tablets, and phones (**end insert**).

.. Test horizontal rule

---------

.. Coments for editing

First, (**edit 4: add comma**) consider a quantity :math:`Q`. (**edit 5: remove** To this end,) (**insert:**)We note that (**end insert**)
:math:`Q>0`, because (**edit 6**: **delete** a) negative (**edit 7: remove** quantity is) (**insert:**)quantities are (**end insert**) (**edit 8**: **delete** just) negative.  (**edit 9: add**) This comes as no surprise. (**end add**)

.. Test tailored latex figure references with page number

Let us refer to Figure :ref:`fig:impact` again.

Test references in a list:

 * :ref:`sec1`

 * :ref:`subsec1`

 * :ref:`fig:impact`

Appendix: Testing headings ending with ``verbatim inline``
----------------------------------------------------------

The point here is to test 1) ``verbatim`` code in headings, and 2)
ending a heading with verbatim code as this triggers a special
case in LaTeX.

We also test mdash---used as alternative to hyphen without spaces around,
or in quotes:


..

    *Fun is fun*.---Unknown.



The ndash should also be tested - as in the Hanson - Nilson equations
on page 277 - 278.

And finally, what about admons, quotes, and boxes? They are tested
in a separate document: ``admon.do.txt``.

.. [#example-of-the-third-footnote] Not much to add here, but the footnote
   is at the end with only one newline.
************** File: testdoc.gwiki *****************
#summary A Document for Testing DocOnce

By *Hans Petter Langtangen* (hpl at simula.no), *Kaare Dump*, *A. Dummy Author*, *I. S. Overworked and Outburned*, and *J. Doe* (j_doe at cyberspace.com)
==== Jan 32, 2100 ====

Made with DocOnce




<wiki: toc max_depth="2" />




<wiki:comment> !split </wiki:comment>




The format of this document is
gwiki

*Abstract.* This is a document with many test constructions for doconce syntax.
It was used heavily for the development and kept for testing
numerous constructions, also special and less common cases.

And exactly for test purposes we have an extra line here, which
is part of the abstract.

<wiki:comment> Cannot demonstrate chapter headings since abstract and chapter </wiki:comment>
<wiki:comment> are mutually exclusive in LaTeX </wiki:comment>

== Section 1 ==


Here is a nested list:


  * item1
  * item2
  * item3 which continues    on the next line to test that feature
  * and a sublist

    * with indented subitem1
    * and a subitem2


  * and perhaps an ordered sublist

   # first item
   # second item,      continuing on a new line



*Here is a list with paragraph heading.*


  * item1
  * item2

==== Here is a list with subsubsection heading ====

  * item1
  * item2





Here are two references. Equation (my:eq1) is fine. Eq. (my:eq1) too.
Even Equation (my:eq1) without the tilde.


==== Subsection 1 ====

<wiki:comment> Refer to section/appendix etc. at the beginning of the line </wiki:comment>
<wiki:comment> and other special fix situations for HTML. </wiki:comment>

More text, with a reference back to
the section [#Section_1] and [#Subsection_1], and further to the
the sections [#Subsection_1] and [#URLs], which
encourages you to do the tasks in [#Problem_2:_Flip_a_Coin] and [#Exercise_10:_Make_references_to_projects_and_problems].
 [#Appendix:_Just_for_testing;_part_I] and [#Appendix:_Just_for_testing;_part_II] are also nice elements.

==== Test Section reference at beginning of line and after a sentence ====

The section [#Subsection_1] is fine.
The section [#URLs] too.


<wiki:comment> sphinx code-blocks: pycod=python cod=fortran cppcod=c++ sys=console </wiki:comment>

==== Computer code ====

Let's do some copying from files too. First from subroutine up to the very end,

{{{
      subroutine test()
      integer i
      real*8 r
      r = 0
      do i = 1, i
         r = r + i
      end do
      return
C     END1

      program testme
      call test()
      return
}}}
and then just the subroutine,
{{{

      subroutine test()
      integer i
      real*8 r
      r = 0
      do i = 1, i
         r = r + i
      end do
      return
}}}
and finally the complete file with a plain text verbatim environment
(`envir=ccq`):
{{{
C     a comment

      subroutine test()
      integer i
      real*8 r
      r = 0
      do i = 1, i
         r = r + i
      end do
      return
C     END1

      program testme
      call test()
      return
}}}

Testing other code environments. First Python:

{{{
!bc pycod
def f(x):
    return x+1
!ec
}}}
which gets rendered as

{{{
def f(x):
    return x+1
}}}

Test paragraph and subsubsection headings before
before code.

*Paragraph heading before code.*

{{{
import sys
sys.path.insert(0, os.pardir)
}}}

==== Subsubsection heading before code ====

{{{
def h(z):
    return z+1
}}}

Here is a program that is supposed to be interactive via
Python Online Tutorial, but that service is not accessible
for the present format.

{{{
class Line:
    def __init__(self, a, b):
        self.a, self.b = a, b

    def __call__(self, x):
        a, b = self.a, self.b
        return a*x + b

line = Line(2, 1)
y = line(x=3)
print(y)
}}}

Some more Python code (actually specified as a sage cell, but
such cells are not supported by this format).

{{{
a = 2
b = 3
print('a+b:', a + b)

# In a sage cell we can also plot
from matplotlib.pyplot import *
from numpy import *
x = linspace(0, 4*pi, 101)
y = exp(-0.1*x)*cos(x)
plot(x, y)
xlabel('x'); ylabel('y')
show()
}}}


Then Cython (with -h option so it is hidden in html/sphinx):

{{{
cpdef f(double x):
    return x + 1
}}}

Standard Python shell sessions:

{{{
>>> from numpy import linspace, sin
>>> # Some comment
>>> x = linspace(0, 2, 11)
>>> y = sin(x)
>>> y[0]
0
>>> import matplotlib.pyplot as plt
>>> plt.plot(x, y)
}}}

Similar IPython sessions:

{{{
In [1]: from numpy import linspace, sin
In [2]: # Some comment
In [3]: x = linspace(0, 2, 11)
In [4]: y = sin(x)
In [5]: y[0]
Out[5]: 0
In [6]: import matplotlib.pyplot as plt
In [7]: plt.plot(x, y)
In [8]: a='multiple-\nline\noutput'
In [9]: a
Out[9]: 'multiple-\nline\noutput'
In [10]: print(a)
multiple-
line
output
}}}

Here is the interactive session again, but with `pyshell-t`.

{{{
>>> from numpy import linspace, sin
>>> # Some comment
>>> x = linspace(0, 2, 11)
>>> y = sin(x)
>>> y[0]
0
>>> import matplotlib.pyplot as plt
>>> plt.plot(x, y)
}}}

<wiki:comment> This one tests a + sign before a code environment </wiki:comment>
C++:
{{{
#include <iostream>

int main()
{
   std::cout << "Sample output" << std::endl;
   return 0
}
}}}
<wiki:comment> The next should get correctly typset in sphinx (cod is fcod) </wiki:comment>
<wiki:comment> It also tests emoji before code </wiki:comment>
And a little bit of Fortran: :dizzy_face:

{{{
!bc cod
      subroutine midpt(x, length, a, b)
      real*8 a, b, x
      x = (a + b)/2
      length = b - a
      return
      end
!ec
}}}
which then is typeset as

{{{
      subroutine midpt(x, length, a, b)
      real*8 a, b, x
      x = (a + b)/2
      length = b - a
      return
      end
}}}

HTML:

{{{
<table>
<tr><td>Column 1</td><td>Column 2</td></tr>
<tr><td>0.67526 </td><td>0.92871 </td></tr>
<!-- comment -->
</table>
}}}

But inline HTML code is also important, like text that starts with
`<a href="` (which can destroy the following text if not properly
quoted).

Matlab with comments requires special typesetting:

{{{
% Comment on the beginning of the line can be escaped by %%
if a > b
  % Indented comment needs this trick
  c = a + b
end
}}}

And here is a system call:

{{{
Terminal> mkdir test
Terminal> cd test
Terminal> myprog -f
output1
output2
}}}

Any valid pygments lexer/language name can appear to, e.g.,

{{{
!bc restructuredtext
=======
Heading
=======

Some text.
!ec
}}}
results in

{{{
=======
Heading
=======

Some text.
}}}

<wiki:comment> Here goes hidden code. </wiki:comment>
<wiki:comment> Python can be treated by some formats, Fortran is always out. </wiki:comment>





Finally, `!bc do` supports highlighting of DocOnce source:

{{{
======= DocOnce test file =======

===== Computer code =====

Inline verbatim code, as in `import numpy as np`, is allowed, as well as
code blocks:

!bc pycod
from math import sin

def f(x):
    """Example on a function."""
    return sin(x) + 1

print(f(0))
!ec


===== Mathematics =====

Formulas can be inline, as in $\nabla\cdot\bm{u} = 0$, or typeset
as equations:

!bt
\begin{align*}
\nabla\cdot\bm{u} &= 0,\\ 
\bm{u} &= \nabla\phi .
\end{align*}
!et

=== Subsubsection heading ===

DocOnce files can have chapters, sections, subsections, and subsubsections.

__Paragraph heading.__ Paragraphs may have headings.
}}}

It is time to test `verbatim inline font` especially with `a newline
inside the text` and an exclamation mark at the end: `BEGIN`! For
spellcheck, test `a verbatim expression` in `another` in a `third`.
Also test exclamation mark as in `!bc` and `!ec` as well as `a != b`.
Also test backslashes and braces like `\begin`, `\begin{enumerate}`,
`\end{this}\end{that}`, and `{something \inside braces}`.

The following attempt to exemplify colored text does not work in
format gwiki.
Here is some <font color="red">red color</font> and an attempt to write <font color="green">with
green color containing a linebreak

code.</font> Some formats will only display 

this correctly when `html` 

is the output format.
But here some more running text is added which is not part of
the previous blocks with line breaks.

==== Running OS commands ====

{{{
Terminal> python -c 'print("Testing\noutput\nfrom\nPython.")'
Testing
output
from
Python.
}}}


==== Footnotes ====

Here is a test of footnotes [^footnote], which are handy in text.
They are used in different flavors, now in


 * list items (note below that footnotes work after math, verbatim, and URLs - bin fact old and emphasize too!)
 * even with math `\nabla^2u`[^math1]
 * and code `h[i] += 1`[^code]   (*must* have space between inline code and footnote!)
 * and [https://google.com links][^google-search]

which gives flexibility in writing.
This is the third[^example-of-the-third-footnote] example.

  [^footnote]: Typesetting of the footnote depends on the format.
Plain text does nothing, LaTeX removes the
definition and inserts the footnote as part of the LaTeX text.
reStructuredText and Sphinx employ a similar type of typesetting
as Extended Markdown and DocOnce, and in HTML we keep the same
syntax, just displayed properly in HTML.
[^math1]: Math footnotes can be dangerous since it
interferes with an exponent.
[^code]: One-line footnote.

[^google-search]: google.com is perhaps the most famous
web site today.

Here is some more text before a new definition of a footnote that was
used above.

*Non-breaking space character.* 
This paragraph aims to test [https://en.wikipedia.org/wiki/Non-breaking_space non-breaking space character], and a typical
example where this is needed is in physical units: 7.4 km is traveled
in `7.4/5.5\approx 1.345` s.  Also check that a~[https://google.com link]~is
not broken across lines (drag the browser window to test this).
(On the other hand, the tilde is used in
computer code, e.g., as in `[~x for x in y]` or in `y=~x`, and should
of course remain a tilde in those contexts.)



==== Subsection 2: Testing figures ====

Test of figures. In particular we refer to Figure fig:impact in which
there is a flow.



---------------------------------------------------------------

Figure:  Visualization *of* a *wave*. (fig:impact)

(the URL of the image file ../doc/src/manual/fig/wave1D.png must be inserted here)

<wiki:comment>
Put the figure file ../doc/src/manual/fig/wave1D.png on the web (e.g., as part of the
googlecode repository) and substitute the line above with the URL.
</wiki:comment>
---------------------------------------------------------------



Figures without captions are allowed and will be inlined.



---------------------------------------------------------------

Figure: 

(the URL of the image file ../doc/src/manual/fig/wave1D.png must be inserted here)

<wiki:comment>
Put the figure file ../doc/src/manual/fig/wave1D.png on the web (e.g., as part of the
googlecode repository) and substitute the line above with the URL.
</wiki:comment>
---------------------------------------------------------------





<wiki:comment> Test multi-line caption in figure with sidecap=True </wiki:comment>

Here is figure myfig with a long (illegal) multi-line caption
containing inline verbatim text:



---------------------------------------------------------------

Figure:  A long caption spanning several lines and containing verbatim words like `my_file_v1` and `my_file_v2` as well as math with subscript as in `t_{i+1}`. (myfig) 

(the URL of the image file ../doc/src/manual/fig/wave1D.png must be inserted here)

<wiki:comment>
Put the figure file ../doc/src/manual/fig/wave1D.png on the web (e.g., as part of the
googlecode repository) and substitute the line above with the URL.
</wiki:comment>
---------------------------------------------------------------



<wiki:comment> Must be a blank line after MOVIE or FIGURE to detect this problem </wiki:comment>

Test URL as figure name:



---------------------------------------------------------------

Figure: 

(the URL of the image file https://raw.github.com/doconce/doconce/master/doc/src/blog/f_plot.png must be inserted here)

<wiki:comment>
Put the figure file https://raw.github.com/doconce/doconce/master/doc/src/blog/f_plot.png on the web (e.g., as part of the
googlecode repository) and substitute the line above with the URL.
</wiki:comment>
---------------------------------------------------------------




<wiki:comment> Test wikimedia type of files that otherwise reside in subdirs </wiki:comment>


*Remark.*
Movies are tested in separate file `movies.do.txt`.


<wiki:comment> Somewhat challenging heading with latex math, \t, \n, ? and parenthesis </wiki:comment>

==== The `\theta` parameter (not `\nabla`?) ====

Functions do not always need to be advanced, here is one
involving `\theta`:
{{{
def f(theta):
    return theta**2
}}}

*More on `\theta`.* Here is more text following headline with math.

Newcommands must also be tested in this test report:
`\frac{1}{2}`, `{1/2}`, `\pmb{x}`, `\frac{Du}{dt}`,
both inline and in block:

{{{
\begin{align}
\frac{Du}{dt} &= 0\nonumber
\\ 
\frac{1}{2} &= {1/2}\\ 
\frac{1}{2}\pmb{x} &= \pmb{n}
\end{align}
}}}

Or with align with label and numbers:

{{{
\begin{align}
\frac{Du}{dt} &= 0
label{aligneq1}
\\ 
\frac{1}{2} &= {1/2}\\ 
\frac{1}{2}\pmb{x} &= \pmb{n}
label{aligneq2}
\end{align}
}}}


<wiki:comment> Must test more complicated align and matrix compositions </wiki:comment>
<wiki:comment> where DocOnce inserts auto-numbered labels etc. </wiki:comment>

First one numbered (automatically):

{{{
\begin{align}
\begin{pmatrix}
G_2 + G_3 & -G_3 & -G_2 & 0 \\ 
-G_3 & G_3 + G_4 & 0 & -G_4 \\ 
-G_2 & 0 & G_1 + G_2 & 0 \\ 
0 & -G_4 & 0 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
 v_1 \\ 
 v_2 \\ 
 v_3 \\ 
 v_4
\end{pmatrix}
+ \cdots \\ 
\begin{pmatrix}
 C_5 + C_6 & -C_6 & 0 & 0 \\ 
 -C_6 & C_6 & 0 & 0 \\ 
 0 & 0 & 0 & 0 \\ 
 0 & 0 & 0 & 0
\end{pmatrix}
  &= \frac{d}{dt}\begin{pmatrix}
 v_1 \\ 
 v_2 \\ 
 v_3 \\ 
 v_4
\end{pmatrix} +
\begin{pmatrix}
 0 \\ 
 0 \\ 
 0 \\ 
 -i_0
\end{pmatrix}
\nonumber
\end{align}
}}}

Second numbered (automatically):

{{{
\begin{align}
\begin{pmatrix}
G_1 + G_2\\ 
-G_3 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
 v_1 \\ 
 v_2
\end{pmatrix}
+ \cdots\nonumber
\\ 
\left(\begin{array}{ll}
y & 2\\ 
2 & 1
\end{array}\right)
\left(\begin{array}{ll}
0 \\ x
\end{array}\right)
&= \begin{pmatrix}
A \\ B
\end{pmatrix}
\end{align}
}}}

Both numbered, with label by the user:

{{{
\begin{align}
\begin{pmatrix}
G_1 + G_2\\ 
-G_3 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
 v_1 \\ 
 v_2
\end{pmatrix}
+ \cdots label{mymatrix:eq1}
\\ 
label{mymatrix:eq2}
\left(\begin{array}{ll}
y & 2\\ 
2 & 1
\end{array}\right)
\left(\begin{array}{ll}
0 \\ x
\end{array}\right)
&= \begin{pmatrix}
A \\ B
\end{pmatrix}
\end{align}
}}}
Now we refer to Equations (mymatrix:eq1)-(mymatrix:eq2).

==== Custom Environments ====

Here is an attempt to create a theorem environment via Mako
(for counting theorems) and comment lines to help replacing lines in
the `.tex` by proper begin-end LaTeX environments for theorems.
Should look nice in most formats!



<wiki:comment> begin theorem </wiki:comment>



*Theorem 5.*
Let `a=1` and `b=2`. Then `c=3`.
<wiki:comment> end theorem </wiki:comment>

<wiki:comment> begin proof </wiki:comment>
*Proof.*
Since `c=a+b`, the result follows from straightforward addition.
`END`
<wiki:comment> end proof </wiki:comment>

As we see, the proof of Theorem 5 is a modest
achievement.


==== Tables ====

<wiki:comment> index with comma could fool sphinx </wiki:comment>

Let us take this table from the manual:



 ||  _time_   ||  _velocity_   ||  _acceleration_   ||
 ||  0.0      ||  1.4186       ||  -5.01            ||
 ||  2.0      ||  1.376512     ||  11.919           ||
 ||  4.0      ||  1.1E+1       ||  14.717624        ||



The DocOnce source code reads
{{{

  |--------------------------------|
  |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    |
  |--------------------------------|

}}}

Here is yet another table to test that we can handle more than
one table:


 ||  _time_   ||  _velocity_   ||  _acceleration_   ||
 ||  0.0      ||  1.4186       ||  -5.01            ||
 ||  1.0      ||  1.376512     ||  11.919           ||
 ||  3.0      ||  1.1E+1       ||  14.717624        ||


And one with math headings (that are expanded and must be treated
accordingly), verbatim heading and entry, and no space around the pipe
symbol:


 ||  _`i`_   ||  _`h_i`_    ||  _`\bar T_i`_   ||   _`L_i`_    ||
 ||  0       ||  0          ||  288            ||  -0.0065     ||
 ||  1       ||  11,000     ||  216            ||  0.0         ||
 ||  2       ||  20,000     ||  216            ||  0.001       ||
 ||  3       ||  32,000     ||  228            ||  0.0028      ||
 ||  4       ||  47,000     ||  270            ||  0.0         ||
 ||  5       ||  51,000     ||  270            ||  -0.0028     ||
 ||  6       ||  71,000     ||  214            ||  `NaN`       ||


And add one with verbatim headings (with underscores),
and rows starting with `|-` because of a negative number,
and `|` right before and after verbatim word (with no space):


 ||  _exact_   ||  _`v_1`_    ||  _`a_i` + `v_2`_   ||  _`verb_3_`_   ||
 ||  9         ||  9.62       ||  5.57              ||  8.98          ||
 ||  -20       ||  -23.39     ||  -7.65             ||  -19.93        ||
 ||  10        ||  17.74      ||  -4.50             ||  9.96          ||
 ||  0         ||  -9.19      ||  4.13              ||  -0.26         ||


Pipe symbols in verbatim and math text in tables used to pose difficulties,
but not
anymore:


 ||      _`S`_       ||     _command_      ||
 ||  $ ||a_0|| $     ||  `norm|length`     ||
 ||  `x\cap y`       ||  `x|y`             ||



Here is a table with X alignment:


 ||   _Type_   ||                                                                                                       _Description_                                                                                                         ||
 ||  X         ||  Alignment character that is used for specifying a potentially very long text in a column in a table. It makes use of the `tabularx` package in LaTeX, otherwise (for other formats) it means `l` (centered alignment).     ||
 ||  l,r,c     ||  standard alignment characters                                                                                                                                                                                              ||


Finally, a table with math
and URLs.

<wiki:comment> Mako code to expand URLs in the table </wiki:comment>
<wiki:comment> (These types of tables did not work before Jan 2014) </wiki:comment>



 ||  `\mathcal{L}=0`             ||  [../doc/src/manual/mov/wave_frames/frame_0080.png `080`]     ||  [../doc/src/manual/mov/wave_frames/frame_0085.png `085`]     ||
 ||  `a=b`                       ||  [../doc/src/manual/mov/wave_frames/frame_0090.png `090`]     ||  [../doc/src/manual/mov/wave_frames/frame_0095.png `095`]     ||
 ||  `\nabla\cdot\bm{u} =0 `     ||  [../doc/src/manual/mov/wave_frames/frame_0100.png `100`]     ||  [../doc/src/manual/mov/wave_frames/frame_0105.png `105`]     ||



==== A test of verbatim words in heading with subscript `a_i`: `my_file_v1` and `my_file_v2` ====

*Paragraph with verbatim and math: `my_file_v1.py` and `my_file_v2.py` define some math `a_{i-1}`.* Here is more `__verbatim__` code and
some plain text on a new line.

<wiki:comment> Test various types of headlines </wiki:comment>
==== *Just bold* ====

Some text.

==== *Just emphasize* ====

Some text.

==== `Just verbatim` ====

Some text.

==== *Bold* beginning ====

Some text.

==== *Emphasize* beginning ====

Some text.

==== `Verbatim` beginning ====

Some text.

==== Maybe *bold end* ====

Some text.

==== Maybe *emphasize end* ====

Some text.

==== Maybe `verbatim end` ====

Some text.

==== The middle has *bold* word ====

Some text.

==== The middle has *emphasize* word ====

Some text.

==== The middle has `verbatim` word ====

Some text.


**Just emphasize*.* Some text.


*`Just verbatim`.* Some text.


**Emphasize* beginning.* Some text.


*`Verbatim beginning`.* Some text.


*Maybe *emphasize end*.* Some text.


*Maybe `verbatim end`.* Some text.


*The middle has *emphasize* word.* Some text.


*The middle has `verbatim` word.* Some text.


*Ampersand.*
We can test Hennes & Mauritz, often abbreviated H&M, but written
as `Hennes & Mauritz` and `H & M`.
A sole `&` must also work.
<wiki:comment> Note: substitutions must not occur inside verbatim, just in ordinary text. </wiki:comment>

{{{
# Just to check that ampersand works in code blocks:
c = a & b
}}}

*Quotes.*
Let us also add a test of quotes such as "double quotes, with numbers
like 3.14 and newline/comma and hyphen (as in double-quote)"; written
in the standard LaTeX-style that gives correct LaTeX formatting and
ordinary double quotes for all non-LaTeX formats.  Here is another
sentence that "caused" a bug in the past because double backtick
quotes could imply verbatim text up to a verbatim word starting with
period, like `.txt`.

More quotes to be tested for spellcheck:
("with parenthesis"), "with newline"
and "with comma", "hyphen"-wise, and "period".


==== Bibliography test ====

Here is an example: [1] discussed propagation of
large destructive water waves, [2] gave
an overview of numerical methods for solving the Navier - Stokes equations,
while the use of Backward Kolmogorov equations for analyzing
random vibrations was investigated in [3].
The book chapter [4] contains information on
C++ software tools for programming multigrid methods. A real retro
reference is [5] about a big FORTRAN package.
Multiple references are also possible, e.g., see
[1] [4].

We need to cite more than 10 papers to reproduce an old formatting
problem with blanks in the keys in reST format:
[6] [3] [7] [1]
and
[2] [8] [9] [10] [11] [12] [13]
and all the work of
[14] [4] [15] as well as
old work [5] and [16], and the
talk [17].
Langtangen also had two thesis [18] [16]
back in the days.
More retro citations are
the old ME-IN323 book [19] and the
[20] OONSKI '94 paper.




<wiki:comment> --- begin exercise --- </wiki:comment>

==== Example 1: Examples can be typeset as exercises ====

Examples can start with a subsection heading starting with `Example:`
and then, with the command-line option `--examples_as_exercises` be
typeset as exercises. This is useful if one has solution
environments as part of the example.


*a)*
State some problem.

*Solution.*
The answer to this subproblem can be written here.

*b)*
State some other problem.

*Hint 1.*
A hint can be given.

*Hint 2.*
Maybe even another hint?

*Solution.*
The answer to this other subproblem goes here,
maybe over multiple doconce input lines.

<wiki:comment> --- end exercise --- </wiki:comment>


==== User-defined environments ====

The example in the section [#Example_1:_A_test_function] demonstrates how to write a test function.
That is, a special test function for a function `add` appears in
the example in the section [#Example_1:_A_test_function].



==== Example 1: A test function ====

Suppose we want to write a test function for checking the
implementation of a Python function for addition.

{{{
def add(a, b):
    return a + b

def test_add():
    a = 1; b = 1
    expected = a + b
    computed = add(a, b)
    assert expected == computed
}}}





==== Example 2: Addition ====

We have

{{{
\[ 1 + 1 = 2 \]
}}}
or in tabular form:


 ||  _Problem_   ||  _Result_   ||
 ||  `1+1`       ||  `2`        ||




*Highlight box!* 
This environment is used to highlight something:

{{{
\[ E = mc^2 \]
}}}





==== URLs ====

Testing of URLs: hpl's home page [https://folk.uio.no/hpl hpl], or
the entire URL if desired, https://folk.uio.no/hpl.  Here is a
plain file link testdoc.do.txt, or testdoc.do.txt, or
testdoc.do.txt or testdoc.do.txt or [testdoc.do.txt a link with
newline]. Can test spaces with the link with word
too: [https://folk.uio.no/hpl hpl] or [https://folk.uio.no/hpl hpl]. Also `file:///` works: [file:///home/hpl/vc/doconce/doc/demos/manual/manual.html link to a
file] is
fine to have. Moreover, "loose" URLs work, i.e., no quotes, just
the plain URL as in https://folk.uio.no/hpl, if followed by space, comma,
colon, semi-colon, question mark, exclamation mark, but not a period
(which gets confused with the periods inside the URL).

Mail addresses can also be used: [mailto:hpl@simula.no `hpl@simula.no`], or just a [mailto:hpl@simula.no mail link], or a raw mailto:hpl@simula.no.

Here are some tough tests of URLs, especially for the `latex` format:
[https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas Newton-Cotes] formulas
and a [https://www.springer.com/mathematics/computational+science+%26+engineering/book/978-3-642-23098-1 good book]. Need to test
Newton-Cotes with percentage in URL too:
https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas
and https://en.wikipedia.org/wiki/Newton-Cotes#Open_Newton.E2.80.93Cotes_formulae which has a shebang.

For the `--device=paper` option it is important to test that URLs with
monospace font link text get a footnote
(unless the `--latex_no_program_footnotelink`
is used), as in this reference to
[https://github.com/hplgit/INF5620/tree/gh-pages/src/decay/experiments/decay_mod.py `decay_mod`], [https://tinyurl.com/pwyasaa/formulas.ball1.py `ball1.py`],
and [https://tinyurl.com/pwyasaa/formulas.ball2.py `ball2.py`].


<wiki:comment> Comments should be inserted outside paragraphs (because in the rst </wiki:comment>
<wiki:comment> format extra blanks make a paragraph break). </wiki:comment>

<wiki:comment> Note that when there is no https: or file:, it can be a file link </wiki:comment>
<wiki:comment> if the link name is URL, url, "URL", or "url". Such files should, </wiki:comment>
<wiki:comment> if rst output is desired, but placed in a `_static*` folder. </wiki:comment>

More tough tests: repeated URLs whose footnotes when using the
`--device=paper` option must be correct. We have
[https://google.com google], [https://google.com google], and
[https://google.com google], which should result in exactly three
footnotes.



<wiki:comment> !split and check if these extra words are included properly in the comment </wiki:comment>

== LaTeX Mathematics ==

Here is an equation without label using backslash-bracket environment:
{{{
\[ a = b + c \]
}}}

or with number and label, as in Equation (my:eq1), using the equation environment:

{{{
\begin{equation}
{\partial u\over\partial t} = \nabla^2 u label{my:eq1}
\end{equation}
}}}

We can refer to this equation by Equation (my:eq1).

Here is a system without equation numbers, using the align-asterisk environment:

{{{
\begin{align*}
\pmb{a} &= \pmb{q}\times\pmb{n} \\ 
b &= \nabla^2 u + \nabla^4 v
\end{align*}
}}}



More mathematical typesetting is demonstrated in the coming exercises.

Below, we have [#Problem_2:_Flip_a_Coin] and [#Project_4:_Compute_a_Probability],
as well as [#Project_5:_Explore_Distributions_of_Random_Circles] and [#Project_11:_References_to_Project_demo:ex:2_in_a_heading_works_for_gwiki], and in
between there we have [#Exercise_10:_Make_references_to_projects_and_problems].


== Exercises ==



<wiki:comment> --- begin exercise --- </wiki:comment>

==== Problem 2: Flip a Coin ====

<wiki:comment> keywords = random numbers; Monte Carlo simulation; ipynb </wiki:comment>

<wiki:comment> Torture tests </wiki:comment>


*a)*
Make a program that simulates flipping a coin `N` times.
Print out "tail" or "head" for each flip and
let the program count the number of heads.

<wiki:comment> --- begin hint in exercise --- </wiki:comment>

*Hint 1.*
Use `r = random.random()` and define head as `r <= 0.5`.

<wiki:comment> --- end hint in exercise --- </wiki:comment>

<wiki:comment> --- begin hint in exercise --- </wiki:comment>

*Hint 2.*
Draw an integer among `\{1,2\}` with
`r = random.randint(1,2)` and define head when `r` is 1.

<wiki:comment> --- end hint in exercise --- </wiki:comment>


<wiki:comment> --- begin answer of exercise --- </wiki:comment>
*Answer.*
If the `random.random()` function returns a number `<1/2`, let it be
head, otherwise tail. Repeat this `N` number of times.
<wiki:comment> --- end answer of exercise --- </wiki:comment>


<wiki:comment> --- begin solution of exercise --- </wiki:comment>
*Solution.*
{{{
import sys, random
N = int(sys.argv[1])
heads = 0
for i in range(N):
    r = random.random()
    if r <= 0.5:
        heads += 1
print('Flipping a coin %d times gave %d heads' % (N, heads))
}}}
<wiki:comment> --- end solution of exercise --- </wiki:comment>

*b)*
Vectorize the code in a) using boolean indexing.

Vectorized code can be written in many ways.
Sometimes the code is less intuitive, sometimes not.
At least there is not much to find in the section [#Section_1].

*c)*
Vectorize the code in a) using `numpy.sum`.


<wiki:comment> --- begin answer of exercise --- </wiki:comment>
*Answer.*
`np.sum(np.where(r <= 0.5, 1, 0))` or `np.sum(r <= 0.5)`.
<wiki:comment> --- end answer of exercise --- </wiki:comment>

In this latter subexercise, we have an
example where the code is easy to read.


==== My remarks ====

Remarks with such a subsubsection is treated as more text
after the last subexercise. Test a list too:


# Mark 1.
# Mark 2.

Filenames: `flip_coin.py`, `flip_coin.pdf`.

<wiki:comment> Closing remarks for this Problem </wiki:comment>

==== Remarks ====

These are the exercise remarks, appearing at the very end.

<wiki:comment> solution files: mysol.txt, mysol_flip_coin.py, yet_another.file </wiki:comment>

<wiki:comment> --- end exercise --- </wiki:comment>


==== Not an exercise ====

Should be possible to stick a normal section in the middle of many
exercises.



<wiki:comment> --- begin exercise --- </wiki:comment>

==== Exercise 3: Test of plain text exercise ====

Very short exercise. What is the capital
of Norway?
Filename: `myexer1`.

<wiki:comment> --- end exercise --- </wiki:comment>




<wiki:comment> --- begin exercise --- </wiki:comment>

==== Project 4: Compute a Probability ====

<wiki:comment> Minimalistic exercise </wiki:comment>


What is the probability of getting a number between 0.5 and 0.6 when
drawing uniformly distributed random numbers from the interval `[0,1)`?


At the end we have a list because that caused problems in LaTeX
in previous DocOnce versions:


# item1
# item2

<wiki:comment> --- begin hint in exercise --- </wiki:comment>

*Hint.*
To answer this question empirically, let a program
draw `N` such random numbers using Python's standard `random` module,
count how many of them, `M`, that fall in the interval `(0.5,0.6)`, and
compute the probability as `M/N`.

<wiki:comment> --- end hint in exercise --- </wiki:comment>

<wiki:comment> --- end exercise --- </wiki:comment>




<wiki:comment> --- begin exercise --- </wiki:comment>

==== Project 5: Explore Distributions of Random Circles ====

<wiki:comment> keywords = ipynb </wiki:comment>

The formula for a circle is given by

{{{
\begin{align}
x &= x_0 + R\cos 2\pi t,
label{circle:x}\\ 
y &= y_0 + R\sin 2\pi t,
label{circle:y}
\end{align}
}}}
where `R` is the radius of the circle, `(x_0,y_0)` is the
center point, and `t` is a parameter in the unit interval `[0,1]`.
For any `t`, `(x,y)` computed from Equations (circle:x)-(circle:y)
is a point on the circle.
The formula can be used to generate `n` points on a circle:

{{{
import numpy as np

def circle(R, x0, y0, n=501):
    t = np.linspace(0, 1, n)
    x = x0 + R*np.cos(2*np.pi*t)
    y = y0 + R*np.sin(2*np.pi*t)
    return x, y

x, y = circle(2.0, 0, 0)
}}}

<wiki:comment> Often in an exercise we have some comments about the solution </wiki:comment>
<wiki:comment> which we normally want to keep where they are. </wiki:comment>

The goal of this project is to draw `N` circles with random
center and radius. Plot each circle using the `circle` function
above.


*a)*
Let `R` be normally distributed and `(x_0,y_0)` uniformly distributed.

<wiki:comment> --- begin hint in exercise --- </wiki:comment>

*Hint.*
Use the `numpy.random` module to draw the
`x_0`, `y_0`, and `R` quantities.

<wiki:comment> --- end hint in exercise --- </wiki:comment>


<wiki:comment> --- begin answer of exercise --- </wiki:comment>
*Answer.*
Here goes the short answer to part a).
<wiki:comment> --- end answer of exercise --- </wiki:comment>


<wiki:comment> --- begin solution of exercise --- </wiki:comment>
*Solution.*
Here goes a full solution to part a).
<wiki:comment> --- end solution of exercise --- </wiki:comment>

*b)*
Let `R` be uniformly distributed and `(x_0,y_0)` normally distributed.
Filename: `norm`.

*c)*
Let `R` and `(x_0,y_0)` be normally distributed.


Filename: `circles`.

<wiki:comment> Closing remarks for this Project </wiki:comment>

==== Remarks ====

At the very end of the exercise it may be appropriate to summarize
and give some perspectives.


<wiki:comment> --- end exercise --- </wiki:comment>




<wiki:comment> --- begin exercise --- </wiki:comment>

==== Exercise 6: Determine some Distance ====

Intro to this exercise. Questions are in subexercises below.


<wiki:comment> --- begin solution of exercise --- </wiki:comment>
*Solution.*
Here goes a full solution of the whole exercise.
With some math `a=b` in this solution:
{{{
\[ \hbox{math in solution: } a = b \]
}}}
And code `a=b` in this solution:
{{{
a = b  # code in solution
}}}
End of solution is here.

<wiki:comment> --- end solution of exercise --- </wiki:comment>


*a)*
Subexercises are numbered a), b), etc.

<wiki:comment> --- begin hint in exercise --- </wiki:comment>

*Hint 1.*
First hint to subexercise a).
With math `a=b` in hint:

{{{
\[ a=b. \]
}}}
And with code (in plain verbatim) returning `x+1` in hint:

{{{
def func(x):
    return x + 1  # with code in hint
}}}

<wiki:comment> --- end hint in exercise --- </wiki:comment>

<wiki:comment> --- begin hint in exercise --- </wiki:comment>

*Hint 2.*
Second hint to subexercise a).

Test list in hint:


# item1
# item2

<wiki:comment> --- end hint in exercise --- </wiki:comment>
Filename: `subexer_a.pdf`.


<wiki:comment> --- begin answer of exercise --- </wiki:comment>
*Answer.*
Short answer to subexercise a).
With math in answer: `a=b`.
<wiki:comment> --- end answer of exercise --- </wiki:comment>

*b)*
Here goes the text for subexercise b).


Some math `\cos^2 x + \sin^2 x = 1` written one a single line:

{{{
\[ \cos^2 x + \sin^2 x = 1 \thinspace .\]
}}}

<wiki:comment> --- begin hint in exercise --- </wiki:comment>

*Hint.*
A hint for this subexercise.

<wiki:comment> --- end hint in exercise --- </wiki:comment>
Filename: `subexer_b.pdf`.


<wiki:comment> --- begin solution of exercise --- </wiki:comment>
*Solution.*
Here goes the solution of this subexercise.
<wiki:comment> --- end solution of exercise --- </wiki:comment>



<wiki:comment> No meaning in this weired test example: </wiki:comment>
The text here belongs to the main (intro) part of the exercise. Need
closing remarks to have text after subexercises.

Test list in exercise:


# item1
# item2<wiki:comment> Closing remarks for this Exercise </wiki:comment>


==== Remarks ====

Some final closing remarks, e.g., summarizing the main findings
and their implications in other problems can be made. These
remarks will appear at the end of the typeset exercise.


<wiki:comment> --- end exercise --- </wiki:comment>




<wiki:comment> --- begin exercise --- </wiki:comment>

==== Some exercise without the "Exercise:" prefix ====

<wiki:comment> Another minimalistic exercise </wiki:comment>

Just some text. And some math saying that `e^0=1` on a single line,
to test that math block insertion is correct:

{{{
\[ \exp{(0)} = 1 \]
}}}

And a test that the code `lambda x: x+2` is correctly placed here:

{{{
lambda x: x+2
}}}


<wiki:comment> Have some comments at the end of the exercise to see that </wiki:comment>
<wiki:comment> the Filename: ... is written correctly. </wiki:comment>
<wiki:comment> --- end exercise --- </wiki:comment>




<wiki:comment> --- begin exercise --- </wiki:comment>

==== Exercise 8: Solution of differential equation ====



Given

{{{
\[ \frac{dy}{dx} = -y(x),\quad y(0)=1 \]
}}}
What is the solution of this equation?

Choice A: `y=e^{-y}`

Choice B: `y=e^{y}`

Choice C: 
{{{
from math import exp
def f(x):
    return exp(x)
}}}

Choice D: The solution cannot be found because there is a derivative in the equation.

Choice E: The equation is meaningless: an equation must be an equation
for `x` or `y`, not a function `y(x)`.



<wiki:comment> --- end exercise --- </wiki:comment>




<wiki:comment> --- begin exercise --- </wiki:comment>

==== Example 9: Just an example ====

<wiki:comment> This example needs the --examples_as_exercises option, otherwise </wiki:comment>
<wiki:comment> it is just typeset as it is written. </wiki:comment>


*a)*
What is the capital of Norway?

*Answer.*
Oslo.

<wiki:comment> --- end exercise --- </wiki:comment>


== Here goes another section ==

With some text, before we continue with exercises.

== More Exercises ==



<wiki:comment> --- begin exercise --- </wiki:comment>

==== Exercise 10: Make references to projects and problems ====

<wiki:comment> Test comments not at the end only </wiki:comment>
Pick a statement from [#Project_5:_Explore_Distributions_of_Random_Circles] or [#Problem_2:_Flip_a_Coin]
and verify it.

Test list at the end of an exercise without other elements (like subexercise,
hint, etc.):


# item1
# item2

Filename: `verify_formula.py`.

<wiki:comment> --- end exercise --- </wiki:comment>




<wiki:comment> --- begin exercise --- </wiki:comment>

==== Project 11: References to [#Project_4:_Compute_a_Probability] in a heading works for gwiki ====

Refer to the previous exercise as [#Exercise_10:_Make_references_to_projects_and_problems],
the two before that as [#Project_4:_Compute_a_Probability] and [#Project_5:_Explore_Distributions_of_Random_Circles],
and this one as [#Project_11:_References_to_Project_demo:ex:2_in_a_heading_works_for_gwiki].
Filename: `selc_composed.pdf`.

<wiki:comment> --- end exercise --- </wiki:comment>


== References ==


 # *H. P. Langtangen and G. Pedersen*.     Propagation of Large Destructive Waves,    *International Journal of Applied Mechanics and Engineering*,    7(1),    pp. 187-204,    2002.
 # *H. P. Langtangen, K.-A. Mardal and R. Winther*.     Numerical Methods for Incompressible Viscous Flow,    *Advances in Water Resources*,    25,    pp. 1125-1146,    2002.
 # *H. P. Langtangen*.     Numerical Solution of First Passage Problems in Random Vibrations,    *SIAM Journal of Scientific and Statistical Computing*,    15,    pp. 997-996,    1994.
 # *K.-A. Mardal, G. W. Zumbusch and H. P. Langtangen*.     Software Tools for Multigrid Methods,    *Advanced Topics in Computational Partial Differential Equations -- Numerical Methods and Diffpack Programming*,    edited by *H. P. Langtangen and A. Tveito*,    Springer,    2003,    Edited book,    http://some.where.org.
 # *H. P. Langtangen*.     The FEMDEQS Program System,    *Department of Mathematics, University of Oslo*,    1989,    http://www.math.uio.no/old/days/hpl/femdeqs.pdf.
 # *H. P. Langtangen*.     Stochastic Breakthrough Time Analysis of an Enhanced Oil Recovery Process,    *SIAM Journal on Scientific Computing*,    13,    pp. 1394-1417,    1992.
 # *M. Mortensen, H. P. Langtangen and G. N. Wells*.     A FEniCS-Based Programming Framework for Modeling Turbulent Flow by the Reynolds-Averaged Navier-Stokes Equations,    *Advances in Water Resources*,    34(9),    [https://dx.doi.org/10.1016/j.advwatres.2011.02.013 doi: 10.1016/j.advwatres.2011.02.013],    2011.
 # *S. Glimsdal, G. Pedersen, K. Atakan, C. B. Harbitz, H. P. Langtangen and F. L\ovholt*.     Propagation of the Dec. 26, 2004 Indian Ocean Tsunami: Effects of Dispersion and Source Characteristics,    *International Journal of Fluid Mechanics Research*,    33(1),    pp. 15-43,    2006.
 # *S. Rahman, J. Gorman, C. H. W. Barnes, D. A. Williams and H. P. Langtangen*.     Numerical Investigation of a Piezoelectric Surface Acoustic Wave Interaction With a One-Dimensional Channel,    *Physical Review B: Condensed Matter and Materials Physics*,    74,    2006,    035308.
# *J. B. Haga, H. Osnes and H. P. Langtangen*.     On the Causes of Pressure Oscillations in Low-Permeable and Low-Compressible Porous Media,    *International Journal of Analytical and Numerical Methods in Geomechanics*,    [https://dx.doi.org/10.1002/nag.1062 doi: 10.1002/nag.1062],    2011,    http://onlinelibrary.wiley.com/doi/10.1002/nag.1062/abstract.
# *H. P. Langtangen*.     *Computational Partial Differential Equations - Numerical Methods and Diffpack Programming*,    second edition,    *Texts in Computational Science and Engineering*,    Springer,    2003.
# *H. P. Langtangen*.     *Python Scripting for Computational Science*,    third edition,    *Texts in Computational Science and Engineering*,    Springer,    2008.
# *H. P. Langtangen and G. Pedersen*.     Finite Elements for the Boussinesq Wave Equations,    Waves and Non-linear Processes in Hydrodynamics,    edited by *J. Grue, B. Gjevik and J. E. Weber*,    Kluwer Academic Publishers,    pp. pp. 117-126,    1995,    http://www.amazon.ca/Waves-Nonlinear-Processes-Hydrodynamics-John/dp/0792340310.
# *H. P. Langtangen*.     *A Primer on Scientific Programming With Python*,    third edition,    *Texts in Computational Science and Engineering*,    Springer,    2012.
# *P. V. Jeberg, H. P. Langtangen and C. B. Terp*.     Optimization With Diffpack: Practical Example From Welding,    *Simula Research Laboratory*,    2004,    Internal report.
# *H. P. Langtangen*.     Computational Methods for Two-Phase Flow in Oil Reservoirs,    Ph.D. Thesis,    Mechanics Division, Department of Mathematics, University of Oslo,    1989,    Dr. Scient. thesis..
# *H. P. Langtangen*.     Computational Modeling of Huge Tsunamis From Asteroid Impacts,    2007,    Invited keynote lecture at the \emphInternational conference on Computational Science 2007 (ICCS'07), Beijing, China.
# *H. P. Langtangen*.     Solution of the Navier-Stokes Equations With the Finite Element Method in Two and Three Dimensions,    M.Sc. Thesis,    Mechanics Division, Department of Mathematics, University of Oslo,    1985,    Cand.Scient. thesis.
# *H. P. Langtangen and A. Tveito*.     Numerical Methods in Continuum Mechanics,    *Center for Industrial Research*,    1991,    Lecture notes for a course (ME-IN 324). 286 pages..
# *H. P. Langtangen*.     Diffpack: Software for Partial Differential Equations,    *Proceedings of the Second Annual Object-Oriented Numerics Conference (OON-SKI'94), Sunriver, Oregon, USA*,    edited by *A. Vermeulen*,    1994.

== Appendix: Just for testing; part I ==


This is the first appendix.

==== A subsection within an appendix ====

Some text.

== Appendix: Just for testing; part II ==


This is more stuff for an appendix.

==== Appendix: Testing identical titles ====

Without label.


==== Appendix: Testing identical titles ====

With label.

==== Appendix: Testing identical titles ====

What about inserting a quiz?



======= Test of quizzes =======


Fundamental test: What is the capital of Norway?

Answer 1: Stockholm

Answer 2: London

Answer 3: Oslo

Choice D: Bergen




==== Appendix: Testing identical titles ====

Without label.

*Tip.* 
Here is a tip or hint box, typeset as a notice box.





Need a lot of text to surround the summary box.
Version control systems allow you to record the history of files
and share files among several computers and collaborators in a
professional way. File changes on one computer are updated or
merged with changes on another computer. Especially when working
with programs or technical reports it is essential
to have changes documented and to
ensure that every computer and person involved in the project
have the latest updates of the files.
Greg Wilson' excellent [https://software-carpentry.org/2010/07/script-for-introduction-to-version-control/ Script for Introduction to Version Control] provides a more detailed motivation why you will benefit greatly
from using version control systems.

*Summary.* 
*Bold remark:* Make some text with this summary.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.



Projects that you want to share among several computers or project
workers are today most conveniently stored at some web site "in the
cloud" and updated through communication with that site. I strongly
recommend you to use such sites for all serious programming and
scientific writing work - and all other important files.

The simplest services for hosting project files are [https://dropbox.com Dropbox] and [https://drive.google.com Google Drive].
It is very easy to get started with these systems, and they allow you
to share files among laptops and mobile units with as many users as
you want. The systems offer a kind of version control in that the
files are stored frequently (several times per minute), and you can go
back to previous versions for the last 30 days. However, it is
challenging  to find the right version from the past when there are
so many of them.

More seriously, when several people may edit files simultaneously, it
can be difficult detect who did what when, roll back to previous
versions, and to manually merge the edits when these are
incompatible. Then one needs more sophisticated tools than Dropbox or
Google Drive: project hosting services with true version control
systems.  The following text aims at providing you with the minimum
information to started with such systems. Numerous other tutorials
contain more comprehensive material and in-depth explanations of the
concepts and tools.

The idea with project hosting services is that you have the files
associated with a project in the cloud. Many people may share these
files.  Every time you want to work on the project you explicitly
update your version of the files, edit the files as you like, and
synchronize the files with the "master version" at the site where the
project is hosted.  If you at some point need to go back to a
version of the files at some particular point in the past,
this is an easy operation. You can also use tools to see
what various people have done with the files in the various versions.

All these services are very similar. Below we describe how you get
started with Bitbucket, GitHub, and Googlecode. Launchpad works very
similarly to the latter three. All the project hosting services have
excellent introductions available at their web sites, but the recipes
below are much shorter and aim at getting you started as quickly as
possible by concentrating on the most important need-to-know steps.
The Git tutorials we refer to later in this document contain more
detailed information and constitute of course very valuable readings
when you use version control systems every day. The point now is
to get started.


==== Appendix: Testing inline comments ====

<wiki:comment> Names can be [ A-Za-z0-9_'+-]+ </wiki:comment>

Projects that you want to share among several computers or project
workers are today most conveniently stored at some web site "in the
cloud" and updated through communication with that
site.  I strongly recommend you to use such sites for all serious
programming and scientific writing work - and all other important
files.

The simplest services for hosting project files is Dropbox.  It
is very easy to get started with Dropbox, and it allows you to share
files among .

<wiki:comment> Test horizontal rule </wiki:comment>

------

<wiki:comment> Coments for editing </wiki:comment>

First consider a quantity `Q`. 
`Q>0`, because  negative   negative. 

<wiki:comment> Test tailored latex figure references with page number </wiki:comment>
Let us refer to Figure fig:impact again.

Test references in a list:


 * [#Section_1]
 * [#Subsection_1]
 * fig:impact

==== Appendix: Testing headings ending with `verbatim inline` ====

The point here is to test 1) `verbatim` code in headings, and 2)
ending a heading with verbatim code as this triggers a special
case in LaTeX.

We also test mdash---used as alternative to hyphen without spaces around,
or in quotes:





The ndash should also be tested - as in the Hanson - Nilson equations
on page 277 - 278.

And finally, what about admons, quotes, and boxes? They are tested
in a separate document: `admon.do.txt`.

[^example-of-the-third-footnote]: Not much to add here, but the footnote
is at the end with only one newline.

************** File: testdoc.mwiki *****************
#TITLE (actually governed by the filename): A Document for Testing DocOnce

By '''Hans Petter Langtangen''' (hpl at simula.no), '''Kaare Dump''', '''A. Dummy Author''', '''I. S. Overworked and Outburned''', and '''J. Doe''' (j_doe at cyberspace.com)
==== Jan 32, 2100 ====

Made with DocOnce




__TOC__




<!-- !split -->




The format of this document is
mwiki

''Abstract.'' This is a document with many test constructions for doconce syntax.
It was used heavily for the development and kept for testing
numerous constructions, also special and less common cases.

And exactly for test purposes we have an extra line here, which
is part of the abstract.

<!-- Cannot demonstrate chapter headings since abstract and chapter -->
<!-- are mutually exclusive in LaTeX -->

== Section 1 ==


Here is a nested list:


<ul>
  <li> item1
  <li> item2
  <li> item3 which continues
    on the next line to test that feature
  <li> and a sublist

<ul>
    <li><li> with indented subitem1
    <li><li> and a subitem2
</ul>

  <li> and perhaps an ordered sublist

<ol type="a">
   <li><li> first item
   <li><li> second item,
      continuing on a new line
</ol>

</ul>

''Here is a list with paragraph heading.''


<ul>
  <li> item1
  <li> item2
</ul>

==== Here is a list with subsubsection heading ====

<ul>
  <li> item1
  <li> item2
</ul>


{{quote box
| quote = Here are two lines that make up
a block quote for testing ''emphasized words'' and '''boldface words''',
also with hypens:
''pre''-fix, post-''fix'', '''pre'''-fix, post-'''fix'''.
| textstyle = font-size: 90%;
}}



Here are two references. Equation&nbsp;(my:eq1) is fine. Eq.&nbsp;(my:eq1) too.
Even Equation (my:eq1) without the tilde.


==== Subsection 1 ====

<!-- Refer to section/appendix etc. at the beginning of the line -->
<!-- and other special fix situations for HTML. -->

More text, with a reference back to
the section [#Section_1] and [#Subsection_1], and further to the
the sections [#Subsection_1] and [#URLs], which
encourages you to do the tasks in [#Problem_2:_Flip_a_Coin] and [#Exercise_10:_Make_references_to_projects_and_problems].
 [#Appendix:_Just_for_testing;_part_I] and [#Appendix:_Just_for_testing;_part_II] are also nice elements.

==== Test Section reference at beginning of line and after a sentence ====

The section [#Subsection_1] is fine.
The section [#URLs] too.


<!-- sphinx code-blocks: pycod=python cod=fortran cppcod=c++ sys=console -->

==== Computer code ====

Let's do some copying from files too. First from subroutine up to the very end,

<syntaxhighlight lang="fortran">
      subroutine test()
      integer i
      real*8 r
      r = 0
      do i = 1, i
         r = r + i
      end do
      return
C     END1

      program testme
      call test()
      return
</syntaxhighlight>
and then just the subroutine,
<syntaxhighlight lang="fortran">
      subroutine test()
      integer i
      real*8 r
      r = 0
      do i = 1, i
         r = r + i
      end do
      return
</syntaxhighlight>
and finally the complete file with a plain text verbatim environment
(<code>envir=ccq</code>):
<syntaxhighlight lang="text">
C     a comment

      subroutine test()
      integer i
      real*8 r
      r = 0
      do i = 1, i
         r = r + i
      end do
      return
C     END1

      program testme
      call test()
      return
</syntaxhighlight>

Testing other code environments. First Python:

<syntaxhighlight lang="text">
!bc pycod
def f(x):
    return x+1
!ec
</syntaxhighlight>
which gets rendered as

<syntaxhighlight lang="python">
def f(x):
    return x+1
</syntaxhighlight>

Test paragraph and subsubsection headings before
before code.

''Paragraph heading before code.''

<syntaxhighlight lang="python">
import sys
sys.path.insert(0, os.pardir)
</syntaxhighlight>

==== Subsubsection heading before code ====

<syntaxhighlight lang="python">
def h(z):
    return z+1
</syntaxhighlight>

Here is a program that is supposed to be interactive via
Python Online Tutorial, but that service is not accessible
for the present format.

<syntaxhighlight lang="python">
class Line:
    def __init__(self, a, b):
        self.a, self.b = a, b

    def __call__(self, x):
        a, b = self.a, self.b
        return a*x + b

line = Line(2, 1)
y = line(x=3)
print(y)
</syntaxhighlight>

Some more Python code (actually specified as a sage cell, but
such cells are not supported by this format).

<syntaxhighlight lang="python">
a = 2
b = 3
print('a+b:', a + b)

# In a sage cell we can also plot
from matplotlib.pyplot import *
from numpy import *
x = linspace(0, 4*pi, 101)
y = exp(-0.1*x)*cos(x)
plot(x, y)
xlabel('x'); ylabel('y')
show()
</syntaxhighlight>


Then Cython (with -h option so it is hidden in html/sphinx):

<syntaxhighlight lang="python">
cpdef f(double x):
    return x + 1
</syntaxhighlight>

Standard Python shell sessions:

<syntaxhighlight lang="python">
>>> from numpy import linspace, sin
>>> # Some comment
>>> x = linspace(0, 2, 11)
>>> y = sin(x)
>>> y[0]
0
>>> import matplotlib.pyplot as plt
>>> plt.plot(x, y)
</syntaxhighlight>

Similar IPython sessions:

<syntaxhighlight lang="python">
In [1]: from numpy import linspace, sin
In [2]: # Some comment
In [3]: x = linspace(0, 2, 11)
In [4]: y = sin(x)
In [5]: y[0]
Out[5]: 0
In [6]: import matplotlib.pyplot as plt
In [7]: plt.plot(x, y)
In [8]: a='multiple-\nline\noutput'
In [9]: a
Out[9]: 'multiple-\nline\noutput'
In [10]: print(a)
multiple-
line
output
</syntaxhighlight>

Here is the interactive session again, but with <code>pyshell-t</code>.

<syntaxhighlight lang="python">
>>> from numpy import linspace, sin
>>> # Some comment
>>> x = linspace(0, 2, 11)
>>> y = sin(x)
>>> y[0]
0
>>> import matplotlib.pyplot as plt
>>> plt.plot(x, y)
</syntaxhighlight>

<!-- This one tests a + sign before a code environment -->
C++:
<syntaxhighlight lang="cpp">
#include <iostream>

int main()
{
   std::cout << "Sample output" << std::endl;
   return 0
}
</syntaxhighlight>
<!-- The next should get correctly typset in sphinx (cod is fcod) -->
<!-- It also tests emoji before code -->
And a little bit of Fortran: :dizzy_face:

<syntaxhighlight lang="text">
!bc cod
      subroutine midpt(x, length, a, b)
      real*8 a, b, x
      x = (a + b)/2
      length = b - a
      return
      end
!ec
</syntaxhighlight>
which then is typeset as

<syntaxhighlight lang="python">
      subroutine midpt(x, length, a, b)
      real*8 a, b, x
      x = (a + b)/2
      length = b - a
      return
      end
</syntaxhighlight>

HTML:

<syntaxhighlight lang="html5">
<table>
<tr><td>Column 1</td><td>Column 2</td></tr>
<tr><td>0.67526 </td><td>0.92871 </td></tr>
<!-- comment -->
</table>
</syntaxhighlight>

But inline HTML code is also important, like text that starts with
<code><a href="</code> (which can destroy the following text if not properly
quoted).

Matlab with comments requires special typesetting:

<syntaxhighlight lang="matlab">
% Comment on the beginning of the line can be escaped by %%
if a > b
  % Indented comment needs this trick
  c = a + b
end
</syntaxhighlight>

And here is a system call:

<syntaxhighlight lang="bash">
Terminal> mkdir test
Terminal> cd test
Terminal> myprog -f
output1
output2
</syntaxhighlight>

Any valid pygments lexer/language name can appear to, e.g.,

<syntaxhighlight lang="text">
!bc restructuredtext
=======
Heading
=======

Some text.
!ec
</syntaxhighlight>
results in

<syntaxhighlight lang="text">
=======
Heading
=======

Some text.
</syntaxhighlight>

<!-- Here goes hidden code. -->
<!-- Python can be treated by some formats, Fortran is always out. -->





Finally, <code>!bc do</code> supports highlighting of DocOnce source:

<syntaxhighlight lang="text">
======= DocOnce test file =======

===== Computer code =====

Inline verbatim code, as in `import numpy as np`, is allowed, as well as
code blocks:

!bc pycod
from math import sin

def f(x):
    """Example on a function."""
    return sin(x) + 1

print(f(0))
!ec


===== Mathematics =====

Formulas can be inline, as in $\nabla\cdot\bm{u} = 0$, or typeset
as equations:

!bt
\begin{align*}
\nabla\cdot\bm{u} &= 0,\\ 
\bm{u} &= \nabla\phi .
\end{align*}
!et

=== Subsubsection heading ===

DocOnce files can have chapters, sections, subsections, and subsubsections.

__Paragraph heading.__ Paragraphs may have headings.
</syntaxhighlight>

It is time to test <code>verbatim inline font</code> especially with <code>a newline
inside the text</code> and an exclamation mark at the end: <code>BEGIN</code>! For
spellcheck, test <code>a verbatim expression</code> in <code>another</code> in a <code>third</code>.
Also test exclamation mark as in <code>!bc</code> and <code>!ec</code> as well as <code>a != b</code>.
Also test backslashes and braces like <code>\begin</code>, <code>\begin{enumerate}</code>,
<code>\end{this}\end{that}</code>, and <code>{something \inside braces}</code>.

The following attempt to exemplify colored text does not work in
format mwiki.
Here is some <font color="red">red color</font> and an attempt to write <font color="green">with
green color containing a linebreak<br />
code.</font> Some formats will only display <br />
this correctly when <code>html</code> <br />
is the output format.
But here some more running text is added which is not part of
the previous blocks with line breaks.

==== Running OS commands ====

<syntaxhighlight lang="bash">
Terminal> python -c 'print("Testing\noutput\nfrom\nPython.")'
Testing
output
from
Python.
</syntaxhighlight>


==== Footnotes ====

Here is a test of footnotes [^footnote], which are handy in text.
They are used in different flavors, now in


<ul>
 <li> list items (note below that footnotes work after math, verbatim, and URLs - bin fact old and emphasize too!)
 <li> even with math <math>\nabla^2u</math>[^math1]
 <li> and code <code>h[i] += 1</code>[^code]
   (''must'' have space between inline code and footnote!)
 <li> and [https://google.com links][^google-search]
</ul>

which gives flexibility in writing.
This is the third[^example-of-the-third-footnote] example.

  [^footnote]: Typesetting of the footnote depends on the format.
Plain text does nothing, LaTeX removes the
definition and inserts the footnote as part of the LaTeX text.
reStructuredText and Sphinx employ a similar type of typesetting
as Extended Markdown and DocOnce, and in HTML we keep the same
syntax, just displayed properly in HTML.
[^math1]: Math footnotes can be dangerous since it
interferes with an exponent.
[^code]: One-line footnote.

[^google-search]: google.com is perhaps the most famous
web site today.

Here is some more text before a new definition of a footnote that was
used above.


{{mbox
| type = notice
| textstyle = font-size: 90%;
| text = '''Non-breaking space character.''' This paragraph aims to test [https://en.wikipedia.org/wiki/Non-breaking_space non-breaking space character], and a typical
example where this is needed is in physical units: 7.4&nbsp;km is traveled
in&nbsp;<math>7.4/5.5\approx 1.345</math>&nbsp;s.  Also check that a~[https://google.com link]~is
not broken across lines (drag the browser window to test this).
(On the other hand, the tilde is used in
computer code, e.g., as in <code>[~x for x in y]</code> or in <code>y=~x</code>, and should
of course remain a tilde in those contexts.)
}}



==== Subsection 2: Testing figures ====

Test of figures. In particular we refer to Figure fig:impact in which
there is a flow.


[[File:Wave1D.png|frame|200px|alt=Wave1D.png|Visualization '''of''' a ''wave''. (fig:impact)]] <!-- not yet uploaded to common.wikimedia.org -->


Figures without captions are allowed and will be inlined.


[[File:Wave1D.png|frame|200px|alt=Wave1D.png|<span title=""></span>]] <!-- not yet uploaded to common.wikimedia.org -->




<!-- Test multi-line caption in figure with sidecap=True -->

Here is figure myfig with a long (illegal) multi-line caption
containing inline verbatim text:


[[File:Wave1D.png|frame|500px|alt=Wave1D.png|A long caption spanning several lines and containing verbatim words like <code>my_file_v1</code> and <code>my_file_v2</code> as well as math with subscript as in <math>t_{i+1}</math>. (myfig)]] <!-- not yet uploaded to common.wikimedia.org -->


<!-- Must be a blank line after MOVIE or FIGURE to detect this problem -->

Test URL as figure name:


[[File:f_plot.png|frame|500px|link=https://raw.github.com/doconce/doconce/master/doc/src/blog|alt=f_plot.png|<span title=""></span>]]



<!-- Test wikimedia type of files that otherwise reside in subdirs -->

    [[File:Df plot.png|frame|800px|alt=Df plot.png|This is a wikimedia figure file.]] <!-- user: Hplwp, filename: df_plot.png, timestamp: 2013-01-10T11:37:05Z -->


<!-- Non-uploaded file with no caption -->

[[File:Df2s8765s plot.png|frame|200,px|alt=Df2s8765s plot.png|<span title=""></span>]] <!-- not yet uploaded to common.wikimedia.org -->



''Remark.''
Movies are tested in separate file <code>movies.do.txt</code>.


<!-- Somewhat challenging heading with latex math, \t, \n, ? and parenthesis -->

==== The <math>\theta</math> parameter (not <math>\nabla</math>?) ====

Functions do not always need to be advanced, here is one
involving <math>\theta</math>:
<syntaxhighlight lang="text">
def f(theta):
    return theta**2
</syntaxhighlight>

''More on <math>\theta</math>.''
Here is more text following headline with math.

Newcommands must also be tested in this test report:
<math>\frac{1}{2}</math>, <math>{1/2}</math>, <math>\pmb{x}</math>, <math>\frac{Du}{dt}</math>,
both inline and in block:

:<math>
\begin{align}
\frac{Du}{dt} &= 0\nonumber
\\ 
\frac{1}{2} &= {1/2}\\ 
\frac{1}{2}\pmb{x} &= \pmb{n}
\end{align}
</math>

Or with align with label and numbers:

:<math>
\begin{align}
\frac{Du}{dt} &= 0
\\ 
\frac{1}{2} &= {1/2}\\ 
\frac{1}{2}\pmb{x} &= \pmb{n}
\end{align}
</math>

The labels above are removed in mwiki since mwiki cannot refer to
labels in equations.

<!-- Must test more complicated align and matrix compositions -->
<!-- where DocOnce inserts auto-numbered labels etc. -->

First one numbered (automatically):

:<math>
\begin{align}
\begin{pmatrix}
G_2 + G_3 & -G_3 & -G_2 & 0 \\ 
-G_3 & G_3 + G_4 & 0 & -G_4 \\ 
-G_2 & 0 & G_1 + G_2 & 0 \\ 
0 & -G_4 & 0 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
 v_1 \\ 
 v_2 \\ 
 v_3 \\ 
 v_4
\end{pmatrix}
+ \cdots \\ 
\begin{pmatrix}
 C_5 + C_6 & -C_6 & 0 & 0 \\ 
 -C_6 & C_6 & 0 & 0 \\ 
 0 & 0 & 0 & 0 \\ 
 0 & 0 & 0 & 0
\end{pmatrix}
  &= \frac{d}{dt}\begin{pmatrix}
 v_1 \\ 
 v_2 \\ 
 v_3 \\ 
 v_4
\end{pmatrix} +
\begin{pmatrix}
 0 \\ 
 0 \\ 
 0 \\ 
 -i_0
\end{pmatrix}
\nonumber
\end{align}
</math>

Second numbered (automatically):

:<math>
\begin{align}
\begin{pmatrix}
G_1 + G_2\\ 
-G_3 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
 v_1 \\ 
 v_2
\end{pmatrix}
+ \cdots\nonumber
\\ 
\left(\begin{array}{ll}
y & 2\\ 
2 & 1
\end{array}\right)
\left(\begin{array}{ll}
0 \\ x
\end{array}\right)
&= \begin{pmatrix}
A \\ B
\end{pmatrix}
\end{align}
</math>

Both numbered, with label by the user:

:<math>
\begin{align}
\begin{pmatrix}
G_1 + G_2\\ 
-G_3 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
 v_1 \\ 
 v_2
\end{pmatrix}
+ \cdots \\ 
\left(\begin{array}{ll}
y & 2\\ 
2 & 1
\end{array}\right)
\left(\begin{array}{ll}
0 \\ x
\end{array}\right)
&= \begin{pmatrix}
A \\ B
\end{pmatrix}
\end{align}
</math>
Now we refer to Equations (mymatrix:eq1)-(mymatrix:eq2).

==== Custom Environments ====

Here is an attempt to create a theorem environment via Mako
(for counting theorems) and comment lines to help replacing lines in
the <code>.tex</code> by proper begin-end LaTeX environments for theorems.
Should look nice in most formats!



<!-- begin theorem -->



''Theorem 5.''
Let <math>a=1</math> and <math>b=2</math>. Then <math>c=3</math>.
<!-- end theorem -->

<!-- begin proof -->
''Proof.''
Since <math>c=a+b</math>, the result follows from straightforward addition.
<math>\Diamond</math>
<!-- end proof -->

As we see, the proof of Theorem 5 is a modest
achievement.


==== Tables ====

<!-- index with comma could fool sphinx -->

Let us take this table from the manual:


<table border="1">
<thead>
<tr><th align="center">time</th> <th align="center">velocity</th> <th align="center">acceleration</th> </tr>
</thead>
<tbody>
<tr><td align="left">   0.0     </td> <td align="right">   1.4186      </td> <td align="right">   -5.01           </td> </tr>
<tr><td align="left">   2.0     </td> <td align="right">   1.376512    </td> <td align="right">   11.919          </td> </tr>
<tr><td align="left">   4.0     </td> <td align="right">   1.1E+1      </td> <td align="right">   14.717624       </td> </tr>
</tbody>
</table>

The DocOnce source code reads
<syntaxhighlight lang="text">

  |--------------------------------|
  |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>

Here is yet another table to test that we can handle more than
one table:

<table border="1">
<thead>
<tr><th align="left">time</th> <th align="left">velocity</th> <th align="left">acceleration</th> </tr>
</thead>
<tbody>
<tr><td align="left">   0.0     </td> <td align="left">   1.4186      </td> <td align="left">   -5.01           </td> </tr>
<tr><td align="left">   1.0     </td> <td align="left">   1.376512    </td> <td align="left">   11.919          </td> </tr>
<tr><td align="left">   3.0     </td> <td align="left">   1.1E+1      </td> <td align="left">   14.717624       </td> </tr>
</tbody>
</table>
And one with math headings (that are expanded and must be treated
accordingly), verbatim heading and entry, and no space around the pipe
symbol:

<table border="1">
<thead>
<tr><th align="center"><math>i</math></th> <th align="center"><math>h_i</math></th> <th align="center"><math>\bar T_i</math></th> <td align="center"><code>L_i</code></td> </tr>
</thead>
<tbody>
<tr><td align="left">   0                 </td> <td align="right">   0                   </td> <td align="right">   288                      </td> <td align="right">   -0.0065             </td> </tr>
<tr><td align="left">   1                 </td> <td align="right">   11,000              </td> <td align="right">   216                      </td> <td align="right">   0.0                 </td> </tr>
<tr><td align="left">   2                 </td> <td align="right">   20,000              </td> <td align="right">   216                      </td> <td align="right">   0.001               </td> </tr>
<tr><td align="left">   3                 </td> <td align="right">   32,000              </td> <td align="right">   228                      </td> <td align="right">   0.0028              </td> </tr>
<tr><td align="left">   4                 </td> <td align="right">   47,000              </td> <td align="right">   270                      </td> <td align="right">   0.0                 </td> </tr>
<tr><td align="left">   5                 </td> <td align="right">   51,000              </td> <td align="right">   270                      </td> <td align="right">   -0.0028             </td> </tr>
<tr><td align="left">   6                 </td> <td align="right">   71,000              </td> <td align="right">   214                      </td> <td align="right">   <code>NaN</code>    </td> </tr>
</tbody>
</table>
And add one with verbatim headings (with underscores),
and rows starting with <code>|-</code> because of a negative number,
and <code>|</code> right before and after verbatim word (with no space):

<table border="1">
<thead>
<tr><th align="center">exact</th> <td align="center"><code>v_1</code></td> <td align="center"><math>a_i</math> + <code>v_2</code></td> <td align="center"><code>verb_3_</code></td> </tr>
</thead>
<tbody>
<tr><td align="right">   9        </td> <td align="right">   9.62                </td> <td align="right">   5.57                                   </td> <td align="right">   8.98                    </td> </tr>
<tr><td align="right">   -20      </td> <td align="right">   -23.39              </td> <td align="right">   -7.65                                  </td> <td align="right">   -19.93                  </td> </tr>
<tr><td align="right">   10       </td> <td align="right">   17.74               </td> <td align="right">   -4.50                                  </td> <td align="right">   9.96                    </td> </tr>
<tr><td align="right">   0        </td> <td align="right">   -9.19               </td> <td align="right">   4.13                                   </td> <td align="right">   -0.26                   </td> </tr>
</tbody>
</table>
Pipe symbols in verbatim and math text in tables used to pose difficulties,
but not
anymore:

<table border="1">
<thead>
<tr><th align="center">   <math>S</math>   </th> <th align="center">        command         </th> </tr>
</thead>
<tbody>
<tr><td align="left">   $ ||a_0|| $             </td> <td align="right">   <code>norm|length</code>    </td> </tr>
<tr><td align="left">   <math>x\cap y</math>    </td> <td align="right">   <code>x|y</code>            </td> </tr>
</tbody>
</table>

Here is a table with X alignment:

<table border="1">
<thead>
<tr><th align="center"> Type</th> <th align="center">                                                                                                                Description                                                                                                                 </th> </tr>
</thead>
<tbody>
<tr><td align="center">   X        </td> <td align="left">   Alignment character that is used for specifying a potentially very long text in a column in a table. It makes use of the <code>tabularx</code> package in LaTeX, otherwise (for other formats) it means <code>l</code> (centered alignment).    </td> </tr>
<tr><td align="center">   l,r,c    </td> <td align="left">   standard alignment characters                                                                                                                                                                                                                   </td> </tr>
</tbody>
</table>
Finally, a table with math
and URLs.

<!-- Mako code to expand URLs in the table -->
<!-- (These types of tables did not work before Jan 2014) -->


<table border="1">
<tr></tr>
<tbody>
<tr><td align="center">   <math>\mathcal{L}=0</math>            </td> <td align="center">   [../doc/src/manual/mov/wave_frames/frame_0080.png <code>080</code>]    </td> <td align="center">   [../doc/src/manual/mov/wave_frames/frame_0085.png <code>085</code>]    </td> </tr>
<tr><td align="center">   <math>a=b</math>                      </td> <td align="center">   [../doc/src/manual/mov/wave_frames/frame_0090.png <code>090</code>]    </td> <td align="center">   [../doc/src/manual/mov/wave_frames/frame_0095.png <code>095</code>]    </td> </tr>
<tr><td align="center">   <math>\nabla\cdot\bm{u} =0 </math>    </td> <td align="center">   [../doc/src/manual/mov/wave_frames/frame_0100.png <code>100</code>]    </td> <td align="center">   [../doc/src/manual/mov/wave_frames/frame_0105.png <code>105</code>]    </td> </tr>
</tbody>
</table>

==== A test of verbatim words in heading with subscript <math>a_i</math>: <code>my_file_v1</code> and <code>my_file_v2</code> ====

''Paragraph with verbatim and math: <code>my_file_v1.py</code> and <code>my_file_v2.py</code> define some math <math>a_{i-1}</math>.''
Here is more <code>__verbatim__</code> code and
some plain text on a new line.

<!-- Test various types of headlines -->
==== '''Just bold''' ====

Some text.

==== ''Just emphasize'' ====

Some text.

==== <code>Just verbatim</code> ====

Some text.

==== '''Bold''' beginning ====

Some text.

==== ''Emphasize'' beginning ====

Some text.

==== <code>Verbatim</code> beginning ====

Some text.

==== Maybe '''bold end''' ====

Some text.

==== Maybe ''emphasize end'' ====

Some text.

==== Maybe <code>verbatim end</code> ====

Some text.

==== The middle has '''bold''' word ====

Some text.

==== The middle has ''emphasize'' word ====

Some text.

==== The middle has <code>verbatim</code> word ====

Some text.


''''Just emphasize''.''
Some text.


''<code>Just verbatim</code>.''
Some text.


''''Emphasize'' beginning.''
Some text.


''<code>Verbatim beginning</code>.''
Some text.


''Maybe ''emphasize end''.''
Some text.


''Maybe <code>verbatim end</code>.''
Some text.


''The middle has ''emphasize'' word.''
Some text.


''The middle has <code>verbatim</code> word.''
Some text.


''Ampersand.''
We can test Hennes & Mauritz, often abbreviated H&M, but written
as <code>Hennes & Mauritz</code> and <code>H & M</code>.
A sole <code>&</code> must also work.
<!-- Note: substitutions must not occur inside verbatim, just in ordinary text. -->

<syntaxhighlight lang="text">
# Just to check that ampersand works in code blocks:
c = a & b
</syntaxhighlight>

''Quotes.''
Let us also add a test of quotes such as "double quotes, with numbers
like 3.14 and newline/comma and hyphen (as in double-quote)"; written
in the standard LaTeX-style that gives correct LaTeX formatting and
ordinary double quotes for all non-LaTeX formats.  Here is another
sentence that "caused" a bug in the past because double backtick
quotes could imply verbatim text up to a verbatim word starting with
period, like <code>.txt</code>.

More quotes to be tested for spellcheck:
("with parenthesis"), "with newline"
and "with comma", "hyphen"-wise, and "period".


==== Bibliography test ====

Here is an example: [1] discussed propagation of
large destructive water waves, [2] gave
an overview of numerical methods for solving the Navier - Stokes equations,
while the use of Backward Kolmogorov equations for analyzing
random vibrations was investigated in [3].
The book chapter [4] contains information on
C++ software tools for programming multigrid methods. A real retro
reference is [5] about a big FORTRAN package.
Multiple references are also possible, e.g., see
[1] [4].

We need to cite more than 10 papers to reproduce an old formatting
problem with blanks in the keys in reST format:
[6] [3] [7] [1]
and
[2] [8] [9] [10] [11] [12] [13]
and all the work of
[14] [4] [15] as well as
old work [5] and [16], and the
talk [17].
Langtangen also had two thesis [18] [16]
back in the days.
More retro citations are
the old ME-IN323 book [19] and the
[20] OONSKI '94 paper.




<!-- --- begin exercise --- -->

==== Example 1: Examples can be typeset as exercises ====

Examples can start with a subsection heading starting with <code>Example:</code>
and then, with the command-line option <code>--examples_as_exercises</code> be
typeset as exercises. This is useful if one has solution
environments as part of the example.


''a)''
State some problem.

''Solution.''
The answer to this subproblem can be written here.

''b)''
State some other problem.

''Hint 1.''
A hint can be given.

''Hint 2.''
Maybe even another hint?

''Solution.''
The answer to this other subproblem goes here,
maybe over multiple doconce input lines.

<!-- --- end exercise --- -->


==== User-defined environments ====

The example in the section [#Example_1:_A_test_function] demonstrates how to write a test function.
That is, a special test function for a function <code>add</code> appears in
the example in the section [#Example_1:_A_test_function].



==== Example 1: A test function ====

Suppose we want to write a test function for checking the
implementation of a Python function for addition.

<syntaxhighlight lang="python">
def add(a, b):
    return a + b

def test_add():
    a = 1; b = 1
    expected = a + b
    computed = add(a, b)
    assert expected == computed
</syntaxhighlight>





==== Example 2: Addition ====

We have

:<math>
 1 + 1 = 2 
</math>
or in tabular form:

<table border="1">
<thead>
<tr><th align="center">    Problem     </th> <th align="center">    Result    </th> </tr>
</thead>
<tbody>
<tr><td align="center">   <math>1+1</math>    </td> <td align="center">   <math>2</math>    </td> </tr>
</tbody>
</table>



{{mbox
| type = notice
| textstyle = font-size: 90%;
| text = '''Highlight box!''' This environment is used to highlight something:

:<math>
 E = mc^2 
</math>
}}





==== URLs ====

Testing of URLs: hpl's home page [https://folk.uio.no/hpl hpl], or
the entire URL if desired, https://folk.uio.no/hpl.  Here is a
plain file link testdoc.do.txt, or testdoc.do.txt, or
testdoc.do.txt or testdoc.do.txt or [testdoc.do.txt a link with
newline]. Can test spaces with the link with word
too: [https://folk.uio.no/hpl hpl] or [https://folk.uio.no/hpl hpl]. Also <code>file:///</code> works: [file:///home/hpl/vc/doconce/doc/demos/manual/manual.html link to a
file] is
fine to have. Moreover, "loose" URLs work, i.e., no quotes, just
the plain URL as in https://folk.uio.no/hpl, if followed by space, comma,
colon, semi-colon, question mark, exclamation mark, but not a period
(which gets confused with the periods inside the URL).

Mail addresses can also be used: [mailto:hpl@simula.no <code>hpl@simula.no</code>], or just a [mailto:hpl@simula.no mail link], or a raw mailto:hpl@simula.no.

Here are some tough tests of URLs, especially for the <code>latex</code> format:
[https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas Newton-Cotes] formulas
and a [https://www.springer.com/mathematics/computational+science+%26+engineering/book/978-3-642-23098-1 good book]. Need to test
Newton-Cotes with percentage in URL too:
https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas
and https://en.wikipedia.org/wiki/Newton-Cotes#Open_Newton.E2.80.93Cotes_formulae which has a shebang.

For the <code>--device=paper</code> option it is important to test that URLs with
monospace font link text get a footnote
(unless the <code>--latex_no_program_footnotelink</code>
is used), as in this reference to
[https://github.com/hplgit/INF5620/tree/gh-pages/src/decay/experiments/decay_mod.py <code>decay_mod</code>], [https://tinyurl.com/pwyasaa/formulas.ball1.py <code>ball1.py</code>],
and [https://tinyurl.com/pwyasaa/formulas.ball2.py <code>ball2.py</code>].


<!-- Comments should be inserted outside paragraphs (because in the rst -->
<!-- format extra blanks make a paragraph break). -->

<!-- Note that when there is no https: or file:, it can be a file link -->
<!-- if the link name is URL, url, "URL", or "url". Such files should, -->
<!-- if rst output is desired, but placed in a <code>_static*</code> folder. -->

More tough tests: repeated URLs whose footnotes when using the
<code>--device=paper</code> option must be correct. We have
[https://google.com google], [https://google.com google], and
[https://google.com google], which should result in exactly three
footnotes.



<!-- !split and check if these extra words are included properly in the comment -->

== LaTeX Mathematics ==

Here is an equation without label using backslash-bracket environment:
:<math>
 a = b + c 
</math>

or with number and label, as in Equation (my:eq1), using the equation environment:

:<math>
{\partial u\over\partial t} = \nabla^2 u </math>

We can refer to this equation by Equation (my:eq1).

Here is a system without equation numbers, using the align-asterisk environment:

:<math>
\begin{align*}
\pmb{a} &= \pmb{q}\times\pmb{n} \\ 
b &= \nabla^2 u + \nabla^4 v
\end{align*}
</math>



More mathematical typesetting is demonstrated in the coming exercises.

Below, we have [#Problem_2:_Flip_a_Coin] and [#Project_4:_Compute_a_Probability],
as well as [#Project_5:_Explore_Distributions_of_Random_Circles] and [#Project_11:_References_to_Project_demo:ex:2_in_a_heading_works_for_mwiki], and in
between there we have [#Exercise_10:_Make_references_to_projects_and_problems].


== Exercises ==



<!-- --- begin exercise --- -->

==== Problem 2: Flip a Coin ====

<!-- keywords = random numbers; Monte Carlo simulation; ipynb -->

<!-- Torture tests -->


''a)''
Make a program that simulates flipping a coin <math>N</math> times.
Print out "tail" or "head" for each flip and
let the program count the number of heads.

<!-- --- begin hint in exercise --- -->

''Hint 1.''
Use <code>r = random.random()</code> and define head as <code>r <= 0.5</code>.

<!-- --- end hint in exercise --- -->

<!-- --- begin hint in exercise --- -->

''Hint 2.''
Draw an integer among <math>\{1,2\}</math> with
<code>r = random.randint(1,2)</code> and define head when <code>r</code> is 1.

<!-- --- end hint in exercise --- -->


<!-- --- begin answer of exercise --- -->
''Answer.''
If the <code>random.random()</code> function returns a number <math><1/2</math>, let it be
head, otherwise tail. Repeat this <math>N</math> number of times.
<!-- --- end answer of exercise --- -->


<!-- --- begin solution of exercise --- -->
''Solution.''
<syntaxhighlight lang="python">
import sys, random
N = int(sys.argv[1])
heads = 0
for i in range(N):
    r = random.random()
    if r <= 0.5:
        heads += 1
print('Flipping a coin %d times gave %d heads' % (N, heads))
</syntaxhighlight>
<!-- --- end solution of exercise --- -->

''b)''
Vectorize the code in a) using boolean indexing.

Vectorized code can be written in many ways.
Sometimes the code is less intuitive, sometimes not.
At least there is not much to find in the section [#Section_1].

''c)''
Vectorize the code in a) using <code>numpy.sum</code>.


<!-- --- begin answer of exercise --- -->
''Answer.''
<code>np.sum(np.where(r <= 0.5, 1, 0))</code> or <code>np.sum(r <= 0.5)</code>.
<!-- --- end answer of exercise --- -->

In this latter subexercise, we have an
example where the code is easy to read.


==== My remarks ====

Remarks with such a subsubsection is treated as more text
after the last subexercise. Test a list too:


<ol>
<li> Mark 1.
<li> Mark 2.
</ol>

Filenames: <code>flip_coin.py</code>, <code>flip_coin.pdf</code>.

<!-- Closing remarks for this Problem -->

==== Remarks ====

These are the exercise remarks, appearing at the very end.

<!-- solution files: mysol.txt, mysol_flip_coin.py, yet_another.file -->

<!-- --- end exercise --- -->


==== Not an exercise ====

Should be possible to stick a normal section in the middle of many
exercises.



<!-- --- begin exercise --- -->

==== Exercise 3: Test of plain text exercise ====

Very short exercise. What is the capital
of Norway?
Filename: <code>myexer1</code>.

<!-- --- end exercise --- -->




<!-- --- begin exercise --- -->

==== Project 4: Compute a Probability ====

<!-- Minimalistic exercise -->


What is the probability of getting a number between 0.5 and 0.6 when
drawing uniformly distributed random numbers from the interval <math>[0,1)</math>?


At the end we have a list because that caused problems in LaTeX
in previous DocOnce versions:


<ol>
<li> item1
<li> item2
</ol>

<!-- --- begin hint in exercise --- -->

''Hint.''
To answer this question empirically, let a program
draw <math>N</math> such random numbers using Python's standard <code>random</code> module,
count how many of them, <math>M</math>, that fall in the interval <math>(0.5,0.6)</math>, and
compute the probability as <math>M/N</math>.

<!-- --- end hint in exercise --- -->

<!-- --- end exercise --- -->




<!-- --- begin exercise --- -->

==== Project 5: Explore Distributions of Random Circles ====

<!-- keywords = ipynb -->

The formula for a circle is given by

:<math>
\begin{align}
x &= x_0 + R\cos 2\pi t,
\\ 
y &= y_0 + R\sin 2\pi t,
\end{align}
</math>
where <math>R</math> is the radius of the circle, <math>(x_0,y_0)</math> is the
center point, and <math>t</math> is a parameter in the unit interval <math>[0,1]</math>.
For any <math>t</math>, <math>(x,y)</math> computed from Equations (circle:x)-(circle:y)
is a point on the circle.
The formula can be used to generate <code>n</code> points on a circle:

<syntaxhighlight lang="python">
import numpy as np

def circle(R, x0, y0, n=501):
    t = np.linspace(0, 1, n)
    x = x0 + R*np.cos(2*np.pi*t)
    y = y0 + R*np.sin(2*np.pi*t)
    return x, y

x, y = circle(2.0, 0, 0)
</syntaxhighlight>

<!-- Often in an exercise we have some comments about the solution -->
<!-- which we normally want to keep where they are. -->

The goal of this project is to draw <math>N</math> circles with random
center and radius. Plot each circle using the <code>circle</code> function
above.


''a)''
Let <math>R</math> be normally distributed and <math>(x_0,y_0)</math> uniformly distributed.

<!-- --- begin hint in exercise --- -->

''Hint.''
Use the <code>numpy.random</code> module to draw the
<math>x_0</math>, <math>y_0</math>, and <math>R</math> quantities.

<!-- --- end hint in exercise --- -->


<!-- --- begin answer of exercise --- -->
''Answer.''
Here goes the short answer to part a).
<!-- --- end answer of exercise --- -->


<!-- --- begin solution of exercise --- -->
''Solution.''
Here goes a full solution to part a).
<!-- --- end solution of exercise --- -->

''b)''
Let <math>R</math> be uniformly distributed and <math>(x_0,y_0)</math> normally distributed.
Filename: <code>norm</code>.

''c)''
Let <math>R</math> and <math>(x_0,y_0)</math> be normally distributed.


Filename: <code>circles</code>.

<!-- Closing remarks for this Project -->

==== Remarks ====

At the very end of the exercise it may be appropriate to summarize
and give some perspectives.


<!-- --- end exercise --- -->




<!-- --- begin exercise --- -->

==== Exercise 6: Determine some Distance ====

Intro to this exercise. Questions are in subexercises below.


<!-- --- begin solution of exercise --- -->
''Solution.''
Here goes a full solution of the whole exercise.
With some math <math>a=b</math> in this solution:
:<math>
 \hbox{math in solution: } a = b 
</math>
And code <code>a=b</code> in this solution:
<syntaxhighlight lang="text">
a = b  # code in solution
</syntaxhighlight>
End of solution is here.

<!-- --- end solution of exercise --- -->


''a)''
Subexercises are numbered a), b), etc.

<!-- --- begin hint in exercise --- -->

''Hint 1.''
First hint to subexercise a).
With math <math>a=b</math> in hint:

:<math>
 a=b. 
</math>
And with code (in plain verbatim) returning <math>x+1</math> in hint:

<syntaxhighlight lang="text">
def func(x):
    return x + 1  # with code in hint
</syntaxhighlight>

<!-- --- end hint in exercise --- -->

<!-- --- begin hint in exercise --- -->

''Hint 2.''
Second hint to subexercise a).

Test list in hint:


<ol>
<li> item1
<li> item2
</ol>

<!-- --- end hint in exercise --- -->
Filename: <code>subexer_a.pdf</code>.


<!-- --- begin answer of exercise --- -->
''Answer.''
Short answer to subexercise a).
With math in answer: <math>a=b</math>.
<!-- --- end answer of exercise --- -->

''b)''
Here goes the text for subexercise b).


Some math <math>\cos^2 x + \sin^2 x = 1</math> written one a single line:

:<math>
 \cos^2 x + \sin^2 x = 1 \thinspace .
</math>

<!-- --- begin hint in exercise --- -->

''Hint.''
A hint for this subexercise.

<!-- --- end hint in exercise --- -->
Filename: <code>subexer_b.pdf</code>.


<!-- --- begin solution of exercise --- -->
''Solution.''
Here goes the solution of this subexercise.
<!-- --- end solution of exercise --- -->



<!-- No meaning in this weired test example: -->
The text here belongs to the main (intro) part of the exercise. Need
closing remarks to have text after subexercises.

Test list in exercise:


<ol>
<li> item1
<li> item2
<!-- Closing remarks for this Exercise -->
</ol>

==== Remarks ====

Some final closing remarks, e.g., summarizing the main findings
and their implications in other problems can be made. These
remarks will appear at the end of the typeset exercise.


<!-- --- end exercise --- -->




<!-- --- begin exercise --- -->

==== Some exercise without the "Exercise:" prefix ====

<!-- Another minimalistic exercise -->

Just some text. And some math saying that <math>e^0=1</math> on a single line,
to test that math block insertion is correct:

:<math>
 \exp{(0)} = 1 
</math>

And a test that the code <code>lambda x: x+2</code> is correctly placed here:

<syntaxhighlight lang="text">
lambda x: x+2
</syntaxhighlight>


<!-- Have some comments at the end of the exercise to see that -->
<!-- the Filename: ... is written correctly. -->
<!-- --- end exercise --- -->




<!-- --- begin exercise --- -->

==== Exercise 8: Solution of differential equation ====



Given

:<math>
 \frac{dy}{dx} = -y(x),\quad y(0)=1 
</math>
What is the solution of this equation?

Choice A: <math>y=e^{-y}</math>

Choice B: <math>y=e^{y}</math>

Choice C: <syntaxhighlight lang="python">
from math import exp
def f(x):
    return exp(x)
</syntaxhighlight>

Choice D: The solution cannot be found because there is a derivative in the equation.

Choice E: The equation is meaningless: an equation must be an equation
for <math>x</math> or <math>y</math>, not a function <math>y(x)</math>.



<!-- --- end exercise --- -->




<!-- --- begin exercise --- -->

==== Example 9: Just an example ====

<!-- This example needs the --examples_as_exercises option, otherwise -->
<!-- it is just typeset as it is written. -->


''a)''
What is the capital of Norway?

''Answer.''
Oslo.

<!-- --- end exercise --- -->


== Here goes another section ==

With some text, before we continue with exercises.

== More Exercises ==



<!-- --- begin exercise --- -->

==== Exercise 10: Make references to projects and problems ====

<!-- Test comments not at the end only -->
Pick a statement from [#Project_5:_Explore_Distributions_of_Random_Circles] or [#Problem_2:_Flip_a_Coin]
and verify it.

Test list at the end of an exercise without other elements (like subexercise,
hint, etc.):


<ol>
<li> item1
<li> item2
</ol>

Filename: <code>verify_formula.py</code>.

<!-- --- end exercise --- -->




<!-- --- begin exercise --- -->

==== Project 11: References to [#Project_4:_Compute_a_Probability] in a heading works for mwiki ====

Refer to the previous exercise as [#Exercise_10:_Make_references_to_projects_and_problems],
the two before that as [#Project_4:_Compute_a_Probability] and [#Project_5:_Explore_Distributions_of_Random_Circles],
and this one as [#Project_11:_References_to_Project_demo:ex:2_in_a_heading_works_for_mwiki].
Filename: <code>selc_composed.pdf</code>.

<!-- --- end exercise --- -->


== References ==


<ol>
 <li> '''H. P. Langtangen and G. Pedersen'''. 
    Propagation of Large Destructive Waves,
    ''International Journal of Applied Mechanics and Engineering'',
    7(1),
    pp. 187-204,
    2002.
 <li> '''H. P. Langtangen, K.-A. Mardal and R. Winther'''. 
    Numerical Methods for Incompressible Viscous Flow,
    ''Advances in Water Resources'',
    25,
    pp. 1125-1146,
    2002.
 <li> '''H. P. Langtangen'''. 
    Numerical Solution of First Passage Problems in Random Vibrations,
    ''SIAM Journal of Scientific and Statistical Computing'',
    15,
    pp. 997-996,
    1994.
 <li> '''K.-A. Mardal, G. W. Zumbusch and H. P. Langtangen'''. 
    Software Tools for Multigrid Methods,
    ''Advanced Topics in Computational Partial Differential Equations -- Numerical Methods and Diffpack Programming'',
    edited by '''H. P. Langtangen and A. Tveito''',
    Springer,
    2003,
    Edited book,
    http://some.where.org.
 <li> '''H. P. Langtangen'''. 
    The FEMDEQS Program System,
    ''Department of Mathematics, University of Oslo'',
    1989,
    http://www.math.uio.no/old/days/hpl/femdeqs.pdf.
 <li> '''H. P. Langtangen'''. 
    Stochastic Breakthrough Time Analysis of an Enhanced Oil Recovery Process,
    ''SIAM Journal on Scientific Computing'',
    13,
    pp. 1394-1417,
    1992.
 <li> '''M. Mortensen, H. P. Langtangen and G. N. Wells'''. 
    A FEniCS-Based Programming Framework for Modeling Turbulent Flow by the Reynolds-Averaged Navier-Stokes Equations,
    ''Advances in Water Resources'',
    34(9),
    [https://dx.doi.org/10.1016/j.advwatres.2011.02.013 doi: 10.1016/j.advwatres.2011.02.013],
    2011.
 <li> '''S. Glimsdal, G. Pedersen, K. Atakan, C. B. Harbitz, H. P. Langtangen and F. L\ovholt'''. 
    Propagation of the Dec.&nbsp;26, 2004 Indian Ocean Tsunami: Effects of Dispersion and Source Characteristics,
    ''International Journal of Fluid Mechanics Research'',
    33(1),
    pp. 15-43,
    2006.
 <li> '''S. Rahman, J. Gorman, C. H. W. Barnes, D. A. Williams and H. P. Langtangen'''. 
    Numerical Investigation of a Piezoelectric Surface Acoustic Wave Interaction With a One-Dimensional Channel,
    ''Physical Review B: Condensed Matter and Materials Physics'',
    74,
    2006,
    035308.
<li> '''J. B. Haga, H. Osnes and H. P. Langtangen'''. 
    On the Causes of Pressure Oscillations in Low-Permeable and Low-Compressible Porous Media,
    ''International Journal of Analytical and Numerical Methods in Geomechanics'',
    [https://dx.doi.org/10.1002/nag.1062 doi: 10.1002/nag.1062],
    2011,
    http://onlinelibrary.wiley.com/doi/10.1002/nag.1062/abstract.
<li> '''H. P. Langtangen'''. 
    ''Computational Partial Differential Equations - Numerical Methods and Diffpack Programming'',
    second edition,
    ''Texts in Computational Science and Engineering'',
    Springer,
    2003.
<li> '''H. P. Langtangen'''. 
    ''Python Scripting for Computational Science'',
    third edition,
    ''Texts in Computational Science and Engineering'',
    Springer,
    2008.
<li> '''H. P. Langtangen and G. Pedersen'''. 
    Finite Elements for the Boussinesq Wave Equations,
    Waves and Non-linear Processes in Hydrodynamics,
    edited by '''J. Grue, B. Gjevik and J. E. Weber''',
    Kluwer Academic Publishers,
    pp. pp. 117-126,
    1995,
    http://www.amazon.ca/Waves-Nonlinear-Processes-Hydrodynamics-John/dp/0792340310.
<li> '''H. P. Langtangen'''. 
    ''A Primer on Scientific Programming With Python'',
    third edition,
    ''Texts in Computational Science and Engineering'',
    Springer,
    2012.
<li> '''P. V. Jeberg, H. P. Langtangen and C. B. Terp'''. 
    Optimization With Diffpack: Practical Example From Welding,
    ''Simula Research Laboratory'',
    2004,
    Internal report.
<li> '''H. P. Langtangen'''. 
    Computational Methods for Two-Phase Flow in Oil Reservoirs,
    Ph.D. Thesis,
    Mechanics Division, Department of Mathematics, University of Oslo,
    1989,
    Dr.&nbsp;Scient.&nbsp;thesis..
<li> '''H. P. Langtangen'''. 
    Computational Modeling of Huge Tsunamis From Asteroid Impacts,
    2007,
    Invited keynote lecture at the \emphInternational conference on Computational Science 2007 (ICCS'07), Beijing, China.
<li> '''H. P. Langtangen'''. 
    Solution of the Navier-Stokes Equations With the Finite Element Method in Two and Three Dimensions,
    M.Sc. Thesis,
    Mechanics Division, Department of Mathematics, University of Oslo,
    1985,
    Cand.Scient. thesis.
<li> '''H. P. Langtangen and A. Tveito'''. 
    Numerical Methods in Continuum Mechanics,
    ''Center for Industrial Research'',
    1991,
    Lecture notes for a course (ME-IN 324). 286 pages..
<li> '''H. P. Langtangen'''. 
    Diffpack: Software for Partial Differential Equations,
    ''Proceedings of the Second Annual Object-Oriented Numerics Conference (OON-SKI'94), Sunriver, Oregon, USA'',
    edited by '''A. Vermeulen''',
    1994.
</ol>

== Appendix: Just for testing; part I ==


This is the first appendix.

==== A subsection within an appendix ====

Some text.

== Appendix: Just for testing; part II ==


This is more stuff for an appendix.

==== Appendix: Testing identical titles ====

Without label.


==== Appendix: Testing identical titles ====

With label.

==== Appendix: Testing identical titles ====

What about inserting a quiz?



======= Test of quizzes =======


Fundamental test: What is the capital of Norway?

Answer 1: Stockholm

Answer 2: London

Answer 3: Oslo

Choice D: Bergen




==== Appendix: Testing identical titles ====

Without label.


{{mbox
| type = notice
| textstyle = font-size: 90%;
| text = '''Tip.''' Here is a tip or hint box, typeset as a notice box.
}}





Need a lot of text to surround the summary box.
Version control systems allow you to record the history of files
and share files among several computers and collaborators in a
professional way. File changes on one computer are updated or
merged with changes on another computer. Especially when working
with programs or technical reports it is essential
to have changes documented and to
ensure that every computer and person involved in the project
have the latest updates of the files.
Greg Wilson' excellent [https://software-carpentry.org/2010/07/script-for-introduction-to-version-control/ Script for Introduction to Version Control] provides a more detailed motivation why you will benefit greatly
from using version control systems.


{{mbox
| type = Summary.
| textstyle = font-size: 90%;
| text = '''Summary.''' '''Bold remark:''' Make some text with this summary.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
}}



Projects that you want to share among several computers or project
workers are today most conveniently stored at some web site "in the
cloud" and updated through communication with that site. I strongly
recommend you to use such sites for all serious programming and
scientific writing work - and all other important files.

The simplest services for hosting project files are [https://dropbox.com Dropbox] and [https://drive.google.com Google Drive].
It is very easy to get started with these systems, and they allow you
to share files among laptops and mobile units with as many users as
you want. The systems offer a kind of version control in that the
files are stored frequently (several times per minute), and you can go
back to previous versions for the last 30 days. However, it is
challenging  to find the right version from the past when there are
so many of them.

More seriously, when several people may edit files simultaneously, it
can be difficult detect who did what when, roll back to previous
versions, and to manually merge the edits when these are
incompatible. Then one needs more sophisticated tools than Dropbox or
Google Drive: project hosting services with true version control
systems.  The following text aims at providing you with the minimum
information to started with such systems. Numerous other tutorials
contain more comprehensive material and in-depth explanations of the
concepts and tools.

The idea with project hosting services is that you have the files
associated with a project in the cloud. Many people may share these
files.  Every time you want to work on the project you explicitly
update your version of the files, edit the files as you like, and
synchronize the files with the "master version" at the site where the
project is hosted.  If you at some point need to go back to a
version of the files at some particular point in the past,
this is an easy operation. You can also use tools to see
what various people have done with the files in the various versions.

All these services are very similar. Below we describe how you get
started with Bitbucket, GitHub, and Googlecode. Launchpad works very
similarly to the latter three. All the project hosting services have
excellent introductions available at their web sites, but the recipes
below are much shorter and aim at getting you started as quickly as
possible by concentrating on the most important need-to-know steps.
The Git tutorials we refer to later in this document contain more
detailed information and constitute of course very valuable readings
when you use version control systems every day. The point now is
to get started.


==== Appendix: Testing inline comments ====

<!-- Names can be [ A-Za-z0-9_'+-]+ -->

Projects that you want to share among several computers or project
workers are today most conveniently stored at some web site "in the
cloud" and updated through communication with that
site. [hpl's semi opinion 1: not sure if in the cloud is
understood by
all.] I strongly recommend you to use such sites for all serious
programming and scientific writing work - and all other important
files.

The simplest services for hosting project files is Dropbox. [mp 2: Simply go to https://dropbox.com and watch the video. It explains
how files, like <code>myfile.py</code>, perhaps containing much math, like
<math>\partial u/\partial t</math>, are easily communicated between machines.] It
is very easy to get started with Dropbox, and it allows you to share
files among [hpl 3: laptops and mobile units -> computers, tablets,
and phones].

<!-- Test horizontal rule -->

----

<!-- Coments for editing -->

First[add 4: ,] consider a quantity <math>Q</math>. [edit 5: To this end, -> We note that]
<math>Q>0</math>, because [del 6: a] negative [edit 7: quantity is -> quantities
are] [del 8: just] negative. [add 9: This comes as no surprise.]

<!-- Test tailored latex figure references with page number -->
Let us refer to Figure fig:impact again.

Test references in a list:


<ul>
 <li> [#Section_1]
 <li> [#Subsection_1]
 <li> fig:impact
</ul>

==== Appendix: Testing headings ending with <code>verbatim inline</code> ====

The point here is to test 1) <code>verbatim</code> code in headings, and 2)
ending a heading with verbatim code as this triggers a special
case in LaTeX.

We also test mdash---used as alternative to hyphen without spaces around,
or in quotes:


{{quote box
| quote = ''Fun is fun''.---Unknown.
| textstyle = font-size: 90%;
}}



The ndash should also be tested - as in the Hanson - Nilson equations
on page 277 - 278.

And finally, what about admons, quotes, and boxes? They are tested
in a separate document: <code>admon.do.txt</code>.

[^example-of-the-third-footnote]: Not much to add here, but the footnote
is at the end with only one newline.

************** File: testdoc.cwiki *****************
#summary A Document for Testing DocOnce
<wiki:toc max_depth="2" />
By **Hans Petter Langtangen** (hpl at simula.no), **Kaare Dump**, **A. Dummy Author**, **I. S. Overworked and Outburned**, and **J. Doe** (j_doe at cyberspace.com)
=== Jan 32, 2100 ===

Made with DocOnce




<<TableOfContents>>




<wiki:comment> !split </wiki:comment>




The format of this document is
cwiki

//Abstract.// This is a document with many test constructions for doconce syntax.
It was used heavily for the development and kept for testing
numerous constructions, also special and less common cases.

And exactly for test purposes we have an extra line here, which
is part of the abstract.

<wiki:comment> Cannot demonstrate chapter headings since abstract and chapter </wiki:comment>
<wiki:comment> are mutually exclusive in LaTeX </wiki:comment>

= Section 1 =


Here is a nested list:


  * item1
  * item2
  * item3 which continues    on the next line to test that feature
  * and a sublist

    ** with indented subitem1
    //* and a subitem2


  // and perhaps an ordered sublist

   ## first item
   ## second item,      continuing on a new line



//Here is a list with paragraph heading.//


  * item1
  * item2

=== Here is a list with subsubsection heading ===

  * item1
  * item2





Here are two references. Equation (my:eq1) is fine. Eq. (my:eq1) too.
Even Equation (my:eq1) without the tilde.


== Subsection 1 ==



<wiki:comment> Refer to section/appendix etc. at the beginning of the line </wiki:comment>
<wiki:comment> and other special fix situations for HTML. </wiki:comment>

More text, with a reference back to
the section [#Section_1] and [#Subsection_1], and further to the
the sections [#Subsection_1] and [#URLs], which
encourages you to do the tasks in [#Problem_2:_Flip_a_Coin] and [#Exercise_10:_Make_references_to_projects_and_problems].
 [#Appendix:_Just_for_testing;_part_I] and [#Appendix:_Just_for_testing;_part_II] are also nice elements.

=== Test Section reference at beginning of line and after a sentence ===

The section [#Subsection_1] is fine.
The section [#URLs] too.


<wiki:comment> sphinx code-blocks: pycod=python cod=fortran cppcod=c++ sys=console </wiki:comment>

=== Computer code ===

Let's do some copying from files too. First from subroutine up to the very end,

{{{
      subroutine test()
      integer i
      real*8 r
      r = 0
      do i = 1, i
         r = r + i
      end do
      return
C     END1

      program testme
      call test()
      return
}}}
and then just the subroutine,
{{{

      subroutine test()
      integer i
      real*8 r
      r = 0
      do i = 1, i
         r = r + i
      end do
      return
}}}
and finally the complete file with a plain text verbatim environment
({{{envir=ccq}}}):
{{{
C     a comment

      subroutine test()
      integer i
      real*8 r
      r = 0
      do i = 1, i
         r = r + i
      end do
      return
C     END1

      program testme
      call test()
      return
}}}

Testing other code environments. First Python:

{{{
!bc pycod
def f(x):
    return x+1
!ec
}}}
which gets rendered as

{{{
def f(x):
    return x+1
}}}

Test paragraph and subsubsection headings before
before code.

//Paragraph heading before code.//

{{{
import sys
sys.path.insert(0, os.pardir)
}}}

=== Subsubsection heading before code ===

{{{
def h(z):
    return z+1
}}}

Here is a program that is supposed to be interactive via
Python Online Tutorial, but that service is not accessible
for the present format.

{{{
class Line:
    def __init__(self, a, b):
        self.a, self.b = a, b

    def __call__(self, x):
        a, b = self.a, self.b
        return a*x + b

line = Line(2, 1)
y = line(x=3)
print(y)
}}}

Some more Python code (actually specified as a sage cell, but
such cells are not supported by this format).

{{{
a = 2
b = 3
print('a+b:', a + b)

# In a sage cell we can also plot
from matplotlib.pyplot import *
from numpy import *
x = linspace(0, 4*pi, 101)
y = exp(-0.1*x)*cos(x)
plot(x, y)
xlabel('x'); ylabel('y')
show()
}}}


Then Cython (with -h option so it is hidden in html/sphinx):

{{{
cpdef f(double x):
    return x + 1
}}}

Standard Python shell sessions:

{{{
>>> from numpy import linspace, sin
>>> # Some comment
>>> x = linspace(0, 2, 11)
>>> y = sin(x)
>>> y[0]
0
>>> import matplotlib.pyplot as plt
>>> plt.plot(x, y)
}}}

Similar IPython sessions:

{{{
In [1]: from numpy import linspace, sin
In [2]: # Some comment
In [3]: x = linspace(0, 2, 11)
In [4]: y = sin(x)
In [5]: y[0]
Out[5]: 0
In [6]: import matplotlib.pyplot as plt
In [7]: plt.plot(x, y)
In [8]: a='multiple-\nline\noutput'
In [9]: a
Out[9]: 'multiple-\nline\noutput'
In [10]: print(a)
multiple-
line
output
}}}

Here is the interactive session again, but with {{{pyshell-t}}}.

{{{
>>> from numpy import linspace, sin
>>> # Some comment
>>> x = linspace(0, 2, 11)
>>> y = sin(x)
>>> y[0]
0
>>> import matplotlib.pyplot as plt
>>> plt.plot(x, y)
}}}

<wiki:comment> This one tests a + sign before a code environment </wiki:comment>
C++:
{{{
#include <iostream>

int main()
{
   std::cout << "Sample output" << std::endl;
   return 0
}
}}}
<wiki:comment> The next should get correctly typset in sphinx (cod is fcod) </wiki:comment>
<wiki:comment> It also tests emoji before code </wiki:comment>
And a little bit of Fortran: :dizzy_face:

{{{
!bc cod
      subroutine midpt(x, length, a, b)
      real*8 a, b, x
      x = (a + b)/2
      length = b - a
      return
      end
!ec
}}}
which then is typeset as

{{{
      subroutine midpt(x, length, a, b)
      real*8 a, b, x
      x = (a + b)/2
      length = b - a
      return
      end
}}}

HTML:

{{{
<table>
<tr><td>Column 1</td><td>Column 2</td></tr>
<tr><td>0.67526 </td><td>0.92871 </td></tr>
<!-- comment -->
</table>
}}}

But inline HTML code is also important, like text that starts with
{{{<a href="}}} (which can destroy the following text if not properly
quoted).

Matlab with comments requires special typesetting:

{{{
% Comment on the beginning of the line can be escaped by %%
if a > b
  % Indented comment needs this trick
  c = a + b
end
}}}

And here is a system call:

{{{
Terminal> mkdir test
Terminal> cd test
Terminal> myprog -f
output1
output2
}}}

Any valid pygments lexer/language name can appear to, e.g.,

{{{
!bc restructuredtext
=======
Heading
=======

Some text.
!ec
}}}
results in

{{{
=======
Heading
=======

Some text.
}}}

<wiki:comment> Here goes hidden code. </wiki:comment>
<wiki:comment> Python can be treated by some formats, Fortran is always out. </wiki:comment>





Finally, {{{!bc do}}} supports highlighting of DocOnce source:

{{{
======= DocOnce test file =======

===== Computer code =====

Inline verbatim code, as in `import numpy as np`, is allowed, as well as
code blocks:

!bc pycod
from math import sin

def f(x):
    """Example on a function."""
    return sin(x) + 1

print(f(0))
!ec


===== Mathematics =====

Formulas can be inline, as in $\nabla\cdot\bm{u} = 0$, or typeset
as equations:

!bt
\begin{align*}
\nabla\cdot\bm{u} &= 0,\\ 
\bm{u} &= \nabla\phi .
\end{align*}
!et

=== Subsubsection heading ===

DocOnce files can have chapters, sections, subsections, and subsubsections.

__Paragraph heading.__ Paragraphs may have headings.
}}}

It is time to test {{{verbatim inline font}}} especially with {{{a newline
inside the text}}} and an exclamation mark at the end: {{{BEGIN}}}! For
spellcheck, test {{{a verbatim expression}}} in {{{another}}} in a {{{third}}}.
Also test exclamation mark as in {{{!bc}}} and {{{!ec}}} as well as {{{a != b}}}.
Also test backslashes and braces like {{{\begin}}}, {{{\begin{enumerate}}}},
{{{\end{this}\end{that}}}}, and {{{{something \inside braces}}}}.

The following attempt to exemplify colored text does not work in
format cwiki.
Here is some <font color="red">red color</font> and an attempt to write <font color="green">with
green color containing a linebreak<br />
code.</font> Some formats will only display <br />
this correctly when {{{html}}} <br />
is the output format.
But here some more running text is added which is not part of
the previous blocks with line breaks.

=== Running OS commands ===

{{{
Terminal> python -c 'print("Testing\noutput\nfrom\nPython.")'
Testing
output
from
Python.
}}}


=== Footnotes ===

Here is a test of footnotes [^footnote], which are handy in text.
They are used in different flavors, now in


 * list items (note below that footnotes work after math, verbatim, and URLs - bin fact old and emphasize too!)
 * even with math {{{\nabla^2u}}}[^math1]
 * and code {{{h[i] += 1}}}[^code]   (//must// have space between inline code and footnote!)
 * and [[https://google.com|links]][^google-search]

which gives flexibility in writing.
This is the third[^example-of-the-third-footnote] example.

  [^footnote]: Typesetting of the footnote depends on the format.
Plain text does nothing, LaTeX removes the
definition and inserts the footnote as part of the LaTeX text.
reStructuredText and Sphinx employ a similar type of typesetting
as Extended Markdown and DocOnce, and in HTML we keep the same
syntax, just displayed properly in HTML.
[^math1]: Math footnotes can be dangerous since it
interferes with an exponent.
[^code]: One-line footnote.

[^google-search]: [[google.com]] is perhaps the most famous
web site today.

Here is some more text before a new definition of a footnote that was
used above.

//Non-breaking space character.// 
This paragraph aims to test [[https://en.wikipedia.org/wiki/Non-breaking_space|non-breaking space character]], and a typical
example where this is needed is in physical units: 7.4 km is traveled
in {{{7.4/5.5\approx 1.345}}} s.  Also check that a~[[https://google.com|link]]~is
not broken across lines (drag the browser window to test this).
(On the other hand, the tilde is used in
computer code, e.g., as in {{{[~x for x in y]}}} or in {{{y=~x}}}, and should
of course remain a tilde in those contexts.)



== Subsection 2: Testing figures ==


Test of figures. In particular we refer to Figure fig:impact in which
there is a flow.

{{../doc/src/manual/fig/wave1D.png| Visualization **of** a //wave//. (fig:impact)}}

Figures without captions are allowed and will be inlined.

{{../doc/src/manual/fig/wave1D.png|}}



<wiki:comment> Test multi-line caption in figure with sidecap=True </wiki:comment>

Here is figure myfig with a long (illegal) multi-line caption
containing inline verbatim text:

{{../doc/src/manual/fig/wave1D.png| A long caption spanning several lines and containing verbatim words like {{{my_file_v1}}} and {{{my_file_v2}}} as well as math with subscript as in {{{t_{i+1}}}}. (myfig) }}

<wiki:comment> Must be a blank line after MOVIE or FIGURE to detect this problem </wiki:comment>

Test URL as figure name:

{{https://raw.github.com/doconce/doconce/master/doc/src/blog/f_plot.png|}}


<wiki:comment> Test wikimedia type of files that otherwise reside in subdirs </wiki:comment>


//Remark.//
Movies are tested in separate file {{{movies.do.txt}}}.


<wiki:comment> Somewhat challenging heading with latex math, \t, \n, ? and parenthesis </wiki:comment>

== The {{{\theta}}} parameter (not {{{\nabla}}}?) ==


Functions do not always need to be advanced, here is one
involving {{{\theta}}}:
{{{
def f(theta):
    return theta**2
}}}

//More on {{{\theta}}}.// Here is more text following headline with math.

Newcommands must also be tested in this test report:
{{{\frac{1}{2}}}}, {{{{1/2}}}}, {{{\pmb{x}}}}, {{{\frac{Du}{dt}}}},
both inline and in block:

{{{
\begin{align}
\frac{Du}{dt} &= 0\nonumber
\\ 
\frac{1}{2} &= {1/2}\\ 
\frac{1}{2}\pmb{x} &= \pmb{n}
\end{align}
}}}

Or with align with label and numbers:

{{{
\begin{align}
\frac{Du}{dt} &= 0
label{aligneq1}
\\ 
\frac{1}{2} &= {1/2}\\ 
\frac{1}{2}\pmb{x} &= \pmb{n}
label{aligneq2}
\end{align}
}}}


<wiki:comment> Must test more complicated align and matrix compositions </wiki:comment>
<wiki:comment> where DocOnce inserts auto-numbered labels etc. </wiki:comment>

First one numbered (automatically):

{{{
\begin{align}
\begin{pmatrix}
G_2 + G_3 & -G_3 & -G_2 & 0 \\ 
-G_3 & G_3 + G_4 & 0 & -G_4 \\ 
-G_2 & 0 & G_1 + G_2 & 0 \\ 
0 & -G_4 & 0 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
 v_1 \\ 
 v_2 \\ 
 v_3 \\ 
 v_4
\end{pmatrix}
+ \cdots \\ 
\begin{pmatrix}
 C_5 + C_6 & -C_6 & 0 & 0 \\ 
 -C_6 & C_6 & 0 & 0 \\ 
 0 & 0 & 0 & 0 \\ 
 0 & 0 & 0 & 0
\end{pmatrix}
  &= \frac{d}{dt}\begin{pmatrix}
 v_1 \\ 
 v_2 \\ 
 v_3 \\ 
 v_4
\end{pmatrix} +
\begin{pmatrix}
 0 \\ 
 0 \\ 
 0 \\ 
 -i_0
\end{pmatrix}
\nonumber
\end{align}
}}}

Second numbered (automatically):

{{{
\begin{align}
\begin{pmatrix}
G_1 + G_2\\ 
-G_3 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
 v_1 \\ 
 v_2
\end{pmatrix}
+ \cdots\nonumber
\\ 
\left(\begin{array}{ll}
y & 2\\ 
2 & 1
\end{array}\right)
\left(\begin{array}{ll}
0 \\ x
\end{array}\right)
&= \begin{pmatrix}
A \\ B
\end{pmatrix}
\end{align}
}}}

Both numbered, with label by the user:

{{{
\begin{align}
\begin{pmatrix}
G_1 + G_2\\ 
-G_3 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
 v_1 \\ 
 v_2
\end{pmatrix}
+ \cdots label{mymatrix:eq1}
\\ 
label{mymatrix:eq2}
\left(\begin{array}{ll}
y & 2\\ 
2 & 1
\end{array}\right)
\left(\begin{array}{ll}
0 \\ x
\end{array}\right)
&= \begin{pmatrix}
A \\ B
\end{pmatrix}
\end{align}
}}}
Now we refer to Equations (mymatrix:eq1)-(mymatrix:eq2).

== Custom Environments ==

Here is an attempt to create a theorem environment via Mako
(for counting theorems) and comment lines to help replacing lines in
the {{{.tex}}} by proper begin-end LaTeX environments for theorems.
Should look nice in most formats!



<wiki:comment> begin theorem </wiki:comment>



//Theorem 5.//
Let {{{a=1}}} and {{{b=2}}}. Then {{{c=3}}}.
<wiki:comment> end theorem </wiki:comment>

<wiki:comment> begin proof </wiki:comment>
//Proof.//
Since {{{c=a+b}}}, the result follows from straightforward addition.
END
<wiki:comment> end proof </wiki:comment>

As we see, the proof of Theorem 5 is a modest
achievement.


== Tables ==



<wiki:comment> index with comma could fool sphinx </wiki:comment>

Let us take this table from the manual:



 | =time     | =velocity     | =acceleration     |
 |  0.0      |  1.4186       |  -5.01            |
 |  2.0      |  1.376512     |  11.919           |
 |  4.0      |  1.1E+1       |  14.717624        |



The DocOnce source code reads
{{{

  |--------------------------------|
  |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    |
  |--------------------------------|

}}}

Here is yet another table to test that we can handle more than
one table:


 | =time     | =velocity     | =acceleration     |
 |  0.0      |  1.4186       |  -5.01            |
 |  1.0      |  1.376512     |  11.919           |
 |  3.0      |  1.1E+1       |  14.717624        |


And one with math headings (that are expanded and must be treated
accordingly), verbatim heading and entry, and no space around the pipe
symbol:


 | ={{{i}}}     | ={{{h_i}}}     | ={{{\bar T_i}}}     | ={{{L_i}}}     |
 |  0           |  0             |  288                |  -0.0065       |
 |  1           |  11,000        |  216                |  0.0           |
 |  2           |  20,000        |  216                |  0.001         |
 |  3           |  32,000        |  228                |  0.0028        |
 |  4           |  47,000        |  270                |  0.0           |
 |  5           |  51,000        |  270                |  -0.0028       |
 |  6           |  71,000        |  214                |  {{{NaN}}}     |


And add one with verbatim headings (with underscores),
and rows starting with {{{|-}}} because of a negative number,
and {{{|}}} right before and after verbatim word (with no space):


 | =exact     | ={{{v_1}}}     | ={{{a_i}}} + {{{v_2}}}     | ={{{verb_3_}}}     |
 |  9         |  9.62          |  5.57                      |  8.98              |
 |  -20       |  -23.39        |  -7.65                     |  -19.93            |
 |  10        |  17.74         |  -4.50                     |  9.96              |
 |  0         |  -9.19         |  4.13                      |  -0.26             |


Pipe symbols in verbatim and math text in tables used to pose difficulties,
but not
anymore:


 | ={{{S}}}           | =command               |
 |  $ ||a_0|| $       |  {{{norm|length}}}     |
 |  {{{x\cap y}}}     |  {{{x|y}}}             |



Here is a table with X alignment:


 | =Type      | =Description                                                                                                                                                                                                                        |
 |  X         |  Alignment character that is used for specifying a potentially very long text in a column in a table. It makes use of the {{{tabularx}}} package in LaTeX, otherwise (for other formats) it means {{{l}}} (centered alignment).     |
 |  l,r,c     |  standard alignment characters                                                                                                                                                                                                      |


Finally, a table with math
and URLs.

<wiki:comment> Mako code to expand URLs in the table </wiki:comment>
<wiki:comment> (These types of tables did not work before Jan 2014) </wiki:comment>



 | =                                | =                                                       | =                |
 |  {{{\mathcal{L}=0}}}             |  [[../doc/src/manual/mov/wave_frames/frame_0080.png     |  {{{080}}}]]     |  [[../doc/src/manual/mov/wave_frames/frame_0085.png     |  {{{085}}}]]     |
 |  {{{a=b}}}                       |  [[../doc/src/manual/mov/wave_frames/frame_0090.png     |  {{{090}}}]]     |  [[../doc/src/manual/mov/wave_frames/frame_0095.png     |  {{{095}}}]]     |
 |  {{{\nabla\cdot\bm{u} =0 }}}     |  [[../doc/src/manual/mov/wave_frames/frame_0100.png     |  {{{100}}}]]     |  [[../doc/src/manual/mov/wave_frames/frame_0105.png     |  {{{105}}}]]     |



== A test of verbatim words in heading with subscript {{{a_i}}}: {{{my_file_v1}}} and {{{my_file_v2}}} ==

//Paragraph with verbatim and math: {{{my_file_v1.py}}} and {{{my_file_v2.py}}} define some math {{{a_{i-1}}}}.// Here is more {{{__verbatim__}}} code and
some plain text on a new line.

<wiki:comment> Test various types of headlines </wiki:comment>
== **Just bold** ==

Some text.

== //Just emphasize// ==

Some text.

== {{{Just verbatim}}} ==

Some text.

== **Bold** beginning ==

Some text.

== //Emphasize// beginning ==

Some text.

== {{{Verbatim}}} beginning ==

Some text.

== Maybe **bold end** ==

Some text.

== Maybe //emphasize end// ==

Some text.

== Maybe {{{verbatim end}}} ==

Some text.

== The middle has **bold** word ==

Some text.

== The middle has //emphasize// word ==

Some text.

== The middle has {{{verbatim}}} word ==

Some text.


////Just emphasize//.// Some text.


//{{{Just verbatim}}}.// Some text.


////Emphasize// beginning.// Some text.


//{{{Verbatim beginning}}}.// Some text.


//Maybe //emphasize end//.// Some text.


//Maybe {{{verbatim end}}}.// Some text.


//The middle has //emphasize// word.// Some text.


//The middle has {{{verbatim}}} word.// Some text.


//Ampersand.//
We can test Hennes & Mauritz, often abbreviated H&M, but written
as {{{Hennes & Mauritz}}} and {{{H & M}}}.
A sole {{{&}}} must also work.
<wiki:comment> Note: substitutions must not occur inside verbatim, just in ordinary text. </wiki:comment>

{{{
# Just to check that ampersand works in code blocks:
c = a & b
}}}

//Quotes.//
Let us also add a test of quotes such as "double quotes, with numbers
like 3.14 and newline/comma and hyphen (as in double-quote)"; written
in the standard LaTeX-style that gives correct LaTeX formatting and
ordinary double quotes for all non-LaTeX formats.  Here is another
sentence that "caused" a bug in the past because double backtick
quotes could imply verbatim text up to a verbatim word starting with
period, like {{{.txt}}}.

More quotes to be tested for spellcheck:
("with parenthesis"), "with newline"
and "with comma", "hyphen"-wise, and "period".


== Bibliography test ==

Here is an example: [1] discussed propagation of
large destructive water waves, [2] gave
an overview of numerical methods for solving the Navier - Stokes equations,
while the use of Backward Kolmogorov equations for analyzing
random vibrations was investigated in [3].
The book chapter [4] contains information on
C++ software tools for programming multigrid methods. A real retro
reference is [5] about a big FORTRAN package.
Multiple references are also possible, e.g., see
[1] [4].

We need to cite more than 10 papers to reproduce an old formatting
problem with blanks in the keys in reST format:
[6] [3] [7] [1]
and
[2] [8] [9] [10] [11] [12] [13]
and all the work of
[14] [4] [15] as well as
old work [5] and [16], and the
talk [17].
Langtangen also had two thesis [18] [16]
back in the days.
More retro citations are
the old ME-IN323 book [19] and the
[20] OONSKI '94 paper.




<wiki:comment> --- begin exercise --- </wiki:comment>

== Example 1: Examples can be typeset as exercises ==


Examples can start with a subsection heading starting with {{{Example:}}}
and then, with the command-line option {{{--examples_as_exercises}}} be
typeset as exercises. This is useful if one has solution
environments as part of the example.


//a)//
State some problem.

//Solution.//
The answer to this subproblem can be written here.

//b)//
State some other problem.

//Hint 1.//
A hint can be given.

//Hint 2.//
Maybe even another hint?

//Solution.//
The answer to this other subproblem goes here,
maybe over multiple doconce input lines.

<wiki:comment> --- end exercise --- </wiki:comment>


== User-defined environments ==



The example in the section [#Example_1:_A_test_function] demonstrates how to write a test function.
That is, a special test function for a function {{{add}}} appears in
the example in the section [#Example_1:_A_test_function].



== Example 1: A test function ==


Suppose we want to write a test function for checking the
implementation of a Python function for addition.

{{{
def add(a, b):
    return a + b

def test_add():
    a = 1; b = 1
    expected = a + b
    computed = add(a, b)
    assert expected == computed
}}}





== Example 2: Addition ==


We have

{{{
\[ 1 + 1 = 2 \]
}}}
or in tabular form:


 | =Problem       | =Result      |
 |  {{{1+1}}}     |  {{{2}}}     |




//Highlight box!// 
This environment is used to highlight something:

{{{
\[ E = mc^2 \]
}}}





== URLs ==


Testing of URLs: hpl's home page [[https://folk.uio.no/hpl|hpl]], or
the entire URL if desired, [[https://folk.uio.no/hpl]].  Here is a
plain file link [[testdoc.do.txt]], or [[testdoc.do.txt]], or
[[testdoc.do.txt]] or [[testdoc.do.txt]] or [[testdoc.do.txt|a link with
newline]]. Can test spaces with the link with word
too: [[https://folk.uio.no/hpl|hpl]] or [[https://folk.uio.no/hpl|hpl]]. Also {{{file:///}}} works: [[file:///home/hpl/vc/doconce/doc/demos/manual/manual.html|link to a
file]] is
fine to have. Moreover, "loose" URLs work, i.e., no quotes, just
the plain URL as in [[https://folk.uio.no/hpl]], if followed by space, comma,
colon, semi-colon, question mark, exclamation mark, but not a period
(which gets confused with the periods inside the URL).

Mail addresses can also be used: [[mailto:hpl@simula.no|{{{hpl@simula.no}}}]], or just a [[mailto:hpl@simula.no|mail link]], or a raw [[mailto:hpl@simula.no]].

Here are some tough tests of URLs, especially for the {{{latex}}} format:
[[https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas|Newton-Cotes]] formulas
and a [[https://www.springer.com/mathematics/computational+science+%26+engineering/book/978-3-642-23098-1|good book]]. Need to test
Newton-Cotes with percentage in URL too:
[[https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas]]
and [[https://en.wikipedia.org/wiki/Newton-Cotes#Open_Newton.E2.80.93Cotes_formulae]] which has a shebang.

For the {{{--device=paper}}} option it is important to test that URLs with
monospace font link text get a footnote
(unless the {{{--latex_no_program_footnotelink}}}
is used), as in this reference to
[[https://github.com/hplgit/INF5620/tree/gh-pages/src/decay/experiments/decay_mod.py|{{{decay_mod}}}]], [[https://tinyurl.com/pwyasaa/formulas.ball1.py|{{{ball1.py}}}]],
and [[https://tinyurl.com/pwyasaa/formulas.ball2.py|{{{ball2.py}}}]].


<wiki:comment> Comments should be inserted outside paragraphs (because in the rst </wiki:comment>
<wiki:comment> format extra blanks make a paragraph break). </wiki:comment>

<wiki:comment> Note that when there is no https: or file:, it can be a file link </wiki:comment>
<wiki:comment> if the link name is URL, url, "URL", or "url". Such files should, </wiki:comment>
<wiki:comment> if rst output is desired, but placed in a {{{_static*}}} folder. </wiki:comment>

More tough tests: repeated URLs whose footnotes when using the
{{{--device=paper}}} option must be correct. We have
[[https://google.com|google]], [[https://google.com|google]], and
[[https://google.com|google]], which should result in exactly three
footnotes.



<wiki:comment> !split and check if these extra words are included properly in the comment </wiki:comment>

= LaTeX Mathematics =

Here is an equation without label using backslash-bracket environment:
{{{
\[ a = b + c \]
}}}

or with number and label, as in Equation (my:eq1), using the equation environment:

{{{
\begin{equation}
{\partial u\over\partial t} = \nabla^2 u label{my:eq1}
\end{equation}
}}}

We can refer to this equation by Equation (my:eq1).

Here is a system without equation numbers, using the align-asterisk environment:

{{{
\begin{align*}
\pmb{a} &= \pmb{q}\times\pmb{n} \\ 
b &= \nabla^2 u + \nabla^4 v
\end{align*}
}}}



More mathematical typesetting is demonstrated in the coming exercises.

Below, we have [#Problem_2:_Flip_a_Coin] and [#Project_4:_Compute_a_Probability],
as well as [#Project_5:_Explore_Distributions_of_Random_Circles] and [#Project_11:_References_to_Project_demo:ex:2_in_a_heading_works_for_cwiki], and in
between there we have [#Exercise_10:_Make_references_to_projects_and_problems].


= Exercises =



<wiki:comment> --- begin exercise --- </wiki:comment>

== Problem 2: Flip a Coin ==

<wiki:comment> keywords = random numbers; Monte Carlo simulation; ipynb </wiki:comment>

<wiki:comment> Torture tests </wiki:comment>


//a)//
Make a program that simulates flipping a coin {{{N}}} times.
Print out "tail" or "head" for each flip and
let the program count the number of heads.

<wiki:comment> --- begin hint in exercise --- </wiki:comment>

//Hint 1.//
Use {{{r = random.random()}}} and define head as {{{r <= 0.5}}}.

<wiki:comment> --- end hint in exercise --- </wiki:comment>

<wiki:comment> --- begin hint in exercise --- </wiki:comment>

//Hint 2.//
Draw an integer among {{{\{1,2\}}}} with
{{{r = random.randint(1,2)}}} and define head when {{{r}}} is 1.

<wiki:comment> --- end hint in exercise --- </wiki:comment>


<wiki:comment> --- begin answer of exercise --- </wiki:comment>
//Answer.//
If the {{{random.random()}}} function returns a number {{{<1/2}}}, let it be
head, otherwise tail. Repeat this {{{N}}} number of times.
<wiki:comment> --- end answer of exercise --- </wiki:comment>


<wiki:comment> --- begin solution of exercise --- </wiki:comment>
//Solution.//
{{{
import sys, random
N = int(sys.argv[1])
heads = 0
for i in range(N):
    r = random.random()
    if r <= 0.5:
        heads += 1
print('Flipping a coin %d times gave %d heads' % (N, heads))
}}}
<wiki:comment> --- end solution of exercise --- </wiki:comment>

//b)//
Vectorize the code in a) using boolean indexing.

Vectorized code can be written in many ways.
Sometimes the code is less intuitive, sometimes not.
At least there is not much to find in the section [#Section_1].

//c)//
Vectorize the code in a) using {{{numpy.sum}}}.


<wiki:comment> --- begin answer of exercise --- </wiki:comment>
//Answer.//
{{{np.sum(np.where(r <= 0.5, 1, 0))}}} or {{{np.sum(r <= 0.5)}}}.
<wiki:comment> --- end answer of exercise --- </wiki:comment>

In this latter subexercise, we have an
example where the code is easy to read.


=== My remarks ===

Remarks with such a subsubsection is treated as more text
after the last subexercise. Test a list too:


# Mark 1.
# Mark 2.

Filenames: {{{flip_coin.py}}}, {{{flip_coin.pdf}}}.

<wiki:comment> Closing remarks for this Problem </wiki:comment>

=== Remarks ===

These are the exercise remarks, appearing at the very end.

<wiki:comment> solution files: mysol.txt, mysol_flip_coin.py, yet_another.file </wiki:comment>

<wiki:comment> --- end exercise --- </wiki:comment>


== Not an exercise ==

Should be possible to stick a normal section in the middle of many
exercises.



<wiki:comment> --- begin exercise --- </wiki:comment>

== Exercise 3: Test of plain text exercise ==


Very short exercise. What is the capital
of Norway?
Filename: {{{myexer1}}}.

<wiki:comment> --- end exercise --- </wiki:comment>




<wiki:comment> --- begin exercise --- </wiki:comment>

== Project 4: Compute a Probability ==


<wiki:comment> Minimalistic exercise </wiki:comment>


What is the probability of getting a number between 0.5 and 0.6 when
drawing uniformly distributed random numbers from the interval {{{[0,1)}}}?


At the end we have a list because that caused problems in LaTeX
in previous DocOnce versions:


# item1
# item2

<wiki:comment> --- begin hint in exercise --- </wiki:comment>

//Hint.//
To answer this question empirically, let a program
draw {{{N}}} such random numbers using Python's standard {{{random}}} module,
count how many of them, {{{M}}}, that fall in the interval {{{(0.5,0.6)}}}, and
compute the probability as {{{M/N}}}.

<wiki:comment> --- end hint in exercise --- </wiki:comment>

<wiki:comment> --- end exercise --- </wiki:comment>




<wiki:comment> --- begin exercise --- </wiki:comment>

== Project 5: Explore Distributions of Random Circles ==

<wiki:comment> keywords = ipynb </wiki:comment>

The formula for a circle is given by

{{{
\begin{align}
x &= x_0 + R\cos 2\pi t,
label{circle:x}\\ 
y &= y_0 + R\sin 2\pi t,
label{circle:y}
\end{align}
}}}
where {{{R}}} is the radius of the circle, {{{(x_0,y_0)}}} is the
center point, and {{{t}}} is a parameter in the unit interval {{{[0,1]}}}.
For any {{{t}}}, {{{(x,y)}}} computed from Equations (circle:x)-(circle:y)
is a point on the circle.
The formula can be used to generate {{{n}}} points on a circle:

{{{
import numpy as np

def circle(R, x0, y0, n=501):
    t = np.linspace(0, 1, n)
    x = x0 + R*np.cos(2*np.pi*t)
    y = y0 + R*np.sin(2*np.pi*t)
    return x, y

x, y = circle(2.0, 0, 0)
}}}

<wiki:comment> Often in an exercise we have some comments about the solution </wiki:comment>
<wiki:comment> which we normally want to keep where they are. </wiki:comment>

The goal of this project is to draw {{{N}}} circles with random
center and radius. Plot each circle using the {{{circle}}} function
above.


//a)//
Let {{{R}}} be normally distributed and {{{(x_0,y_0)}}} uniformly distributed.

<wiki:comment> --- begin hint in exercise --- </wiki:comment>

//Hint.//
Use the {{{numpy.random}}} module to draw the
{{{x_0}}}, {{{y_0}}}, and {{{R}}} quantities.

<wiki:comment> --- end hint in exercise --- </wiki:comment>


<wiki:comment> --- begin answer of exercise --- </wiki:comment>
//Answer.//
Here goes the short answer to part a).
<wiki:comment> --- end answer of exercise --- </wiki:comment>


<wiki:comment> --- begin solution of exercise --- </wiki:comment>
//Solution.//
Here goes a full solution to part a).
<wiki:comment> --- end solution of exercise --- </wiki:comment>

//b)//
Let {{{R}}} be uniformly distributed and {{{(x_0,y_0)}}} normally distributed.
Filename: {{{norm}}}.

//c)//
Let {{{R}}} and {{{(x_0,y_0)}}} be normally distributed.


Filename: {{{circles}}}.

<wiki:comment> Closing remarks for this Project </wiki:comment>

=== Remarks ===

At the very end of the exercise it may be appropriate to summarize
and give some perspectives.


<wiki:comment> --- end exercise --- </wiki:comment>




<wiki:comment> --- begin exercise --- </wiki:comment>

== Exercise 6: Determine some Distance ==


Intro to this exercise. Questions are in subexercises below.


<wiki:comment> --- begin solution of exercise --- </wiki:comment>
//Solution.//
Here goes a full solution of the whole exercise.
With some math {{{a=b}}} in this solution:
{{{
\[ \hbox{math in solution: } a = b \]
}}}
And code {{{a=b}}} in this solution:
{{{
a = b  # code in solution
}}}
End of solution is here.

<wiki:comment> --- end solution of exercise --- </wiki:comment>


//a)//
Subexercises are numbered a), b), etc.

<wiki:comment> --- begin hint in exercise --- </wiki:comment>

//Hint 1.//
First hint to subexercise a).
With math {{{a=b}}} in hint:

{{{
\[ a=b. \]
}}}
And with code (in plain verbatim) returning {{{x+1}}} in hint:

{{{
def func(x):
    return x + 1  # with code in hint
}}}

<wiki:comment> --- end hint in exercise --- </wiki:comment>

<wiki:comment> --- begin hint in exercise --- </wiki:comment>

//Hint 2.//
Second hint to subexercise a).

Test list in hint:


# item1
# item2

<wiki:comment> --- end hint in exercise --- </wiki:comment>
Filename: {{{subexer_a.pdf}}}.


<wiki:comment> --- begin answer of exercise --- </wiki:comment>
//Answer.//
Short answer to subexercise a).
With math in answer: {{{a=b}}}.
<wiki:comment> --- end answer of exercise --- </wiki:comment>

//b)//
Here goes the text for subexercise b).


Some math {{{\cos^2 x + \sin^2 x = 1}}} written one a single line:

{{{
\[ \cos^2 x + \sin^2 x = 1 \thinspace .\]
}}}

<wiki:comment> --- begin hint in exercise --- </wiki:comment>

//Hint.//
A hint for this subexercise.

<wiki:comment> --- end hint in exercise --- </wiki:comment>
Filename: {{{subexer_b.pdf}}}.


<wiki:comment> --- begin solution of exercise --- </wiki:comment>
//Solution.//
Here goes the solution of this subexercise.
<wiki:comment> --- end solution of exercise --- </wiki:comment>



<wiki:comment> No meaning in this weired test example: </wiki:comment>
The text here belongs to the main (intro) part of the exercise. Need
closing remarks to have text after subexercises.

Test list in exercise:


# item1
# item2<wiki:comment> Closing remarks for this Exercise </wiki:comment>


=== Remarks ===

Some final closing remarks, e.g., summarizing the main findings
and their implications in other problems can be made. These
remarks will appear at the end of the typeset exercise.


<wiki:comment> --- end exercise --- </wiki:comment>




<wiki:comment> --- begin exercise --- </wiki:comment>

== Some exercise without the "Exercise:" prefix ==

<wiki:comment> Another minimalistic exercise </wiki:comment>

Just some text. And some math saying that {{{e^0=1}}} on a single line,
to test that math block insertion is correct:

{{{
\[ \exp{(0)} = 1 \]
}}}

And a test that the code {{{lambda x: x+2}}} is correctly placed here:

{{{
lambda x: x+2
}}}


<wiki:comment> Have some comments at the end of the exercise to see that </wiki:comment>
<wiki:comment> the Filename: ... is written correctly. </wiki:comment>
<wiki:comment> --- end exercise --- </wiki:comment>




<wiki:comment> --- begin exercise --- </wiki:comment>

== Exercise 8: Solution of differential equation ==




Given

{{{
\[ \frac{dy}{dx} = -y(x),\quad y(0)=1 \]
}}}
What is the solution of this equation?

Choice A: 
{{{y=e^{-y}}}}

Choice B: 
{{{y=e^{y}}}}

Choice C: 
{{{
from math import exp
def f(x):
    return exp(x)
}}}

Choice D: The solution cannot be found because there is a derivative in the equation.

Choice E: The equation is meaningless: an equation must be an equation
for {{{x}}} or {{{y}}}, not a function {{{y(x)}}}.



<wiki:comment> --- end exercise --- </wiki:comment>




<wiki:comment> --- begin exercise --- </wiki:comment>

== Example 9: Just an example ==

<wiki:comment> This example needs the --examples_as_exercises option, otherwise </wiki:comment>
<wiki:comment> it is just typeset as it is written. </wiki:comment>


//a)//
What is the capital of Norway?

//Answer.//
Oslo.

<wiki:comment> --- end exercise --- </wiki:comment>


= Here goes another section =

With some text, before we continue with exercises.

= More Exercises =



<wiki:comment> --- begin exercise --- </wiki:comment>

== Exercise 10: Make references to projects and problems ==


<wiki:comment> Test comments not at the end only </wiki:comment>
Pick a statement from [#Project_5:_Explore_Distributions_of_Random_Circles] or [#Problem_2:_Flip_a_Coin]
and verify it.

Test list at the end of an exercise without other elements (like subexercise,
hint, etc.):


# item1
# item2

Filename: {{{verify_formula.py}}}.

<wiki:comment> --- end exercise --- </wiki:comment>




<wiki:comment> --- begin exercise --- </wiki:comment>

== Project 11: References to [#Project_4:_Compute_a_Probability] in a heading works for cwiki ==


Refer to the previous exercise as [#Exercise_10:_Make_references_to_projects_and_problems],
the two before that as [#Project_4:_Compute_a_Probability] and [#Project_5:_Explore_Distributions_of_Random_Circles],
and this one as [#Project_11:_References_to_Project_demo:ex:2_in_a_heading_works_for_cwiki].
Filename: {{{selc_composed.pdf}}}.

<wiki:comment> --- end exercise --- </wiki:comment>


= References =


 # **H. P. Langtangen and G. Pedersen**.     Propagation of Large Destructive Waves,    //International Journal of Applied Mechanics and Engineering//,    7(1),    pp. 187-204,    2002.
 # **H. P. Langtangen, K.-A. Mardal and R. Winther**.     Numerical Methods for Incompressible Viscous Flow,    //Advances in Water Resources//,    25,    pp. 1125-1146,    2002.
 # **H. P. Langtangen**.     Numerical Solution of First Passage Problems in Random Vibrations,    //SIAM Journal of Scientific and Statistical Computing//,    15,    pp. 997-996,    1994.
 # **K.-A. Mardal, G. W. Zumbusch and H. P. Langtangen**.     Software Tools for Multigrid Methods,    //Advanced Topics in Computational Partial Differential Equations -- Numerical Methods and Diffpack Programming//,    edited by **H. P. Langtangen and A. Tveito**,    Springer,    2003,    Edited book,    [[http://some.where.org]].
 # **H. P. Langtangen**.     The FEMDEQS Program System,    //Department of Mathematics, University of Oslo//,    1989,    [[http://www.math.uio.no/old/days/hpl/femdeqs.pdf]].
 # **H. P. Langtangen**.     Stochastic Breakthrough Time Analysis of an Enhanced Oil Recovery Process,    //SIAM Journal on Scientific Computing//,    13,    pp. 1394-1417,    1992.
 # **M. Mortensen, H. P. Langtangen and G. N. Wells**.     A FEniCS-Based Programming Framework for Modeling Turbulent Flow by the Reynolds-Averaged Navier-Stokes Equations,    //Advances in Water Resources//,    34(9),    [[https://dx.doi.org/10.1016/j.advwatres.2011.02.013|doi: 10.1016/j.advwatres.2011.02.013]],    2011.
 # **S. Glimsdal, G. Pedersen, K. Atakan, C. B. Harbitz, H. P. Langtangen and F. L\ovholt**.     Propagation of the Dec. 26, 2004 Indian Ocean Tsunami: Effects of Dispersion and Source Characteristics,    //International Journal of Fluid Mechanics Research//,    33(1),    pp. 15-43,    2006.
 # **S. Rahman, J. Gorman, C. H. W. Barnes, D. A. Williams and H. P. Langtangen**.     Numerical Investigation of a Piezoelectric Surface Acoustic Wave Interaction With a One-Dimensional Channel,    //Physical Review B: Condensed Matter and Materials Physics//,    74,    2006,    035308.
# **J. B. Haga, H. Osnes and H. P. Langtangen**.     On the Causes of Pressure Oscillations in Low-Permeable and Low-Compressible Porous Media,    //International Journal of Analytical and Numerical Methods in Geomechanics//,    [[https://dx.doi.org/10.1002/nag.1062|doi: 10.1002/nag.1062]],    2011,    [[http://onlinelibrary.wiley.com/doi/10.1002/nag.1062/abstract]].
# **H. P. Langtangen**.     //Computational Partial Differential Equations - Numerical Methods and Diffpack Programming//,    second edition,    //Texts in Computational Science and Engineering//,    Springer,    2003.
# **H. P. Langtangen**.     //Python Scripting for Computational Science//,    third edition,    //Texts in Computational Science and Engineering//,    Springer,    2008.
# **H. P. Langtangen and G. Pedersen**.     Finite Elements for the Boussinesq Wave Equations,    Waves and Non-linear Processes in Hydrodynamics,    edited by **J. Grue, B. Gjevik and J. E. Weber**,    Kluwer Academic Publishers,    pp. pp. 117-126,    1995,    [[http://www.amazon.ca/Waves-Nonlinear-Processes-Hydrodynamics-John/dp/0792340310]].
# **H. P. Langtangen**.     //A Primer on Scientific Programming With Python//,    third edition,    //Texts in Computational Science and Engineering//,    Springer,    2012.
# **P. V. Jeberg, H. P. Langtangen and C. B. Terp**.     Optimization With Diffpack: Practical Example From Welding,    //Simula Research Laboratory//,    2004,    Internal report.
# **H. P. Langtangen**.     Computational Methods for Two-Phase Flow in Oil Reservoirs,    Ph.D. Thesis,    Mechanics Division, Department of Mathematics, University of Oslo,    1989,    Dr. Scient. thesis..
# **H. P. Langtangen**.     Computational Modeling of Huge Tsunamis From Asteroid Impacts,    2007,    Invited keynote lecture at the \emphInternational conference on Computational Science 2007 (ICCS'07), Beijing, China.
# **H. P. Langtangen**.     Solution of the Navier-Stokes Equations With the Finite Element Method in Two and Three Dimensions,    M.Sc. Thesis,    Mechanics Division, Department of Mathematics, University of Oslo,    1985,    Cand.Scient. thesis.
# **H. P. Langtangen and A. Tveito**.     Numerical Methods in Continuum Mechanics,    //Center for Industrial Research//,    1991,    Lecture notes for a course (ME-IN 324). 286 pages..
# **H. P. Langtangen**.     Diffpack: Software for Partial Differential Equations,    //Proceedings of the Second Annual Object-Oriented Numerics Conference (OON-SKI'94), Sunriver, Oregon, USA//,    edited by **A. Vermeulen**,    1994.

= Appendix: Just for testing; part I =


This is the first appendix.

== A subsection within an appendix ==

Some text.

= Appendix: Just for testing; part II =


This is more stuff for an appendix.

== Appendix: Testing identical titles ==

Without label.


== Appendix: Testing identical titles ==


With label.

== Appendix: Testing identical titles ==


What about inserting a quiz?



======= Test of quizzes =======


Fundamental test: What is the capital of Norway?

Answer 1: Stockholm

Answer 2: London

Answer 3: Oslo

Choice D: Bergen




== Appendix: Testing identical titles ==

Without label.

//Tip.// 
Here is a tip or hint box, typeset as a notice box.





Need a lot of text to surround the summary box.
Version control systems allow you to record the history of files
and share files among several computers and collaborators in a
professional way. File changes on one computer are updated or
merged with changes on another computer. Especially when working
with programs or technical reports it is essential
to have changes documented and to
ensure that every computer and person involved in the project
have the latest updates of the files.
Greg Wilson' excellent [[https://software-carpentry.org/2010/07/script-for-introduction-to-version-control/|Script for Introduction to Version Control]] provides a more detailed motivation why you will benefit greatly
from using version control systems.

//Summary.// 
**Bold remark:** Make some text with this summary.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.



Projects that you want to share among several computers or project
workers are today most conveniently stored at some web site "in the
cloud" and updated through communication with that site. I strongly
recommend you to use such sites for all serious programming and
scientific writing work - and all other important files.

The simplest services for hosting project files are [[https://dropbox.com|Dropbox]] and [[https://drive.google.com|Google Drive]].
It is very easy to get started with these systems, and they allow you
to share files among laptops and mobile units with as many users as
you want. The systems offer a kind of version control in that the
files are stored frequently (several times per minute), and you can go
back to previous versions for the last 30 days. However, it is
challenging  to find the right version from the past when there are
so many of them.

More seriously, when several people may edit files simultaneously, it
can be difficult detect who did what when, roll back to previous
versions, and to manually merge the edits when these are
incompatible. Then one needs more sophisticated tools than Dropbox or
Google Drive: project hosting services with true version control
systems.  The following text aims at providing you with the minimum
information to started with such systems. Numerous other tutorials
contain more comprehensive material and in-depth explanations of the
concepts and tools.

The idea with project hosting services is that you have the files
associated with a project in the cloud. Many people may share these
files.  Every time you want to work on the project you explicitly
update your version of the files, edit the files as you like, and
synchronize the files with the "master version" at the site where the
project is hosted.  If you at some point need to go back to a
version of the files at some particular point in the past,
this is an easy operation. You can also use tools to see
what various people have done with the files in the various versions.

All these services are very similar. Below we describe how you get
started with Bitbucket, GitHub, and Googlecode. Launchpad works very
similarly to the latter three. All the project hosting services have
excellent introductions available at their web sites, but the recipes
below are much shorter and aim at getting you started as quickly as
possible by concentrating on the most important need-to-know steps.
The Git tutorials we refer to later in this document contain more
detailed information and constitute of course very valuable readings
when you use version control systems every day. The point now is
to get started.


== Appendix: Testing inline comments ==

<wiki:comment> Names can be [ A-Za-z0-9_'+-]+ </wiki:comment>

Projects that you want to share among several computers or project
workers are today most conveniently stored at some web site "in the
cloud" and updated through communication with that
site. [hpl's semi opinion 1: not sure if in the cloud is
understood by
all.] I strongly recommend you to use such sites for all serious
programming and scientific writing work - and all other important
files.

The simplest services for hosting project files is Dropbox. [mp 2: Simply go to [[https://dropbox.com]] and watch the video. It explains
how files, like {{{myfile.py}}}, perhaps containing much math, like
{{{\partial u/\partial t}}}, are easily communicated between machines.] It
is very easy to get started with Dropbox, and it allows you to share
files among [hpl 3: laptops and mobile units -> computers, tablets,
and phones].

<wiki:comment> Test horizontal rule </wiki:comment>

----

<wiki:comment> Coments for editing </wiki:comment>

First[add 4: ,] consider a quantity {{{Q}}}. [edit 5: To this end, -> We note that]
{{{Q>0}}}, because [del 6: a] negative [edit 7: quantity is -> quantities
are] [del 8: just] negative. [add 9: This comes as no surprise.]

<wiki:comment> Test tailored latex figure references with page number </wiki:comment>
Let us refer to Figure fig:impact again.

Test references in a list:


 * [#Section_1]
 * [#Subsection_1]
 * fig:impact

== Appendix: Testing headings ending with {{{verbatim inline}}} ==

The point here is to test 1) {{{verbatim}}} code in headings, and 2)
ending a heading with verbatim code as this triggers a special
case in LaTeX.

We also test mdash---used as alternative to hyphen without spaces around,
or in quotes:





The ndash should also be tested - as in the Hanson - Nilson equations
on page 277 - 278.

And finally, what about admons, quotes, and boxes? They are tested
in a separate document: {{{admon.do.txt}}}.

[^example-of-the-third-footnote]: Not much to add here, but the footnote
is at the end with only one newline.

************** File: testdoc.st *****************
TITLE: A Document for Testing DocOnce
BY: Hans Petter Langtangen (Center for Biomedical Computing, Simula Research Laboratory, and Department of Informatics, University of Oslo); Kaare Dump (Segfault, Cyberspace); A. Dummy Author; I. S. Overworked and Outburned (Inst1, and Inst2, Somewhere, and Third Inst, Elsewhere, and Fourth Inst); J. Doe
DATE: Jan 32, 2100
Made with DocOnce

# !split

The format of this document is
st
*Abstract.* This is a document with many test constructions for doconce syntax.
It was used heavily for the development and kept for testing
numerous constructions, also special and less common cases.

And exactly for test purposes we have an extra line here, which
is part of the abstract.

Section 1

Here is a nested list:

  - item1
  - item2
  - item3 which continues
    on the next line to test that feature
  - and a sublist
    - with indented subitem1
    - and a subitem2

  - and perhaps an ordered sublist
   a. first item
   b. second item,
      continuing on a new line

*Here is a list with paragraph heading.*

  - item1
  - item2

Here is a list with subsubsection heading

  - item1
  - item2





Here are two references. Equation (ref{my:eq1}) is fine. Eq. (ref{my:eq1}) too.
Even Equation (ref{my:eq1}) without the tilde.

Subsection 1

More text, with a reference back to
the section "Section 1" and "Subsection 1", and further to the
the sections "Subsection 1" and "URLs", which
encourages you to do the tasks in "Problem 2: Flip a Coin" and "Exercise 10: Make references to projects and problems".
 "Appendix: Just for testing; part I" and "Appendix: Just for testing; part II" are also nice elements.

Test Section reference at beginning of line and after a sentence

The section "Subsection 1" is fine.
The section "URLs" too.

Computer code

Let's do some copying from files too. First from subroutine up to the very end::

              subroutine test()
              integer i
              real*8 r
              r = 0
              do i = 1, i
                 r = r + i
              end do
              return
        C     END1
        
              program testme
              call test()
              return

and then just the subroutine::

        
              subroutine test()
              integer i
              real*8 r
              r = 0
              do i = 1, i
                 r = r + i
              end do
              return

and finally the complete file with a plain text verbatim environment
('envir=ccq')::

        C     a comment
        
              subroutine test()
              integer i
              real*8 r
              r = 0
              do i = 1, i
                 r = r + i
              end do
              return
        C     END1
        
              program testme
              call test()
              return

Testing other code environments. First Python::

        !bc pycod
        def f(x):
            return x+1
        !ec

which gets rendered as::

        def f(x):
            return x+1

Here is a program that is supposed to be interactive via
Python Online Tutorial, but that service is not accessible
for the present format::

        class Line:
            def __init__(self, a, b):
                self.a, self.b = a, b
        
            def __call__(self, x):
                a, b = self.a, self.b
                return a*x + b
        
        line = Line(2, 1)
        y = line(x=3)
        print(y)

Some more Python code (actually specified as a sage cell, but
such cells are not supported by this format)::

        a = 2
        b = 3
        print('a+b:', a + b)
        
        # In a sage cell we can also plot
        from matplotlib.pyplot import *
        from numpy import *
        x = linspace(0, 4*pi, 101)
        y = exp(-0.1*x)*cos(x)
        plot(x, y)
        xlabel('x'); ylabel('y')
        show()

Then Cython (with -h option so it is hidden in html/sphinx)::

        cpdef f(double x):
            return x + 1

Standard Python shell sessions::

        >>> from numpy import linspace, sin
        >>> # Some comment
        >>> x = linspace(0, 2, 11)
        >>> y = sin(x)
        >>> y[0]
        0
        >>> import matplotlib.pyplot as plt
        >>> plt.plot(x, y)

Similar IPython sessions::

        In [1]: from numpy import linspace, sin
        In [2]: # Some comment
        In [3]: x = linspace(0, 2, 11)
        In [4]: y = sin(x)
        In [5]: y[0]
        Out[5]: 0
        In [6]: import matplotlib.pyplot as plt
        In [7]: plt.plot(x, y)
        In [8]: a='multiple-\nline\noutput'
        In [9]: a
        Out[9]: 'multiple-\nline\noutput'
        In [10]: print(a)
        multiple-
        line
        output

Here is the interactive session again, but with 'pyshell-t'::

        >>> from numpy import linspace, sin
        >>> # Some comment
        >>> x = linspace(0, 2, 11)
        >>> y = sin(x)
        >>> y[0]
        0
        >>> import matplotlib.pyplot as plt
        >>> plt.plot(x, y)

C++::

        #include <iostream>
        
        int main()
        {
           std::cout << "Sample output" << std::endl;
           return 0
        }

And a little bit of Fortran: :dizzy_face::

        !bc cod
              subroutine midpt(x, length, a, b)
              real*8 a, b, x
              x = (a + b)/2
              length = b - a
              return
              end
        !ec

which then is typeset as::

              subroutine midpt(x, length, a, b)
              real*8 a, b, x
              x = (a + b)/2
              length = b - a
              return
              end

HTML::

        <table>
        <tr><td>Column 1</td><td>Column 2</td></tr>
        <tr><td>0.67526 </td><td>0.92871 </td></tr>
        <!-- comment -->
        </table>

But inline HTML code is also important, like text that starts with
'<a href="' (which can destroy the following text if not properly
quoted).

Matlab with comments requires special typesetting::

        % Comment on the beginning of the line can be escaped by %%
        if a > b
          % Indented comment needs this trick
          c = a + b
        end

And here is a system call::

        Terminal> mkdir test
        Terminal> cd test
        Terminal> myprog -f
        output1
        output2

Any valid pygments lexer/language name can appear to, e.g.::

        !bc restructuredtext
        =======
        Heading
        =======
        
        Some text.
        !ec

results in::

        =======
        Heading
        =======
        
        Some text.

Finally, '!bc do' supports highlighting of DocOnce source::

        ======= DocOnce test file =======
        
        ===== Computer code =====
        
        Inline verbatim code, as in `import numpy as np`, is allowed, as well as
        code blocks:
        
        !bc pycod
        from math import sin
        
        def f(x):
            """Example on a function."""
            return sin(x) + 1
        
        print(f(0))
        !ec
        
        
        ===== Mathematics =====
        
        Formulas can be inline, as in $\nabla\cdot\bm{u} = 0$, or typeset
        as equations:
        
        !bt
        \begin{align*}
        \nabla\cdot\bm{u} &= 0,\\ 
        \bm{u} &= \nabla\phi .
        \end{align*}
        !et
        
        === Subsubsection heading ===
        
        DocOnce files can have chapters, sections, subsections, and subsubsections.
        
        __Paragraph heading.__ Paragraphs may have headings.

It is time to test 'verbatim inline font' especially with 'a newline
inside the text' and an exclamation mark at the end: 'BEGIN'! For
spellcheck, test 'a verbatim expression' in 'another' in a 'third'.
Also test exclamation mark as in '!bc' and '!ec' as well as 'a != b'.
Also test backslashes and braces like '\begin', '\begin{enumerate}',
'\end{this}\end{that}', and '{something \inside braces}'.

The following attempt to exemplify colored text does not work in
format st.
Here is some red color and an attempt to write with
green color containing a linebreak
code. Some formats will only display 
this correctly when 'html' 
is the output format.
But here some more running text is added which is not part of
the previous blocks with line breaks.

Running OS commands::

        Terminal> python -c 'print("Testing\noutput\nfrom\nPython.")'
        Testing
        output
        from
        Python.

Footnotes

Here is a test of footnotes [^footnote], which are handy in text.
They are used in different flavors, now in

 - list items (note below that footnotes work after math, verbatim, and URLs - bin fact old and emphasize too!)
 - even with math \nabla^2u[^math1]
 - and code 'h[i] += 1'[^code]
   (*must* have space between inline code and footnote!)
 - and "https://google.com":links[^google-search]

which gives flexibility in writing.
This is the third[^example-of-the-third-footnote] example.

  [^footnote]: Typesetting of the footnote depends on the format.
Plain text does nothing, LaTeX removes the
definition and inserts the footnote as part of the LaTeX text.
reStructuredText and Sphinx employ a similar type of typesetting
as Extended Markdown and DocOnce, and in HTML we keep the same
syntax, just displayed properly in HTML.
[^math1]: Math footnotes can be dangerous since it
interferes with an exponent.
[^code]: One-line footnote.

[^google-search]: "google.com":google.com is perhaps the most famous
web site today.

Here is some more text before a new definition of a footnote that was
used above.

*Non-breaking space character.* 
This paragraph aims to test "https://en.wikipedia.org/wiki/Non-breaking_space":non-breaking space character, and a typical
example where this is needed is in physical units: 7.4 km is traveled
in 7.4/5.5\approx 1.345 s.  Also check that a~"https://google.com":link is
not broken across lines (drag the browser window to test this).
(On the other hand, the tilde is used in
computer code, e.g., as in '[~x for x in y]' or in 'y=~x', and should
of course remain a tilde in those contexts.)



Subsection 2: Testing figures

Test of figures. In particular we refer to Figure ref{fig:impact} in which
there is a flow.

FIGURE:[../doc/src/manual/fig/wave1D, width=200] Visualization **of** a *wave*. {fig:impact}

Figures without captions are allowed and will be inlined.

FIGURE:[../doc/src/manual/fig/wave1D, width=200]

Here is figure ref{myfig} with a long (illegal) multi-line caption
containing inline verbatim text:

FIGURE: [../doc/src/manual/fig/wave1D.png, width=500 sidecap=True] A long caption spanning several lines and containing verbatim words like 'my_file_v1' and 'my_file_v2' as well as math with subscript as in t_{i+1}. {myfig} 

Test URL as figure name:

FIGURE: [https://raw.github.com/doconce/doconce/master/doc/src/blog/f_plot.png, width=500 frac=0.8]

*Remark.*
Movies are tested in separate file 'movies.do.txt'.

The \theta parameter (not \nabla?)

Functions do not always need to be advanced, here is one
involving \theta::

        def f(theta):
            return theta**2

*More on \theta.* Here is more text following headline with math.

Newcommands must also be tested in this test report:
\frac{1}{2}, {1/2}, \pmb{x}, \frac{Du}{dt},
both inline and in block::

        \begin{align}
        \frac{Du}{dt} &= 0\nonumber
        \\ 
        \frac{1}{2} &= {1/2}\\ 
        \frac{1}{2}\pmb{x} &= \pmb{n}
        \end{align}

Or with align with label and numbers::

        \begin{align}
        \frac{Du}{dt} &= 0
        label{aligneq1}
        \\ 
        \frac{1}{2} &= {1/2}\\ 
        \frac{1}{2}\pmb{x} &= \pmb{n}
        label{aligneq2}
        \end{align}

First one numbered (automatically)::

        \begin{align}
        \begin{pmatrix}
        G_2 + G_3 & -G_3 & -G_2 & 0 \\ 
        -G_3 & G_3 + G_4 & 0 & -G_4 \\ 
        -G_2 & 0 & G_1 + G_2 & 0 \\ 
        0 & -G_4 & 0 & G_4
        \end{pmatrix}
        &=
        \begin{pmatrix}
         v_1 \\ 
         v_2 \\ 
         v_3 \\ 
         v_4
        \end{pmatrix}
        + \cdots \\ 
        \begin{pmatrix}
         C_5 + C_6 & -C_6 & 0 & 0 \\ 
         -C_6 & C_6 & 0 & 0 \\ 
         0 & 0 & 0 & 0 \\ 
         0 & 0 & 0 & 0
        \end{pmatrix}
          &= \frac{d}{dt}\begin{pmatrix}
         v_1 \\ 
         v_2 \\ 
         v_3 \\ 
         v_4
        \end{pmatrix} +
        \begin{pmatrix}
         0 \\ 
         0 \\ 
         0 \\ 
         -i_0
        \end{pmatrix}
        \nonumber
        \end{align}

Second numbered (automatically)::

        \begin{align}
        \begin{pmatrix}
        G_1 + G_2\\ 
        -G_3 & G_4
        \end{pmatrix}
        &=
        \begin{pmatrix}
         v_1 \\ 
         v_2
        \end{pmatrix}
        + \cdots\nonumber
        \\ 
        \left(\begin{array}{ll}
        y & 2\\ 
        2 & 1
        \end{array}\right)
        \left(\begin{array}{ll}
        0 \\ x
        \end{array}\right)
        &= \begin{pmatrix}
        A \\ B
        \end{pmatrix}
        \end{align}

Both numbered, with label by the user::

        \begin{align}
        \begin{pmatrix}
        G_1 + G_2\\ 
        -G_3 & G_4
        \end{pmatrix}
        &=
        \begin{pmatrix}
         v_1 \\ 
         v_2
        \end{pmatrix}
        + \cdots label{mymatrix:eq1}
        \\ 
        label{mymatrix:eq2}
        \left(\begin{array}{ll}
        y & 2\\ 
        2 & 1
        \end{array}\right)
        \left(\begin{array}{ll}
        0 \\ x
        \end{array}\right)
        &= \begin{pmatrix}
        A \\ B
        \end{pmatrix}
        \end{align}

Now we refer to Equations (mymatrix:eq1)-(mymatrix:eq2).

Custom Environments

Here is an attempt to create a theorem environment via Mako
(for counting theorems) and comment lines to help replacing lines in
the '.tex' by proper begin-end LaTeX environments for theorems.
Should look nice in most formats!

*Theorem 5.*
Let a=1 and b=2. Then c=3.

*Proof.*
Since c=a+b, the result follows from straightforward addition.
END

As we see, the proof of Theorem 5 is a modest
achievement.

Tables

Let us take this table from the manual:

====  ========  ============  
time  velocity  acceleration  
====  ========  ============  
0.0     1.4186         -5.01  
2.0   1.376512        11.919  
4.0     1.1E+1     14.717624  
====  ========  ============  

The DocOnce source code reads::

        
          |--------------------------------|
          |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    |
          |--------------------------------|
        

Here is yet another table to test that we can handle more than
one table:

====  ========  ============  
time  velocity  acceleration  
====  ========  ============  
0.0   1.4186    -5.01         
1.0   1.376512  11.919        
3.0   1.1E+1    14.717624     
====  ========  ============  

And one with math headings (that are expanded and must be treated
accordingly), verbatim heading and entry, and no space around the pipe
symbol:

=  ======  ========  =======  
i   h_i    \bar T_i   'L_i'   
=  ======  ========  =======  
0       0       288  -0.0065  
1  11,000       216      0.0  
2  20,000       216    0.001  
3  32,000       228   0.0028  
4  47,000       270      0.0  
5  51,000       270  -0.0028  
6  71,000       214    'NaN'  
=  ======  ========  =======  

And add one with verbatim headings (with underscores),
and rows starting with '|-' because of a negative number,
and '|' right before and after verbatim word (with no space):

=====  ======  ===========  =========  
exact  'v_1'   a_i + 'v_2'  'verb_3_'  
=====  ======  ===========  =========  
    9    9.62         5.57       8.98  
  -20  -23.39        -7.65     -19.93  
   10   17.74        -4.50       9.96  
    0   -9.19         4.13      -0.26  
=====  ======  ===========  =========  

Pipe symbols in verbatim and math text in tables used to pose difficulties,
but not
anymore:

===========  =======  =======  
     S       command  
===========  =======  =======  
$ ||a_0|| $    'norm  
x\cap y           'x  
===========  =======  =======  

Here is a table with X alignment:

=====  ======================================================================================================================================================================================================================  
 Type                                                                                                       Description                                                                                                        
=====  ======================================================================================================================================================================================================================  
  X    Alignment character that is used for specifying a potentially very long text in a column in a table. It makes use of the 'tabularx' package in LaTeX, otherwise (for other formats) it means 'l' (centered alignment).  
l,r,c  standard alignment characters                                                                                                                                                                                           
=====  ======================================================================================================================================================================================================================  

Finally, a table with math
and URLs.

====================  ======================================================  ======================================================  
                                                                                                                                      
====================  ======================================================  ======================================================  
   \mathcal{L}=0      ../doc/src/manual/mov/wave_frames/frame_0080.png:'080'  ../doc/src/manual/mov/wave_frames/frame_0085.png:'085'  
        a=b           ../doc/src/manual/mov/wave_frames/frame_0090.png:'090'  ../doc/src/manual/mov/wave_frames/frame_0095.png:'095'  
\nabla\cdot\bm{u} =0  ../doc/src/manual/mov/wave_frames/frame_0100.png:'100'  ../doc/src/manual/mov/wave_frames/frame_0105.png:'105'  
====================  ======================================================  ======================================================  

A test of verbatim words in heading with subscript a_i: 'my_file_v1' and 'my_file_v2'

*Paragraph with verbatim and math: 'my_file_v1.py' and 'my_file_v2.py' define some math a_{i-1}.* Here is more '__verbatim__' code and
some plain text on a new line.

**Just bold**

Some text.

*Just emphasize*

Some text.

'Just verbatim'

Some text.

**Bold** beginning

Some text.

*Emphasize* beginning

Some text.

'Verbatim' beginning

Some text.

Maybe **bold end**

Some text.

Maybe *emphasize end*

Some text.

Maybe 'verbatim end'

Some text.

The middle has **bold** word

Some text.

The middle has *emphasize* word

Some text.

The middle has 'verbatim' word

Some text.

**Just emphasize*.* Some text.

*'Just verbatim'.* Some text.

**Emphasize* beginning.* Some text.

*'Verbatim beginning'.* Some text.

*Maybe *emphasize end*.* Some text.

*Maybe 'verbatim end'.* Some text.

*The middle has *emphasize* word.* Some text.

*The middle has 'verbatim' word.* Some text.

*Ampersand.*
We can test Hennes & Mauritz, often abbreviated H&M, but written
as 'Hennes & Mauritz' and 'H & M'.
A sole '&' must also work::

        # Just to check that ampersand works in code blocks:
        c = a & b

*Quotes.*
Let us also add a test of quotes such as "double quotes, with numbers
like 3.14 and newline/comma and hyphen (as in double-quote)"; written
in the standard LaTeX-style that gives correct LaTeX formatting and
ordinary double quotes for all non-LaTeX formats.  Here is another
sentence that "caused" a bug in the past because double backtick
quotes could imply verbatim text up to a verbatim word starting with
period, like '.txt'.

More quotes to be tested for spellcheck:
("with parenthesis"), "with newline"
and "with comma", "hyphen"-wise, and "period".

Bibliography test

Here is an example: [1] discussed propagation of
large destructive water waves, [2] gave
an overview of numerical methods for solving the Navier - Stokes equations,
while the use of Backward Kolmogorov equations for analyzing
random vibrations was investigated in [3].
The book chapter [4] contains information on
C++ software tools for programming multigrid methods. A real retro
reference is [5] about a big FORTRAN package.
Multiple references are also possible, e.g., see
[1] [4].

We need to cite more than 10 papers to reproduce an old formatting
problem with blanks in the keys in reST format:
[6] [3] [7] [1]
and
[2] [8] [9] [10] [11] [12] [13]
and all the work of
[14] [4] [15] as well as
old work [5] and [16], and the
talk [17].
Langtangen also had two thesis [18] [16]
back in the days.
More retro citations are
the old ME-IN323 book [19] and the
[20] OONSKI '94 paper.

# --- begin exercise ---

Example 1: Examples can be typeset as exercises

Examples can start with a subsection heading starting with 'Example:'
and then, with the command-line option '--examples_as_exercises' be
typeset as exercises. This is useful if one has solution
environments as part of the example.

*a)*
State some problem.

*Solution.*
The answer to this subproblem can be written here.

*b)*
State some other problem.

*Hint 1.*
A hint can be given.

*Hint 2.*
Maybe even another hint?

*Solution.*
The answer to this other subproblem goes here,
maybe over multiple doconce input lines.

# --- end exercise ---

User-defined environments

The example in the section "Example 1: A test function" demonstrates how to write a test function.
That is, a special test function for a function 'add' appears in
the example in the section "Example 1: A test function".

Example 1: A test function

Suppose we want to write a test function for checking the
implementation of a Python function for addition::

        def add(a, b):
            return a + b
        
        def test_add():
            a = 1; b = 1
            expected = a + b
            computed = add(a, b)
            assert expected == computed

Example 2: Addition

We have::

        \[ 1 + 1 = 2 \]

or in tabular form:

=======  ======  
Problem  Result  
=======  ======  
  1+1      2     
=======  ======  

*Highlight box!* 
This environment is used to highlight something::

        \[ E = mc^2 \]



URLs

Testing of URLs: hpl's home page "https://folk.uio.no/hpl":hpl, or
the entire URL if desired, "https://folk.uio.no/hpl":https://folk.uio.no/hpl.  Here is a
plain file link "testdoc.do.txt":testdoc.do.txt, or "testdoc.do.txt":testdoc.do.txt, or
"testdoc.do.txt":testdoc.do.txt or "testdoc.do.txt":testdoc.do.txt or "testdoc.do.txt":a link with
newline. Can test spaces with the link with word
too: "https://folk.uio.no/hpl":hpl or "https://folk.uio.no/hpl":hpl. Also 'file:///' works: "file:///home/hpl/vc/doconce/doc/demos/manual/manual.html":link to a
file is
fine to have. Moreover, "loose" URLs work, i.e., no quotes, just
the plain URL as in "https://folk.uio.no/hpl":https://folk.uio.no/hpl, if followed by space, comma,
colon, semi-colon, question mark, exclamation mark, but not a period
(which gets confused with the periods inside the URL).

Mail addresses can also be used: mailto:hpl@simula.no:'hpl@simula.no', or just a "mailto:hpl@simula.no":mail link, or a raw "mailto:hpl@simula.no":mailto:hpl@simula.no.

Here are some tough tests of URLs, especially for the 'latex' format:
"https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas":Newton-Cotes formulas
and a "https://www.springer.com/mathematics/computational+science+%26+engineering/book/978-3-642-23098-1":good book. Need to test
Newton-Cotes with percentage in URL too:
"https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas":https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas
and "https://en.wikipedia.org/wiki/Newton-Cotes#Open_Newton.E2.80.93Cotes_formulae":https://en.wikipedia.org/wiki/Newton-Cotes#Open_Newton.E2.80.93Cotes_formulae which has a shebang.

For the '--device=paper' option it is important to test that URLs with
monospace font link text get a footnote
(unless the '--latex_no_program_footnotelink'
is used), as in this reference to
https://github.com/hplgit/INF5620/tree/gh-pages/src/decay/experiments/decay_mod.py:'decay_mod', https://tinyurl.com/pwyasaa/formulas.ball1.py:'ball1.py',
and https://tinyurl.com/pwyasaa/formulas.ball2.py:'ball2.py'.

More tough tests: repeated URLs whose footnotes when using the
'--device=paper' option must be correct. We have
"https://google.com":google, "https://google.com":google, and
"https://google.com":google, which should result in exactly three
footnotes.

# !split and check if these extra words are included properly in the comment

LaTeX Mathematics

Here is an equation without label using backslash-bracket environment::

        \[ a = b + c \]

or with number and label, as in Equation (my:eq1), using the equation environment::

        \begin{equation}
        {\partial u\over\partial t} = \nabla^2 u label{my:eq1}
        \end{equation}

We can refer to this equation by Equation (my:eq1).

Here is a system without equation numbers, using the align-asterisk environment::

        \begin{align*}
        \pmb{a} &= \pmb{q}\times\pmb{n} \\ 
        b &= \nabla^2 u + \nabla^4 v
        \end{align*}

More mathematical typesetting is demonstrated in the coming exercises.

Below, we have "Problem 2: Flip a Coin" and "Project 4: Compute a Probability",
as well as "Project 5: Explore Distributions of Random Circles" and "Project 11: References to Project ref{demo:ex:2} in a heading works for st", and in
between there we have "Exercise 10: Make references to projects and problems".

Exercises

# --- begin exercise ---

Problem 2: Flip a Coin

*a)*
Make a program that simulates flipping a coin N times.
Print out "tail" or "head" for each flip and
let the program count the number of heads.

# --- begin hint in exercise ---

*Hint 1.*
Use 'r = random.random()' and define head as 'r <= 0.5'.

# --- end hint in exercise ---

# --- begin hint in exercise ---

*Hint 2.*
Draw an integer among \{1,2\} with
'r = random.randint(1,2)' and define head when 'r' is 1.

# --- end hint in exercise ---

# --- begin answer of exercise ---
*Answer.*
If the 'random.random()' function returns a number <1/2, let it be
head, otherwise tail. Repeat this N number of times.
# --- end answer of exercise ---

# --- begin solution of exercise ---
*Solution.*::

        import sys, random
        N = int(sys.argv[1])
        heads = 0
        for i in range(N):
            r = random.random()
            if r <= 0.5:
                heads += 1
        print('Flipping a coin %d times gave %d heads' % (N, heads))

# --- end solution of exercise ---

*b)*
Vectorize the code in a) using boolean indexing.

Vectorized code can be written in many ways.
Sometimes the code is less intuitive, sometimes not.
At least there is not much to find in the section "Section 1".

*c)*
Vectorize the code in a) using 'numpy.sum'.

# --- begin answer of exercise ---
*Answer.*
'np.sum(np.where(r <= 0.5, 1, 0))' or 'np.sum(r <= 0.5)'.
# --- end answer of exercise ---

In this latter subexercise, we have an
example where the code is easy to read.

My remarks

Remarks with such a subsubsection is treated as more text
after the last subexercise. Test a list too:

1. Mark 1.
2. Mark 2.

Filenames: 'flip_coin.py', 'flip_coin.pdf'.

Remarks

These are the exercise remarks, appearing at the very end.

# --- end exercise ---

Not an exercise

Should be possible to stick a normal section in the middle of many
exercises.

# --- begin exercise ---

Exercise 3: Test of plain text exercise

Very short exercise. What is the capital
of Norway?
Filename: 'myexer1'.

# --- end exercise ---

# --- begin exercise ---

Project 4: Compute a Probability

What is the probability of getting a number between 0.5 and 0.6 when
drawing uniformly distributed random numbers from the interval [0,1)?

At the end we have a list because that caused problems in LaTeX
in previous DocOnce versions:

1. item1
2. item2

# --- begin hint in exercise ---

*Hint.*
To answer this question empirically, let a program
draw N such random numbers using Python's standard 'random' module,
count how many of them, M, that fall in the interval (0.5,0.6), and
compute the probability as M/N.

# --- end hint in exercise ---

# --- end exercise ---

# --- begin exercise ---

Project 5: Explore Distributions of Random Circles

The formula for a circle is given by::

        \begin{align}
        x &= x_0 + R\cos 2\pi t,
        label{circle:x}\\ 
        y &= y_0 + R\sin 2\pi t,
        label{circle:y}
        \end{align}

where R is the radius of the circle, (x_0,y_0) is the
center point, and t is a parameter in the unit interval [0,1].
For any t, (x,y) computed from Equations (circle:x)-(circle:y)
is a point on the circle.
The formula can be used to generate 'n' points on a circle::

        import numpy as np
        
        def circle(R, x0, y0, n=501):
            t = np.linspace(0, 1, n)
            x = x0 + R*np.cos(2*np.pi*t)
            y = y0 + R*np.sin(2*np.pi*t)
            return x, y
        
        x, y = circle(2.0, 0, 0)

The goal of this project is to draw N circles with random
center and radius. Plot each circle using the 'circle' function
above.

*a)*
Let R be normally distributed and (x_0,y_0) uniformly distributed.

# --- begin hint in exercise ---

*Hint.*
Use the 'numpy.random' module to draw the
x_0, y_0, and R quantities.

# --- end hint in exercise ---

# --- begin answer of exercise ---
*Answer.*
Here goes the short answer to part a).
# --- end answer of exercise ---

# --- begin solution of exercise ---
*Solution.*
Here goes a full solution to part a).
# --- end solution of exercise ---

*b)*
Let R be uniformly distributed and (x_0,y_0) normally distributed.
Filename: 'norm'.

*c)*
Let R and (x_0,y_0) be normally distributed.

Filename: 'circles'.

Remarks

At the very end of the exercise it may be appropriate to summarize
and give some perspectives.

# --- end exercise ---

# --- begin exercise ---

Exercise 6: Determine some Distance

Intro to this exercise. Questions are in subexercises below.

# --- begin solution of exercise ---
*Solution.*
Here goes a full solution of the whole exercise.
With some math a=b in this solution::

        \[ \hbox{math in solution: } a = b \]

And code 'a=b' in this solution::

        a = b  # code in solution

End of solution is here.

# --- end solution of exercise ---

*a)*
Subexercises are numbered a), b), etc.

# --- begin hint in exercise ---

*Hint 1.*
First hint to subexercise a).
With math a=b in hint::

        \[ a=b. \]

And with code (in plain verbatim) returning x+1 in hint::

        def func(x):
            return x + 1  # with code in hint

# --- end hint in exercise ---

# --- begin hint in exercise ---

*Hint 2.*
Second hint to subexercise a).

Test list in hint:

1. item1
2. item2

# --- end hint in exercise ---
Filename: 'subexer_a.pdf'.

# --- begin answer of exercise ---
*Answer.*
Short answer to subexercise a).
With math in answer: a=b.
# --- end answer of exercise ---

*b)*
Here goes the text for subexercise b).

Some math \cos^2 x + \sin^2 x = 1 written one a single line::

        \[ \cos^2 x + \sin^2 x = 1 \thinspace .\]

# --- begin hint in exercise ---

*Hint.*
A hint for this subexercise.

# --- end hint in exercise ---
Filename: 'subexer_b.pdf'.

# --- begin solution of exercise ---
*Solution.*
Here goes the solution of this subexercise.
# --- end solution of exercise ---

The text here belongs to the main (intro) part of the exercise. Need
closing remarks to have text after subexercises.

Test list in exercise:

1. item1
2. item2

Remarks

Some final closing remarks, e.g., summarizing the main findings
and their implications in other problems can be made. These
remarks will appear at the end of the typeset exercise.

# --- end exercise ---

# --- begin exercise ---

Some exercise without the "Exercise:" prefix

Just some text. And some math saying that e^0=1 on a single line,
to test that math block insertion is correct::

        \[ \exp{(0)} = 1 \]

And a test that the code 'lambda x: x+2' is correctly placed here::

        lambda x: x+2

# --- end exercise ---

# --- begin exercise ---

Exercise 8: Solution of differential equation




Question: Given::

        \[ \frac{dy}{dx} = -y(x),\quad y(0)=1 \]

What is the solution of this equation?

Choice A: y=e^{-y}

Choice B: y=e^{y}

Choice C: 
Code::

        from math import exp
        def f(x):
            return exp(x)

Choice D: The solution cannot be found because there is a derivative in the equation.

Choice E: The equation is meaningless: an equation must be an equation
for x or y, not a function y(x).



# --- end exercise ---

# --- begin exercise ---

Example 9: Just an example

*a)*
What is the capital of Norway?

*Answer.*
Oslo.

# --- end exercise ---

Here goes another section

With some text, before we continue with exercises.

More Exercises

# --- begin exercise ---

Exercise 10: Make references to projects and problems

Pick a statement from "Project 5: Explore Distributions of Random Circles" or "Problem 2: Flip a Coin"
and verify it.

Test list at the end of an exercise without other elements (like subexercise,
hint, etc.):

1. item1
2. item2

Filename: 'verify_formula.py'.

# --- end exercise ---

# --- begin exercise ---

Project 11: References to "Project 4: Compute a Probability" in a heading works for st

Refer to the previous exercise as "Exercise 10: Make references to projects and problems",
the two before that as "Project 4: Compute a Probability" and "Project 5: Explore Distributions of Random Circles",
and this one as "Project 11: References to Project ref{demo:ex:2} in a heading works for st".
Filename: 'selc_composed.pdf'.

# --- end exercise ---

References

 1. **H. P. Langtangen and G. Pedersen**. 
    Propagation of Large Destructive Waves,
    *International Journal of Applied Mechanics and Engineering*,
    7(1),
    pp. 187-204,
    2002.
 2. **H. P. Langtangen, K.-A. Mardal and R. Winther**. 
    Numerical Methods for Incompressible Viscous Flow,
    *Advances in Water Resources*,
    25,
    pp. 1125-1146,
    2002.
 3. **H. P. Langtangen**. 
    Numerical Solution of First Passage Problems in Random Vibrations,
    *SIAM Journal of Scientific and Statistical Computing*,
    15,
    pp. 997-996,
    1994.
 4. **K.-A. Mardal, G. W. Zumbusch and H. P. Langtangen**. 
    Software Tools for Multigrid Methods,
    *Advanced Topics in Computational Partial Differential Equations -- Numerical Methods and Diffpack Programming*,
    edited by **H. P. Langtangen and A. Tveito**,
    Springer,
    2003,
    Edited book,
    "http://some.where.org":http://some.where.org.
 5. **H. P. Langtangen**. 
    The FEMDEQS Program System,
    *Department of Mathematics, University of Oslo*,
    1989,
    "http://www.math.uio.no/old/days/hpl/femdeqs.pdf":http://www.math.uio.no/old/days/hpl/femdeqs.pdf.
 6. **H. P. Langtangen**. 
    Stochastic Breakthrough Time Analysis of an Enhanced Oil Recovery Process,
    *SIAM Journal on Scientific Computing*,
    13,
    pp. 1394-1417,
    1992.
 7. **M. Mortensen, H. P. Langtangen and G. N. Wells**. 
    A FEniCS-Based Programming Framework for Modeling Turbulent Flow by the Reynolds-Averaged Navier-Stokes Equations,
    *Advances in Water Resources*,
    34(9),
    "https://dx.doi.org/10.1016/j.advwatres.2011.02.013":doi: 10.1016/j.advwatres.2011.02.013,
    2011.
 8. **S. Glimsdal, G. Pedersen, K. Atakan, C. B. Harbitz, H. P. Langtangen and F. L\ovholt**. 
    Propagation of the Dec. 26, 2004 Indian Ocean Tsunami: Effects of Dispersion and Source Characteristics,
    *International Journal of Fluid Mechanics Research*,
    33(1),
    pp. 15-43,
    2006.
 9. **S. Rahman, J. Gorman, C. H. W. Barnes, D. A. Williams and H. P. Langtangen**. 
    Numerical Investigation of a Piezoelectric Surface Acoustic Wave Interaction With a One-Dimensional Channel,
    *Physical Review B: Condensed Matter and Materials Physics*,
    74,
    2006,
    035308.
10. **J. B. Haga, H. Osnes and H. P. Langtangen**. 
    On the Causes of Pressure Oscillations in Low-Permeable and Low-Compressible Porous Media,
    *International Journal of Analytical and Numerical Methods in Geomechanics*,
    "https://dx.doi.org/10.1002/nag.1062":doi: 10.1002/nag.1062,
    2011,
    "http://onlinelibrary.wiley.com/doi/10.1002/nag.1062/abstract":http://onlinelibrary.wiley.com/doi/10.1002/nag.1062/abstract.
11. **H. P. Langtangen**. 
    *Computational Partial Differential Equations - Numerical Methods and Diffpack Programming*,
    second edition,
    *Texts in Computational Science and Engineering*,
    Springer,
    2003.
12. **H. P. Langtangen**. 
    *Python Scripting for Computational Science*,
    third edition,
    *Texts in Computational Science and Engineering*,
    Springer,
    2008.
13. **H. P. Langtangen and G. Pedersen**. 
    Finite Elements for the Boussinesq Wave Equations,
    Waves and Non-linear Processes in Hydrodynamics,
    edited by **J. Grue, B. Gjevik and J. E. Weber**,
    Kluwer Academic Publishers,
    pp. pp. 117-126,
    1995,
    "http://www.amazon.ca/Waves-Nonlinear-Processes-Hydrodynamics-John/dp/0792340310":http://www.amazon.ca/Waves-Nonlinear-Processes-Hydrodynamics-John/dp/0792340310.
14. **H. P. Langtangen**. 
    *A Primer on Scientific Programming With Python*,
    third edition,
    *Texts in Computational Science and Engineering*,
    Springer,
    2012.
15. **P. V. Jeberg, H. P. Langtangen and C. B. Terp**. 
    Optimization With Diffpack: Practical Example From Welding,
    *Simula Research Laboratory*,
    2004,
    Internal report.
16. **H. P. Langtangen**. 
    Computational Methods for Two-Phase Flow in Oil Reservoirs,
    Ph.D. Thesis,
    Mechanics Division, Department of Mathematics, University of Oslo,
    1989,
    Dr. Scient. thesis..
17. **H. P. Langtangen**. 
    Computational Modeling of Huge Tsunamis From Asteroid Impacts,
    2007,
    Invited keynote lecture at the \emphInternational conference on Computational Science 2007 (ICCS'07), Beijing, China.
18. **H. P. Langtangen**. 
    Solution of the Navier-Stokes Equations With the Finite Element Method in Two and Three Dimensions,
    M.Sc. Thesis,
    Mechanics Division, Department of Mathematics, University of Oslo,
    1985,
    Cand.Scient. thesis.
19. **H. P. Langtangen and A. Tveito**. 
    Numerical Methods in Continuum Mechanics,
    *Center for Industrial Research*,
    1991,
    Lecture notes for a course (ME-IN 324). 286 pages..
20. **H. P. Langtangen**. 
    Diffpack: Software for Partial Differential Equations,
    *Proceedings of the Second Annual Object-Oriented Numerics Conference (OON-SKI'94), Sunriver, Oregon, USA*,
    edited by **A. Vermeulen**,
    1994.

Appendix: Just for testing; part I

This is the first appendix.

A subsection within an appendix

Some text.

Appendix: Just for testing; part II

This is more stuff for an appendix.

Appendix: Testing identical titles

Without label.

Appendix: Testing identical titles

With label.

Appendix: Testing identical titles

What about inserting a quiz?




Fundamental test: What is the capital of Norway?

Answer 1: Stockholm

Answer 2: London

Answer 3: Oslo

Choice D: Bergen



Appendix: Testing identical titles

Without label.

*Tip.* 
Here is a tip or hint box, typeset as a notice box.



Need a lot of text to surround the summary box.
Version control systems allow you to record the history of files
and share files among several computers and collaborators in a
professional way. File changes on one computer are updated or
merged with changes on another computer. Especially when working
with programs or technical reports it is essential
to have changes documented and to
ensure that every computer and person involved in the project
have the latest updates of the files.
Greg Wilson' excellent "https://software-carpentry.org/2010/07/script-for-introduction-to-version-control/":Script for Introduction to Version Control provides a more detailed motivation why you will benefit greatly
from using version control systems.

*Summary.* 
**Bold remark:** Make some text with this summary.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.



Projects that you want to share among several computers or project
workers are today most conveniently stored at some web site "in the
cloud" and updated through communication with that site. I strongly
recommend you to use such sites for all serious programming and
scientific writing work - and all other important files.

The simplest services for hosting project files are "https://dropbox.com":Dropbox and "https://drive.google.com":Google Drive.
It is very easy to get started with these systems, and they allow you
to share files among laptops and mobile units with as many users as
you want. The systems offer a kind of version control in that the
files are stored frequently (several times per minute), and you can go
back to previous versions for the last 30 days. However, it is
challenging  to find the right version from the past when there are
so many of them.

More seriously, when several people may edit files simultaneously, it
can be difficult detect who did what when, roll back to previous
versions, and to manually merge the edits when these are
incompatible. Then one needs more sophisticated tools than Dropbox or
Google Drive: project hosting services with true version control
systems.  The following text aims at providing you with the minimum
information to started with such systems. Numerous other tutorials
contain more comprehensive material and in-depth explanations of the
concepts and tools.

The idea with project hosting services is that you have the files
associated with a project in the cloud. Many people may share these
files.  Every time you want to work on the project you explicitly
update your version of the files, edit the files as you like, and
synchronize the files with the "master version" at the site where the
project is hosted.  If you at some point need to go back to a
version of the files at some particular point in the past,
this is an easy operation. You can also use tools to see
what various people have done with the files in the various versions.

All these services are very similar. Below we describe how you get
started with Bitbucket, GitHub, and Googlecode. Launchpad works very
similarly to the latter three. All the project hosting services have
excellent introductions available at their web sites, but the recipes
below are much shorter and aim at getting you started as quickly as
possible by concentrating on the most important need-to-know steps.
The Git tutorials we refer to later in this document contain more
detailed information and constitute of course very valuable readings
when you use version control systems every day. The point now is
to get started.

Appendix: Testing inline comments

Projects that you want to share among several computers or project
workers are today most conveniently stored at some web site "in the
cloud" and updated through communication with that
site. [hpl's semi opinion 1: not sure if in the cloud is
understood by
all.] I strongly recommend you to use such sites for all serious
programming and scientific writing work - and all other important
files.

The simplest services for hosting project files is Dropbox. [mp 2: Simply go to "https://dropbox.com":https://dropbox.com and watch the video. It explains
how files, like 'myfile.py', perhaps containing much math, like
\partial u/\partial t, are easily communicated between machines.] It
is very easy to get started with Dropbox, and it allows you to share
files among [hpl 3: laptops and mobile units -> computers, tablets,
and phones].

------

First[add 4: ,] consider a quantity Q. [edit 5: To this end, -> We note that]
Q>0, because [del 6: a] negative [edit 7: quantity is -> quantities
are] [del 8: just] negative. [add 9: This comes as no surprise.]

Let us refer to Figure ref{fig:impact} again.

Test references in a list:

 - "Section 1"
 - "Subsection 1"
 - ref{fig:impact}

Appendix: Testing headings ending with 'verbatim inline'

The point here is to test 1) 'verbatim' code in headings, and 2)
ending a heading with verbatim code as this triggers a special
case in LaTeX.

We also test mdash---used as alternative to hyphen without spaces around,
or in quotes:





The ndash should also be tested - as in the Hanson - Nilson equations
on page 277 - 278.

And finally, what about admons, quotes, and boxes? They are tested
in a separate document: 'admon.do.txt'.

[^example-of-the-third-footnote]: Not much to add here, but the footnote
is at the end with only one newline.
************** File: testdoc.epytext *****************
TITLE: A Document for Testing DocOnce
BY: Hans Petter Langtangen (Center for Biomedical Computing, Simula Research Laboratory, and Department of Informatics, University of Oslo); Kaare Dump (Segfault, Cyberspace); A. Dummy Author; I. S. Overworked and Outburned (Inst1, and Inst2, Somewhere, and Third Inst, Elsewhere, and Fourth Inst); J. Doe
DATE: Jan 32, 2100
Made with DocOnce

# !split

The format of this document is
epytext

I{Abstract.} This is a document with many test constructions for doconce syntax.
It was used heavily for the development and kept for testing
numerous constructions, also special and less common cases.

And exactly for test purposes we have an extra line here, which
is part of the abstract.

Section 1
=========

Here is a nested list:

  - item1
  - item2
  - item3 which continues
    on the next line to test that feature
  - and a sublist
    - with indented subitem1
    - and a subitem2

  - and perhaps an ordered sublist
   a. first item
   b. second item,
      continuing on a new line

I{Here is a list with paragraph heading.}

  - item1
  - item2

Here is a list with subsubsection heading
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  - item1
  - item2





Here are two references. Equation (ref{my:eq1}) is fine. Eq. (ref{my:eq1}) too.
Even Equation (ref{my:eq1}) without the tilde.

Subsection 1
------------

More text, with a reference back to
the section "Section 1" and "Subsection 1", and further to the
the sections "Subsection 1" and "URLs", which
encourages you to do the tasks in "Problem 2: Flip a Coin" and "Exercise 10: Make references to projects and problems".
 "Appendix: Just for testing; part I" and "Appendix: Just for testing; part II" are also nice elements.

Test Section reference at beginning of line and after a sentence
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The section "Subsection 1" is fine.
The section "URLs" too.

Computer code
~~~~~~~~~~~~~

Let's do some copying from files too. First from subroutine up to the very end::

              subroutine test()
              integer i
              real*8 r
              r = 0
              do i = 1, i
                 r = r + i
              end do
              return
        C     END1
        
              program testme
              call test()
              return

and then just the subroutine::

        
              subroutine test()
              integer i
              real*8 r
              r = 0
              do i = 1, i
                 r = r + i
              end do
              return

and finally the complete file with a plain text verbatim environment
(C{envir=ccq})::

        C     a comment
        
              subroutine test()
              integer i
              real*8 r
              r = 0
              do i = 1, i
                 r = r + i
              end do
              return
        C     END1
        
              program testme
              call test()
              return

Testing other code environments. First Python::

        !bc pycod
        def f(x):
            return x+1
        !ec

which gets rendered as::

        def f(x):
            return x+1

Here is a program that is supposed to be interactive via
Python Online Tutorial, but that service is not accessible
for the present format::

        class Line:
            def __init__(self, a, b):
                self.a, self.b = a, b
        
            def __call__(self, x):
                a, b = self.a, self.b
                return a*x + b
        
        line = Line(2, 1)
        y = line(x=3)
        print(y)

Some more Python code (actually specified as a sage cell, but
such cells are not supported by this format)::

        a = 2
        b = 3
        print('a+b:', a + b)
        
        # In a sage cell we can also plot
        from matplotlib.pyplot import *
        from numpy import *
        x = linspace(0, 4*pi, 101)
        y = exp(-0.1*x)*cos(x)
        plot(x, y)
        xlabel('x'); ylabel('y')
        show()

Then Cython (with -h option so it is hidden in html/sphinx)::

        cpdef f(double x):
            return x + 1

Standard Python shell sessions::

        >>> from numpy import linspace, sin
        >>> # Some comment
        >>> x = linspace(0, 2, 11)
        >>> y = sin(x)
        >>> y[0]
        0
        >>> import matplotlib.pyplot as plt
        >>> plt.plot(x, y)

Similar IPython sessions::

            NOTE: A verbatim block has been removed because
                  it causes problems for Epytext.

Here is the interactive session again, but with C{pyshell-t}::

        >>> from numpy import linspace, sin
        >>> # Some comment
        >>> x = linspace(0, 2, 11)
        >>> y = sin(x)
        >>> y[0]
        0
        >>> import matplotlib.pyplot as plt
        >>> plt.plot(x, y)

C++::

        #include <iostream>
        
        int main()
        {
           std::cout << "Sample output" << std::endl;
           return 0
        }

And a little bit of Fortran: :dizzy_face::

        !bc cod
              subroutine midpt(x, length, a, b)
              real*8 a, b, x
              x = (a + b)/2
              length = b - a
              return
              end
        !ec

which then is typeset as::

              subroutine midpt(x, length, a, b)
              real*8 a, b, x
              x = (a + b)/2
              length = b - a
              return
              end

HTML::

        <table>
        <tr><td>Column 1</td><td>Column 2</td></tr>
        <tr><td>0.67526 </td><td>0.92871 </td></tr>
        <!-- comment -->
        </table>

But inline HTML code is also important, like text that starts with
C{<a href="} (which can destroy the following text if not properly
quoted).

Matlab with comments requires special typesetting::

        % Comment on the beginning of the line can be escaped by %%
        if a > b
          % Indented comment needs this trick
          c = a + b
        end

And here is a system call::

        Terminal> mkdir test
        Terminal> cd test
        Terminal> myprog -f
        output1
        output2

Any valid pygments lexer/language name can appear to, e.g.::

        !bc restructuredtext
        =======
        Heading
        =======
        
        Some text.
        !ec

results in::

        =======
        Heading
        =======
        
        Some text.

Finally, C{!bc do} supports highlighting of DocOnce source::

            NOTE: A verbatim block has been removed because
                  it causes problems for Epytext.

It is time to test C{verbatim inline font} especially with C{a newline
inside the text} and an exclamation mark at the end: C{BEGIN}! For
spellcheck, test C{a verbatim expression} in C{another} in a C{third}.
Also test exclamation mark as in C{!bc} and C{!ec} as well as C{a != b}.
Also test backslashes and braces like C{\begin}, C{\begin{enumerate}},
C{\end{this}\end{that}}, and C{{something \inside braces}}.

The following attempt to exemplify colored text does not work in
format epytext.
Here is some red color and an attempt to write with
green color containing a linebreak
code. Some formats will only display 
this correctly when C{html} 
is the output format.
But here some more running text is added which is not part of
the previous blocks with line breaks.

Running OS commands
~~~~~~~~~~~~~~~~~~~

            NOTE: A verbatim block has been removed because
                  it causes problems for Epytext.

Footnotes
~~~~~~~~~

Here is a test of footnotes [^footnote], which are handy in text.
They are used in different flavors, now in

 - list items (note below that footnotes work after math, verbatim, and URLs - bin fact old and emphasize too!)
 - even with math M{\nabla^2u}[^math1]
 - and code C{h[i] += 1}[^code]
   (I{must} have space between inline code and footnote!)
 - and U{links<https://google.com>}[^google-search]

which gives flexibility in writing.
This is the third[^example-of-the-third-footnote] example.

  [^footnote]: Typesetting of the footnote depends on the format.
Plain text does nothing, LaTeX removes the
definition and inserts the footnote as part of the LaTeX text.
reStructuredText and Sphinx employ a similar type of typesetting
as Extended Markdown and DocOnce, and in HTML we keep the same
syntax, just displayed properly in HTML.
[^math1]: Math footnotes can be dangerous since it
interferes with an exponent.
[^code]: One-line footnote.

[^google-search]: U{google.com<google.com>} is perhaps the most famous
web site today.

Here is some more text before a new definition of a footnote that was
used above.

I{Non-breaking space character.} 
This paragraph aims to test U{non-breaking space character<https://en.wikipedia.org/wiki/Non-breaking_space>}, and a typical
example where this is needed is in physical units: 7.4 km is traveled
in M{7.4/5.5\approx 1.345} s.  Also check that a U{link<https://google.com>} is
not broken across lines (drag the browser window to test this).
(On the other hand, the tilde is used in
computer code, e.g., as in C{[~x for x in y]} or in C{y=~x}, and should
of course remain a tilde in those contexts.)



Subsection 2: Testing figures
-----------------------------

Test of figures. In particular we refer to Figure ref{fig:impact} in which
there is a flow.

FIGURE:[../doc/src/manual/fig/wave1D, width=200] Visualization B{of} a I{wave}. {fig:impact}

Figures without captions are allowed and will be inlined.

FIGURE:[../doc/src/manual/fig/wave1D, width=200]

Here is figure ref{myfig} with a long (illegal) multi-line caption
containing inline verbatim text:

FIGURE: [../doc/src/manual/fig/wave1D.png, width=500 sidecap=True] A long caption spanning several lines and containing verbatim words like C{my_file_v1} and C{my_file_v2} as well as math with subscript as in M{t_{i+1}}. {myfig} 

Test URL as figure name:

FIGURE: [https://raw.github.com/doconce/doconce/master/doc/src/blog/f_plot.png, width=500 frac=0.8]

I{Remark.}
Movies are tested in separate file C{movies.do.txt}.

The M{\theta} parameter (not M{\nabla}?)
----------------------------------------

Functions do not always need to be advanced, here is one
involving M{\theta}::

        def f(theta):
            return theta**2

I{More on M{\theta}.} Here is more text following headline with math.

Newcommands must also be tested in this test report:
M{\frac{1}{2}}, M{{1/2}}, M{\pmb{x}}, M{\frac{Du}{dt}},
both inline and in block::

            NOTE: A verbatim block has been removed because
                  it causes problems for Epytext.

Or with align with label and numbers::

        \begin{align}
        \frac{Du}{dt} &= 0
        label{aligneq1}
        \\ 
        \frac{1}{2} &= {1/2}\\ 
        \frac{1}{2}\pmb{x} &= \pmb{n}
        label{aligneq2}
        \end{align}

First one numbered (automatically)::

            NOTE: A verbatim block has been removed because
                  it causes problems for Epytext.

Second numbered (automatically)::

            NOTE: A verbatim block has been removed because
                  it causes problems for Epytext.

Both numbered, with label by the user::

        \begin{align}
        \begin{pmatrix}
        G_1 + G_2\\ 
        -G_3 & G_4
        \end{pmatrix}
        &=
        \begin{pmatrix}
         v_1 \\ 
         v_2
        \end{pmatrix}
        + \cdots label{mymatrix:eq1}
        \\ 
        label{mymatrix:eq2}
        \left(\begin{array}{ll}
        y & 2\\ 
        2 & 1
        \end{array}\right)
        \left(\begin{array}{ll}
        0 \\ x
        \end{array}\right)
        &= \begin{pmatrix}
        A \\ B
        \end{pmatrix}
        \end{align}

Now we refer to Equations (mymatrix:eq1)-(mymatrix:eq2).

Custom Environments
-------------------

Here is an attempt to create a theorem environment via Mako
(for counting theorems) and comment lines to help replacing lines in
the C{.tex} by proper begin-end LaTeX environments for theorems.
Should look nice in most formats!

I{Theorem 5.}
Let M{a=1} and M{b=2}. Then M{c=3}.

I{Proof.}
Since M{c=a+b}, the result follows from straightforward addition.
M{END}

As we see, the proof of Theorem 5 is a modest
achievement.

Tables
------

Let us take this table from the manual:

====  ========  ============  
time  velocity  acceleration  
====  ========  ============  
0.0     1.4186         -5.01  
2.0   1.376512        11.919  
4.0     1.1E+1     14.717624  
====  ========  ============  

The DocOnce source code reads::

        
          |--------------------------------|
          |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    |
          |--------------------------------|
        

Here is yet another table to test that we can handle more than
one table:

====  ========  ============  
time  velocity  acceleration  
====  ========  ============  
0.0   1.4186    -5.01         
1.0   1.376512  11.919        
3.0   1.1E+1    14.717624     
====  ========  ============  

And one with math headings (that are expanded and must be treated
accordingly), verbatim heading and entry, and no space around the pipe
symbol:

====  ======  ===========  =======  
M{i}  M{h_i}  M{\bar T_i}   C{L_i}  
====  ======  ===========  =======  
0          0          288  -0.0065  
1     11,000          216      0.0  
2     20,000          216    0.001  
3     32,000          228   0.0028  
4     47,000          270      0.0  
5     51,000          270  -0.0028  
6     71,000          214   C{NaN}  
====  ======  ===========  =======  

And add one with verbatim headings (with underscores),
and rows starting with C{|-} because of a negative number,
and C{|} right before and after verbatim word (with no space):

=====  ======  ===============  ==========  
exact  C{v_1}  M{a_i} + C{v_2}  C{verb_3_}  
=====  ======  ===============  ==========  
    9    9.62             5.57        8.98  
  -20  -23.39            -7.65      -19.93  
   10   17.74            -4.50        9.96  
    0   -9.19             4.13       -0.26  
=====  ======  ===============  ==========  

Pipe symbols in verbatim and math text in tables used to pose difficulties,
but not
anymore:

===========  ==============  
    M{S}        command      
===========  ==============  
$ ||a_0|| $  C{norm|length}  
M{x\cap y}           C{x|y}  
===========  ==============  

Here is a table with X alignment:

=====  ========================================================================================================================================================================================================================  
 Type                                                                                                        Description                                                                                                         
=====  ========================================================================================================================================================================================================================  
  X    Alignment character that is used for specifying a potentially very long text in a column in a table. It makes use of the C{tabularx} package in LaTeX, otherwise (for other formats) it means C{l} (centered alignment).  
l,r,c  standard alignment characters                                                                                                                                                                                             
=====  ========================================================================================================================================================================================================================  

Finally, a table with math
and URLs.

========================  ===========================================================  ===========================================================  
                                                                                                                                                    
========================  ===========================================================  ===========================================================  
    M{\mathcal{L}=0}      U{C{080}<../doc/src/manual/mov/wave_frames/frame_0080.png>}  U{C{085}<../doc/src/manual/mov/wave_frames/frame_0085.png>}  
         M{a=b}           U{C{090}<../doc/src/manual/mov/wave_frames/frame_0090.png>}  U{C{095}<../doc/src/manual/mov/wave_frames/frame_0095.png>}  
M{\nabla\cdot\bm{u} =0 }  U{C{100}<../doc/src/manual/mov/wave_frames/frame_0100.png>}  U{C{105}<../doc/src/manual/mov/wave_frames/frame_0105.png>}  
========================  ===========================================================  ===========================================================  

A test of verbatim words in heading with subscript M{a_i}: C{my_file_v1} and C{my_file_v2}
------------------------------------------------------------------------------------------

I{Paragraph with verbatim and math: C{my_file_v1.py} and C{my_file_v2.py} define some math M{a_{i-1}}.} Here is more C{__verbatim__} code and
some plain text on a new line.

B{Just bold}
------------

Some text.

I{Just emphasize}
-----------------

Some text.

C{Just verbatim}
----------------

Some text.

B{Bold} beginning
-----------------

Some text.

I{Emphasize} beginning
----------------------

Some text.

C{Verbatim} beginning
---------------------

Some text.

Maybe B{bold end}
-----------------

Some text.

Maybe I{emphasize end}
----------------------

Some text.

Maybe C{verbatim end}
---------------------

Some text.

The middle has B{bold} word
---------------------------

Some text.

The middle has I{emphasize} word
--------------------------------

Some text.

The middle has C{verbatim} word
-------------------------------

Some text.

I{I{Just emphasize}.} Some text.

I{C{Just verbatim}.} Some text.

I{I{Emphasize} beginning.} Some text.

I{C{Verbatim beginning}.} Some text.

I{Maybe I{emphasize end}.} Some text.

I{Maybe C{verbatim end}.} Some text.

I{The middle has I{emphasize} word.} Some text.

I{The middle has C{verbatim} word.} Some text.

I{Ampersand.}
We can test Hennes & Mauritz, often abbreviated H&M, but written
as C{Hennes & Mauritz} and C{H & M}.
A sole C{&} must also work::

        # Just to check that ampersand works in code blocks:
        c = a & b

I{Quotes.}
Let us also add a test of quotes such as "double quotes, with numbers
like 3.14 and newline/comma and hyphen (as in double-quote)"; written
in the standard LaTeX-style that gives correct LaTeX formatting and
ordinary double quotes for all non-LaTeX formats.  Here is another
sentence that "caused" a bug in the past because double backtick
quotes could imply verbatim text up to a verbatim word starting with
period, like C{.txt}.

More quotes to be tested for spellcheck:
("with parenthesis"), "with newline"
and "with comma", "hyphen"-wise, and "period".

Bibliography test
-----------------

Here is an example: [1] discussed propagation of
large destructive water waves, [2] gave
an overview of numerical methods for solving the Navier - Stokes equations,
while the use of Backward Kolmogorov equations for analyzing
random vibrations was investigated in [3].
The book chapter [4] contains information on
C++ software tools for programming multigrid methods. A real retro
reference is [5] about a big FORTRAN package.
Multiple references are also possible, e.g., see
[1] [4].

We need to cite more than 10 papers to reproduce an old formatting
problem with blanks in the keys in reST format:
[6] [3] [7] [1]
and
[2] [8] [9] [10] [11] [12] [13]
and all the work of
[14] [4] [15] as well as
old work [5] and [16], and the
talk [17].
Langtangen also had two thesis [18] [16]
back in the days.
More retro citations are
the old ME-IN323 book [19] and the
[20] OONSKI '94 paper.

# --- begin exercise ---

Example 1: Examples can be typeset as exercises
-----------------------------------------------

Examples can start with a subsection heading starting with C{Example:}
and then, with the command-line option C{--examples_as_exercises} be
typeset as exercises. This is useful if one has solution
environments as part of the example.

I{a)}
State some problem.

I{Solution.}
The answer to this subproblem can be written here.

I{b)}
State some other problem.

I{Hint 1.}
A hint can be given.

I{Hint 2.}
Maybe even another hint?

I{Solution.}
The answer to this other subproblem goes here,
maybe over multiple doconce input lines.

# --- end exercise ---

User-defined environments
-------------------------

The example in the section "Example 1: A test function" demonstrates how to write a test function.
That is, a special test function for a function C{add} appears in
the example in the section "Example 1: A test function".

Example 1: A test function
--------------------------

Suppose we want to write a test function for checking the
implementation of a Python function for addition::

        def add(a, b):
            return a + b
        
        def test_add():
            a = 1; b = 1
            expected = a + b
            computed = add(a, b)
            assert expected == computed

Example 2: Addition
-------------------

We have::

        \[ 1 + 1 = 2 \]

or in tabular form:

=======  ======  
Problem  Result  
=======  ======  
 M{1+1}   M{2}   
=======  ======  

I{Highlight box!} 
This environment is used to highlight something::

        \[ E = mc^2 \]



URLs
----

Testing of URLs: hpl's home page U{hpl<https://folk.uio.no/hpl>}, or
the entire URL if desired, U{https://folk.uio.no/hpl<https://folk.uio.no/hpl>}.  Here is a
plain file link U{testdoc.do.txt<testdoc.do.txt>}, or U{testdoc.do.txt<testdoc.do.txt>}, or
U{testdoc.do.txt<testdoc.do.txt>} or U{testdoc.do.txt<testdoc.do.txt>} or U{a link with
newline<testdoc.do.txt>}. Can test spaces with the link with word
too: U{hpl<https://folk.uio.no/hpl>} or U{hpl<https://folk.uio.no/hpl>}. Also C{file:///} works: U{link to a
file<file:///home/hpl/vc/doconce/doc/demos/manual/manual.html>} is
fine to have. Moreover, "loose" URLs work, i.e., no quotes, just
the plain URL as in U{https://folk.uio.no/hpl<https://folk.uio.no/hpl>}, if followed by space, comma,
colon, semi-colon, question mark, exclamation mark, but not a period
(which gets confused with the periods inside the URL).

Mail addresses can also be used: U{C{hpl@simula.no}<mailto:hpl@simula.no>}, or just a U{mail link<mailto:hpl@simula.no>}, or a raw U{mailto:hpl@simula.no<mailto:hpl@simula.no>}.

Here are some tough tests of URLs, especially for the C{latex} format:
U{Newton-Cotes<https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas>} formulas
and a U{good book<https://www.springer.com/mathematics/computational+science+%26+engineering/book/978-3-642-23098-1>}. Need to test
Newton-Cotes with percentage in URL too:
U{https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas<https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas>}
and U{https://en.wikipedia.org/wiki/Newton-Cotes#Open_Newton.E2.80.93Cotes_formulae<https://en.wikipedia.org/wiki/Newton-Cotes#Open_Newton.E2.80.93Cotes_formulae>} which has a shebang.

For the C{--device=paper} option it is important to test that URLs with
monospace font link text get a footnote
(unless the C{--latex_no_program_footnotelink}
is used), as in this reference to
U{C{decay_mod}<https://github.com/hplgit/INF5620/tree/gh-pages/src/decay/experiments/decay_mod.py>}, U{C{ball1.py}<https://tinyurl.com/pwyasaa/formulas.ball1.py>},
and U{C{ball2.py}<https://tinyurl.com/pwyasaa/formulas.ball2.py>}.

More tough tests: repeated URLs whose footnotes when using the
C{--device=paper} option must be correct. We have
U{google<https://google.com>}, U{google<https://google.com>}, and
U{google<https://google.com>}, which should result in exactly three
footnotes.

# !split and check if these extra words are included properly in the comment

LaTeX Mathematics
=================

Here is an equation without label using backslash-bracket environment::

        \[ a = b + c \]

or with number and label, as in Equation (my:eq1), using the equation environment::

            NOTE: A verbatim block has been removed because
                  it causes problems for Epytext.

We can refer to this equation by Equation (my:eq1).

Here is a system without equation numbers, using the align-asterisk environment::

            NOTE: A verbatim block has been removed because
                  it causes problems for Epytext.

More mathematical typesetting is demonstrated in the coming exercises.

Below, we have "Problem 2: Flip a Coin" and "Project 4: Compute a Probability",
as well as "Project 5: Explore Distributions of Random Circles" and "Project 11: References to Project ref{demo:ex:2} in a heading works for epytext", and in
between there we have "Exercise 10: Make references to projects and problems".

Exercises
=========

# --- begin exercise ---

Problem 2: Flip a Coin
----------------------

I{a)}
Make a program that simulates flipping a coin M{N} times.
Print out "tail" or "head" for each flip and
let the program count the number of heads.

# --- begin hint in exercise ---

I{Hint 1.}
Use C{r = random.random()} and define head as C{r <= 0.5}.

# --- end hint in exercise ---

# --- begin hint in exercise ---

I{Hint 2.}
Draw an integer among M{\{1,2\}} with
C{r = random.randint(1,2)} and define head when C{r} is 1.

# --- end hint in exercise ---

# --- begin answer of exercise ---
I{Answer.}
If the C{random.random()} function returns a number M{<1/2}, let it be
head, otherwise tail. Repeat this M{N} number of times.
# --- end answer of exercise ---

# --- begin solution of exercise ---
I{Solution.}::

        import sys, random
        N = int(sys.argv[1])
        heads = 0
        for i in range(N):
            r = random.random()
            if r <= 0.5:
                heads += 1
        print('Flipping a coin %d times gave %d heads' % (N, heads))

# --- end solution of exercise ---

I{b)}
Vectorize the code in a) using boolean indexing.

Vectorized code can be written in many ways.
Sometimes the code is less intuitive, sometimes not.
At least there is not much to find in the section "Section 1".

I{c)}
Vectorize the code in a) using C{numpy.sum}.

# --- begin answer of exercise ---
I{Answer.}
C{np.sum(np.where(r <= 0.5, 1, 0))} or C{np.sum(r <= 0.5)}.
# --- end answer of exercise ---

In this latter subexercise, we have an
example where the code is easy to read.

My remarks
~~~~~~~~~~

Remarks with such a subsubsection is treated as more text
after the last subexercise. Test a list too:

1. Mark 1.
2. Mark 2.

Filenames: C{flip_coin.py}, C{flip_coin.pdf}.

Remarks
~~~~~~~

These are the exercise remarks, appearing at the very end.

# --- end exercise ---

Not an exercise
---------------

Should be possible to stick a normal section in the middle of many
exercises.

# --- begin exercise ---

Exercise 3: Test of plain text exercise
---------------------------------------

Very short exercise. What is the capital
of Norway?
Filename: C{myexer1}.

# --- end exercise ---

# --- begin exercise ---

Project 4: Compute a Probability
--------------------------------

What is the probability of getting a number between 0.5 and 0.6 when
drawing uniformly distributed random numbers from the interval M{[0,1)}?

At the end we have a list because that caused problems in LaTeX
in previous DocOnce versions:

1. item1
2. item2

# --- begin hint in exercise ---

I{Hint.}
To answer this question empirically, let a program
draw M{N} such random numbers using Python's standard C{random} module,
count how many of them, M{M}, that fall in the interval M{(0.5,0.6)}, and
compute the probability as M{M/N}.

# --- end hint in exercise ---

# --- end exercise ---

# --- begin exercise ---

Project 5: Explore Distributions of Random Circles
--------------------------------------------------

The formula for a circle is given by::

        \begin{align}
        x &= x_0 + R\cos 2\pi t,
        label{circle:x}\\ 
        y &= y_0 + R\sin 2\pi t,
        label{circle:y}
        \end{align}

where M{R} is the radius of the circle, M{(x_0,y_0)} is the
center point, and M{t} is a parameter in the unit interval M{[0,1]}.
For any M{t}, M{(x,y)} computed from Equations (circle:x)-(circle:y)
is a point on the circle.
The formula can be used to generate C{n} points on a circle::

        import numpy as np
        
        def circle(R, x0, y0, n=501):
            t = np.linspace(0, 1, n)
            x = x0 + R*np.cos(2*np.pi*t)
            y = y0 + R*np.sin(2*np.pi*t)
            return x, y
        
        x, y = circle(2.0, 0, 0)

The goal of this project is to draw M{N} circles with random
center and radius. Plot each circle using the C{circle} function
above.

I{a)}
Let M{R} be normally distributed and M{(x_0,y_0)} uniformly distributed.

# --- begin hint in exercise ---

I{Hint.}
Use the C{numpy.random} module to draw the
M{x_0}, M{y_0}, and M{R} quantities.

# --- end hint in exercise ---

# --- begin answer of exercise ---
I{Answer.}
Here goes the short answer to part a).
# --- end answer of exercise ---

# --- begin solution of exercise ---
I{Solution.}
Here goes a full solution to part a).
# --- end solution of exercise ---

I{b)}
Let M{R} be uniformly distributed and M{(x_0,y_0)} normally distributed.
Filename: C{norm}.

I{c)}
Let M{R} and M{(x_0,y_0)} be normally distributed.

Filename: C{circles}.

Remarks
~~~~~~~

At the very end of the exercise it may be appropriate to summarize
and give some perspectives.

# --- end exercise ---

# --- begin exercise ---

Exercise 6: Determine some Distance
-----------------------------------

Intro to this exercise. Questions are in subexercises below.

# --- begin solution of exercise ---
I{Solution.}
Here goes a full solution of the whole exercise.
With some math M{a=b} in this solution::

        \[ \hbox{math in solution: } a = b \]

And code C{a=b} in this solution::

        a = b  # code in solution

End of solution is here.

# --- end solution of exercise ---

I{a)}
Subexercises are numbered a), b), etc.

# --- begin hint in exercise ---

I{Hint 1.}
First hint to subexercise a).
With math M{a=b} in hint::

        \[ a=b. \]

And with code (in plain verbatim) returning M{x+1} in hint::

        def func(x):
            return x + 1  # with code in hint

# --- end hint in exercise ---

# --- begin hint in exercise ---

I{Hint 2.}
Second hint to subexercise a).

Test list in hint:

1. item1
2. item2

# --- end hint in exercise ---
Filename: C{subexer_a.pdf}.

# --- begin answer of exercise ---
I{Answer.}
Short answer to subexercise a).
With math in answer: M{a=b}.
# --- end answer of exercise ---

I{b)}
Here goes the text for subexercise b).

Some math M{\cos^2 x + \sin^2 x = 1} written one a single line::

        \[ \cos^2 x + \sin^2 x = 1 \thinspace .\]

# --- begin hint in exercise ---

I{Hint.}
A hint for this subexercise.

# --- end hint in exercise ---
Filename: C{subexer_b.pdf}.

# --- begin solution of exercise ---
I{Solution.}
Here goes the solution of this subexercise.
# --- end solution of exercise ---

The text here belongs to the main (intro) part of the exercise. Need
closing remarks to have text after subexercises.

Test list in exercise:

1. item1
2. item2

Remarks
~~~~~~~

Some final closing remarks, e.g., summarizing the main findings
and their implications in other problems can be made. These
remarks will appear at the end of the typeset exercise.

# --- end exercise ---

# --- begin exercise ---

Some exercise without the "Exercise:" prefix
--------------------------------------------

Just some text. And some math saying that M{e^0=1} on a single line,
to test that math block insertion is correct::

        \[ \exp{(0)} = 1 \]

And a test that the code C{lambda x: x+2} is correctly placed here::

        lambda x: x+2

# --- end exercise ---

# --- begin exercise ---

Exercise 8: Solution of differential equation
---------------------------------------------




Question: Given::

        \[ \frac{dy}{dx} = -y(x),\quad y(0)=1 \]

What is the solution of this equation?

Choice A: M{y=e^{-y}}

Choice B: M{y=e^{y}}

Choice C: 
Code::

        from math import exp
        def f(x):
            return exp(x)

Choice D: The solution cannot be found because there is a derivative in the equation.

Choice E: The equation is meaningless: an equation must be an equation
for M{x} or M{y}, not a function M{y(x)}.



# --- end exercise ---

# --- begin exercise ---

Example 9: Just an example
--------------------------

I{a)}
What is the capital of Norway?

I{Answer.}
Oslo.

# --- end exercise ---

Here goes another section
=========================

With some text, before we continue with exercises.

More Exercises
==============

# --- begin exercise ---

Exercise 10: Make references to projects and problems
-----------------------------------------------------

Pick a statement from "Project 5: Explore Distributions of Random Circles" or "Problem 2: Flip a Coin"
and verify it.

Test list at the end of an exercise without other elements (like subexercise,
hint, etc.):

1. item1
2. item2

Filename: C{verify_formula.py}.

# --- end exercise ---

# --- begin exercise ---

Project 11: References to "Project 4: Compute a Probability" in a heading works for epytext
-------------------------------------------------------------------------------------------

Refer to the previous exercise as "Exercise 10: Make references to projects and problems",
the two before that as "Project 4: Compute a Probability" and "Project 5: Explore Distributions of Random Circles",
and this one as "Project 11: References to Project ref{demo:ex:2} in a heading works for epytext".
Filename: C{selc_composed.pdf}.

# --- end exercise ---

References
==========

 1. B{H. P. Langtangen and G. Pedersen}. 
    Propagation of Large Destructive Waves,
    I{International Journal of Applied Mechanics and Engineering},
    7(1),
    pp. 187-204,
    2002.
 2. B{H. P. Langtangen, K.-A. Mardal and R. Winther}. 
    Numerical Methods for Incompressible Viscous Flow,
    I{Advances in Water Resources},
    25,
    pp. 1125-1146,
    2002.
 3. B{H. P. Langtangen}. 
    Numerical Solution of First Passage Problems in Random Vibrations,
    I{SIAM Journal of Scientific and Statistical Computing},
    15,
    pp. 997-996,
    1994.
 4. B{K.-A. Mardal, G. W. Zumbusch and H. P. Langtangen}. 
    Software Tools for Multigrid Methods,
    I{Advanced Topics in Computational Partial Differential Equations -- Numerical Methods and Diffpack Programming},
    edited by B{H. P. Langtangen and A. Tveito},
    Springer,
    2003,
    Edited book,
    U{http://some.where.org<http://some.where.org>}.
 5. B{H. P. Langtangen}. 
    The FEMDEQS Program System,
    I{Department of Mathematics, University of Oslo},
    1989,
    U{http://www.math.uio.no/old/days/hpl/femdeqs.pdf<http://www.math.uio.no/old/days/hpl/femdeqs.pdf>}.
 6. B{H. P. Langtangen}. 
    Stochastic Breakthrough Time Analysis of an Enhanced Oil Recovery Process,
    I{SIAM Journal on Scientific Computing},
    13,
    pp. 1394-1417,
    1992.
 7. B{M. Mortensen, H. P. Langtangen and G. N. Wells}. 
    A FEniCS-Based Programming Framework for Modeling Turbulent Flow by the Reynolds-Averaged Navier-Stokes Equations,
    I{Advances in Water Resources},
    34(9),
    U{doi: 10.1016/j.advwatres.2011.02.013<https://dx.doi.org/10.1016/j.advwatres.2011.02.013>},
    2011.
 8. B{S. Glimsdal, G. Pedersen, K. Atakan, C. B. Harbitz, H. P. Langtangen and F. L\ovholt}. 
    Propagation of the Dec. 26, 2004 Indian Ocean Tsunami: Effects of Dispersion and Source Characteristics,
    I{International Journal of Fluid Mechanics Research},
    33(1),
    pp. 15-43,
    2006.
 9. B{S. Rahman, J. Gorman, C. H. W. Barnes, D. A. Williams and H. P. Langtangen}. 
    Numerical Investigation of a Piezoelectric Surface Acoustic Wave Interaction With a One-Dimensional Channel,
    I{Physical Review B: Condensed Matter and Materials Physics},
    74,
    2006,
    035308.
10. B{J. B. Haga, H. Osnes and H. P. Langtangen}. 
    On the Causes of Pressure Oscillations in Low-Permeable and Low-Compressible Porous Media,
    I{International Journal of Analytical and Numerical Methods in Geomechanics},
    U{doi: 10.1002/nag.1062<https://dx.doi.org/10.1002/nag.1062>},
    2011,
    U{http://onlinelibrary.wiley.com/doi/10.1002/nag.1062/abstract<http://onlinelibrary.wiley.com/doi/10.1002/nag.1062/abstract>}.
11. B{H. P. Langtangen}. 
    I{Computational Partial Differential Equations - Numerical Methods and Diffpack Programming},
    second edition,
    I{Texts in Computational Science and Engineering},
    Springer,
    2003.
12. B{H. P. Langtangen}. 
    I{Python Scripting for Computational Science},
    third edition,
    I{Texts in Computational Science and Engineering},
    Springer,
    2008.
13. B{H. P. Langtangen and G. Pedersen}. 
    Finite Elements for the Boussinesq Wave Equations,
    Waves and Non-linear Processes in Hydrodynamics,
    edited by B{J. Grue, B. Gjevik and J. E. Weber},
    Kluwer Academic Publishers,
    pp. pp. 117-126,
    1995,
    U{http://www.amazon.ca/Waves-Nonlinear-Processes-Hydrodynamics-John/dp/0792340310<http://www.amazon.ca/Waves-Nonlinear-Processes-Hydrodynamics-John/dp/0792340310>}.
14. B{H. P. Langtangen}. 
    I{A Primer on Scientific Programming With Python},
    third edition,
    I{Texts in Computational Science and Engineering},
    Springer,
    2012.
15. B{P. V. Jeberg, H. P. Langtangen and C. B. Terp}. 
    Optimization With Diffpack: Practical Example From Welding,
    I{Simula Research Laboratory},
    2004,
    Internal report.
16. B{H. P. Langtangen}. 
    Computational Methods for Two-Phase Flow in Oil Reservoirs,
    Ph.D. Thesis,
    Mechanics Division, Department of Mathematics, University of Oslo,
    1989,
    Dr. Scient. thesis..
17. B{H. P. Langtangen}. 
    Computational Modeling of Huge Tsunamis From Asteroid Impacts,
    2007,
    Invited keynote lecture at the \emphInternational conference on Computational Science 2007 (ICCS'07), Beijing, China.
18. B{H. P. Langtangen}. 
    Solution of the Navier-Stokes Equations With the Finite Element Method in Two and Three Dimensions,
    M.Sc. Thesis,
    Mechanics Division, Department of Mathematics, University of Oslo,
    1985,
    Cand.Scient. thesis.
19. B{H. P. Langtangen and A. Tveito}. 
    Numerical Methods in Continuum Mechanics,
    I{Center for Industrial Research},
    1991,
    Lecture notes for a course (ME-IN 324). 286 pages..
20. B{H. P. Langtangen}. 
    Diffpack: Software for Partial Differential Equations,
    I{Proceedings of the Second Annual Object-Oriented Numerics Conference (OON-SKI'94), Sunriver, Oregon, USA},
    edited by B{A. Vermeulen},
    1994.

Appendix: Just for testing; part I
==================================

This is the first appendix.

A subsection within an appendix
-------------------------------

Some text.

Appendix: Just for testing; part II
===================================

This is more stuff for an appendix.

Appendix: Testing identical titles
----------------------------------

Without label.

Appendix: Testing identical titles
----------------------------------

With label.

Appendix: Testing identical titles
----------------------------------

What about inserting a quiz?




Fundamental test: What is the capital of Norway?

Answer 1: Stockholm

Answer 2: London

Answer 3: Oslo

Choice D: Bergen



Appendix: Testing identical titles
----------------------------------

Without label.

I{Tip.} 
Here is a tip or hint box, typeset as a notice box.



Need a lot of text to surround the summary box.
Version control systems allow you to record the history of files
and share files among several computers and collaborators in a
professional way. File changes on one computer are updated or
merged with changes on another computer. Especially when working
with programs or technical reports it is essential
to have changes documented and to
ensure that every computer and person involved in the project
have the latest updates of the files.
Greg Wilson' excellent U{Script for Introduction to Version Control<https://software-carpentry.org/2010/07/script-for-introduction-to-version-control/>} provides a more detailed motivation why you will benefit greatly
from using version control systems.

I{Summary.} 
B{Bold remark:} Make some text with this summary.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.



Projects that you want to share among several computers or project
workers are today most conveniently stored at some web site "in the
cloud" and updated through communication with that site. I strongly
recommend you to use such sites for all serious programming and
scientific writing work - and all other important files.

The simplest services for hosting project files are U{Dropbox<https://dropbox.com>} and U{Google Drive<https://drive.google.com>}.
It is very easy to get started with these systems, and they allow you
to share files among laptops and mobile units with as many users as
you want. The systems offer a kind of version control in that the
files are stored frequently (several times per minute), and you can go
back to previous versions for the last 30 days. However, it is
challenging  to find the right version from the past when there are
so many of them.

More seriously, when several people may edit files simultaneously, it
can be difficult detect who did what when, roll back to previous
versions, and to manually merge the edits when these are
incompatible. Then one needs more sophisticated tools than Dropbox or
Google Drive: project hosting services with true version control
systems.  The following text aims at providing you with the minimum
information to started with such systems. Numerous other tutorials
contain more comprehensive material and in-depth explanations of the
concepts and tools.

The idea with project hosting services is that you have the files
associated with a project in the cloud. Many people may share these
files.  Every time you want to work on the project you explicitly
update your version of the files, edit the files as you like, and
synchronize the files with the "master version" at the site where the
project is hosted.  If you at some point need to go back to a
version of the files at some particular point in the past,
this is an easy operation. You can also use tools to see
what various people have done with the files in the various versions.

All these services are very similar. Below we describe how you get
started with Bitbucket, GitHub, and Googlecode. Launchpad works very
similarly to the latter three. All the project hosting services have
excellent introductions available at their web sites, but the recipes
below are much shorter and aim at getting you started as quickly as
possible by concentrating on the most important need-to-know steps.
The Git tutorials we refer to later in this document contain more
detailed information and constitute of course very valuable readings
when you use version control systems every day. The point now is
to get started.

Appendix: Testing inline comments
---------------------------------

Projects that you want to share among several computers or project
workers are today most conveniently stored at some web site "in the
cloud" and updated through communication with that
site. [hpl's semi opinion 1: not sure if in the cloud is
understood by
all.] I strongly recommend you to use such sites for all serious
programming and scientific writing work - and all other important
files.

The simplest services for hosting project files is Dropbox. [mp 2: Simply go to U{https://dropbox.com<https://dropbox.com>} and watch the video. It explains
how files, like C{myfile.py}, perhaps containing much math, like
M{\partial u/\partial t}, are easily communicated between machines.] It
is very easy to get started with Dropbox, and it allows you to share
files among [hpl 3: laptops and mobile units -> computers, tablets,
and phones].

------

First[add 4: ,] consider a quantity M{Q}. [edit 5: To this end, -> We note that]
M{Q>0}, because [del 6: a] negative [edit 7: quantity is -> quantities
are] [del 8: just] negative. [add 9: This comes as no surprise.]

Let us refer to Figure ref{fig:impact} again.

Test references in a list:

 - "Section 1"
 - "Subsection 1"
 - ref{fig:impact}

Appendix: Testing headings ending with C{verbatim inline}
---------------------------------------------------------

The point here is to test 1) C{verbatim} code in headings, and 2)
ending a heading with verbatim code as this triggers a special
case in LaTeX.

We also test mdash---used as alternative to hyphen without spaces around,
or in quotes:





The ndash should also be tested - as in the Hanson - Nilson equations
on page 277 - 278.

And finally, what about admons, quotes, and boxes? They are tested
in a separate document: C{admon.do.txt}.

[^example-of-the-third-footnote]: Not much to add here, but the footnote
is at the end with only one newline.
************** File: testdoc.txt *****************
A Document for Testing DocOnce
==============================

Hans Petter Langtangen [1, 2] (hpl@simula.no)
Kaare Dump [3] 
A. Dummy Author  
I. S. Overworked and Outburned [4, 5, 6, 7] 
J. Doe  (j_doe@cyberspace.com)

[1] Center for Biomedical Computing, Simula Research Laboratory
[2] Department of Informatics, University of Oslo
[3] Segfault, Cyberspace
[4] Inst1
[5] Inst2, Somewhere
[6] Third Inst, Elsewhere
[7] Fourth Inst

Date: Jan 32, 2100

Made with DocOnce

Table of contents:

 Section 1 
     Here is a list with subsubsection heading 
   Subsection 1 
     Test Section reference at beginning of line and after a sentence 
     Computer code 
     Running OS commands 
     Footnotes 
   Subsection 2: Testing figures 
   The \theta parameter (not \nabla?) 
   Custom Environments 
   Tables 
   A test of verbatim words in heading with subscript a_i: my_file_v1 and my_file_v2 
   _Just bold_ 
   *Just emphasize* 
   Just verbatim 
   _Bold_ beginning 
   *Emphasize* beginning 
   Verbatim beginning 
   Maybe _bold end_ 
   Maybe *emphasize end* 
   Maybe verbatim end 
   The middle has _bold_ word 
   The middle has *emphasize* word 
   The middle has verbatim word 
   Bibliography test 
   Example 1: Examples can be typeset as exercises 
   User-defined environments 
   Example 1: A test function 
   Example 2: Addition 
   URLs 
 LaTeX Mathematics 
 Exercises 
   Problem 2: Flip a Coin 
     My remarks 
     Remarks 
   Not an exercise 
   Exercise 3: Test of plain text exercise 
   Project 4: Compute a Probability 
   Project 5: Explore Distributions of Random Circles 
     Remarks 
   Exercise 6: Determine some Distance 
     Remarks 
   Some exercise without the "Exercise:" prefix 
   Exercise 8: Solution of differential equation 
   Example 9: Just an example 
 Here goes another section 
 More Exercises 
   Exercise 10: Make references to projects and problems 
   Project 11: References to "Project 4: Compute a Probability" in a heading works for plain 
 References 
 Appendix: Just for testing; part I 
   A subsection within an appendix 
 Appendix: Just for testing; part II 
   Appendix: Testing identical titles 
   Appendix: Testing identical titles 
   Appendix: Testing identical titles 
   Appendix: Testing identical titles 
   Appendix: Testing inline comments 
   Appendix: Testing headings ending with verbatim inline 

# !split

The format of this document is
plain

*Abstract.* This is a document with many test constructions for doconce syntax.
It was used heavily for the development and kept for testing
numerous constructions, also special and less common cases.

And exactly for test purposes we have an extra line here, which
is part of the abstract.

Section 1
=========

Here is a nested list:

  * item1

  * item2

  * item3 which continues
    on the next line to test that feature

  * and a sublist

    * with indented subitem1

    * and a subitem2

  * and perhaps an ordered sublist

   a. first item

   b. second item,
      continuing on a new line

*Here is a list with paragraph heading.*

  * item1

  * item2

Here is a list with subsubsection heading
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  * item1

  * item2

        Here are two lines that make up
        a block quote for testing *emphasized words* and _boldface words_,
        also with hypens:
        *pre*-fix, post-*fix*, _pre_-fix, post-_fix_.


Here are two references. Equation (ref{my:eq1}) is fine. Eq. (ref{my:eq1}) too.
Even Equation (ref{my:eq1}) without the tilde.

Subsection 1
------------

More text, with a reference back to
the section "Section 1" and "Subsection 1", and further to the
the sections "Subsection 1" and "URLs", which
encourages you to do the tasks in "Problem 2: Flip a Coin" and "Exercise 10: Make references to projects and problems".
 "Appendix: Just for testing; part I" and "Appendix: Just for testing; part II" are also nice elements.

Test Section reference at beginning of line and after a sentence
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The section "Subsection 1" is fine.
The section "URLs" too.

Computer code
~~~~~~~~~~~~~

Let's do some copying from files too. First from subroutine up to the very end::

              subroutine test()
              integer i
              real*8 r
              r = 0
              do i = 1, i
                 r = r + i
              end do
              return
        C     END1
        
              program testme
              call test()
              return

and then just the subroutine::

        
              subroutine test()
              integer i
              real*8 r
              r = 0
              do i = 1, i
                 r = r + i
              end do
              return

and finally the complete file with a plain text verbatim environment
(envir=ccq)::

        C     a comment
        
              subroutine test()
              integer i
              real*8 r
              r = 0
              do i = 1, i
                 r = r + i
              end do
              return
        C     END1
        
              program testme
              call test()
              return

Testing other code environments. First Python::

        !bc pycod
        def f(x):
            return x+1
        !ec

which gets rendered as::

        def f(x):
            return x+1

Here is a program that is supposed to be interactive via
Python Online Tutorial, but that service is not accessible
for the present format::

        class Line:
            def __init__(self, a, b):
                self.a, self.b = a, b
        
            def __call__(self, x):
                a, b = self.a, self.b
                return a*x + b
        
        line = Line(2, 1)
        y = line(x=3)
        print(y)

Some more Python code (actually specified as a sage cell, but
such cells are not supported by this format)::

        a = 2
        b = 3
        print('a+b:', a + b)
        
        # In a sage cell we can also plot
        from matplotlib.pyplot import *
        from numpy import *
        x = linspace(0, 4*pi, 101)
        y = exp(-0.1*x)*cos(x)
        plot(x, y)
        xlabel('x'); ylabel('y')
        show()

Then Cython (with -h option so it is hidden in html/sphinx)::

        cpdef f(double x):
            return x + 1

Standard Python shell sessions::

        >>> from numpy import linspace, sin
        >>> # Some comment
        >>> x = linspace(0, 2, 11)
        >>> y = sin(x)
        >>> y[0]
        0
        >>> import matplotlib.pyplot as plt
        >>> plt.plot(x, y)

Similar IPython sessions::

        In [1]: from numpy import linspace, sin
        In [2]: # Some comment
        In [3]: x = linspace(0, 2, 11)
        In [4]: y = sin(x)
        In [5]: y[0]
        Out[5]: 0
        In [6]: import matplotlib.pyplot as plt
        In [7]: plt.plot(x, y)
        In [8]: a='multiple-\nline\noutput'
        In [9]: a
        Out[9]: 'multiple-\nline\noutput'
        In [10]: print(a)
        multiple-
        line
        output

Here is the interactive session again, but with pyshell-t::

        >>> from numpy import linspace, sin
        >>> # Some comment
        >>> x = linspace(0, 2, 11)
        >>> y = sin(x)
        >>> y[0]
        0
        >>> import matplotlib.pyplot as plt
        >>> plt.plot(x, y)

C++::

        #include <iostream>
        
        int main()
        {
           std::cout << "Sample output" << std::endl;
           return 0
        }

And a little bit of Fortran: :dizzy_face::

        !bc cod
              subroutine midpt(x, length, a, b)
              real*8 a, b, x
              x = (a + b)/2
              length = b - a
              return
              end
        !ec

which then is typeset as::

              subroutine midpt(x, length, a, b)
              real*8 a, b, x
              x = (a + b)/2
              length = b - a
              return
              end

HTML::

        <table>
        <tr><td>Column 1</td><td>Column 2</td></tr>
        <tr><td>0.67526 </td><td>0.92871 </td></tr>
        <!-- comment -->
        </table>

But inline HTML code is also important, like text that starts with
<a href=" (which can destroy the following text if not properly
quoted).

Matlab with comments requires special typesetting::

        % Comment on the beginning of the line can be escaped by %%
        if a > b
          % Indented comment needs this trick
          c = a + b
        end

And here is a system call::

        Terminal> mkdir test
        Terminal> cd test
        Terminal> myprog -f
        output1
        output2

Any valid pygments lexer/language name can appear to, e.g.::

        !bc restructuredtext
        =======
        Heading
        =======
        
        Some text.
        !ec

results in::

        =======
        Heading
        =======
        
        Some text.

Finally, !bc do supports highlighting of DocOnce source::

        ======= DocOnce test file =======
        
        ===== Computer code =====
        
        Inline verbatim code, as in `import numpy as np`, is allowed, as well as
        code blocks:
        
        !bc pycod
        from math import sin
        
        def f(x):
            """Example on a function."""
            return sin(x) + 1
        
        print(f(0))
        !ec
        
        
        ===== Mathematics =====
        
        Formulas can be inline, as in $\nabla\cdot\bm{u} = 0$, or typeset
        as equations:
        
        !bt
        \begin{align*}
        \nabla\cdot\bm{u} &= 0,\\ 
        \bm{u} &= \nabla\phi .
        \end{align*}
        !et
        
        === Subsubsection heading ===
        
        DocOnce files can have chapters, sections, subsections, and subsubsections.
        
        __Paragraph heading.__ Paragraphs may have headings.

It is time to test verbatim inline font especially with a newline
inside the text and an exclamation mark at the end: BEGIN! For
spellcheck, test a verbatim expression in another in a third.
Also test exclamation mark as in !bc and !ec as well as a != b.
Also test backslashes and braces like \begin, \begin{enumerate},
\end{this}\end{that}, and {something \inside braces}.

The following attempt to exemplify colored text does not work in
format plain.
Here is some red color and an attempt to write with
green color containing a linebreak
code. Some formats will only display 
this correctly when html 
is the output format.
But here some more running text is added which is not part of
the previous blocks with line breaks.

Running OS commands
~~~~~~~~~~~~~~~~~~~

        Terminal> python -c 'print("Testing\noutput\nfrom\nPython.")'
        Testing
        output
        from
        Python.

Footnotes
~~~~~~~~~

Here is a test of footnotes [^footnote], which are handy in text.
They are used in different flavors, now in

 * list items (note below that footnotes work after math, verbatim, and URLs - bin fact old and emphasize too!)

 * even with math \nabla^2u[^math1]

 * and code h[i] += 1[^code]
   (*must* have space between inline code and footnote!)

 * and links (https://google.com)[^google-search]

which gives flexibility in writing.
This is the third[^example-of-the-third-footnote] example.

  [^footnote]: Typesetting of the footnote depends on the format.
Plain text does nothing, LaTeX removes the
definition and inserts the footnote as part of the LaTeX text.
reStructuredText and Sphinx employ a similar type of typesetting
as Extended Markdown and DocOnce, and in HTML we keep the same
syntax, just displayed properly in HTML.
[^math1]: Math footnotes can be dangerous since it
interferes with an exponent.
[^code]: One-line footnote.

[^google-search]: google.com is perhaps the most famous
web site today.

Here is some more text before a new definition of a footnote that was
used above.


Non-breaking space character ------------------------------------------------------------------------------------------------|
|                                                                                                                            |
| This paragraph aims to test non-breaking space character (https://en.wikipedia.org/wiki/Non-breaking_space), and a typical |
| example where this is needed is in physical units: 7.4 km is traveled                                                      |
| in 7.4/5.5\approx 1.345 s.  Also check that a link (https://google.com) is                                                 |
| not broken across lines (drag the browser window to test this).                                                            |
| (On the other hand, the tilde is used in                                                                                   |
| computer code, e.g., as in [~x for x in y] or in y=~x, and should                                                          |
| of course remain a tilde in those contexts.)                                                                               |
|----------------------------------------------------------------------------------------------------------------------------|


Subsection 2: Testing figures
-----------------------------

Test of figures. In particular we refer to Figure ref{fig:impact} in which
there is a flow.

FIGURE:[../doc/src/manual/fig/wave1D, width=200] Visualization _of_ a *wave*. {fig:impact}

Figures without captions are allowed and will be inlined.

FIGURE:[../doc/src/manual/fig/wave1D, width=200]

Here is figure ref{myfig} with a long (illegal) multi-line caption
containing inline verbatim text:

FIGURE: [../doc/src/manual/fig/wave1D.png, width=500 sidecap=True] A long caption spanning several lines and containing verbatim words like my_file_v1 and my_file_v2 as well as math with subscript as in t_{i+1}. {myfig} 

Test URL as figure name:

FIGURE: [https://raw.github.com/doconce/doconce/master/doc/src/blog/f_plot.png, width=500 frac=0.8]

*Remark.*
Movies are tested in separate file movies.do.txt.

The \theta parameter (not \nabla?)
----------------------------------

Functions do not always need to be advanced, here is one
involving \theta::

        def f(theta):
            return theta**2

*More on \theta.* Here is more text following headline with math.

Newcommands must also be tested in this test report:
\frac{1}{2}, {1/2}, \pmb{x}, \frac{Du}{dt},
both inline and in block::

        \begin{align}
        \frac{Du}{dt} &= 0\nonumber
        \\ 
        \frac{1}{2} &= {1/2}\\ 
        \frac{1}{2}\pmb{x} &= \pmb{n}
        \end{align}

Or with align with label and numbers::

        \begin{align}
        \frac{Du}{dt} &= 0
        label{aligneq1}
        \\ 
        \frac{1}{2} &= {1/2}\\ 
        \frac{1}{2}\pmb{x} &= \pmb{n}
        label{aligneq2}
        \end{align}

First one numbered (automatically)::

        \begin{align}
        \begin{pmatrix}
        G_2 + G_3 & -G_3 & -G_2 & 0 \\ 
        -G_3 & G_3 + G_4 & 0 & -G_4 \\ 
        -G_2 & 0 & G_1 + G_2 & 0 \\ 
        0 & -G_4 & 0 & G_4
        \end{pmatrix}
        &=
        \begin{pmatrix}
         v_1 \\ 
         v_2 \\ 
         v_3 \\ 
         v_4
        \end{pmatrix}
        + \cdots \\ 
        \begin{pmatrix}
         C_5 + C_6 & -C_6 & 0 & 0 \\ 
         -C_6 & C_6 & 0 & 0 \\ 
         0 & 0 & 0 & 0 \\ 
         0 & 0 & 0 & 0
        \end{pmatrix}
          &= \frac{d}{dt}\begin{pmatrix}
         v_1 \\ 
         v_2 \\ 
         v_3 \\ 
         v_4
        \end{pmatrix} +
        \begin{pmatrix}
         0 \\ 
         0 \\ 
         0 \\ 
         -i_0
        \end{pmatrix}
        \nonumber
        \end{align}

Second numbered (automatically)::

        \begin{align}
        \begin{pmatrix}
        G_1 + G_2\\ 
        -G_3 & G_4
        \end{pmatrix}
        &=
        \begin{pmatrix}
         v_1 \\ 
         v_2
        \end{pmatrix}
        + \cdots\nonumber
        \\ 
        \left(\begin{array}{ll}
        y & 2\\ 
        2 & 1
        \end{array}\right)
        \left(\begin{array}{ll}
        0 \\ x
        \end{array}\right)
        &= \begin{pmatrix}
        A \\ B
        \end{pmatrix}
        \end{align}

Both numbered, with label by the user::

        \begin{align}
        \begin{pmatrix}
        G_1 + G_2\\ 
        -G_3 & G_4
        \end{pmatrix}
        &=
        \begin{pmatrix}
         v_1 \\ 
         v_2
        \end{pmatrix}
        + \cdots label{mymatrix:eq1}
        \\ 
        label{mymatrix:eq2}
        \left(\begin{array}{ll}
        y & 2\\ 
        2 & 1
        \end{array}\right)
        \left(\begin{array}{ll}
        0 \\ x
        \end{array}\right)
        &= \begin{pmatrix}
        A \\ B
        \end{pmatrix}
        \end{align}

Now we refer to Equations (mymatrix:eq1)-(mymatrix:eq2).

Custom Environments
-------------------

Here is an attempt to create a theorem environment via Mako
(for counting theorems) and comment lines to help replacing lines in
the .tex by proper begin-end LaTeX environments for theorems.
Should look nice in most formats!

*Theorem 5.*
Let a=1 and b=2. Then c=3.

*Proof.*
Since c=a+b, the result follows from straightforward addition.
END

As we see, the proof of Theorem 5 is a modest
achievement.

Tables
------

Let us take this table from the manual:

====  ========  ============  
time  velocity  acceleration  
====  ========  ============  
0.0     1.4186         -5.01  
2.0   1.376512        11.919  
4.0     1.1E+1     14.717624  
====  ========  ============  

The DocOnce source code reads::

        
          |--------------------------------|
          |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    |
          |--------------------------------|
        

Here is yet another table to test that we can handle more than
one table:

====  ========  ============  
time  velocity  acceleration  
====  ========  ============  
0.0   1.4186    -5.01         
1.0   1.376512  11.919        
3.0   1.1E+1    14.717624     
====  ========  ============  

And one with math headings (that are expanded and must be treated
accordingly), verbatim heading and entry, and no space around the pipe
symbol:

=  ======  ========  =======  
i   h_i    \bar T_i    L_i    
=  ======  ========  =======  
0       0       288  -0.0065  
1  11,000       216      0.0  
2  20,000       216    0.001  
3  32,000       228   0.0028  
4  47,000       270      0.0  
5  51,000       270  -0.0028  
6  71,000       214      NaN  
=  ======  ========  =======  

And add one with verbatim headings (with underscores),
and rows starting with |- because of a negative number,
and | right before and after verbatim word (with no space):

=====  ======  =========  =======  
exact   v_1    a_i + v_2  verb_3_  
=====  ======  =========  =======  
    9    9.62       5.57     8.98  
  -20  -23.39      -7.65   -19.93  
   10   17.74      -4.50     9.96  
    0   -9.19       4.13    -0.26  
=====  ======  =========  =======  

Pipe symbols in verbatim and math text in tables used to pose difficulties,
but not
anymore (except for plain text and matlabnb).

Here is a table with X alignment:

=====  ==================================================================================================================================================================================================================  
 Type                                                                                                     Description                                                                                                      
=====  ==================================================================================================================================================================================================================  
  X    Alignment character that is used for specifying a potentially very long text in a column in a table. It makes use of the tabularx package in LaTeX, otherwise (for other formats) it means l (centered alignment).  
l,r,c  standard alignment characters                                                                                                                                                                                       
=====  ==================================================================================================================================================================================================================  

Finally, a table with math
and URLs.

====================  ======================================================  ======================================================  
                                                                                                                                      
====================  ======================================================  ======================================================  
   \mathcal{L}=0      080 (../doc/src/manual/mov/wave_frames/frame_0080.png)  085 (../doc/src/manual/mov/wave_frames/frame_0085.png)  
        a=b           090 (../doc/src/manual/mov/wave_frames/frame_0090.png)  095 (../doc/src/manual/mov/wave_frames/frame_0095.png)  
\nabla\cdot\bm{u} =0  100 (../doc/src/manual/mov/wave_frames/frame_0100.png)  105 (../doc/src/manual/mov/wave_frames/frame_0105.png)  
====================  ======================================================  ======================================================  

A test of verbatim words in heading with subscript a_i: my_file_v1 and my_file_v2
---------------------------------------------------------------------------------

*Paragraph with verbatim and math: my_file_v1.py and my_file_v2.py define some math a_{i-1}.* Here is more __verbatim__ code and
some plain text on a new line.

_Just bold_
-----------

Some text.

*Just emphasize*
----------------

Some text.

Just verbatim
-------------

Some text.

_Bold_ beginning
----------------

Some text.

*Emphasize* beginning
---------------------

Some text.

Verbatim beginning
------------------

Some text.

Maybe _bold end_
----------------

Some text.

Maybe *emphasize end*
---------------------

Some text.

Maybe verbatim end
------------------

Some text.

The middle has _bold_ word
--------------------------

Some text.

The middle has *emphasize* word
-------------------------------

Some text.

The middle has verbatim word
----------------------------

Some text.

**Just emphasize*.* Some text.

*Just verbatim.* Some text.

**Emphasize* beginning.* Some text.

*Verbatim beginning.* Some text.

*Maybe *emphasize end*.* Some text.

*Maybe verbatim end.* Some text.

*The middle has *emphasize* word.* Some text.

*The middle has verbatim word.* Some text.

*Ampersand.*
We can test Hennes & Mauritz, often abbreviated H&M, but written
as Hennes & Mauritz and H & M.
A sole & must also work::

        # Just to check that ampersand works in code blocks:
        c = a & b

*Quotes.*
Let us also add a test of quotes such as "double quotes, with numbers
like 3.14 and newline/comma and hyphen (as in double-quote)"; written
in the standard LaTeX-style that gives correct LaTeX formatting and
ordinary double quotes for all non-LaTeX formats.  Here is another
sentence that "caused" a bug in the past because double backtick
quotes could imply verbatim text up to a verbatim word starting with
period, like .txt.

More quotes to be tested for spellcheck:
("with parenthesis"), "with newline"
and "with comma", "hyphen"-wise, and "period".

Bibliography test
-----------------

Here is an example: [1] discussed propagation of
large destructive water waves, [2] gave
an overview of numerical methods for solving the Navier - Stokes equations,
while the use of Backward Kolmogorov equations for analyzing
random vibrations was investigated in [3].
The book chapter [4] contains information on
C++ software tools for programming multigrid methods. A real retro
reference is [5] about a big FORTRAN package.
Multiple references are also possible, e.g., see
[1] [4].

We need to cite more than 10 papers to reproduce an old formatting
problem with blanks in the keys in reST format:
[6] [3] [7] [1]
and
[2] [8] [9] [10] [11] [12] [13]
and all the work of
[14] [4] [15] as well as
old work [5] and [16], and the
talk [17].
Langtangen also had two thesis [18] [16]
back in the days.
More retro citations are
the old ME-IN323 book [19] and the
[20] OONSKI '94 paper.

# --- begin exercise ---

Example 1: Examples can be typeset as exercises
-----------------------------------------------

Examples can start with a subsection heading starting with Example:
and then, with the command-line option --examples_as_exercises be
typeset as exercises. This is useful if one has solution
environments as part of the example.

*a)*
State some problem.

*Solution.*
The answer to this subproblem can be written here.

*b)*
State some other problem.

*Hint 1.*
A hint can be given.

*Hint 2.*
Maybe even another hint?

*Solution.*
The answer to this other subproblem goes here,
maybe over multiple doconce input lines.

# --- end exercise ---

User-defined environments
-------------------------

The example in the section "Example 1: A test function" demonstrates how to write a test function.
That is, a special test function for a function add appears in
the example in the section "Example 1: A test function".

Example 1: A test function
--------------------------

Suppose we want to write a test function for checking the
implementation of a Python function for addition::

        def add(a, b):
            return a + b
        
        def test_add():
            a = 1; b = 1
            expected = a + b
            computed = add(a, b)
            assert expected == computed

Example 2: Addition
-------------------

We have::

        \[ 1 + 1 = 2 \]

or in tabular form:

=======  ======  
Problem  Result  
=======  ======  
  1+1      2     
=======  ======  


Highlight box! -------------------------------------|
|                                                   |
| This environment is used to highlight something:: |
|                                                   |
|         \[ E = mc^2 \]                            |
|---------------------------------------------------|


URLs
----

Testing of URLs: hpl's home page hpl (https://folk.uio.no/hpl), or
the entire URL if desired, https://folk.uio.no/hpl.  Here is a
plain file link testdoc.do.txt, or testdoc.do.txt, or
testdoc.do.txt or testdoc.do.txt or a link with
newline (testdoc.do.txt). Can test spaces with the link with word
too: hpl (https://folk.uio.no/hpl) or hpl (https://folk.uio.no/hpl). Also file:/// works: link to a
file (file:///home/hpl/vc/doconce/doc/demos/manual/manual.html) is
fine to have. Moreover, "loose" URLs work, i.e., no quotes, just
the plain URL as in https://folk.uio.no/hpl, if followed by space, comma,
colon, semi-colon, question mark, exclamation mark, but not a period
(which gets confused with the periods inside the URL).

Mail addresses can also be used: hpl@simula.no (mailto:hpl@simula.no), or just a mail link (mailto:hpl@simula.no), or a raw mailto:hpl@simula.no.

Here are some tough tests of URLs, especially for the latex format:
Newton-Cotes (https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas) formulas
and a good book (https://www.springer.com/mathematics/computational+science+%26+engineering/book/978-3-642-23098-1). Need to test
Newton-Cotes with percentage in URL too:
https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas
and https://en.wikipedia.org/wiki/Newton-Cotes#Open_Newton.E2.80.93Cotes_formulae which has a shebang.

For the --device=paper option it is important to test that URLs with
monospace font link text get a footnote
(unless the --latex_no_program_footnotelink
is used), as in this reference to
decay_mod (https://github.com/hplgit/INF5620/tree/gh-pages/src/decay/experiments/decay_mod.py), ball1.py (https://tinyurl.com/pwyasaa/formulas.ball1.py),
and ball2.py (https://tinyurl.com/pwyasaa/formulas.ball2.py).

More tough tests: repeated URLs whose footnotes when using the
--device=paper option must be correct. We have
google (https://google.com), google (https://google.com), and
google (https://google.com), which should result in exactly three
footnotes.

# !split and check if these extra words are included properly in the comment

LaTeX Mathematics
=================

Here is an equation without label using backslash-bracket environment::

        \[ a = b + c \]

or with number and label, as in Equation (my:eq1), using the equation environment::

        \begin{equation}
        {\partial u\over\partial t} = \nabla^2 u label{my:eq1}
        \end{equation}

We can refer to this equation by Equation (my:eq1).

Here is a system without equation numbers, using the align-asterisk environment::

        \begin{align*}
        \pmb{a} &= \pmb{q}\times\pmb{n} \\ 
        b &= \nabla^2 u + \nabla^4 v
        \end{align*}

More mathematical typesetting is demonstrated in the coming exercises.

Below, we have "Problem 2: Flip a Coin" and "Project 4: Compute a Probability",
as well as "Project 5: Explore Distributions of Random Circles" and "Project 11: References to Project ref{demo:ex:2} in a heading works for plain", and in
between there we have "Exercise 10: Make references to projects and problems".

Exercises
=========

# --- begin exercise ---

Problem 2: Flip a Coin
----------------------

*a)*
Make a program that simulates flipping a coin N times.
Print out "tail" or "head" for each flip and
let the program count the number of heads.

# --- begin hint in exercise ---

*Hint 1.*
Use r = random.random() and define head as r <= 0.5.

# --- end hint in exercise ---

# --- begin hint in exercise ---

*Hint 2.*
Draw an integer among \{1,2\} with
r = random.randint(1,2) and define head when r is 1.

# --- end hint in exercise ---

# --- begin answer of exercise ---
*Answer.*
If the random.random() function returns a number <1/2, let it be
head, otherwise tail. Repeat this N number of times.
# --- end answer of exercise ---

# --- begin solution of exercise ---
*Solution.*::

        import sys, random
        N = int(sys.argv[1])
        heads = 0
        for i in range(N):
            r = random.random()
            if r <= 0.5:
                heads += 1
        print('Flipping a coin %d times gave %d heads' % (N, heads))

# --- end solution of exercise ---

*b)*
Vectorize the code in a) using boolean indexing.

Vectorized code can be written in many ways.
Sometimes the code is less intuitive, sometimes not.
At least there is not much to find in the section "Section 1".

*c)*
Vectorize the code in a) using numpy.sum.

# --- begin answer of exercise ---
*Answer.*
np.sum(np.where(r <= 0.5, 1, 0)) or np.sum(r <= 0.5).
# --- end answer of exercise ---

In this latter subexercise, we have an
example where the code is easy to read.

My remarks
~~~~~~~~~~

Remarks with such a subsubsection is treated as more text
after the last subexercise. Test a list too:

1. Mark 1.

2. Mark 2.

Filenames: flip_coin.py, flip_coin.pdf.

Remarks
~~~~~~~

These are the exercise remarks, appearing at the very end.

# --- end exercise ---

Not an exercise
---------------

Should be possible to stick a normal section in the middle of many
exercises.

# --- begin exercise ---

Exercise 3: Test of plain text exercise
---------------------------------------

Very short exercise. What is the capital
of Norway?
Filename: myexer1.

# --- end exercise ---

# --- begin exercise ---

Project 4: Compute a Probability
--------------------------------

What is the probability of getting a number between 0.5 and 0.6 when
drawing uniformly distributed random numbers from the interval [0,1)?

At the end we have a list because that caused problems in LaTeX
in previous DocOnce versions:

1. item1

2. item2

# --- begin hint in exercise ---

*Hint.*
To answer this question empirically, let a program
draw N such random numbers using Python's standard random module,
count how many of them, M, that fall in the interval (0.5,0.6), and
compute the probability as M/N.

# --- end hint in exercise ---

# --- end exercise ---

# --- begin exercise ---

Project 5: Explore Distributions of Random Circles
--------------------------------------------------

The formula for a circle is given by::

        \begin{align}
        x &= x_0 + R\cos 2\pi t,
        label{circle:x}\\ 
        y &= y_0 + R\sin 2\pi t,
        label{circle:y}
        \end{align}

where R is the radius of the circle, (x_0,y_0) is the
center point, and t is a parameter in the unit interval [0,1].
For any t, (x,y) computed from Equations (circle:x)-(circle:y)
is a point on the circle.
The formula can be used to generate n points on a circle::

        import numpy as np
        
        def circle(R, x0, y0, n=501):
            t = np.linspace(0, 1, n)
            x = x0 + R*np.cos(2*np.pi*t)
            y = y0 + R*np.sin(2*np.pi*t)
            return x, y
        
        x, y = circle(2.0, 0, 0)

The goal of this project is to draw N circles with random
center and radius. Plot each circle using the circle function
above.

*a)*
Let R be normally distributed and (x_0,y_0) uniformly distributed.

# --- begin hint in exercise ---

*Hint.*
Use the numpy.random module to draw the
x_0, y_0, and R quantities.

# --- end hint in exercise ---

# --- begin answer of exercise ---
*Answer.*
Here goes the short answer to part a).
# --- end answer of exercise ---

# --- begin solution of exercise ---
*Solution.*
Here goes a full solution to part a).
# --- end solution of exercise ---

*b)*
Let R be uniformly distributed and (x_0,y_0) normally distributed.
Filename: norm.

*c)*
Let R and (x_0,y_0) be normally distributed.

Filename: circles.

Remarks
~~~~~~~

At the very end of the exercise it may be appropriate to summarize
and give some perspectives.

# --- end exercise ---

# --- begin exercise ---

Exercise 6: Determine some Distance
-----------------------------------

Intro to this exercise. Questions are in subexercises below.

# --- begin solution of exercise ---
*Solution.*
Here goes a full solution of the whole exercise.
With some math a=b in this solution::

        \[ \hbox{math in solution: } a = b \]

And code a=b in this solution::

        a = b  # code in solution

End of solution is here.

# --- end solution of exercise ---

*a)*
Subexercises are numbered a), b), etc.

# --- begin hint in exercise ---

*Hint 1.*
First hint to subexercise a).
With math a=b in hint::

        \[ a=b. \]

And with code (in plain verbatim) returning x+1 in hint::

        def func(x):
            return x + 1  # with code in hint

# --- end hint in exercise ---

# --- begin hint in exercise ---

*Hint 2.*
Second hint to subexercise a).

Test list in hint:

1. item1

2. item2

# --- end hint in exercise ---
Filename: subexer_a.pdf.

# --- begin answer of exercise ---
*Answer.*
Short answer to subexercise a).
With math in answer: a=b.
# --- end answer of exercise ---

*b)*
Here goes the text for subexercise b).

Some math \cos^2 x + \sin^2 x = 1 written one a single line::

        \[ \cos^2 x + \sin^2 x = 1 \thinspace .\]

# --- begin hint in exercise ---

*Hint.*
A hint for this subexercise.

# --- end hint in exercise ---
Filename: subexer_b.pdf.

# --- begin solution of exercise ---
*Solution.*
Here goes the solution of this subexercise.
# --- end solution of exercise ---

The text here belongs to the main (intro) part of the exercise. Need
closing remarks to have text after subexercises.

Test list in exercise:

1. item1

2. item2

Remarks
~~~~~~~

Some final closing remarks, e.g., summarizing the main findings
and their implications in other problems can be made. These
remarks will appear at the end of the typeset exercise.

# --- end exercise ---

# --- begin exercise ---

Some exercise without the "Exercise:" prefix
--------------------------------------------

Just some text. And some math saying that e^0=1 on a single line,
to test that math block insertion is correct::

        \[ \exp{(0)} = 1 \]

And a test that the code lambda x: x+2 is correctly placed here::

        lambda x: x+2

# --- end exercise ---

# --- begin exercise ---

Exercise 8: Solution of differential equation
---------------------------------------------




Question: Given::

        \[ \frac{dy}{dx} = -y(x),\quad y(0)=1 \]

What is the solution of this equation?

Choice A: y=e^{-y}

Choice B: y=e^{y}

Choice C: 
Code::

        from math import exp
        def f(x):
            return exp(x)

Choice D: The solution cannot be found because there is a derivative in the equation.

Choice E: The equation is meaningless: an equation must be an equation
for x or y, not a function y(x).



# --- end exercise ---

# --- begin exercise ---

Example 9: Just an example
--------------------------

*a)*
What is the capital of Norway?

*Answer.*
Oslo.

# --- end exercise ---

Here goes another section
=========================

With some text, before we continue with exercises.

More Exercises
==============

# --- begin exercise ---

Exercise 10: Make references to projects and problems
-----------------------------------------------------

Pick a statement from "Project 5: Explore Distributions of Random Circles" or "Problem 2: Flip a Coin"
and verify it.

Test list at the end of an exercise without other elements (like subexercise,
hint, etc.):

1. item1

2. item2

Filename: verify_formula.py.

# --- end exercise ---

# --- begin exercise ---

Project 11: References to "Project 4: Compute a Probability" in a heading works for plain
-----------------------------------------------------------------------------------------

Refer to the previous exercise as "Exercise 10: Make references to projects and problems",
the two before that as "Project 4: Compute a Probability" and "Project 5: Explore Distributions of Random Circles",
and this one as "Project 11: References to Project ref{demo:ex:2} in a heading works for plain".
Filename: selc_composed.pdf.

# --- end exercise ---

References
==========

 1. _H. P. Langtangen and G. Pedersen_. 
    Propagation of Large Destructive Waves,
    *International Journal of Applied Mechanics and Engineering*,
    7(1),
    pp. 187-204,
    2002.

 2. _H. P. Langtangen, K.-A. Mardal and R. Winther_. 
    Numerical Methods for Incompressible Viscous Flow,
    *Advances in Water Resources*,
    25,
    pp. 1125-1146,
    2002.

 3. _H. P. Langtangen_. 
    Numerical Solution of First Passage Problems in Random Vibrations,
    *SIAM Journal of Scientific and Statistical Computing*,
    15,
    pp. 997-996,
    1994.

 4. _K.-A. Mardal, G. W. Zumbusch and H. P. Langtangen_. 
    Software Tools for Multigrid Methods,
    *Advanced Topics in Computational Partial Differential Equations -- Numerical Methods and Diffpack Programming*,
    edited by _H. P. Langtangen and A. Tveito_,
    Springer,
    2003,
    Edited book,
    http://some.where.org.

 5. _H. P. Langtangen_. 
    The FEMDEQS Program System,
    *Department of Mathematics, University of Oslo*,
    1989,
    http://www.math.uio.no/old/days/hpl/femdeqs.pdf.

 6. _H. P. Langtangen_. 
    Stochastic Breakthrough Time Analysis of an Enhanced Oil Recovery Process,
    *SIAM Journal on Scientific Computing*,
    13,
    pp. 1394-1417,
    1992.

 7. _M. Mortensen, H. P. Langtangen and G. N. Wells_. 
    A FEniCS-Based Programming Framework for Modeling Turbulent Flow by the Reynolds-Averaged Navier-Stokes Equations,
    *Advances in Water Resources*,
    34(9),
    doi: 10.1016/j.advwatres.2011.02.013 (https://dx.doi.org/10.1016/j.advwatres.2011.02.013),
    2011.

 8. _S. Glimsdal, G. Pedersen, K. Atakan, C. B. Harbitz, H. P. Langtangen and F. L\ovholt_. 
    Propagation of the Dec. 26, 2004 Indian Ocean Tsunami: Effects of Dispersion and Source Characteristics,
    *International Journal of Fluid Mechanics Research*,
    33(1),
    pp. 15-43,
    2006.

 9. _S. Rahman, J. Gorman, C. H. W. Barnes, D. A. Williams and H. P. Langtangen_. 
    Numerical Investigation of a Piezoelectric Surface Acoustic Wave Interaction With a One-Dimensional Channel,
    *Physical Review B: Condensed Matter and Materials Physics*,
    74,
    2006,
    035308.

10. _J. B. Haga, H. Osnes and H. P. Langtangen_. 
    On the Causes of Pressure Oscillations in Low-Permeable and Low-Compressible Porous Media,
    *International Journal of Analytical and Numerical Methods in Geomechanics*,
    doi: 10.1002/nag.1062 (https://dx.doi.org/10.1002/nag.1062),
    2011,
    http://onlinelibrary.wiley.com/doi/10.1002/nag.1062/abstract.

11. _H. P. Langtangen_. 
    *Computational Partial Differential Equations - Numerical Methods and Diffpack Programming*,
    second edition,
    *Texts in Computational Science and Engineering*,
    Springer,
    2003.

12. _H. P. Langtangen_. 
    *Python Scripting for Computational Science*,
    third edition,
    *Texts in Computational Science and Engineering*,
    Springer,
    2008.

13. _H. P. Langtangen and G. Pedersen_. 
    Finite Elements for the Boussinesq Wave Equations,
    Waves and Non-linear Processes in Hydrodynamics,
    edited by _J. Grue, B. Gjevik and J. E. Weber_,
    Kluwer Academic Publishers,
    pp. pp. 117-126,
    1995,
    http://www.amazon.ca/Waves-Nonlinear-Processes-Hydrodynamics-John/dp/0792340310.

14. _H. P. Langtangen_. 
    *A Primer on Scientific Programming With Python*,
    third edition,
    *Texts in Computational Science and Engineering*,
    Springer,
    2012.

15. _P. V. Jeberg, H. P. Langtangen and C. B. Terp_. 
    Optimization With Diffpack: Practical Example From Welding,
    *Simula Research Laboratory*,
    2004,
    Internal report.

16. _H. P. Langtangen_. 
    Computational Methods for Two-Phase Flow in Oil Reservoirs,
    Ph.D. Thesis,
    Mechanics Division, Department of Mathematics, University of Oslo,
    1989,
    Dr. Scient. thesis..

17. _H. P. Langtangen_. 
    Computational Modeling of Huge Tsunamis From Asteroid Impacts,
    2007,
    Invited keynote lecture at the \emphInternational conference on Computational Science 2007 (ICCS'07), Beijing, China.

18. _H. P. Langtangen_. 
    Solution of the Navier-Stokes Equations With the Finite Element Method in Two and Three Dimensions,
    M.Sc. Thesis,
    Mechanics Division, Department of Mathematics, University of Oslo,
    1985,
    Cand.Scient. thesis.

19. _H. P. Langtangen and A. Tveito_. 
    Numerical Methods in Continuum Mechanics,
    *Center for Industrial Research*,
    1991,
    Lecture notes for a course (ME-IN 324). 286 pages..

20. _H. P. Langtangen_. 
    Diffpack: Software for Partial Differential Equations,
    *Proceedings of the Second Annual Object-Oriented Numerics Conference (OON-SKI'94), Sunriver, Oregon, USA*,
    edited by _A. Vermeulen_,
    1994.

Appendix: Just for testing; part I
==================================

This is the first appendix.

A subsection within an appendix
-------------------------------

Some text.

Appendix: Just for testing; part II
===================================

This is more stuff for an appendix.

Appendix: Testing identical titles
----------------------------------

Without label.

Appendix: Testing identical titles
----------------------------------

With label.

Appendix: Testing identical titles
----------------------------------

What about inserting a quiz?




Fundamental test: What is the capital of Norway?

Answer 1: Stockholm

Answer 2: London

Answer 3: Oslo

Choice D: Bergen



Appendix: Testing identical titles
----------------------------------

Without label.


Tip --------------------------------------------------|
|                                                     |
| Here is a tip or hint box, typeset as a notice box. |
|-----------------------------------------------------|


Need a lot of text to surround the summary box.
Version control systems allow you to record the history of files
and share files among several computers and collaborators in a
professional way. File changes on one computer are updated or
merged with changes on another computer. Especially when working
with programs or technical reports it is essential
to have changes documented and to
ensure that every computer and person involved in the project
have the latest updates of the files.
Greg Wilson' excellent Script for Introduction to Version Control (https://software-carpentry.org/2010/07/script-for-introduction-to-version-control/) provides a more detailed motivation why you will benefit greatly
from using version control systems.


Summary ---------------------------------------------------|
|                                                          |
| _Bold remark:_ Make some text with this summary.         |
| Much testing in this document, otherwise stupid content. |
| Much testing in this document, otherwise stupid content. |
| Much testing in this document, otherwise stupid content. |
| Much testing in this document, otherwise stupid content. |
| Much testing in this document, otherwise stupid content. |
| Much testing in this document, otherwise stupid content. |
| Much testing in this document, otherwise stupid content. |
| Much testing in this document, otherwise stupid content. |
| Much testing in this document, otherwise stupid content. |
|----------------------------------------------------------|


Projects that you want to share among several computers or project
workers are today most conveniently stored at some web site "in the
cloud" and updated through communication with that site. I strongly
recommend you to use such sites for all serious programming and
scientific writing work - and all other important files.

The simplest services for hosting project files are Dropbox (https://dropbox.com) and Google Drive (https://drive.google.com).
It is very easy to get started with these systems, and they allow you
to share files among laptops and mobile units with as many users as
you want. The systems offer a kind of version control in that the
files are stored frequently (several times per minute), and you can go
back to previous versions for the last 30 days. However, it is
challenging  to find the right version from the past when there are
so many of them.

More seriously, when several people may edit files simultaneously, it
can be difficult detect who did what when, roll back to previous
versions, and to manually merge the edits when these are
incompatible. Then one needs more sophisticated tools than Dropbox or
Google Drive: project hosting services with true version control
systems.  The following text aims at providing you with the minimum
information to started with such systems. Numerous other tutorials
contain more comprehensive material and in-depth explanations of the
concepts and tools.

The idea with project hosting services is that you have the files
associated with a project in the cloud. Many people may share these
files.  Every time you want to work on the project you explicitly
update your version of the files, edit the files as you like, and
synchronize the files with the "master version" at the site where the
project is hosted.  If you at some point need to go back to a
version of the files at some particular point in the past,
this is an easy operation. You can also use tools to see
what various people have done with the files in the various versions.

All these services are very similar. Below we describe how you get
started with Bitbucket, GitHub, and Googlecode. Launchpad works very
similarly to the latter three. All the project hosting services have
excellent introductions available at their web sites, but the recipes
below are much shorter and aim at getting you started as quickly as
possible by concentrating on the most important need-to-know steps.
The Git tutorials we refer to later in this document contain more
detailed information and constitute of course very valuable readings
when you use version control systems every day. The point now is
to get started.

Appendix: Testing inline comments
---------------------------------

Projects that you want to share among several computers or project
workers are today most conveniently stored at some web site "in the
cloud" and updated through communication with that
site. [hpl's semi opinion 1: not sure if in the cloud is
understood by
all.] I strongly recommend you to use such sites for all serious
programming and scientific writing work - and all other important
files.

The simplest services for hosting project files is Dropbox. [mp 2: Simply go to https://dropbox.com and watch the video. It explains
how files, like myfile.py, perhaps containing much math, like
\partial u/\partial t, are easily communicated between machines.] It
is very easy to get started with Dropbox, and it allows you to share
files among [hpl 3: laptops and mobile units -> computers, tablets,
and phones].

------

First[add 4: ,] consider a quantity Q. [edit 5: To this end, -> We note that]
Q>0, because [del 6: a] negative [edit 7: quantity is -> quantities
are] [del 8: just] negative. [add 9: This comes as no surprise.]

Let us refer to Figure ref{fig:impact} again.

Test references in a list:

 * "Section 1"

 * "Subsection 1"

 * ref{fig:impact}

Appendix: Testing headings ending with verbatim inline
------------------------------------------------------

The point here is to test 1) verbatim code in headings, and 2)
ending a heading with verbatim code as this triggers a special
case in LaTeX.

We also test mdash---used as alternative to hyphen without spaces around,
or in quotes:

        *Fun is fun*.---Unknown.


The ndash should also be tested - as in the Hanson - Nilson equations
on page 277 - 278.

And finally, what about admons, quotes, and boxes? They are tested
in a separate document: admon.do.txt.

[^example-of-the-third-footnote]: Not much to add here, but the footnote
is at the end with only one newline.
************** File: testdoc.md *****************
% A Document for Testing DocOnce
% **Hans Petter Langtangen** at Center for Biomedical Computing, Simula Research Laboratory and Department of Informatics, University of Oslo;  **Kaare Dump** at Segfault, Cyberspace;  **A. Dummy Author**;  **I. S. Overworked and Outburned** at Inst1 and Inst2, Somewhere and Third Inst, Elsewhere and Fourth Inst;  **J. Doe**
% Jan 32, 2100

Made with DocOnce




<!-- Table of contents: Run pandoc with --toc option -->




<!-- !split -->




The format of this document is
pandoc
*Abstract.* This is a document with many test constructions for doconce syntax.
It was used heavily for the development and kept for testing
numerous constructions, also special and less common cases.

And exactly for test purposes we have an extra line here, which
is part of the abstract.

<!-- Cannot demonstrate chapter headings since abstract and chapter -->
<!-- are mutually exclusive in LaTeX -->



## Section 1
<div id="sec1"></div>

Here is a nested list:

  * item1
  * item2
  * item3 which continues
    on the next line to test that feature
  * and a sublist
    * with indented subitem1
    * and a subitem2

  * and perhaps an ordered sublist
   a. first item
   b. second item,
      continuing on a new line


*Here is a list with paragraph heading.*

  * item1
  * item2

#### Here is a list with subsubsection heading

  * item1
  * item2

> Here are two lines that make up
> a block quote for testing *emphasized words* and **boldface words**,
> also with hypens:
> *pre*-fix, post-*fix*, **pre**-fix, post-**fix**.



Here are two references. Equation\ ([my:eq1](#my:eq1)) is fine. Eq.\ ([my:eq1](#my:eq1)) too.
Even Equation ([my:eq1](#my:eq1)) without the tilde.


### Subsection 1
<div id="subsec1"></div>


<!-- Refer to section/appendix etc. at the beginning of the line -->
<!-- and other special fix situations for HTML. -->

More text, with a reference back to
the section [Section 1](#sec1) and [Subsection 1](#subsec1), and further to the
the sections [Subsection 1](#subsec1) and [URLs](#subsubsec:ex), which
encourages you to do the tasks in [Problem 2: Flip a Coin](#demo:ex:1) and [Exercise 10: Make references to projects and problems](#exer:some:formula).
 [Appendix: Just for testing; part I](#app1) and [Appendix: Just for testing; part II](#app2) are also nice elements.

#### Test Section reference at beginning of line and after a sentence

The section [Subsection 1](#subsec1) is fine.
The section [URLs](#subsubsec:ex) too.


<!-- sphinx code-blocks: pycod=python cod=fortran cppcod=c++ sys=console -->

#### Computer code

Let's do some copying from files too. First from subroutine up to the very end,


~~~{.Fortran}
      subroutine test()
      integer i
      real*8 r
      r = 0
      do i = 1, i
         r = r + i
      end do
      return
C     END1

      program testme
      call test()
      return
~~~

and then just the subroutine,

~~~{.Fortran}
      subroutine test()
      integer i
      real*8 r
      r = 0
      do i = 1, i
         r = r + i
      end do
      return
~~~

and finally the complete file with a plain text verbatim environment
(`envir=ccq`):

~~~
C     a comment

      subroutine test()
      integer i
      real*8 r
      r = 0
      do i = 1, i
         r = r + i
      end do
      return
C     END1

      program testme
      call test()
      return
~~~

Testing other code environments. First Python:


~~~
!bc pycod
def f(x):
    return x+1
!ec
~~~

which gets rendered as


~~~{.Python}
def f(x):
    return x+1
~~~

Test paragraph and subsubsection headings before
before code.

*Paragraph heading before code.*


~~~{.Python}
import sys
sys.path.insert(0, os.pardir)
~~~

#### Subsubsection heading before code


~~~{.Python}
def h(z):
    return z+1
~~~

Here is a program that is supposed to be interactive via
Python Online Tutorial, but that service is not accessible
for the present format.


~~~{.Python}
class Line:
    def __init__(self, a, b):
        self.a, self.b = a, b

    def __call__(self, x):
        a, b = self.a, self.b
        return a*x + b

line = Line(2, 1)
y = line(x=3)
print(y)
~~~

Some more Python code (actually specified as a sage cell, but
such cells are not supported by this format).


~~~{.Python}
a = 2
b = 3
print('a+b:', a + b)

# In a sage cell we can also plot
from matplotlib.pyplot import *
from numpy import *
x = linspace(0, 4*pi, 101)
y = exp(-0.1*x)*cos(x)
plot(x, y)
xlabel('x'); ylabel('y')
show()
~~~

Then Cython (with -h option so it is hidden in html/sphinx):


~~~{.Python}
cpdef f(double x):
    return x + 1
~~~

Standard Python shell sessions:


~~~{.Python}
>>> from numpy import linspace, sin
>>> # Some comment
>>> x = linspace(0, 2, 11)
>>> y = sin(x)
>>> y[0]
0
>>> import matplotlib.pyplot as plt
>>> plt.plot(x, y)
~~~

Similar IPython sessions:


~~~{.Python}
In [1]: from numpy import linspace, sin
In [2]: # Some comment
In [3]: x = linspace(0, 2, 11)
In [4]: y = sin(x)
In [5]: y[0]
Out[5]: 0
In [6]: import matplotlib.pyplot as plt
In [7]: plt.plot(x, y)
In [8]: a='multiple-\nline\noutput'
In [9]: a
Out[9]: 'multiple-\nline\noutput'
In [10]: print(a)
multiple-
line
output
~~~

Here is the interactive session again, but with `pyshell-t`.


~~~{.Python}
>>> from numpy import linspace, sin
>>> # Some comment
>>> x = linspace(0, 2, 11)
>>> y = sin(x)
>>> y[0]
0
>>> import matplotlib.pyplot as plt
>>> plt.plot(x, y)
~~~

<!-- This one tests a + sign before a code environment -->
C++:

~~~{.Cpp}
#include <iostream>

int main()
{
   std::cout << "Sample output" << std::endl;
   return 0
}
~~~

<!-- The next should get correctly typset in sphinx (cod is fcod) -->
<!-- It also tests emoji before code -->
And a little bit of Fortran: :dizzy_face:


~~~
!bc cod
      subroutine midpt(x, length, a, b)
      real*8 a, b, x
      x = (a + b)/2
      length = b - a
      return
      end
!ec
~~~

which then is typeset as


~~~{.Python}
      subroutine midpt(x, length, a, b)
      real*8 a, b, x
      x = (a + b)/2
      length = b - a
      return
      end
~~~

HTML:


~~~{.HTML}
<table>
<tr><td>Column 1</td><td>Column 2</td></tr>
<tr><td>0.67526 </td><td>0.92871 </td></tr>
<!-- comment -->
</table>
~~~

But inline HTML code is also important, like text that starts with
`<a href="` (which can destroy the following text if not properly
quoted).

Matlab with comments requires special typesetting:


~~~
% Comment on the beginning of the line can be escaped by %%
if a > b
  % Indented comment needs this trick
  c = a + b
end
~~~

And here is a system call:


~~~
Terminal> mkdir test
Terminal> cd test
Terminal> myprog -f
output1
output2
~~~

Any valid pygments lexer/language name can appear to, e.g.,


~~~
!bc restructuredtext
=======
Heading
=======

Some text.
!ec
~~~

results in


~~~
=======
Heading
=======

Some text.
~~~

<!-- Here goes hidden code. -->
<!-- Python can be treated by some formats, Fortran is always out. -->





Finally, `!bc do` supports highlighting of DocOnce source:


~~~
======= DocOnce test file =======

===== Computer code =====

Inline verbatim code, as in `import numpy as np`, is allowed, as well as
code blocks:

!bc pycod
from math import sin

def f(x):
    """Example on a function."""
    return sin(x) + 1

print(f(0))
!ec


===== Mathematics =====

Formulas can be inline, as in $\nabla\cdot\boldsymbol{u} = 0$, or typeset
as equations:

!bt
\begin{align*}
\nabla\cdot\boldsymbol{u} &= 0,\\ 
\boldsymbol{u} &= \nabla\phi .
\end{align*}
!et

=== Subsubsection heading ===

DocOnce files can have chapters, sections, subsections, and subsubsections.

__Paragraph heading.__ Paragraphs may have headings.
~~~

It is time to test `verbatim inline font` especially with `a newline
inside the text` and an exclamation mark at the end: `BEGIN`! For
spellcheck, test `a verbatim expression` in `another` in a `third`.
Also test exclamation mark as in `!bc` and `!ec` as well as `a != b`.
Also test backslashes and braces like `\begin`, `\begin{enumerate}`,
`\end{this}\end{that}`, and `{something \inside braces}`.

The following attempt to exemplify colored text does not work in
format pandoc.
Here is some <font color="red">red color</font> and an attempt to write <font color="green">with
green color containing a linebreak\n
code.</font> Some formats will only display \n
this correctly when `html` \n
is the output format.
But here some more running text is added which is not part of
the previous blocks with line breaks.

#### Running OS commands


~~~
Terminal> python -c 'print("Testing\noutput\nfrom\nPython.")'
Testing
output
from
Python.
~~~

#### Footnotes

Here is a test of footnotes [^footnote], which are handy in text.
They are used in different flavors, now in

 * list items (note below that footnotes work after math, verbatim, and URLs - bin fact old and emphasize too!)
 * even with math $\nabla^2u$[^math1]
 * and code `h[i] += 1`[^code]
   (*must* have space between inline code and footnote!)
 * and [links](https://google.com)[^google-search]

which gives flexibility in writing.
This is the third[^example-of-the-third-footnote] example.

  [^footnote]: Typesetting of the footnote depends on the format.
Plain text does nothing, LaTeX removes the
definition and inserts the footnote as part of the LaTeX text.
reStructuredText and Sphinx employ a similar type of typesetting
as Extended Markdown and DocOnce, and in HTML we keep the same
syntax, just displayed properly in HTML.
[^math1]: Math footnotes can be dangerous since it
interferes with an exponent.
[^code]: One-line footnote.

[^google-search]: <google.com> is perhaps the most famous
web site today.

Here is some more text before a new definition of a footnote that was
used above.

*Non-breaking space character.* 
This paragraph aims to test [non-breaking space character](https://en.wikipedia.org/wiki/Non-breaking_space), and a typical
example where this is needed is in physical units: 7.4\ km is traveled
in\ $7.4/5.5\approx 1.345$\ s.  Also check that a~[link](https://google.com)\ is
not broken across lines (drag the browser window to test this).
(On the other hand, the tilde is used in
computer code, e.g., as in `[~x for x in y]` or in `y=~x`, and should
of course remain a tilde in those contexts.)



### Subsection 2: Testing figures
<div id="subsec:ex"></div>

Test of figures. In particular we refer to [Figure](#fig:impact) in which
there is a flow.

<!-- <img src="../doc/src/manual/fig/wave1D.png" width=200><p><em>Visualization **of** a *wave*. <div id="fig:impact"></div></em></p> -->
![<p><em>Visualization **of** a *wave*. <div id="fig:impact"></div></em></p>](../doc/src/manual/fig/wave1D.png)

Figures without captions are allowed and will be inlined.

<!-- <img src="../doc/src/manual/fig/wave1D.png" width=200> -->
![](../doc/src/manual/fig/wave1D.png)



<!-- Test multi-line caption in figure with sidecap=True -->

Here is [figure](#myfig) with a long (illegal) multi-line caption
containing inline verbatim text:

<!-- <img src="../doc/src/manual/fig/wave1D.png" width=500><p><em>A long caption spanning several lines and containing verbatim words like `my_file_v1` and `my_file_v2` as well as math with subscript as in $t_{i+1}$. <div id="myfig"></div></em></p> -->
![<p><em>A long caption spanning several lines and containing verbatim words like `my_file_v1` and `my_file_v2` as well as math with subscript as in $t_{i+1}$. <div id="myfig"></div></em></p>](../doc/src/manual/fig/wave1D.png)

<!-- Must be a blank line after MOVIE or FIGURE to detect this problem -->

Test URL as figure name:

<!-- <img src="https://raw.github.com/doconce/doconce/master/doc/src/blog/f_plot.png" width=500> -->
![](https://raw.github.com/doconce/doconce/master/doc/src/blog/f_plot.png)


<!-- Test wikimedia type of files that otherwise reside in subdirs -->


*Remark.*
Movies are tested in separate file `movies.do.txt`.


<!-- Somewhat challenging heading with latex math, \t, \n, ? and parenthesis -->

### The $\theta$ parameter (not $\nabla$?)
<div id="decay:sec:theta"></div>

Functions do not always need to be advanced, here is one
involving $\theta$:

~~~
def f(theta):
    return theta**2
~~~

*More on $\theta$.* Here is more text following headline with math.

Newcommands must also be tested in this test report:
$\frac{1}{2}$, ${1/2}$, $\pmb{x}$, $\frac{Du}{dt}$,
both inline and in block:

$$
\begin{align}
\frac{Du}{dt} &= 0\nonumber
\\ 
\frac{1}{2} &= {1/2}\\ 
\frac{1}{2}\pmb{x} &= \pmb{n}
\end{align}
$$

Or with align with label and numbers:

$$
\begin{align}
\frac{Du}{dt} &= 0
\label{aligneq1}
\\ 
\frac{1}{2} &= {1/2}\\ 
\frac{1}{2}\pmb{x} &= \pmb{n}
\label{aligneq2}
\end{align}
$$



### Custom Environments

Here is an attempt to create a theorem environment via Mako
(for counting theorems) and comment lines to help replacing lines in
the `.tex` by proper begin-end LaTeX environments for theorems.
Should look nice in most formats!



<!-- begin theorem -->
<div id="theorem:fundamental1"></div>


*Theorem 5.*
Let $a=1$ and $b=2$. Then $c=3$.
<!-- end theorem -->

<!-- begin proof -->
*Proof.*
Since $c=a+b$, the result follows from straightforward addition.
$\Diamond$
<!-- end proof -->

As we see, the proof of Theorem 5 is a modest
achievement.


### Tables
<div id="subsec:table"></div>


<!-- index with comma could fool sphinx -->

Let us take this table from the manual:



time  velocity  acceleration  
----  --------  ------------  
0.0     1.4186         -5.01  
2.0   1.376512        11.919  
4.0     1.1E+1     14.717624  



The DocOnce source code reads

~~~

  |--------------------------------|
  |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    |
  |--------------------------------|

~~~

Here is yet another table to test that we can handle more than
one table:


time  velocity  acceleration  
----  --------  ------------  
0.0   1.4186    -5.01         
1.0   1.376512  11.919        
3.0   1.1E+1    14.717624     


And one with math headings (that are expanded and must be treated
accordingly), verbatim heading and entry, and no space around the pipe
symbol:


$i$  $h_i$   $\bar T_i$   `L_i`   
---  ------  ----------  -------  
0         0         288  -0.0065  
1    11,000         216      0.0  
2    20,000         216    0.001  
3    32,000         228   0.0028  
4    47,000         270      0.0  
5    51,000         270  -0.0028  
6    71,000         214    `NaN`  


And add one with verbatim headings (with underscores),
and rows starting with `|-` because of a negative number,
and `|` right before and after verbatim word (with no space):


exact  `v_1`   $a_i$ + `v_2`  `verb_3_`  
-----  ------  -------------  ---------  
    9    9.62           5.57       8.98  
  -20  -23.39          -7.65     -19.93  
   10   17.74          -4.50       9.96  
    0   -9.19           4.13      -0.26  


Pipe symbols in verbatim and math text in tables used to pose difficulties,
but not
anymore:


    $S$         command     
-----------  -------------  
$ ||a_0|| $  `norm|length`  
$x\cap y$            `x|y`  



Here is a table with X alignment:


 Type                                                                                                       Description                                                                                                        
-----  ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------  
  X    Alignment character that is used for specifying a potentially very long text in a column in a table. It makes use of the `tabularx` package in LaTeX, otherwise (for other formats) it means `l` (centered alignment).  
l,r,c  standard alignment characters                                                                                                                                                                                           


Finally, a table with math
(`bm` that expands to `boldsymbol`, was tricky, but
cleanly handled now)
and URLs.

<!-- Mako code to expand URLs in the table -->
<!-- (These types of tables did not work before Jan 2014) -->



                                                                                                                                                       
-------------------------------  ---------------------------------------------------------  ---------------------------------------------------------  
        $\mathcal{L}=0$          [`080`](../doc/src/manual/mov/wave_frames/frame_0080.png)  [`085`](../doc/src/manual/mov/wave_frames/frame_0085.png)  
             $a=b$               [`090`](../doc/src/manual/mov/wave_frames/frame_0090.png)  [`095`](../doc/src/manual/mov/wave_frames/frame_0095.png)  
$\nabla\cdot\boldsymbol{u} =0 $  [`100`](../doc/src/manual/mov/wave_frames/frame_0100.png)  [`105`](../doc/src/manual/mov/wave_frames/frame_0105.png)  



### A test of verbatim words in heading with subscript $a_i$: `my_file_v1` and `my_file_v2`

*Paragraph with verbatim and math: `my_file_v1.py` and `my_file_v2.py` define some math $a_{i-1}$.* Here is more `__verbatim__` code and
some plain text on a new line.

<!-- Test various types of headlines -->
### **Just bold**

Some text.

### *Just emphasize*

Some text.

### `Just verbatim`

Some text.

### **Bold** beginning

Some text.

### *Emphasize* beginning

Some text.

### `Verbatim` beginning

Some text.

### Maybe **bold end**

Some text.

### Maybe *emphasize end*

Some text.

### Maybe `verbatim end`

Some text.

### The middle has **bold** word

Some text.

### The middle has *emphasize* word

Some text.

### The middle has `verbatim` word

Some text.


**Just emphasize*.* Some text.


*`Just verbatim`.* Some text.


**Emphasize* beginning.* Some text.


*`Verbatim beginning`.* Some text.


*Maybe *emphasize end*.* Some text.


*Maybe `verbatim end`.* Some text.


*The middle has *emphasize* word.* Some text.


*The middle has `verbatim` word.* Some text.


*Ampersand.*
We can test Hennes & Mauritz, often abbreviated H&M, but written
as `Hennes & Mauritz` and `H & M`.
A sole `&` must also work.
<!-- Note: substitutions must not occur inside verbatim, just in ordinary text. -->


~~~
# Just to check that ampersand works in code blocks:
c = a & b
~~~

*Quotes.*
Let us also add a test of quotes such as "double quotes, with numbers
like 3.14 and newline/comma and hyphen (as in double-quote)"; written
in the standard LaTeX-style that gives correct LaTeX formatting and
ordinary double quotes for all non-LaTeX formats.  Here is another
sentence that "caused" a bug in the past because double backtick
quotes could imply verbatim text up to a verbatim word starting with
period, like `.txt`.

More quotes to be tested for spellcheck:
("with parenthesis"), "with newline"
and "with comma", "hyphen"-wise, and "period".


### Bibliography test

Here is an example: [@Langtangen_Pedersen_2002] discussed propagation of
large destructive water waves, [@Langtangen_et_al_2002] gave
an overview of numerical methods for solving the Navier&ndash;Stokes equations,
while the use of Backward Kolmogorov equations for analyzing
random vibrations was investigated in [@Langtangen_1994a].
The book chapter [@Mardal_et_al_2003a] contains information on
C++ software tools for programming multigrid methods. A real retro
reference is [@Langtangen_1988d] about a big FORTRAN package.
Multiple references are also possible, e.g., see
[@Langtangen_Pedersen_2002;@Mardal_et_al_2003a].

We need to cite more than 10 papers to reproduce an old formatting
problem with blanks in the keys in reST format:
[@Langtangen_1992c;@Langtangen_1994a;@Mortensen_et_al_2011;@Langtangen_Pedersen_2002]
and
[@Langtangen_et_al_2002;@Glimsdal_et_al_20006;@Rahman_et_al_2006b;@Haga_et_al_2011a;@Langtangen_2003a;@Langtangen_2008a;@Langtangen:95]
and all the work of
[@Langtangen_2012;@Mardal_et_al_2003a;@Jeberg_et_al_2004] as well as
old work [@Langtangen_1988d] and [@Langtangen_1989e], and the
talk [@Langtangen_talk_2007a].
Langtangen also had two thesis [@Langtangen:85;@Langtangen_1989e]
back in the days.
More retro citations are
the old ME-IN323 book [@Langtangen:91] and the
[@Langtangen:94b] OONSKI '94 paper.




<!-- --- begin exercise --- -->

### Example 1: Examples can be typeset as exercises
<div id="Example"></div>

Examples can start with a subsection heading starting with `Example:`
and then, with the command-line option `--examples_as_exercises` be
typeset as exercises. This is useful if one has solution
environments as part of the example.


*a)*
State some problem.

*Solution.*
The answer to this subproblem can be written here.

*b)*
State some other problem.

*Hint 1.*
A hint can be given.

*Hint 2.*
Maybe even another hint?

*Solution.*
The answer to this other subproblem goes here,
maybe over multiple doconce input lines.

<!-- --- end exercise --- -->


### User-defined environments



The example in the section [Example 1: A test function](#ex:test:1p1) demonstrates how to write a test function.
That is, a special test function for a function `add` appears in
the example in the section [Example 1: A test function](#ex:test:1p1).



### Example 1: A test function
<div id="ex:test:1p1"></div>

Suppose we want to write a test function for checking the
implementation of a Python function for addition.


~~~{.Python}
def add(a, b):
    return a + b

def test_add():
    a = 1; b = 1
    expected = a + b
    computed = add(a, b)
    assert expected == computed
~~~

### Example 2: Addition
<div id="ex:math:1p1"></div>

We have

$$
 1 + 1 = 2 
$$
or in tabular form:


Problem  Result  
-------  ------  
 $1+1$    $2$    




*Highlight box!* 
This environment is used to highlight something:

$$
 E = mc^2 
$$





### URLs
<div id="subsubsec:ex"></div>

Testing of URLs: hpl's home page [hpl](https://folk.uio.no/hpl), or
the entire URL if desired, <https://folk.uio.no/hpl>.  Here is a
plain file link <testdoc.do.txt>, or <testdoc.do.txt>, or
<testdoc.do.txt> or <testdoc.do.txt> or [a link with
newline](testdoc.do.txt). Can test spaces with the link with word
too: [hpl](https://folk.uio.no/hpl) or [hpl](https://folk.uio.no/hpl). Also `file:///` works: [link to a
file](file:///home/hpl/vc/doconce/doc/demos/manual/manual.html) is
fine to have. Moreover, "loose" URLs work, i.e., no quotes, just
the plain URL as in <https://folk.uio.no/hpl>, if followed by space, comma,
colon, semi-colon, question mark, exclamation mark, but not a period
(which gets confused with the periods inside the URL).

Mail addresses can also be used: [`hpl@simula.no`](mailto:hpl@simula.no), or just a [mail link](mailto:hpl@simula.no), or a raw <mailto:hpl@simula.no>.

Here are some tough tests of URLs, especially for the `latex` format:
[Newton-Cotes](https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas) formulas
and a [good book](https://www.springer.com/mathematics/computational+science+%26+engineering/book/978-3-642-23098-1). Need to test
Newton-Cotes with percentage in URL too:
<https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas>
and <https://en.wikipedia.org/wiki/Newton-Cotes#Open_Newton.E2.80.93Cotes_formulae> which has a shebang.

For the `--device=paper` option it is important to test that URLs with
monospace font link text get a footnote
(unless the `--latex_no_program_footnotelink`
is used), as in this reference to
[`decay_mod`](https://github.com/hplgit/INF5620/tree/gh-pages/src/decay/experiments/decay_mod.py), [`ball1.py`](https://tinyurl.com/pwyasaa/formulas.ball1.py),
and [`ball2.py`](https://tinyurl.com/pwyasaa/formulas.ball2.py).


<!-- Comments should be inserted outside paragraphs (because in the rst -->
<!-- format extra blanks make a paragraph break). -->

<!-- Note that when there is no https: or file:, it can be a file link -->
<!-- if the link name is URL, url, "URL", or "url". Such files should, -->
<!-- if rst output is desired, but placed in a `_static*` folder. -->

More tough tests: repeated URLs whose footnotes when using the
`--device=paper` option must be correct. We have
[google](https://google.com), [google](https://google.com), and
[google](https://google.com), which should result in exactly three
footnotes.



<!-- !split and check if these extra words are included properly in the comment -->

## LaTeX Mathematics

Here is an equation without label using backslash-bracket environment:
$$
 a = b + c 
$$

or with number and label, as in ([my:eq1](#my:eq1)), using the equation environment:

$$
\begin{equation}
{\partial u\over\partial t} = \nabla^2 u \label{my:eq1}
\end{equation}
$$

We can refer to this equation by ([my:eq1](#my:eq1)).

Here is a system without equation numbers, using the align-asterisk environment:

$$
\begin{align*}
\pmb{a} &= \pmb{q}\times\pmb{n} \\ 
b &= \nabla^2 u + \nabla^4 v
\end{align*}
$$


And here is a system of equations with labels in an align environment:

$$
\begin{align}
a &= q + 4 + 5+ 6 \label{eq1} \\ 
b &= \nabla^2 u + \nabla^4 x \label{eq2}
\end{align}

$$
We can refer to ([eq1](#eq1))-([eq2](#eq2)). They are a bit simpler than
the Navier&ndash;Stokes equations. And test LaTeX hyphen in `CG-2`.
Also test $a_{i-j}$ as well as $kx-wt$.

Testing `alignat` environment:

$$
\begin{alignat}{2}
a &= q + 4 + 5+ 6\qquad & \mbox{for } q\geq 0 \label{eq1a} \\ 
b &= \nabla^2 u + \nabla^4 x & x\in\Omega \label{eq2a}
\end{alignat}
$$


More mathematical typesetting is demonstrated in the coming exercises.

Below, we have [Problem 2: Flip a Coin](#demo:ex:1) and [Project 4: Compute a Probability](#demo:ex:2),
as well as [Project 5: Explore Distributions of Random Circles](#proj:circle1) and [Project 11: References to Project [demo:ex:2](#demo:ex:2) in a heading works for pandoc](#exer:you), and in
between there we have [Exercise 10: Make references to projects and problems](#exer:some:formula).


## Exercises



<!-- --- begin exercise --- -->

### Problem 2: Flip a Coin
<div id="demo:ex:1"></div>
<!-- keywords = random numbers; Monte Carlo simulation; ipynb -->

<!-- Torture tests -->


*a)*
Make a program that simulates flipping a coin $N$ times.
Print out "tail" or "head" for each flip and
let the program count the number of heads.

<!-- --- begin hint in exercise --- -->

*Hint 1.*
Use `r = random.random()` and define head as `r <= 0.5`.

<!-- --- end hint in exercise --- -->

<!-- --- begin hint in exercise --- -->

*Hint 2.*
Draw an integer among $\{1,2\}$ with
`r = random.randint(1,2)` and define head when `r` is 1.

<!-- --- end hint in exercise --- -->


<!-- --- begin answer of exercise --- -->
*Answer.*
If the `random.random()` function returns a number $<1/2$, let it be
head, otherwise tail. Repeat this $N$ number of times.
<!-- --- end answer of exercise --- -->


<!-- --- begin solution of exercise --- -->
*Solution.*

~~~{.Python}
import sys, random
N = int(sys.argv[1])
heads = 0
for i in range(N):
    r = random.random()
    if r <= 0.5:
        heads += 1
print('Flipping a coin %d times gave %d heads' % (N, heads))
~~~

<!-- --- end solution of exercise --- -->

*b)*
Vectorize the code in a) using boolean indexing.

Vectorized code can be written in many ways.
Sometimes the code is less intuitive, sometimes not.
At least there is not much to find in the section [Section 1](#sec1).

*c)*
Vectorize the code in a) using `numpy.sum`.


<!-- --- begin answer of exercise --- -->
*Answer.*
`np.sum(np.where(r <= 0.5, 1, 0))` or `np.sum(r <= 0.5)`.
<!-- --- end answer of exercise --- -->

In this latter subexercise, we have an
example where the code is easy to read.


#### My remarks

Remarks with such a subsubsection is treated as more text
after the last subexercise. Test a list too:

1. Mark 1.
2. Mark 2.

Filenames: `flip_coin.py`, `flip_coin.pdf`.

<!-- Closing remarks for this Problem -->

#### Remarks

These are the exercise remarks, appearing at the very end.

<!-- solution files: mysol.txt, mysol_flip_coin.py, yet_another.file -->

<!-- --- end exercise --- -->


### Not an exercise

Should be possible to stick a normal section in the middle of many
exercises.



<!-- --- begin exercise --- -->

### Exercise 3: Test of plain text exercise
<div id="my:exer1"></div>

Very short exercise. What is the capital
of Norway?
Filename: `myexer1`.

<!-- --- end exercise --- -->




<!-- --- begin exercise --- -->

### Project 4: Compute a Probability
<div id="demo:ex:2"></div>

<!-- Minimalistic exercise -->


What is the probability of getting a number between 0.5 and 0.6 when
drawing uniformly distributed random numbers from the interval $[0,1)$?


At the end we have a list because that caused problems in LaTeX
in previous DocOnce versions:

1. item1
2. item2

<!-- --- begin hint in exercise --- -->

*Hint.*
To answer this question empirically, let a program
draw $N$ such random numbers using Python's standard `random` module,
count how many of them, $M$, that fall in the interval $(0.5,0.6)$, and
compute the probability as $M/N$.

<!-- --- end hint in exercise --- -->

<!-- --- end exercise --- -->




<!-- --- begin exercise --- -->

### Project 5: Explore Distributions of Random Circles
<div id="proj:circle1"></div>
<!-- keywords = ipynb -->

The formula for a circle is given by

$$
\begin{align}
x &= x_0 + R\cos 2\pi t,
\label{circle:x}\\ 
y &= y_0 + R\sin 2\pi t,
\label{circle:y}
\end{align}
$$
where $R$ is the radius of the circle, $(x_0,y_0)$ is the
center point, and $t$ is a parameter in the unit interval $[0,1]$.
For any $t$, $(x,y)$ computed from ([circle:x](#circle:x))-([circle:y](#circle:y))
is a point on the circle.
The formula can be used to generate `n` points on a circle:


~~~{.Python}
import numpy as np

def circle(R, x0, y0, n=501):
    t = np.linspace(0, 1, n)
    x = x0 + R*np.cos(2*np.pi*t)
    y = y0 + R*np.sin(2*np.pi*t)
    return x, y

x, y = circle(2.0, 0, 0)
~~~

<!-- Often in an exercise we have some comments about the solution -->
<!-- which we normally want to keep where they are. -->

The goal of this project is to draw $N$ circles with random
center and radius. Plot each circle using the `circle` function
above.


*a)*
Let $R$ be normally distributed and $(x_0,y_0)$ uniformly distributed.

<!-- --- begin hint in exercise --- -->

*Hint.*
Use the `numpy.random` module to draw the
$x_0$, $y_0$, and $R$ quantities.

<!-- --- end hint in exercise --- -->


<!-- --- begin answer of exercise --- -->
*Answer.*
Here goes the short answer to part a).
<!-- --- end answer of exercise --- -->


<!-- --- begin solution of exercise --- -->
*Solution.*
Here goes a full solution to part a).
<!-- --- end solution of exercise --- -->

*b)*
Let $R$ be uniformly distributed and $(x_0,y_0)$ normally distributed.
Filename: `norm`.

*c)*
Let $R$ and $(x_0,y_0)$ be normally distributed.


Filename: `circles`.

<!-- Closing remarks for this Project -->

#### Remarks

At the very end of the exercise it may be appropriate to summarize
and give some perspectives.


<!-- --- end exercise --- -->




<!-- --- begin exercise --- -->

### Exercise 6: Determine some Distance
<div id="exer:dist"></div>

Intro to this exercise. Questions are in subexercises below.


<!-- --- begin solution of exercise --- -->
*Solution.*
Here goes a full solution of the whole exercise.
With some math $a=b$ in this solution:
$$
 \hbox{math in solution: } a = b 
$$
And code `a=b` in this solution:

~~~
a = b  # code in solution
~~~

End of solution is here.

<!-- --- end solution of exercise --- -->


*a)*
Subexercises are numbered a), b), etc.

<!-- --- begin hint in exercise --- -->

*Hint 1.*
First hint to subexercise a).
With math $a=b$ in hint:

$$
 a=b. 
$$
And with code (in plain verbatim) returning $x+1$ in hint:


~~~
def func(x):
    return x + 1  # with code in hint
~~~

<!-- --- end hint in exercise --- -->

<!-- --- begin hint in exercise --- -->

*Hint 2.*
Second hint to subexercise a).

Test list in hint:

1. item1
2. item2

<!-- --- end hint in exercise --- -->
Filename: `subexer_a.pdf`.


<!-- --- begin answer of exercise --- -->
*Answer.*
Short answer to subexercise a).
With math in answer: $a=b$.
<!-- --- end answer of exercise --- -->

*b)*
Here goes the text for subexercise b).


Some math $\cos^2 x + \sin^2 x = 1$ written one a single line:

$$
 \cos^2 x + \sin^2 x = 1 \thinspace .
$$

<!-- --- begin hint in exercise --- -->

*Hint.*
A hint for this subexercise.

<!-- --- end hint in exercise --- -->
Filename: `subexer_b.pdf`.


<!-- --- begin solution of exercise --- -->
*Solution.*
Here goes the solution of this subexercise.
<!-- --- end solution of exercise --- -->



<!-- No meaning in this weired test example: -->
The text here belongs to the main (intro) part of the exercise. Need
closing remarks to have text after subexercises.

Test list in exercise:

1. item1
2. item2
<!-- Closing remarks for this Exercise -->

#### Remarks

Some final closing remarks, e.g., summarizing the main findings
and their implications in other problems can be made. These
remarks will appear at the end of the typeset exercise.


<!-- --- end exercise --- -->




<!-- --- begin exercise --- -->

### Some exercise without the "Exercise:" prefix

<!-- Another minimalistic exercise -->

Just some text. And some math saying that $e^0=1$ on a single line,
to test that math block insertion is correct:

$$
 \exp{(0)} = 1 
$$

And a test that the code `lambda x: x+2` is correctly placed here:


~~~
lambda x: x+2
~~~

<!-- Have some comments at the end of the exercise to see that -->
<!-- the Filename: ... is written correctly. -->
<!-- --- end exercise --- -->




<!-- --- begin exercise --- -->

### Exercise 8: Solution of differential equation
<div id="sec:this:exer:de"></div>



Given

$$
 \frac{dy}{dx} = -y(x),\quad y(0)=1 
$$
What is the solution of this equation?

**Choice A:**
 $y=e^{-y}$

**Choice B:**
 $y=e^{y}$

**Choice C:**
 ~~~{.Python}
from math import exp
def f(x):
    return exp(x)
~~~

**Choice D:**
 The solution cannot be found because there is a derivative in the equation.

**Choice E:**
 The equation is meaningless: an equation must be an equation
for $x$ or $y$, not a function $y(x)$.



<!-- --- end exercise --- -->




<!-- --- begin exercise --- -->

### Example 9: Just an example

<!-- This example needs the --examples_as_exercises option, otherwise -->
<!-- it is just typeset as it is written. -->


*a)*
What is the capital of Norway?

*Answer.*
Oslo.

<!-- --- end exercise --- -->


## Here goes another section

With some text, before we continue with exercises.

## More Exercises



<!-- --- begin exercise --- -->

### Exercise 10: Make references to projects and problems
<div id="exer:some:formula"></div>

<!-- Test comments not at the end only -->
Pick a statement from [Project 5: Explore Distributions of Random Circles](#proj:circle1) or [Problem 2: Flip a Coin](#demo:ex:1)
and verify it.

Test list at the end of an exercise without other elements (like subexercise,
hint, etc.):

1. item1
2. item2

Filename: `verify_formula.py`.

<!-- --- end exercise --- -->




<!-- --- begin exercise --- -->

### Project 11: References to [Project 4: Compute a Probability](#demo:ex:2) in a heading works for pandoc
<div id="exer:you"></div>

Refer to the previous exercise as [Exercise 10: Make references to projects and problems](#exer:some:formula),
the two before that as [Project 4: Compute a Probability](#demo:ex:2) and [Project 5: Explore Distributions of Random Circles](#proj:circle1),
and this one as [Project 11: References to Project [demo:ex:2](#demo:ex:2) in a heading works for pandoc](#exer:you).
Filename: `selc_composed.pdf`.

<!-- --- end exercise --- -->


## References

 1. <div id="Langtangen_Pedersen_2002"></div> **H. P. Langtangen and G. Pedersen**. 
    Propagation of Large Destructive Waves,
    *International Journal of Applied Mechanics and Engineering*,
    7(1),
    pp. 187-204,
    2002.
 2. <div id="Langtangen_et_al_2002"></div> **H. P. Langtangen, K.-A. Mardal and R. Winther**. 
    Numerical Methods for Incompressible Viscous Flow,
    *Advances in Water Resources*,
    25,
    pp. 1125-1146,
    2002.
 3. <div id="Langtangen_1994a"></div> **H. P. Langtangen**. 
    Numerical Solution of First Passage Problems in Random Vibrations,
    *SIAM Journal of Scientific and Statistical Computing*,
    15,
    pp. 997-996,
    1994.
 4. <div id="Mardal_et_al_2003a"></div> **K.-A. Mardal, G. W. Zumbusch and H. P. Langtangen**. 
    Software Tools for Multigrid Methods,
    *Advanced Topics in Computational Partial Differential Equations -- Numerical Methods and Diffpack Programming*,
    edited by **H. P. Langtangen and A. Tveito**,
    Springer,
    2003,
    Edited book,
    <http://some.where.org>.
 5. <div id="Langtangen_1988d"></div> **H. P. Langtangen**. 
    The FEMDEQS Program System,
    *Department of Mathematics, University of Oslo*,
    1989,
    <http://www.math.uio.no/old/days/hpl/femdeqs.pdf>.
 6. <div id="Langtangen_1992c"></div> **H. P. Langtangen**. 
    Stochastic Breakthrough Time Analysis of an Enhanced Oil Recovery Process,
    *SIAM Journal on Scientific Computing*,
    13,
    pp. 1394-1417,
    1992.
 7. <div id="Mortensen_et_al_2011"></div> **M. Mortensen, H. P. Langtangen and G. N. Wells**. 
    A FEniCS-Based Programming Framework for Modeling Turbulent Flow by the Reynolds-Averaged Navier-Stokes Equations,
    *Advances in Water Resources*,
    34(9),
    [doi: 10.1016/j.advwatres.2011.02.013](https://dx.doi.org/10.1016/j.advwatres.2011.02.013),
    2011.
 8. <div id="Glimsdal_et_al_20006"></div> **S. Glimsdal, G. Pedersen, K. Atakan, C. B. Harbitz, H. P. Langtangen and F. L\ovholt**. 
    Propagation of the Dec.\ 26, 2004 Indian Ocean Tsunami: Effects of Dispersion and Source Characteristics,
    *International Journal of Fluid Mechanics Research*,
    33(1),
    pp. 15-43,
    2006.
 9. <div id="Rahman_et_al_2006b"></div> **S. Rahman, J. Gorman, C. H. W. Barnes, D. A. Williams and H. P. Langtangen**. 
    Numerical Investigation of a Piezoelectric Surface Acoustic Wave Interaction With a One-Dimensional Channel,
    *Physical Review B: Condensed Matter and Materials Physics*,
    74,
    2006,
    035308.
10. <div id="Haga_et_al_2011a"></div> **J. B. Haga, H. Osnes and H. P. Langtangen**. 
    On the Causes of Pressure Oscillations in Low-Permeable and Low-Compressible Porous Media,
    *International Journal of Analytical and Numerical Methods in Geomechanics*,
    [doi: 10.1002/nag.1062](https://dx.doi.org/10.1002/nag.1062),
    2011,
    <http://onlinelibrary.wiley.com/doi/10.1002/nag.1062/abstract>.
11. <div id="Langtangen_2003a"></div> **H. P. Langtangen**. 
    *Computational Partial Differential Equations - Numerical Methods and Diffpack Programming*,
    second edition,
    *Texts in Computational Science and Engineering*,
    Springer,
    2003.
12. <div id="Langtangen_2008a"></div> **H. P. Langtangen**. 
    *Python Scripting for Computational Science*,
    third edition,
    *Texts in Computational Science and Engineering*,
    Springer,
    2008.
13. <div id="Langtangen:95"></div> **H. P. Langtangen and G. Pedersen**. 
    Finite Elements for the Boussinesq Wave Equations,
    Waves and Non-linear Processes in Hydrodynamics,
    edited by **J. Grue, B. Gjevik and J. E. Weber**,
    Kluwer Academic Publishers,
    pp. pp. 117-126,
    1995,
    <http://www.amazon.ca/Waves-Nonlinear-Processes-Hydrodynamics-John/dp/0792340310>.
14. <div id="Langtangen_2012"></div> **H. P. Langtangen**. 
    *A Primer on Scientific Programming With Python*,
    third edition,
    *Texts in Computational Science and Engineering*,
    Springer,
    2012.
15. <div id="Jeberg_et_al_2004"></div> **P. V. Jeberg, H. P. Langtangen and C. B. Terp**. 
    Optimization With Diffpack: Practical Example From Welding,
    *Simula Research Laboratory*,
    2004,
    Internal report.
16. <div id="Langtangen_1989e"></div> **H. P. Langtangen**. 
    Computational Methods for Two-Phase Flow in Oil Reservoirs,
    Ph.D. Thesis,
    Mechanics Division, Department of Mathematics, University of Oslo,
    1989,
    Dr.\ Scient.\ thesis..
17. <div id="Langtangen_talk_2007a"></div> **H. P. Langtangen**. 
    Computational Modeling of Huge Tsunamis From Asteroid Impacts,
    2007,
    Invited keynote lecture at the \emphInternational conference on Computational Science 2007 (ICCS'07), Beijing, China.
18. <div id="Langtangen:85"></div> **H. P. Langtangen**. 
    Solution of the Navier-Stokes Equations With the Finite Element Method in Two and Three Dimensions,
    M.Sc. Thesis,
    Mechanics Division, Department of Mathematics, University of Oslo,
    1985,
    Cand.Scient. thesis.
19. <div id="Langtangen:91"></div> **H. P. Langtangen and A. Tveito**. 
    Numerical Methods in Continuum Mechanics,
    *Center for Industrial Research*,
    1991,
    Lecture notes for a course (ME-IN 324). 286 pages..
20. <div id="Langtangen:94b"></div> **H. P. Langtangen**. 
    Diffpack: Software for Partial Differential Equations,
    *Proceedings of the Second Annual Object-Oriented Numerics Conference (OON-SKI'94), Sunriver, Oregon, USA*,
    edited by **A. Vermeulen**,
    1994.

## Appendix: Just for testing; part I
<div id="app1"></div>

This is the first appendix.

### A subsection within an appendix

Some text.

## Appendix: Just for testing; part II
<div id="app2"></div>

This is more stuff for an appendix.

### Appendix: Testing identical titles

Without label.


### Appendix: Testing identical titles
<div id="test:title:id1"></div>

With label.

### Appendix: Testing identical titles
<div id="test:title:id2"></div>

What about inserting a quiz?



## Test of quizzes


**Fundamental test:** What is the capital of Norway?

**Answer 1:**
 Stockholm

**Answer 2:**
 London

**Answer 3:**
 Oslo

**Choice D:**
 Bergen




### Appendix: Testing identical titles

Without label.

*Tip.* 
Here is a tip or hint box, typeset as a notice box.





Need a lot of text to surround the summary box.
Version control systems allow you to record the history of files
and share files among several computers and collaborators in a
professional way. File changes on one computer are updated or
merged with changes on another computer. Especially when working
with programs or technical reports it is essential
to have changes documented and to
ensure that every computer and person involved in the project
have the latest updates of the files.
Greg Wilson' excellent [Script for Introduction to Version Control](https://software-carpentry.org/2010/07/script-for-introduction-to-version-control/) provides a more detailed motivation why you will benefit greatly
from using version control systems.

*Summary.* 
**Bold remark:** Make some text with this summary.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.



Projects that you want to share among several computers or project
workers are today most conveniently stored at some web site "in the
cloud" and updated through communication with that site. I strongly
recommend you to use such sites for all serious programming and
scientific writing work - and all other important files.

The simplest services for hosting project files are [Dropbox](https://dropbox.com) and [Google Drive](https://drive.google.com).
It is very easy to get started with these systems, and they allow you
to share files among laptops and mobile units with as many users as
you want. The systems offer a kind of version control in that the
files are stored frequently (several times per minute), and you can go
back to previous versions for the last 30 days. However, it is
challenging  to find the right version from the past when there are
so many of them.

More seriously, when several people may edit files simultaneously, it
can be difficult detect who did what when, roll back to previous
versions, and to manually merge the edits when these are
incompatible. Then one needs more sophisticated tools than Dropbox or
Google Drive: project hosting services with true version control
systems.  The following text aims at providing you with the minimum
information to started with such systems. Numerous other tutorials
contain more comprehensive material and in-depth explanations of the
concepts and tools.

The idea with project hosting services is that you have the files
associated with a project in the cloud. Many people may share these
files.  Every time you want to work on the project you explicitly
update your version of the files, edit the files as you like, and
synchronize the files with the "master version" at the site where the
project is hosted.  If you at some point need to go back to a
version of the files at some particular point in the past,
this is an easy operation. You can also use tools to see
what various people have done with the files in the various versions.

All these services are very similar. Below we describe how you get
started with Bitbucket, GitHub, and Googlecode. Launchpad works very
similarly to the latter three. All the project hosting services have
excellent introductions available at their web sites, but the recipes
below are much shorter and aim at getting you started as quickly as
possible by concentrating on the most important need-to-know steps.
The Git tutorials we refer to later in this document contain more
detailed information and constitute of course very valuable readings
when you use version control systems every day. The point now is
to get started.


### Appendix: Testing inline comments

<!-- Names can be [ A-Za-z0-9_'+-]+ -->

Projects that you want to share among several computers or project
workers are today most conveniently stored at some web site "in the
cloud" and updated through communication with that
site. [hpl's semi opinion 1: not sure if in the cloud is
understood by
all.] I strongly recommend you to use such sites for all serious
programming and scientific writing work - and all other important
files.

The simplest services for hosting project files is Dropbox. [mp 2: Simply go to <https://dropbox.com> and watch the video. It explains
how files, like `myfile.py`, perhaps containing much math, like
$\partial u/\partial t$, are easily communicated between machines.] It
is very easy to get started with Dropbox, and it allows you to share
files among [hpl 3: laptops and mobile units -> computers, tablets,
and phones].

<!-- Test horizontal rule -->

------

<!-- Coments for editing -->

First[add 4: ,] consider a quantity $Q$. [edit 5: To this end, -> We note that]
$Q>0$, because [del 6: a] negative [edit 7: quantity is -> quantities
are] [del 8: just] negative. [add 9: This comes as no surprise.]

<!-- Test tailored latex figure references with page number -->
Let us refer to [Figure](#fig:impact) again.

Test references in a list:

 * [Section 1](#sec1)
 * [Subsection 1](#subsec1)
 * [fig:impact](#fig:impact)

### Appendix: Testing headings ending with `verbatim inline`

The point here is to test 1) `verbatim` code in headings, and 2)
ending a heading with verbatim code as this triggers a special
case in LaTeX.

We also test mdash&mdash;used as alternative to hyphen without spaces around,
or in quotes:

> *Fun is fun*.&mdash;Unknown.



The ndash should also be tested &ndash; as in the Hanson&ndash;Nilson equations
on page 277&ndash;278.

And finally, what about admons, quotes, and boxes? They are tested
in a separate document: `admon.do.txt`.

[^example-of-the-third-footnote]: Not much to add here, but the footnote
is at the end with only one newline.

************** File: testdoc.ipynb *****************
{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<!-- dom:TITLE: A Document for Testing DocOnce -->\n",
    "# A Document for Testing DocOnce\n",
    "<!-- dom:AUTHOR: Hans Petter Langtangen Email:hpl@simula.no at Center for Biomedical Computing, Simula Research Laboratory & Department of Informatics, University of Oslo -->\n",
    "<!-- Author: -->  \n",
    "**Hans Petter Langtangen** (email: `hpl@simula.no`), Center for Biomedical Computing, Simula Research Laboratory and Department of Informatics, University of Oslo  \n",
    "<!-- dom:AUTHOR: Kaare Dump at Segfault, Cyberspace -->\n",
    "<!-- Author: --> **Kaare Dump**, Segfault, Cyberspace  \n",
    "<!-- dom:AUTHOR: A. Dummy Author -->\n",
    "<!-- Author: --> **A. Dummy Author**  \n",
    "<!-- dom:AUTHOR: I. S. Overworked and Outburned at Inst1 & Inst2, Somewhere & Third Inst, Elsewhere & Fourth Inst -->\n",
    "<!-- Author: --> **I. S. Overworked and Outburned**, Inst1 and Inst2, Somewhere and Third Inst, Elsewhere and Fourth Inst  \n",
    "<!-- dom:AUTHOR: J. Doe Email:j_doe@cyberspace.com -->\n",
    "<!-- Author: --> **J. Doe** (email: `j_doe@cyberspace.com`)\n",
    "\n",
    "Date: **Jan 32, 2100**\n",
    "\n",
    "Made with DocOnce\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "The format of this document is\n",
    "ipynb\n",
    "\n",
    "**Abstract.** This is a document with many test constructions for doconce syntax.\n",
    "It was used heavily for the development and kept for testing\n",
    "numerous constructions, also special and less common cases.\n",
    "\n",
    "And exactly for test purposes we have an extra line here, which\n",
    "is part of the abstract.\n",
    "\n",
    "<!-- Cannot demonstrate chapter headings since abstract and chapter -->\n",
    "<!-- are mutually exclusive in LaTeX -->\n",
    "\n",
    "\n",
    "\n",
    "# Section 1\n",
    "<div id=\"sec1\"></div>\n",
    "\n",
    "Here is a nested list:\n",
    "\n",
    "  * item1\n",
    "\n",
    "  * item2\n",
    "\n",
    "  * item3 which continues\n",
    "    on the next line to test that feature\n",
    "\n",
    "  * and a sublist\n",
    "\n",
    "    * with indented subitem1\n",
    "\n",
    "    * and a subitem2\n",
    "\n",
    "\n",
    "  * and perhaps an ordered sublist\n",
    "\n",
    "a. first item\n",
    "\n",
    "b. second item,\n",
    "      continuing on a new line\n",
    "\n",
    "\n",
    "**Here is a list with paragraph heading.**\n",
    "\n",
    "  * item1\n",
    "\n",
    "  * item2\n",
    "\n",
    "### Here is a list with subsubsection heading\n",
    "\n",
    "  * item1\n",
    "\n",
    "  * item2\n",
    "\n",
    "> Here are two lines that make up\n",
    "> a block quote for testing *emphasized words* and **boldface words**,\n",
    "> also with hypens:\n",
    "> *pre*-fix, post-*fix*, **pre**-fix, post-**fix**.\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "Here are two references. Equation ([6](#my:eq1)) is fine. Eq. ([6](#my:eq1)) too.\n",
    "Even Equation ([6](#my:eq1)) without the tilde.\n",
    "\n",
    "\n",
    "## Subsection 1\n",
    "<div id=\"subsec1\"></div>\n",
    "\n",
    "\n",
    "<!-- Refer to section/appendix etc. at the beginning of the line -->\n",
    "<!-- and other special fix situations for HTML. -->\n",
    "\n",
    "More text, with a reference back to\n",
    "the section [Section 1](#sec1) and [Subsection 1](#subsec1), and further to the\n",
    "the sections [Subsection 1](#subsec1) and [URLs](#subsubsec:ex), which\n",
    "encourages you to do the tasks in [Problem 2: Flip a Coin](#demo:ex:1) and [Exercise 10: Make references to projects and problems](#exer:some:formula).\n",
    " [Appendix: Just for testing; part I](#app1) and [Appendix: Just for testing; part II](#app2) are also nice elements.\n",
    "\n",
    "### Test Section reference at beginning of line and after a sentence\n",
    "\n",
    "The section [Subsection 1](#subsec1) is fine.\n",
    "The section [URLs](#subsubsec:ex) too.\n",
    "\n",
    "\n",
    "<!-- sphinx code-blocks: pycod=python cod=fortran cppcod=c++ sys=console -->\n",
    "\n",
    "### Computer code\n",
    "\n",
    "Let's do some copying from files too. First from subroutine up to the very end,"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "              subroutine test()\n",
    "              integer i\n",
    "              real*8 r\n",
    "              r = 0\n",
    "              do i = 1, i\n",
    "                 r = r + i\n",
    "              end do\n",
    "              return\n",
    "        C     END1\n",
    "        \n",
    "              program testme\n",
    "              call test()\n",
    "              return\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "and then just the subroutine,"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "        \n",
    "              subroutine test()\n",
    "              integer i\n",
    "              real*8 r\n",
    "              r = 0\n",
    "              do i = 1, i\n",
    "                 r = r + i\n",
    "              end do\n",
    "              return\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "and finally the complete file with a plain text verbatim environment\n",
    "(`envir=ccq`):"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "        C     a comment\n",
    "        \n",
    "              subroutine test()\n",
    "              integer i\n",
    "              real*8 r\n",
    "              r = 0\n",
    "              do i = 1, i\n",
    "                 r = r + i\n",
    "              end do\n",
    "              return\n",
    "        C     END1\n",
    "        \n",
    "              program testme\n",
    "              call test()\n",
    "              return\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Testing other code environments. First Python:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "        !bc pycod\n",
    "        def f(x):\n",
    "            return x+1\n",
    "        !ec\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "which gets rendered as"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```Python\n",
    "        def f(x):\n",
    "            return x+1\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Test paragraph and subsubsection headings before\n",
    "before code.\n",
    "\n",
    "**Paragraph heading before code.**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```Python\n",
    "        import sys\n",
    "        sys.path.insert(0, os.pardir)\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Subsubsection heading before code"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```Python\n",
    "        def h(z):\n",
    "            return z+1\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here is a program that is supposed to be interactive via\n",
    "Python Online Tutorial, but that service is not accessible\n",
    "for the present format."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "editable": true
   },
   "outputs": [],
   "source": [
    "class Line:\n",
    "    def __init__(self, a, b):\n",
    "        self.a, self.b = a, b\n",
    "\n",
    "    def __call__(self, x):\n",
    "        a, b = self.a, self.b\n",
    "        return a*x + b\n",
    "\n",
    "line = Line(2, 1)\n",
    "y = line(x=3)\n",
    "print(y)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Some more Python code (actually specified as a sage cell, but\n",
    "such cells are not supported by this format)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "editable": true
   },
   "outputs": [],
   "source": [
    "%matplotlib inline\n",
    "\n",
    "a = 2\n",
    "b = 3\n",
    "print('a+b:', a + b)\n",
    "\n",
    "# In a sage cell we can also plot\n",
    "from matplotlib.pyplot import *\n",
    "from numpy import *\n",
    "x = linspace(0, 4*pi, 101)\n",
    "y = exp(-0.1*x)*cos(x)\n",
    "plot(x, y)\n",
    "xlabel('x'); ylabel('y')\n",
    "show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then Cython (with -h option so it is hidden in html/sphinx):"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "        cpdef f(double x):\n",
    "            return x + 1\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Standard Python shell sessions:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "editable": true
   },
   "outputs": [],
   "source": [
    "from numpy import linspace, sin\n",
    "# Some comment\n",
    "x = linspace(0, 2, 11)\n",
    "y = sin(x)\n",
    "y[0]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Similar IPython sessions:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "editable": true
   },
   "outputs": [],
   "source": [
    "from numpy import linspace, sin\n",
    "# Some comment\n",
    "x = linspace(0, 2, 11)\n",
    "y = sin(x)\n",
    "y[0]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "editable": true
   },
   "outputs": [],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "plt.plot(x, y)\n",
    "a='multiple-\\nline\\noutput'\n",
    "a"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "editable": true
   },
   "outputs": [],
   "source": [
    "print(a)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here is the interactive session again, but with `pyshell-t`.\n",
    "This makes a significant difference in the Jupyter Notebook, but\n",
    "not in other formats: code is not typset in cells, but printed\n",
    "verbatim in plain text (`-t` for text)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```Python\n",
    "        >>> from numpy import linspace, sin\n",
    "        >>> # Some comment\n",
    "        >>> x = linspace(0, 2, 11)\n",
    "        >>> y = sin(x)\n",
    "        >>> y[0]\n",
    "        0\n",
    "        >>> import matplotlib.pyplot as plt\n",
    "        >>> plt.plot(x, y)\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<!-- This one tests a + sign before a code environment -->\n",
    "C++:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```Cpp\n",
    "        #include <iostream>\n",
    "        \n",
    "        int main()\n",
    "        {\n",
    "           std::cout << \"Sample output\" << std::endl;\n",
    "           return 0\n",
    "        }\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<!-- The next should get correctly typset in sphinx (cod is fcod) -->\n",
    "<!-- It also tests emoji before code -->\n",
    "And a little bit of Fortran: :dizzy_face:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "        !bc cod\n",
    "              subroutine midpt(x, length, a, b)\n",
    "              real*8 a, b, x\n",
    "              x = (a + b)/2\n",
    "              length = b - a\n",
    "              return\n",
    "              end\n",
    "        !ec\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "which then is typeset as"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```Python\n",
    "        subroutine midpt(x, length, a, b)\n",
    "              real*8 a, b, x\n",
    "              x = (a + b)/2\n",
    "              length = b - a\n",
    "              return\n",
    "              end\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "HTML:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "        <table>\n",
    "        <tr><td>Column 1</td><td>Column 2</td></tr>\n",
    "        <tr><td>0.67526 </td><td>0.92871 </td></tr>\n",
    "        <!-- comment -->\n",
    "        </table>\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "But inline HTML code is also important, like text that starts with\n",
    "`<a href=\"` (which can destroy the following text if not properly\n",
    "quoted).\n",
    "\n",
    "Matlab with comments requires special typesetting:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "        % Comment on the beginning of the line can be escaped by %%\n",
    "        if a > b\n",
    "          % Indented comment needs this trick\n",
    "          c = a + b\n",
    "        end\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And here is a system call:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```\n",
    "        Terminal> mkdir test\n",
    "        Terminal> cd test\n",
    "        Terminal> myprog -f\n",
    "        output1\n",
    "        output2\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Any valid pygments lexer/language name can appear to, e.g.,"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "        !bc restructuredtext\n",
    "        =======\n",
    "        Heading\n",
    "        =======\n",
    "        \n",
    "        Some text.\n",
    "        !ec\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "results in"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "        =======\n",
    "        Heading\n",
    "        =======\n",
    "        \n",
    "        Some text.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<!-- Here goes hidden code. -->\n",
    "<!-- Python can be treated by some formats, Fortran is always out. -->"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "def f(x):\n",
    "    \"\"\"Secret, hidden function to be defined.\"\"\"\n",
    "    return 42"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally, `!bc do` supports highlighting of DocOnce source:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "        ======= DocOnce test file =======\n",
    "        \n",
    "        ===== Computer code =====\n",
    "        \n",
    "        Inline verbatim code, as in `import numpy as np`, is allowed, as well as\n",
    "        code blocks:\n",
    "        \n",
    "        !bc pycod\n",
    "        from math import sin\n",
    "        \n",
    "        def f(x):\n",
    "            \"\"\"Example on a function.\"\"\"\n",
    "            return sin(x) + 1\n",
    "        \n",
    "        print(f(0))\n",
    "        !ec\n",
    "        \n",
    "        \n",
    "        ===== Mathematics =====\n",
    "        \n",
    "        Formulas can be inline, as in $\\nabla\\cdot\\boldsymbol{u} = 0$, or typeset\n",
    "        as equations:\n",
    "        \n",
    "        !bt\n",
    "        \\begin{align*}\n",
    "        \\nabla\\cdot\\boldsymbol{u} &= 0,\\\\\n",
    "        \\boldsymbol{u} &= \\nabla\\phi .\n",
    "        \\end{align*}\n",
    "        !et\n",
    "        \n",
    "        === Subsubsection heading ===\n",
    "        \n",
    "        DocOnce files can have chapters, sections, subsections, and subsubsections.\n",
    "        \n",
    "        __Paragraph heading.__ Paragraphs may have headings.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It is time to test `verbatim inline font` especially with `a newline\n",
    "inside the text` and an exclamation mark at the end: `BEGIN`! For\n",
    "spellcheck, test `a verbatim expression` in `another` in a `third`.\n",
    "Also test exclamation mark as in `!bc` and `!ec` as well as `a != b`.\n",
    "Also test backslashes and braces like `\\begin`, `\\begin{enumerate}`,\n",
    "`\\end{this}\\end{that}`, and `{something \\inside braces}`.\n",
    "\n",
    "The following attempt to exemplify colored text does not work in\n",
    "format ipynb.\n",
    "Here is some <font color=\"red\">red color</font> and an attempt to write <font color=\"green\">with\n",
    "green color containing a linebreak\n",
    "code.</font> Some formats will only display \n",
    "this correctly when `html` \n",
    "is the output format.\n",
    "But here some more running text is added which is not part of\n",
    "the previous blocks with line breaks.\n",
    "\n",
    "### Running OS commands"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "        Terminal> python -c 'print(\"Testing\\noutput\\nfrom\\nPython.\")'\n",
    "        Testing\n",
    "        output\n",
    "        from\n",
    "        Python.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Footnotes\n",
    "\n",
    "Here is a test of footnotes [^footnote], which are handy in text.\n",
    "They are used in different flavors, now in\n",
    "\n",
    " * list items (note below that footnotes work after math, verbatim, and URLs - bin fact old and emphasize too!)\n",
    "\n",
    " * even with math $\\nabla^2u$[^math1]\n",
    "\n",
    " * and code `h[i] += 1`[^code]\n",
    "   (*must* have space between inline code and footnote!)\n",
    "\n",
    " * and [links](https://google.com)[^google-search]\n",
    "\n",
    "which gives flexibility in writing.\n",
    "This is the third[^example-of-the-third-footnote] example.\n",
    "\n",
    "  [^footnote]: Typesetting of the footnote depends on the format.\n",
    "Plain text does nothing, LaTeX removes the\n",
    "definition and inserts the footnote as part of the LaTeX text.\n",
    "reStructuredText and Sphinx employ a similar type of typesetting\n",
    "as Extended Markdown and DocOnce, and in HTML we keep the same\n",
    "syntax, just displayed properly in HTML.\n",
    "[^math1]: Math footnotes can be dangerous since it\n",
    "interferes with an exponent.\n",
    "[^code]: One-line footnote.\n",
    "\n",
    "[^google-search]: <google.com> is perhaps the most famous\n",
    "web site today.\n",
    "\n",
    "Here is some more text before a new definition of a footnote that was\n",
    "used above.\n",
    "\n",
    "**Non-breaking space character.**\n",
    "\n",
    "This paragraph aims to test [non-breaking space character](https://en.wikipedia.org/wiki/Non-breaking_space), and a typical\n",
    "example where this is needed is in physical units: 7.4 km is traveled\n",
    "in $7.4/5.5\\approx 1.345$ s.  Also check that a~[link](https://google.com) is\n",
    "not broken across lines (drag the browser window to test this).\n",
    "(On the other hand, the tilde is used in\n",
    "computer code, e.g., as in `[~x for x in y]` or in `y=~x`, and should\n",
    "of course remain a tilde in those contexts.)\n",
    "\n",
    "\n",
    "\n",
    "## Subsection 2: Testing figures\n",
    "<div id=\"subsec:ex\"></div>\n",
    "\n",
    "Test of figures. In particular we refer to [Figure 1](#fig:impact) in which\n",
    "there is a flow.\n",
    "\n",
    "<!-- dom:FIGURE:[../doc/src/manual/fig/wave1D.png, width=200] Visualization **of** a *wave*. <div id=\"fig:impact\"></div> -->\n",
    "<!-- begin figure -->\n",
    "<div id=\"fig:impact\"></div>\n",
    "<img src=\"../doc/src/manual/fig/wave1D.png\" width=200><p style=\"font-size: 0.9em\"><i>Figure 1: Visualization <b>of</b> a <em>wave</em>.</i></p><!-- end figure -->\n",
    "\n",
    "\n",
    "Figures without captions are allowed and will be inlined.\n",
    "\n",
    "<!-- dom:FIGURE:[../doc/src/manual/fig/wave1D.png, width=200] -->\n",
    "<!-- begin figure -->\n",
    "<img src=\"../doc/src/manual/fig/wave1D.png\" width=200><p style=\"font-size: 0.9em\"><i>Figure 2: </i></p><!-- end figure -->\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "<!-- Test multi-line caption in figure with sidecap=True -->\n",
    "\n",
    "Here is [figure 2](#myfig) with a long (illegal) multi-line caption\n",
    "containing inline verbatim text:\n",
    "\n",
    "<!-- dom:FIGURE: [../doc/src/manual/fig/wave1D.png, width=500 sidecap=True] A long caption spanning several lines and containing verbatim words like `my_file_v1` and `my_file_v2` as well as math with subscript as in $t_{i+1}$. <div id=\"myfig\"></div>  -->\n",
    "<!-- begin figure -->\n",
    "<div id=\"myfig\"></div>\n",
    "<img src=\"../doc/src/manual/fig/wave1D.png\" width=500><p style=\"font-size: 0.9em\"><i>Figure 2: A long caption spanning several lines and containing verbatim words like <code>my_file_v1</code> and <code>my_file_v2</code> as well as math with subscript as in $t_{i+1}$.</i></p><!-- end figure -->\n",
    "\n",
    "\n",
    "<!-- Must be a blank line after MOVIE or FIGURE to detect this problem -->\n",
    "\n",
    "Test URL as figure name:\n",
    "\n",
    "<!-- dom:FIGURE: [https://raw.github.com/doconce/doconce/master/doc/src/blog/f_plot.png, width=500 frac=0.8] -->\n",
    "<!-- begin figure -->\n",
    "<img src=\"https://raw.github.com/doconce/doconce/master/doc/src/blog/f_plot.png\" width=500><p style=\"font-size: 0.9em\"><i>Figure 3: </i></p><!-- end figure -->\n",
    "\n",
    "\n",
    "\n",
    "<!-- Test wikimedia type of files that otherwise reside in subdirs -->\n",
    "\n",
    "\n",
    "**Remark.**\n",
    "Movies are tested in separate file `movies.do.txt`.\n",
    "\n",
    "\n",
    "<!-- Somewhat challenging heading with latex math, \\t, \\n, ? and parenthesis -->\n",
    "\n",
    "## The $\\theta$ parameter (not $\\nabla$?)\n",
    "<div id=\"decay:sec:theta\"></div>\n",
    "\n",
    "Functions do not always need to be advanced, here is one\n",
    "involving $\\theta$:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "        def f(theta):\n",
    "            return theta**2\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**More on $\\theta$.** Here is more text following headline with math.\n",
    "\n",
    "Newcommands must also be tested in this test report:\n",
    "$\\frac{1}{2}$, ${1/2}$, $\\pmb{x}$, $\\frac{Du}{dt}$,\n",
    "both inline and in block:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "$$\n",
    "\\frac{Du}{dt} = 0\\nonumber\n",
    "$$"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<!-- Equation labels as ordinary links -->\n",
    "<div id=\"_auto1\"></div>\n",
    "\n",
    "$$\n",
    "\\begin{equation}  \n",
    "\\frac{1}{2} = {1/2}\n",
    "\\label{_auto1} \\tag{1}\n",
    "\\end{equation}\n",
    "$$"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<!-- Equation labels as ordinary links -->\n",
    "<div id=\"_auto2\"></div>\n",
    "\n",
    "$$\n",
    "\\begin{equation}  \n",
    "\\frac{1}{2}\\pmb{x} = \\pmb{n}\n",
    "\\label{_auto2} \\tag{2}\n",
    "\\end{equation}\n",
    "$$"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Or with align with label and numbers:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<!-- Equation labels as ordinary links -->\n",
    "<div id=\"aligneq1\"></div>\n",
    "\n",
    "$$\n",
    "\\begin{equation}\n",
    "\\frac{Du}{dt} = 0\n",
    "\\label{aligneq1} \\tag{3}\n",
    "\\end{equation}\n",
    "$$"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<!-- Equation labels as ordinary links -->\n",
    "<div id=\"_auto3\"></div>\n",
    "\n",
    "$$\n",
    "\\begin{equation}  \n",
    "\\frac{1}{2} = {1/2}\n",
    "\\label{_auto3} \\tag{4}\n",
    "\\end{equation}\n",
    "$$"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<!-- Equation labels as ordinary links -->\n",
    "<div id=\"aligneq2\"></div>\n",
    "\n",
    "$$\n",
    "\\begin{equation}  \n",
    "\\frac{1}{2}\\pmb{x} = \\pmb{n}\n",
    "\\label{aligneq2} \\tag{5}\n",
    "\\end{equation}\n",
    "$$"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Custom Environments\n",
    "\n",
    "Here is an attempt to create a theorem environment via Mako\n",
    "(for counting theorems) and comment lines to help replacing lines in\n",
    "the `.tex` by proper begin-end LaTeX environments for theorems.\n",
    "Should look nice in most formats!\n",
    "\n",
    "\n",
    "\n",
    "<!-- begin theorem -->\n",
    "<div id=\"theorem:fundamental1\"></div>\n",
    "\n",
    "\n",
    "**Theorem 5.**\n",
    "Let $a=1$ and $b=2$. Then $c=3$.\n",
    "<!-- end theorem -->\n",
    "\n",
    "<!-- begin proof -->\n",
    "**Proof.**\n",
    "Since $c=a+b$, the result follows from straightforward addition.\n",
    "$\\Diamond$\n",
    "<!-- end proof -->\n",
    "\n",
    "As we see, the proof of Theorem 5 is a modest\n",
    "achievement.\n",
    "\n",
    "\n",
    "## Tables\n",
    "<div id=\"subsec:table\"></div>\n",
    "\n",
    "\n",
    "<!-- index with comma could fool sphinx -->\n",
    "\n",
    "Let us take this table from the manual:\n",
    "\n",
    "\n",
    "<table border=\"1\">\n",
    "<thead>\n",
    "<tr><th align=\"center\">time</th> <th align=\"center\">velocity</th> <th align=\"center\">acceleration</th> </tr>\n",
    "</thead>\n",
    "<tbody>\n",
    "<tr><td align=\"left\">   0.0     </td> <td align=\"right\">   1.4186      </td> <td align=\"right\">   -5.01           </td> </tr>\n",
    "<tr><td align=\"left\">   2.0     </td> <td align=\"right\">   1.376512    </td> <td align=\"right\">   11.919          </td> </tr>\n",
    "<tr><td align=\"left\">   4.0     </td> <td align=\"right\">   1.1E+1      </td> <td align=\"right\">   14.717624       </td> </tr>\n",
    "</tbody>\n",
    "</table>\n",
    "\n",
    "The DocOnce source code reads"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "        \n",
    "          |--------------------------------|\n",
    "          |time  | velocity | acceleration |\n",
    "          |--l--------r-----------r--------|\n",
    "          | 0.0  | 1.4186   | -5.01        |\n",
    "          | 2.0  | 1.376512 | 11.919       |\n",
    "          | 4.0  | 1.1E+1   | 14.717624    |\n",
    "          |--------------------------------|\n",
    "        \n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here is yet another table to test that we can handle more than\n",
    "one table:\n",
    "\n",
    "<table border=\"1\">\n",
    "<thead>\n",
    "<tr><th align=\"left\">time</th> <th align=\"left\">velocity</th> <th align=\"left\">acceleration</th> </tr>\n",
    "</thead>\n",
    "<tbody>\n",
    "<tr><td align=\"left\">   0.0     </td> <td align=\"left\">   1.4186      </td> <td align=\"left\">   -5.01           </td> </tr>\n",
    "<tr><td align=\"left\">   1.0     </td> <td align=\"left\">   1.376512    </td> <td align=\"left\">   11.919          </td> </tr>\n",
    "<tr><td align=\"left\">   3.0     </td> <td align=\"left\">   1.1E+1      </td> <td align=\"left\">   14.717624       </td> </tr>\n",
    "</tbody>\n",
    "</table>\n",
    "And one with math headings (that are expanded and must be treated\n",
    "accordingly), verbatim heading and entry, and no space around the pipe\n",
    "symbol:\n",
    "\n",
    "<table border=\"1\">\n",
    "<thead>\n",
    "<tr><th align=\"center\">$i$</th> <th align=\"center\">$h_i$ </th> <th align=\"center\">$\\bar T_i$</th> <th align=\"center\"> <code>L_i</code> </th> </tr>\n",
    "</thead>\n",
    "<tbody>\n",
    "<tr><td align=\"left\">   0      </td> <td align=\"right\">   0         </td> <td align=\"right\">   288           </td> <td align=\"right\">   -0.0065    </td> </tr>\n",
    "<tr><td align=\"left\">   1      </td> <td align=\"right\">   11,000    </td> <td align=\"right\">   216           </td> <td align=\"right\">   0.0        </td> </tr>\n",
    "<tr><td align=\"left\">   2      </td> <td align=\"right\">   20,000    </td> <td align=\"right\">   216           </td> <td align=\"right\">   0.001      </td> </tr>\n",
    "<tr><td align=\"left\">   3      </td> <td align=\"right\">   32,000    </td> <td align=\"right\">   228           </td> <td align=\"right\">   0.0028     </td> </tr>\n",
    "<tr><td align=\"left\">   4      </td> <td align=\"right\">   47,000    </td> <td align=\"right\">   270           </td> <td align=\"right\">   0.0        </td> </tr>\n",
    "<tr><td align=\"left\">   5      </td> <td align=\"right\">   51,000    </td> <td align=\"right\">   270           </td> <td align=\"right\">   -0.0028    </td> </tr>\n",
    "<tr><td align=\"left\">   6      </td> <td align=\"right\">   71,000    </td> <td align=\"right\">   214           </td> <td align=\"right\">   <code>NaN</code>      </td> </tr>\n",
    "</tbody>\n",
    "</table>\n",
    "And add one with verbatim headings (with underscores),\n",
    "and rows starting with `|-` because of a negative number,\n",
    "and `|` right before and after verbatim word (with no space):\n",
    "\n",
    "<table border=\"1\">\n",
    "<thead>\n",
    "<tr><th align=\"center\">exact</th> <th align=\"center\"><code>v_1</code> </th> <th align=\"center\">$a_i$ + <code>v_2</code></th> <th align=\"center\"><code>verb_3_</code></th> </tr>\n",
    "</thead>\n",
    "<tbody>\n",
    "<tr><td align=\"right\">   9        </td> <td align=\"right\">   9.62      </td> <td align=\"right\">   5.57             </td> <td align=\"right\">   8.98         </td> </tr>\n",
    "<tr><td align=\"right\">   -20      </td> <td align=\"right\">   -23.39    </td> <td align=\"right\">   -7.65            </td> <td align=\"right\">   -19.93       </td> </tr>\n",
    "<tr><td align=\"right\">   10       </td> <td align=\"right\">   17.74     </td> <td align=\"right\">   -4.50            </td> <td align=\"right\">   9.96         </td> </tr>\n",
    "<tr><td align=\"right\">   0        </td> <td align=\"right\">   -9.19     </td> <td align=\"right\">   4.13             </td> <td align=\"right\">   -0.26        </td> </tr>\n",
    "</tbody>\n",
    "</table>\n",
    "Pipe symbols in verbatim and math text in tables used to pose difficulties,\n",
    "but not\n",
    "anymore:\n",
    "\n",
    "<table border=\"1\">\n",
    "<thead>\n",
    "<tr><th align=\"center\">    $S$    </th> <th align=\"center\">   command   </th> </tr>\n",
    "</thead>\n",
    "<tbody>\n",
    "<tr><td align=\"left\">   $ ||a_0|| $    </td> <td align=\"right\">   <code>norm|length</code>    </td> </tr>\n",
    "<tr><td align=\"left\">   $x\\cap y$      </td> <td align=\"right\">   <code>x|y</code>            </td> </tr>\n",
    "</tbody>\n",
    "</table>\n",
    "\n",
    "Here is a table with X alignment:\n",
    "\n",
    "<table border=\"1\">\n",
    "<thead>\n",
    "<tr><th align=\"center\"> Type</th> <th align=\"center\">                                                                                                     Description                                                                                                      </th> </tr>\n",
    "</thead>\n",
    "<tbody>\n",
    "<tr><td align=\"center\">   X        </td> <td align=\"left\">   Alignment character that is used for specifying a potentially very long text in a column in a table. It makes use of the <code>tabularx</code> package in LaTeX, otherwise (for other formats) it means <code>l</code> (centered alignment).    </td> </tr>\n",
    "<tr><td align=\"center\">   l,r,c    </td> <td align=\"left\">   standard alignment characters                                                                                                                                                                                             </td> </tr>\n",
    "</tbody>\n",
    "</table>\n",
    "Finally, a table with math\n",
    "and URLs.\n",
    "\n",
    "<!-- Mako code to expand URLs in the table -->\n",
    "<!-- (These types of tables did not work before Jan 2014) -->\n",
    "\n",
    "\n",
    "<table border=\"1\">\n",
    "<tr></tr>\n",
    "<tbody>\n",
    "<tr><td align=\"center\">   $\\mathcal{L}=0$                    </td> <td align=\"center\">   [<code>080</code>](../doc/src/manual/mov/wave_frames/frame_0080.png)    </td> <td align=\"center\">   [<code>085</code>](../doc/src/manual/mov/wave_frames/frame_0085.png)    </td> </tr>\n",
    "<tr><td align=\"center\">   $a=b$                              </td> <td align=\"center\">   [<code>090</code>](../doc/src/manual/mov/wave_frames/frame_0090.png)    </td> <td align=\"center\">   [<code>095</code>](../doc/src/manual/mov/wave_frames/frame_0095.png)    </td> </tr>\n",
    "<tr><td align=\"center\">   $\\nabla\\cdot\\boldsymbol{u} =0 $    </td> <td align=\"center\">   [<code>100</code>](../doc/src/manual/mov/wave_frames/frame_0100.png)    </td> <td align=\"center\">   [<code>105</code>](../doc/src/manual/mov/wave_frames/frame_0105.png)    </td> </tr>\n",
    "</tbody>\n",
    "</table>\n",
    "\n",
    "## A test of verbatim words in heading with subscript $a_i$: `my_file_v1` and `my_file_v2`\n",
    "\n",
    "**Paragraph with verbatim and math: `my_file_v1.py` and `my_file_v2.py` define some math $a_{i-1}$.** Here is more `__verbatim__` code and\n",
    "some plain text on a new line.\n",
    "\n",
    "<!-- Test various types of headlines -->\n",
    "## **Just bold**\n",
    "\n",
    "Some text.\n",
    "\n",
    "## *Just emphasize*\n",
    "\n",
    "Some text.\n",
    "\n",
    "## `Just verbatim`\n",
    "\n",
    "Some text.\n",
    "\n",
    "## **Bold** beginning\n",
    "\n",
    "Some text.\n",
    "\n",
    "## *Emphasize* beginning\n",
    "\n",
    "Some text.\n",
    "\n",
    "## `Verbatim` beginning\n",
    "\n",
    "Some text.\n",
    "\n",
    "## Maybe **bold end**\n",
    "\n",
    "Some text.\n",
    "\n",
    "## Maybe *emphasize end*\n",
    "\n",
    "Some text.\n",
    "\n",
    "## Maybe `verbatim end`\n",
    "\n",
    "Some text.\n",
    "\n",
    "## The middle has **bold** word\n",
    "\n",
    "Some text.\n",
    "\n",
    "## The middle has *emphasize* word\n",
    "\n",
    "Some text.\n",
    "\n",
    "## The middle has `verbatim` word\n",
    "\n",
    "Some text.\n",
    "\n",
    "\n",
    "***Just emphasize*.** Some text.\n",
    "\n",
    "\n",
    "**`Just verbatim`.** Some text.\n",
    "\n",
    "\n",
    "***Emphasize* beginning.** Some text.\n",
    "\n",
    "\n",
    "**`Verbatim beginning`.** Some text.\n",
    "\n",
    "\n",
    "**Maybe *emphasize end*.** Some text.\n",
    "\n",
    "\n",
    "**Maybe `verbatim end`.** Some text.\n",
    "\n",
    "\n",
    "**The middle has *emphasize* word.** Some text.\n",
    "\n",
    "\n",
    "**The middle has `verbatim` word.** Some text.\n",
    "\n",
    "\n",
    "**Ampersand.**\n",
    "We can test Hennes & Mauritz, often abbreviated H&M, but written\n",
    "as `Hennes & Mauritz` and `H & M`.\n",
    "A sole `&` must also work.\n",
    "<!-- Note: substitutions must not occur inside verbatim, just in ordinary text. -->"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "        # Just to check that ampersand works in code blocks:\n",
    "        c = a & b\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Quotes.**\n",
    "Let us also add a test of quotes such as \"double quotes, with numbers\n",
    "like 3.14 and newline/comma and hyphen (as in double-quote)\"; written\n",
    "in the standard LaTeX-style that gives correct LaTeX formatting and\n",
    "ordinary double quotes for all non-LaTeX formats.  Here is another\n",
    "sentence that \"caused\" a bug in the past because double backtick\n",
    "quotes could imply verbatim text up to a verbatim word starting with\n",
    "period, like `.txt`.\n",
    "\n",
    "More quotes to be tested for spellcheck:\n",
    "(\"with parenthesis\"), \"with newline\"\n",
    "and \"with comma\", \"hyphen\"-wise, and \"period\".\n",
    "\n",
    "\n",
    "## Bibliography test\n",
    "\n",
    "Here is an example: [[Langtangen_Pedersen_2002]](#Langtangen_Pedersen_2002) discussed propagation of\n",
    "large destructive water waves, [[Langtangen_et_al_2002]](#Langtangen_et_al_2002) gave\n",
    "an overview of numerical methods for solving the Navier - Stokes equations,\n",
    "while the use of Backward Kolmogorov equations for analyzing\n",
    "random vibrations was investigated in [[Langtangen_1994a]](#Langtangen_1994a).\n",
    "The book chapter [[Mardal_et_al_2003a]](#Mardal_et_al_2003a) contains information on\n",
    "C++ software tools for programming multigrid methods. A real retro\n",
    "reference is [[Langtangen_1988d]](#Langtangen_1988d) about a big FORTRAN package.\n",
    "Multiple references are also possible, e.g., see\n",
    "[[Langtangen_Pedersen_2002;@Mardal_et_al_2003a]](#Langtangen_Pedersen_2002;@Mardal_et_al_2003a).\n",
    "\n",
    "We need to cite more than 10 papers to reproduce an old formatting\n",
    "problem with blanks in the keys in reST format:\n",
    "[[Langtangen_1992c;@Langtangen_1994a;@Mortensen_et_al_2011;@Langtangen_Pedersen_2002]](#Langtangen_1992c;@Langtangen_1994a;@Mortensen_et_al_2011;@Langtangen_Pedersen_2002)\n",
    "and\n",
    "[[Langtangen_et_al_2002;@Glimsdal_et_al_20006;@Rahman_et_al_2006b;@Haga_et_al_2011a;@Langtangen_2003a;@Langtangen_2008a;@Langtangen:95]](#Langtangen_et_al_2002;@Glimsdal_et_al_20006;@Rahman_et_al_2006b;@Haga_et_al_2011a;@Langtangen_2003a;@Langtangen_2008a;@Langtangen:95)\n",
    "and all the work of\n",
    "[[Langtangen_2012;@Mardal_et_al_2003a;@Jeberg_et_al_2004]](#Langtangen_2012;@Mardal_et_al_2003a;@Jeberg_et_al_2004) as well as\n",
    "old work [[Langtangen_1988d]](#Langtangen_1988d) and [[Langtangen_1989e]](#Langtangen_1989e), and the\n",
    "talk [[Langtangen_talk_2007a]](#Langtangen_talk_2007a).\n",
    "Langtangen also had two thesis [[Langtangen:85;@Langtangen_1989e]](#Langtangen:85;@Langtangen_1989e)\n",
    "back in the days.\n",
    "More retro citations are\n",
    "the old ME-IN323 book [[Langtangen:91]](#Langtangen:91) and the\n",
    "[[Langtangen:94b]](#Langtangen:94b) OONSKI '94 paper.\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "<!-- --- begin exercise --- -->\n",
    "\n",
    "## Example 1: Examples can be typeset as exercises\n",
    "<div id=\"Example\"></div>\n",
    "\n",
    "Examples can start with a subsection heading starting with `Example:`\n",
    "and then, with the command-line option `--examples_as_exercises` be\n",
    "typeset as exercises. This is useful if one has solution\n",
    "environments as part of the example.\n",
    "\n",
    "\n",
    "**a)**\n",
    "State some problem.\n",
    "\n",
    "**Solution.**\n",
    "The answer to this subproblem can be written here.\n",
    "\n",
    "**b)**\n",
    "State some other problem.\n",
    "\n",
    "**Hint 1.**\n",
    "A hint can be given.\n",
    "\n",
    "**Hint 2.**\n",
    "Maybe even another hint?\n",
    "\n",
    "**Solution.**\n",
    "The answer to this other subproblem goes here,\n",
    "maybe over multiple doconce input lines.\n",
    "\n",
    "<!-- --- end exercise --- -->\n",
    "\n",
    "\n",
    "## User-defined environments\n",
    "\n",
    "\n",
    "\n",
    "The example in the section [Example 1: A test function](#ex:test:1p1) demonstrates how to write a test function.\n",
    "That is, a special test function for a function `add` appears in\n",
    "the example in the section [Example 1: A test function](#ex:test:1p1).\n",
    "\n",
    "\n",
    "\n",
    "## Example 1: A test function\n",
    "<div id=\"ex:test:1p1\"></div>\n",
    "\n",
    "Suppose we want to write a test function for checking the\n",
    "implementation of a Python function for addition."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "editable": true
   },
   "outputs": [],
   "source": [
    "def add(a, b):\n",
    "    return a + b\n",
    "\n",
    "def test_add():\n",
    "    a = 1; b = 1\n",
    "    expected = a + b\n",
    "    computed = add(a, b)\n",
    "    assert expected == computed"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Example 2: Addition\n",
    "<div id=\"ex:math:1p1\"></div>\n",
    "\n",
    "We have"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "$$\n",
    "1 + 1 = 2\n",
    "$$"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "or in tabular form:\n",
    "\n",
    "<table border=\"1\">\n",
    "<thead>\n",
    "<tr><th align=\"center\">Problem</th> <th align=\"center\">Result</th> </tr>\n",
    "</thead>\n",
    "<tbody>\n",
    "<tr><td align=\"center\">   $1+1$      </td> <td align=\"center\">   $2$       </td> </tr>\n",
    "</tbody>\n",
    "</table>\n",
    "\n",
    "\n",
    "**Highlight box!**\n",
    "\n",
    "This environment is used to highlight something:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "$$\n",
    "E = mc^2\n",
    "$$"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## URLs\n",
    "<div id=\"subsubsec:ex\"></div>\n",
    "\n",
    "Testing of URLs: hpl's home page [hpl](https://folk.uio.no/hpl), or\n",
    "the entire URL if desired, <https://folk.uio.no/hpl>.  Here is a\n",
    "plain file link <testdoc.do.txt>, or <testdoc.do.txt>, or\n",
    "<testdoc.do.txt> or <testdoc.do.txt> or [a link with\n",
    "newline](testdoc.do.txt). Can test spaces with the link with word\n",
    "too: [hpl](https://folk.uio.no/hpl) or [hpl](https://folk.uio.no/hpl). Also `file:///` works: [link to a\n",
    "file](file:///home/hpl/vc/doconce/doc/demos/manual/manual.html) is\n",
    "fine to have. Moreover, \"loose\" URLs work, i.e., no quotes, just\n",
    "the plain URL as in <https://folk.uio.no/hpl>, if followed by space, comma,\n",
    "colon, semi-colon, question mark, exclamation mark, but not a period\n",
    "(which gets confused with the periods inside the URL).\n",
    "\n",
    "Mail addresses can also be used: [`hpl@simula.no`](mailto:hpl@simula.no), or just a [mail link](mailto:hpl@simula.no), or a raw <mailto:hpl@simula.no>.\n",
    "\n",
    "Here are some tough tests of URLs, especially for the `latex` format:\n",
    "[Newton-Cotes](https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas) formulas\n",
    "and a [good book](https://www.springer.com/mathematics/computational+science+%26+engineering/book/978-3-642-23098-1). Need to test\n",
    "Newton-Cotes with percentage in URL too:\n",
    "<https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas>\n",
    "and <https://en.wikipedia.org/wiki/Newton-Cotes#Open_Newton.E2.80.93Cotes_formulae> which has a shebang.\n",
    "\n",
    "For the `--device=paper` option it is important to test that URLs with\n",
    "monospace font link text get a footnote\n",
    "(unless the `--latex_no_program_footnotelink`\n",
    "is used), as in this reference to\n",
    "[`decay_mod`](https://github.com/hplgit/INF5620/tree/gh-pages/src/decay/experiments/decay_mod.py), [`ball1.py`](https://tinyurl.com/pwyasaa/formulas.ball1.py),\n",
    "and [`ball2.py`](https://tinyurl.com/pwyasaa/formulas.ball2.py).\n",
    "\n",
    "\n",
    "<!-- Comments should be inserted outside paragraphs (because in the rst -->\n",
    "<!-- format extra blanks make a paragraph break). -->\n",
    "\n",
    "<!-- Note that when there is no https: or file:, it can be a file link -->\n",
    "<!-- if the link name is URL, url, \"URL\", or \"url\". Such files should, -->\n",
    "<!-- if rst output is desired, but placed in a `_static*` folder. -->\n",
    "\n",
    "More tough tests: repeated URLs whose footnotes when using the\n",
    "`--device=paper` option must be correct. We have\n",
    "[google](https://google.com), [google](https://google.com), and\n",
    "[google](https://google.com), which should result in exactly three\n",
    "footnotes.\n",
    "\n",
    "\n",
    "\n",
    "<!-- !split and check if these extra words are included properly in the comment -->\n",
    "\n",
    "# LaTeX Mathematics\n",
    "\n",
    "Here is an equation without label using backslash-bracket environment:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "$$\n",
    "a = b + c\n",
    "$$"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "or with number and label, as in ([6](#my:eq1)), using the equation environment:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<!-- Equation labels as ordinary links -->\n",
    "<div id=\"my:eq1\"></div>\n",
    "\n",
    "$$\n",
    "\\begin{equation}\n",
    "{\\partial u\\over\\partial t} = \\nabla^2 u \\label{my:eq1} \\tag{6}\n",
    "\\end{equation}\n",
    "$$"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can refer to this equation by ([6](#my:eq1)).\n",
    "\n",
    "Here is a system without equation numbers, using the align-asterisk environment:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "$$\n",
    "\\begin{align*}\n",
    "\\pmb{a} &= \\pmb{q}\\times\\pmb{n} \\\\ \n",
    "b &= \\nabla^2 u + \\nabla^4 v\n",
    "\\end{align*}\n",
    "$$"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "More mathematical typesetting is demonstrated in the coming exercises.\n",
    "\n",
    "Below, we have [Problem 2: Flip a Coin](#demo:ex:1) and [Project 4: Compute a Probability](#demo:ex:2),\n",
    "as well as [Project 5: Explore Distributions of Random Circles](#proj:circle1) and [Project 11: References to Project [demo:ex:2](#demo:ex:2) in a heading works for ipynb](#exer:you), and in\n",
    "between there we have [Exercise 10: Make references to projects and problems](#exer:some:formula).\n",
    "\n",
    "\n",
    "# Exercises\n",
    "\n",
    "\n",
    "\n",
    "<!-- --- begin exercise --- -->\n",
    "\n",
    "## Problem 2: Flip a Coin\n",
    "<div id=\"demo:ex:1\"></div>\n",
    "<!-- keywords = random numbers; Monte Carlo simulation; ipynb -->\n",
    "\n",
    "<!-- Torture tests -->\n",
    "\n",
    "\n",
    "**a)**\n",
    "Make a program that simulates flipping a coin $N$ times.\n",
    "Print out \"tail\" or \"head\" for each flip and\n",
    "let the program count the number of heads.\n",
    "\n",
    "<!-- --- begin hint in exercise --- -->\n",
    "\n",
    "**Hint 1.**\n",
    "Use `r = random.random()` and define head as `r <= 0.5`.\n",
    "\n",
    "<!-- --- end hint in exercise --- -->\n",
    "\n",
    "<!-- --- begin hint in exercise --- -->\n",
    "\n",
    "**Hint 2.**\n",
    "Draw an integer among $\\{1,2\\}$ with\n",
    "`r = random.randint(1,2)` and define head when `r` is 1.\n",
    "\n",
    "<!-- --- end hint in exercise --- -->\n",
    "\n",
    "\n",
    "<!-- --- begin answer of exercise --- -->\n",
    "**Answer.**\n",
    "If the `random.random()` function returns a number $<1/2$, let it be\n",
    "head, otherwise tail. Repeat this $N$ number of times.\n",
    "<!-- --- end answer of exercise --- -->\n",
    "\n",
    "\n",
    "<!-- --- begin solution of exercise --- -->\n",
    "**Solution.**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "editable": true
   },
   "outputs": [],
   "source": [
    "import sys, random\n",
    "N = int(sys.argv[1])\n",
    "heads = 0\n",
    "for i in range(N):\n",
    "    r = random.random()\n",
    "    if r <= 0.5:\n",
    "        heads += 1\n",
    "print('Flipping a coin %d times gave %d heads' % (N, heads))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<!-- --- end solution of exercise --- -->\n",
    "\n",
    "**b)**\n",
    "Vectorize the code in a) using boolean indexing.\n",
    "\n",
    "Vectorized code can be written in many ways.\n",
    "Sometimes the code is less intuitive, sometimes not.\n",
    "At least there is not much to find in the section [Section 1](#sec1).\n",
    "\n",
    "**c)**\n",
    "Vectorize the code in a) using `numpy.sum`.\n",
    "\n",
    "\n",
    "<!-- --- begin answer of exercise --- -->\n",
    "**Answer.**\n",
    "`np.sum(np.where(r <= 0.5, 1, 0))` or `np.sum(r <= 0.5)`.\n",
    "<!-- --- end answer of exercise --- -->\n",
    "\n",
    "In this latter subexercise, we have an\n",
    "example where the code is easy to read.\n",
    "\n",
    "\n",
    "### My remarks\n",
    "\n",
    "Remarks with such a subsubsection is treated as more text\n",
    "after the last subexercise. Test a list too:\n",
    "\n",
    "1. Mark 1.\n",
    "\n",
    "2. Mark 2.\n",
    "\n",
    "Filenames: `flip_coin.py`, `flip_coin.pdf`.\n",
    "\n",
    "<!-- Closing remarks for this Problem -->\n",
    "\n",
    "### Remarks\n",
    "\n",
    "These are the exercise remarks, appearing at the very end.\n",
    "\n",
    "<!-- solution files: mysol.txt, mysol_flip_coin.py, yet_another.file -->\n",
    "\n",
    "<!-- --- end exercise --- -->\n",
    "\n",
    "\n",
    "## Not an exercise\n",
    "\n",
    "Should be possible to stick a normal section in the middle of many\n",
    "exercises.\n",
    "\n",
    "\n",
    "\n",
    "<!-- --- begin exercise --- -->\n",
    "\n",
    "## Exercise 3: Test of plain text exercise\n",
    "<div id=\"my:exer1\"></div>\n",
    "\n",
    "Very short exercise. What is the capital\n",
    "of Norway?\n",
    "Filename: `myexer1`.\n",
    "\n",
    "<!-- --- end exercise --- -->\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "<!-- --- begin exercise --- -->\n",
    "\n",
    "## Project 4: Compute a Probability\n",
    "<div id=\"demo:ex:2\"></div>\n",
    "\n",
    "<!-- Minimalistic exercise -->\n",
    "\n",
    "\n",
    "What is the probability of getting a number between 0.5 and 0.6 when\n",
    "drawing uniformly distributed random numbers from the interval $[0,1)$?\n",
    "\n",
    "\n",
    "At the end we have a list because that caused problems in LaTeX\n",
    "in previous DocOnce versions:\n",
    "\n",
    "1. item1\n",
    "\n",
    "2. item2\n",
    "\n",
    "<!-- --- begin hint in exercise --- -->\n",
    "\n",
    "**Hint.**\n",
    "To answer this question empirically, let a program\n",
    "draw $N$ such random numbers using Python's standard `random` module,\n",
    "count how many of them, $M$, that fall in the interval $(0.5,0.6)$, and\n",
    "compute the probability as $M/N$.\n",
    "\n",
    "<!-- --- end hint in exercise --- -->\n",
    "\n",
    "<!-- --- end exercise --- -->\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "<!-- --- begin exercise --- -->\n",
    "\n",
    "## Project 5: Explore Distributions of Random Circles\n",
    "<div id=\"proj:circle1\"></div>\n",
    "<!-- keywords = ipynb -->\n",
    "\n",
    "The formula for a circle is given by"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<!-- Equation labels as ordinary links -->\n",
    "<div id=\"circle:x\"></div>\n",
    "\n",
    "$$\n",
    "\\begin{equation}\n",
    "x = x_0 + R\\cos 2\\pi t,\n",
    "\\label{circle:x} \\tag{7}\n",
    "\\end{equation}\n",
    "$$"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<!-- Equation labels as ordinary links -->\n",
    "<div id=\"circle:y\"></div>\n",
    "\n",
    "$$\n",
    "\\begin{equation}  \n",
    "y = y_0 + R\\sin 2\\pi t,\n",
    "\\label{circle:y} \\tag{8}\n",
    "\\end{equation}\n",
    "$$"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "where $R$ is the radius of the circle, $(x_0,y_0)$ is the\n",
    "center point, and $t$ is a parameter in the unit interval $[0,1]$.\n",
    "For any $t$, $(x,y)$ computed from ([7](#circle:x))-([8](#circle:y))\n",
    "is a point on the circle.\n",
    "The formula can be used to generate `n` points on a circle:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "editable": true
   },
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "\n",
    "def circle(R, x0, y0, n=501):\n",
    "    t = np.linspace(0, 1, n)\n",
    "    x = x0 + R*np.cos(2*np.pi*t)\n",
    "    y = y0 + R*np.sin(2*np.pi*t)\n",
    "    return x, y\n",
    "\n",
    "x, y = circle(2.0, 0, 0)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<!-- Often in an exercise we have some comments about the solution -->\n",
    "<!-- which we normally want to keep where they are. -->\n",
    "\n",
    "The goal of this project is to draw $N$ circles with random\n",
    "center and radius. Plot each circle using the `circle` function\n",
    "above.\n",
    "\n",
    "\n",
    "**a)**\n",
    "Let $R$ be normally distributed and $(x_0,y_0)$ uniformly distributed.\n",
    "\n",
    "<!-- --- begin hint in exercise --- -->\n",
    "\n",
    "**Hint.**\n",
    "Use the `numpy.random` module to draw the\n",
    "$x_0$, $y_0$, and $R$ quantities.\n",
    "\n",
    "<!-- --- end hint in exercise --- -->\n",
    "\n",
    "\n",
    "<!-- --- begin answer of exercise --- -->\n",
    "**Answer.**\n",
    "Here goes the short answer to part a).\n",
    "<!-- --- end answer of exercise --- -->\n",
    "\n",
    "\n",
    "<!-- --- begin solution of exercise --- -->\n",
    "**Solution.**\n",
    "Here goes a full solution to part a).\n",
    "<!-- --- end solution of exercise --- -->\n",
    "\n",
    "**b)**\n",
    "Let $R$ be uniformly distributed and $(x_0,y_0)$ normally distributed.\n",
    "Filename: `norm`.\n",
    "\n",
    "**c)**\n",
    "Let $R$ and $(x_0,y_0)$ be normally distributed.\n",
    "\n",
    "\n",
    "Filename: `circles`.\n",
    "\n",
    "<!-- Closing remarks for this Project -->\n",
    "\n",
    "### Remarks\n",
    "\n",
    "At the very end of the exercise it may be appropriate to summarize\n",
    "and give some perspectives.\n",
    "\n",
    "\n",
    "<!-- --- end exercise --- -->\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "<!-- --- begin exercise --- -->\n",
    "\n",
    "## Exercise 6: Determine some Distance\n",
    "<div id=\"exer:dist\"></div>\n",
    "\n",
    "Intro to this exercise. Questions are in subexercises below.\n",
    "\n",
    "\n",
    "<!-- --- begin solution of exercise --- -->\n",
    "**Solution.**\n",
    "Here goes a full solution of the whole exercise.\n",
    "With some math $a=b$ in this solution:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "$$\n",
    "\\hbox{math in solution: } a = b\n",
    "$$"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And code `a=b` in this solution:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "        a = b  # code in solution\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "End of solution is here.\n",
    "\n",
    "<!-- --- end solution of exercise --- -->\n",
    "\n",
    "\n",
    "**a)**\n",
    "Subexercises are numbered a), b), etc.\n",
    "\n",
    "<!-- --- begin hint in exercise --- -->\n",
    "\n",
    "**Hint 1.**\n",
    "First hint to subexercise a).\n",
    "With math $a=b$ in hint:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "$$\n",
    "a=b.\n",
    "$$"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And with code (in plain verbatim) returning $x+1$ in hint:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "        def func(x):\n",
    "            return x + 1  # with code in hint\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<!-- --- end hint in exercise --- -->\n",
    "\n",
    "<!-- --- begin hint in exercise --- -->\n",
    "\n",
    "**Hint 2.**\n",
    "Second hint to subexercise a).\n",
    "\n",
    "Test list in hint:\n",
    "\n",
    "1. item1\n",
    "\n",
    "2. item2\n",
    "\n",
    "<!-- --- end hint in exercise --- -->\n",
    "Filename: `subexer_a.pdf`.\n",
    "\n",
    "\n",
    "<!-- --- begin answer of exercise --- -->\n",
    "**Answer.**\n",
    "Short answer to subexercise a).\n",
    "With math in answer: $a=b$.\n",
    "<!-- --- end answer of exercise --- -->\n",
    "\n",
    "**b)**\n",
    "Here goes the text for subexercise b).\n",
    "\n",
    "\n",
    "Some math $\\cos^2 x + \\sin^2 x = 1$ written one a single line:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "$$\n",
    "\\cos^2 x + \\sin^2 x = 1 \\thinspace .\n",
    "$$"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<!-- --- begin hint in exercise --- -->\n",
    "\n",
    "**Hint.**\n",
    "A hint for this subexercise.\n",
    "\n",
    "<!-- --- end hint in exercise --- -->\n",
    "Filename: `subexer_b.pdf`.\n",
    "\n",
    "\n",
    "<!-- --- begin solution of exercise --- -->\n",
    "**Solution.**\n",
    "Here goes the solution of this subexercise.\n",
    "<!-- --- end solution of exercise --- -->\n",
    "\n",
    "\n",
    "\n",
    "<!-- No meaning in this weired test example: -->\n",
    "The text here belongs to the main (intro) part of the exercise. Need\n",
    "closing remarks to have text after subexercises.\n",
    "\n",
    "Test list in exercise:\n",
    "\n",
    "1. item1\n",
    "\n",
    "2. item2\n",
    "<!-- Closing remarks for this Exercise -->\n",
    "\n",
    "### Remarks\n",
    "\n",
    "Some final closing remarks, e.g., summarizing the main findings\n",
    "and their implications in other problems can be made. These\n",
    "remarks will appear at the end of the typeset exercise.\n",
    "\n",
    "\n",
    "<!-- --- end exercise --- -->\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "<!-- --- begin exercise --- -->\n",
    "\n",
    "## Some exercise without the \"Exercise:\" prefix\n",
    "\n",
    "<!-- Another minimalistic exercise -->\n",
    "\n",
    "Just some text. And some math saying that $e^0=1$ on a single line,\n",
    "to test that math block insertion is correct:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "$$\n",
    "\\exp{(0)} = 1\n",
    "$$"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And a test that the code `lambda x: x+2` is correctly placed here:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "        lambda x: x+2\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<!-- Have some comments at the end of the exercise to see that -->\n",
    "<!-- the Filename: ... is written correctly. -->\n",
    "<!-- --- end exercise --- -->\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "<!-- --- begin exercise --- -->\n",
    "\n",
    "## Exercise 8: Solution of differential equation\n",
    "<div id=\"sec:this:exer:de\"></div>\n",
    "\n",
    "\n",
    "\n",
    "Given"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "$$\n",
    "\\frac{dy}{dx} = -y(x),\\quad y(0)=1\n",
    "$$"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "What is the solution of this equation?\n",
    "\n",
    "**Choice A:**\n",
    " $y=e^{-y}$\n",
    "\n",
    "**Choice B:**\n",
    " $y=e^{y}$\n",
    "\n",
    "**Choice C:**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "from math import exp\n",
    "def f(x):\n",
    "    return exp(x)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Choice D:**\n",
    " The solution cannot be found because there is a derivative in the equation.\n",
    "\n",
    "**Choice E:**\n",
    " The equation is meaningless: an equation must be an equation\n",
    "for $x$ or $y$, not a function $y(x)$.\n",
    "\n",
    "\n",
    "\n",
    "<!-- --- end exercise --- -->\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "<!-- --- begin exercise --- -->\n",
    "\n",
    "## Example 9: Just an example\n",
    "\n",
    "<!-- This example needs the --examples_as_exercises option, otherwise -->\n",
    "<!-- it is just typeset as it is written. -->\n",
    "\n",
    "\n",
    "**a)**\n",
    "What is the capital of Norway?\n",
    "\n",
    "**Answer.**\n",
    "Oslo.\n",
    "\n",
    "<!-- --- end exercise --- -->\n",
    "\n",
    "\n",
    "# Here goes another section\n",
    "\n",
    "With some text, before we continue with exercises.\n",
    "\n",
    "# More Exercises\n",
    "\n",
    "\n",
    "\n",
    "<!-- --- begin exercise --- -->\n",
    "\n",
    "## Exercise 10: Make references to projects and problems\n",
    "<div id=\"exer:some:formula\"></div>\n",
    "\n",
    "<!-- Test comments not at the end only -->\n",
    "Pick a statement from [Project 5: Explore Distributions of Random Circles](#proj:circle1) or [Problem 2: Flip a Coin](#demo:ex:1)\n",
    "and verify it.\n",
    "\n",
    "Test list at the end of an exercise without other elements (like subexercise,\n",
    "hint, etc.):\n",
    "\n",
    "1. item1\n",
    "\n",
    "2. item2\n",
    "\n",
    "Filename: `verify_formula.py`.\n",
    "\n",
    "<!-- --- end exercise --- -->\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "<!-- --- begin exercise --- -->\n",
    "\n",
    "## Project 11: References to [Project 4: Compute a Probability](#demo:ex:2) in a heading works for ipynb\n",
    "<div id=\"exer:you\"></div>\n",
    "\n",
    "Refer to the previous exercise as [Exercise 10: Make references to projects and problems](#exer:some:formula),\n",
    "the two before that as [Project 4: Compute a Probability](#demo:ex:2) and [Project 5: Explore Distributions of Random Circles](#proj:circle1),\n",
    "and this one as [Project 11: References to Project [demo:ex:2](#demo:ex:2) in a heading works for ipynb](#exer:you).\n",
    "Filename: `selc_composed.pdf`.\n",
    "\n",
    "<!-- --- end exercise --- -->\n",
    "\n",
    "\n",
    "# References\n",
    "\n",
    "1. <div id=\"Langtangen_Pedersen_2002\"></div> **H. P. Langtangen and G. Pedersen**. \n",
    "    Propagation of Large Destructive Waves,\n",
    "    *International Journal of Applied Mechanics and Engineering*,\n",
    "    7(1),\n",
    "    pp. 187-204,\n",
    "    2002.\n",
    "\n",
    "2. <div id=\"Langtangen_et_al_2002\"></div> **H. P. Langtangen, K.-A. Mardal and R. Winther**. \n",
    "    Numerical Methods for Incompressible Viscous Flow,\n",
    "    *Advances in Water Resources*,\n",
    "    25,\n",
    "    pp. 1125-1146,\n",
    "    2002.\n",
    "\n",
    "3. <div id=\"Langtangen_1994a\"></div> **H. P. Langtangen**. \n",
    "    Numerical Solution of First Passage Problems in Random Vibrations,\n",
    "    *SIAM Journal of Scientific and Statistical Computing*,\n",
    "    15,\n",
    "    pp. 997-996,\n",
    "    1994.\n",
    "\n",
    "4. <div id=\"Mardal_et_al_2003a\"></div> **K.-A. Mardal, G. W. Zumbusch and H. P. Langtangen**. \n",
    "    Software Tools for Multigrid Methods,\n",
    "    *Advanced Topics in Computational Partial Differential Equations -- Numerical Methods and Diffpack Programming*,\n",
    "    edited by **H. P. Langtangen and A. Tveito**,\n",
    "    Springer,\n",
    "    2003,\n",
    "    Edited book,\n",
    "    <http://some.where.org>.\n",
    "\n",
    "5. <div id=\"Langtangen_1988d\"></div> **H. P. Langtangen**. \n",
    "    The FEMDEQS Program System,\n",
    "    *Department of Mathematics, University of Oslo*,\n",
    "    1989,\n",
    "    <http://www.math.uio.no/old/days/hpl/femdeqs.pdf>.\n",
    "\n",
    "6. <div id=\"Langtangen_1992c\"></div> **H. P. Langtangen**. \n",
    "    Stochastic Breakthrough Time Analysis of an Enhanced Oil Recovery Process,\n",
    "    *SIAM Journal on Scientific Computing*,\n",
    "    13,\n",
    "    pp. 1394-1417,\n",
    "    1992.\n",
    "\n",
    "7. <div id=\"Mortensen_et_al_2011\"></div> **M. Mortensen, H. P. Langtangen and G. N. Wells**. \n",
    "    A FEniCS-Based Programming Framework for Modeling Turbulent Flow by the Reynolds-Averaged Navier-Stokes Equations,\n",
    "    *Advances in Water Resources*,\n",
    "    34(9),\n",
    "    [doi: 10.1016/j.advwatres.2011.02.013](https://dx.doi.org/10.1016/j.advwatres.2011.02.013),\n",
    "    2011.\n",
    "\n",
    "8. <div id=\"Glimsdal_et_al_20006\"></div> **S. Glimsdal, G. Pedersen, K. Atakan, C. B. Harbitz, H. P. Langtangen and F. L\\ovholt**. \n",
    "    Propagation of the Dec. 26, 2004 Indian Ocean Tsunami: Effects of Dispersion and Source Characteristics,\n",
    "    *International Journal of Fluid Mechanics Research*,\n",
    "    33(1),\n",
    "    pp. 15-43,\n",
    "    2006.\n",
    "\n",
    "9. <div id=\"Rahman_et_al_2006b\"></div> **S. Rahman, J. Gorman, C. H. W. Barnes, D. A. Williams and H. P. Langtangen**. \n",
    "    Numerical Investigation of a Piezoelectric Surface Acoustic Wave Interaction With a One-Dimensional Channel,\n",
    "    *Physical Review B: Condensed Matter and Materials Physics*,\n",
    "    74,\n",
    "    2006,\n",
    "    035308.\n",
    "\n",
    "10. <div id=\"Haga_et_al_2011a\"></div> **J. B. Haga, H. Osnes and H. P. Langtangen**. \n",
    "    On the Causes of Pressure Oscillations in Low-Permeable and Low-Compressible Porous Media,\n",
    "    *International Journal of Analytical and Numerical Methods in Geomechanics*,\n",
    "    [doi: 10.1002/nag.1062](https://dx.doi.org/10.1002/nag.1062),\n",
    "    2011,\n",
    "    <http://onlinelibrary.wiley.com/doi/10.1002/nag.1062/abstract>.\n",
    "\n",
    "11. <div id=\"Langtangen_2003a\"></div> **H. P. Langtangen**. \n",
    "    *Computational Partial Differential Equations - Numerical Methods and Diffpack Programming*,\n",
    "    second edition,\n",
    "    *Texts in Computational Science and Engineering*,\n",
    "    Springer,\n",
    "    2003.\n",
    "\n",
    "12. <div id=\"Langtangen_2008a\"></div> **H. P. Langtangen**. \n",
    "    *Python Scripting for Computational Science*,\n",
    "    third edition,\n",
    "    *Texts in Computational Science and Engineering*,\n",
    "    Springer,\n",
    "    2008.\n",
    "\n",
    "13. <div id=\"Langtangen:95\"></div> **H. P. Langtangen and G. Pedersen**. \n",
    "    Finite Elements for the Boussinesq Wave Equations,\n",
    "    Waves and Non-linear Processes in Hydrodynamics,\n",
    "    edited by **J. Grue, B. Gjevik and J. E. Weber**,\n",
    "    Kluwer Academic Publishers,\n",
    "    pp. pp. 117-126,\n",
    "    1995,\n",
    "    <http://www.amazon.ca/Waves-Nonlinear-Processes-Hydrodynamics-John/dp/0792340310>.\n",
    "\n",
    "14. <div id=\"Langtangen_2012\"></div> **H. P. Langtangen**. \n",
    "    *A Primer on Scientific Programming With Python*,\n",
    "    third edition,\n",
    "    *Texts in Computational Science and Engineering*,\n",
    "    Springer,\n",
    "    2012.\n",
    "\n",
    "15. <div id=\"Jeberg_et_al_2004\"></div> **P. V. Jeberg, H. P. Langtangen and C. B. Terp**. \n",
    "    Optimization With Diffpack: Practical Example From Welding,\n",
    "    *Simula Research Laboratory*,\n",
    "    2004,\n",
    "    Internal report.\n",
    "\n",
    "16. <div id=\"Langtangen_1989e\"></div> **H. P. Langtangen**. \n",
    "    Computational Methods for Two-Phase Flow in Oil Reservoirs,\n",
    "    Ph.D. Thesis,\n",
    "    Mechanics Division, Department of Mathematics, University of Oslo,\n",
    "    1989,\n",
    "    Dr. Scient. thesis..\n",
    "\n",
    "17. <div id=\"Langtangen_talk_2007a\"></div> **H. P. Langtangen**. \n",
    "    Computational Modeling of Huge Tsunamis From Asteroid Impacts,\n",
    "    2007,\n",
    "    Invited keynote lecture at the \\emphInternational conference on Computational Science 2007 (ICCS'07), Beijing, China.\n",
    "\n",
    "18. <div id=\"Langtangen:85\"></div> **H. P. Langtangen**. \n",
    "    Solution of the Navier-Stokes Equations With the Finite Element Method in Two and Three Dimensions,\n",
    "    M.Sc. Thesis,\n",
    "    Mechanics Division, Department of Mathematics, University of Oslo,\n",
    "    1985,\n",
    "    Cand.Scient. thesis.\n",
    "\n",
    "19. <div id=\"Langtangen:91\"></div> **H. P. Langtangen and A. Tveito**. \n",
    "    Numerical Methods in Continuum Mechanics,\n",
    "    *Center for Industrial Research*,\n",
    "    1991,\n",
    "    Lecture notes for a course (ME-IN 324). 286 pages..\n",
    "\n",
    "20. <div id=\"Langtangen:94b\"></div> **H. P. Langtangen**. \n",
    "    Diffpack: Software for Partial Differential Equations,\n",
    "    *Proceedings of the Second Annual Object-Oriented Numerics Conference (OON-SKI'94), Sunriver, Oregon, USA*,\n",
    "    edited by **A. Vermeulen**,\n",
    "    1994.\n",
    "\n",
    "# Appendix: Just for testing; part I\n",
    "<div id=\"app1\"></div>\n",
    "\n",
    "This is the first appendix.\n",
    "\n",
    "## A subsection within an appendix\n",
    "\n",
    "Some text.\n",
    "\n",
    "# Appendix: Just for testing; part II\n",
    "<div id=\"app2\"></div>\n",
    "\n",
    "This is more stuff for an appendix.\n",
    "\n",
    "## Appendix: Testing identical titles\n",
    "\n",
    "Without label.\n",
    "\n",
    "\n",
    "## Appendix: Testing identical titles\n",
    "<div id=\"test:title:id1\"></div>\n",
    "\n",
    "With label.\n",
    "\n",
    "## Appendix: Testing identical titles\n",
    "<div id=\"test:title:id2\"></div>\n",
    "\n",
    "What about inserting a quiz?\n",
    "\n",
    "\n",
    "\n",
    "## Test of quizzes\n",
    "\n",
    "\n",
    "**Fundamental test:** What is the capital of Norway?\n",
    "\n",
    "**Answer 1:**\n",
    " Stockholm\n",
    "\n",
    "**Answer 2:**\n",
    " London\n",
    "\n",
    "**Answer 3:**\n",
    " Oslo\n",
    "\n",
    "**Choice D:**\n",
    " Bergen\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "## Appendix: Testing identical titles\n",
    "\n",
    "Without label.\n",
    "\n",
    "**Tip.**\n",
    "\n",
    "Here is a tip or hint box, typeset as a notice box.\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "Need a lot of text to surround the summary box.\n",
    "Version control systems allow you to record the history of files\n",
    "and share files among several computers and collaborators in a\n",
    "professional way. File changes on one computer are updated or\n",
    "merged with changes on another computer. Especially when working\n",
    "with programs or technical reports it is essential\n",
    "to have changes documented and to\n",
    "ensure that every computer and person involved in the project\n",
    "have the latest updates of the files.\n",
    "Greg Wilson' excellent [Script for Introduction to Version Control](https://software-carpentry.org/2010/07/script-for-introduction-to-version-control/) provides a more detailed motivation why you will benefit greatly\n",
    "from using version control systems.\n",
    "\n",
    "**Summary.**\n",
    "\n",
    "**Bold remark:** Make some text with this summary.\n",
    "Much testing in this document, otherwise stupid content.\n",
    "Much testing in this document, otherwise stupid content.\n",
    "Much testing in this document, otherwise stupid content.\n",
    "Much testing in this document, otherwise stupid content.\n",
    "Much testing in this document, otherwise stupid content.\n",
    "Much testing in this document, otherwise stupid content.\n",
    "Much testing in this document, otherwise stupid content.\n",
    "Much testing in this document, otherwise stupid content.\n",
    "Much testing in this document, otherwise stupid content.\n",
    "\n",
    "\n",
    "\n",
    "Projects that you want to share among several computers or project\n",
    "workers are today most conveniently stored at some web site \"in the\n",
    "cloud\" and updated through communication with that site. I strongly\n",
    "recommend you to use such sites for all serious programming and\n",
    "scientific writing work - and all other important files.\n",
    "\n",
    "The simplest services for hosting project files are [Dropbox](https://dropbox.com) and [Google Drive](https://drive.google.com).\n",
    "It is very easy to get started with these systems, and they allow you\n",
    "to share files among laptops and mobile units with as many users as\n",
    "you want. The systems offer a kind of version control in that the\n",
    "files are stored frequently (several times per minute), and you can go\n",
    "back to previous versions for the last 30 days. However, it is\n",
    "challenging  to find the right version from the past when there are\n",
    "so many of them.\n",
    "\n",
    "More seriously, when several people may edit files simultaneously, it\n",
    "can be difficult detect who did what when, roll back to previous\n",
    "versions, and to manually merge the edits when these are\n",
    "incompatible. Then one needs more sophisticated tools than Dropbox or\n",
    "Google Drive: project hosting services with true version control\n",
    "systems.  The following text aims at providing you with the minimum\n",
    "information to started with such systems. Numerous other tutorials\n",
    "contain more comprehensive material and in-depth explanations of the\n",
    "concepts and tools.\n",
    "\n",
    "The idea with project hosting services is that you have the files\n",
    "associated with a project in the cloud. Many people may share these\n",
    "files.  Every time you want to work on the project you explicitly\n",
    "update your version of the files, edit the files as you like, and\n",
    "synchronize the files with the \"master version\" at the site where the\n",
    "project is hosted.  If you at some point need to go back to a\n",
    "version of the files at some particular point in the past,\n",
    "this is an easy operation. You can also use tools to see\n",
    "what various people have done with the files in the various versions.\n",
    "\n",
    "All these services are very similar. Below we describe how you get\n",
    "started with Bitbucket, GitHub, and Googlecode. Launchpad works very\n",
    "similarly to the latter three. All the project hosting services have\n",
    "excellent introductions available at their web sites, but the recipes\n",
    "below are much shorter and aim at getting you started as quickly as\n",
    "possible by concentrating on the most important need-to-know steps.\n",
    "The Git tutorials we refer to later in this document contain more\n",
    "detailed information and constitute of course very valuable readings\n",
    "when you use version control systems every day. The point now is\n",
    "to get started.\n",
    "\n",
    "\n",
    "## Appendix: Testing inline comments\n",
    "\n",
    "<!-- Names can be [ A-Za-z0-9_'+-]+ -->\n",
    "\n",
    "Projects that you want to share among several computers or project\n",
    "workers are today most conveniently stored at some web site \"in the\n",
    "cloud\" and updated through communication with that\n",
    "site. [hpl's semi opinion 1: not sure if in the cloud is\n",
    "understood by\n",
    "all.] I strongly recommend you to use such sites for all serious\n",
    "programming and scientific writing work - and all other important\n",
    "files.\n",
    "\n",
    "The simplest services for hosting project files is Dropbox. [mp 2: Simply go to <https://dropbox.com> and watch the video. It explains\n",
    "how files, like `myfile.py`, perhaps containing much math, like\n",
    "$\\partial u/\\partial t$, are easily communicated between machines.] It\n",
    "is very easy to get started with Dropbox, and it allows you to share\n",
    "files among [hpl 3: laptops and mobile units -> computers, tablets,\n",
    "and phones].\n",
    "\n",
    "<!-- Test horizontal rule -->\n",
    "\n",
    "------\n",
    "\n",
    "<!-- Coments for editing -->\n",
    "\n",
    "First[add 4: ,] consider a quantity $Q$. [edit 5: To this end, -> We note that]\n",
    "$Q>0$, because [del 6: a] negative [edit 7: quantity is -> quantities\n",
    "are] [del 8: just] negative. [add 9: This comes as no surprise.]\n",
    "\n",
    "<!-- Test tailored latex figure references with page number -->\n",
    "Let us refer to [Figure 1](#fig:impact) again.\n",
    "\n",
    "Test references in a list:\n",
    "\n",
    " * [Section 1](#sec1)\n",
    "\n",
    " * [Subsection 1](#subsec1)\n",
    "\n",
    " * [fig:impact](#fig:impact)\n",
    "\n",
    "## Appendix: Testing headings ending with `verbatim inline`\n",
    "\n",
    "The point here is to test 1) `verbatim` code in headings, and 2)\n",
    "ending a heading with verbatim code as this triggers a special\n",
    "case in LaTeX.\n",
    "\n",
    "We also test mdash---used as alternative to hyphen without spaces around,\n",
    "or in quotes:\n",
    "\n",
    "> *Fun is fun*.---Unknown.\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "The ndash should also be tested - as in the Hanson - Nilson equations\n",
    "on page 277 - 278.\n",
    "\n",
    "And finally, what about admons, quotes, and boxes? They are tested\n",
    "in a separate document: `admon.do.txt`.\n",
    "\n",
    "[^example-of-the-third-footnote]: Not much to add here, but the footnote\n",
    "is at the end with only one newline."
   ]
  }
 ],
 "metadata": {},
 "nbformat": 4,
 "nbformat_minor": 4
}

************** File: testdoc.m *****************
%% A Document for Testing DocOnce
% 
% Author: Hans Petter Langtangen [1, 2] (hpl@simula.no)
% Author: Kaare Dump [3] 
% Author: A. Dummy Author  
% Author: I. S. Overworked and Outburned [4, 5, 6, 7] 
% Author: J. Doe  (j_doe@cyberspace.com)
% 
% [1] Center for Biomedical Computing, Simula Research Laboratory
% [2] Department of Informatics, University of Oslo
% [3] Segfault, Cyberspace
% [4] Inst1
% [5] Inst2, Somewhere
% [6] Third Inst, Elsewhere
% [7] Fourth Inst
% 
% Date: Jan 32, 2100
% 
% Made with DocOnce
% 
% 
% 
% 
% Table of contents:
% 
%  Section 1 
%      Here is a list with subsubsection heading 
%    Subsection 1 
%      Test Section reference at beginning of line and after a sentence 
%      Computer code 
%      Subsubsection heading before code 
%      Running OS commands 
%      Footnotes 
%    Subsection 2: Testing figures 
%    The $\theta$ parameter (not $\nabla$?) 
%    Custom Environments 
%    Tables 
%    A test of verbatim words in heading with subscript $a_i$: |my_file_v1| and |my_file_v2| 
%    *Just bold* 
%    _Just emphasize_ 
%    |Just verbatim| 
%    *Bold* beginning 
%    _Emphasize_ beginning 
%    |Verbatim| beginning 
%    Maybe *bold end* 
%    Maybe _emphasize end_ 
%    Maybe |verbatim end| 
%    The middle has *bold* word 
%    The middle has _emphasize_ word 
%    The middle has |verbatim| word 
%    Bibliography test 
%    Example 1: Examples can be typeset as exercises 
%    User-defined environments 
%    Example 1: A test function 
%    Example 2: Addition 
%    URLs 
%  LaTeX Mathematics 
%  Exercises 
%    Problem 2: Flip a Coin 
%      My remarks 
%      Remarks 
%    Not an exercise 
%    Exercise 3: Test of plain text exercise 
%    Project 4: Compute a Probability 
%    Project 5: Explore Distributions of Random Circles 
%      Remarks 
%    Exercise 6: Determine some Distance 
%      Remarks 
%    Some exercise without the "Exercise:" prefix 
%    Exercise 8: Solution of differential equation 
%    Example 9: Just an example 
%  Here goes another section 
%  More Exercises 
%    Exercise 10: Make references to projects and problems 
%    Project 11: References to "Project 4: Compute a Probability" in a heading works for matlabnb 
%  References 
%  Appendix: Just for testing; part I 
%    A subsection within an appendix 
%  Appendix: Just for testing; part II 
%    Appendix: Testing identical titles 
%    Appendix: Testing identical titles 
%    Appendix: Testing identical titles 
%    Appendix: Testing identical titles 
%    Appendix: Testing inline comments 
%    Appendix: Testing headings ending with |verbatim inline| 
% 
% 
% 
% 
% 
% % !split
% 
% 
% 
% 
% The format of this document is
% matlabnb
% 
% *Abstract.* This is a document with many test constructions for doconce syntax.
% It was used heavily for the development and kept for testing
% numerous constructions, also special and less common cases.
% 
% And exactly for test purposes we have an extra line here, which
% is part of the abstract.
% 
% % Cannot demonstrate chapter headings since abstract and chapter
% % are mutually exclusive in LaTeX
% 
%% Section 1
% 
% Here is a nested list:
% 
%   * item1
% 
%   * item2
% 
%   * item3 which continues
%     on the next line to test that feature
% 
%   * and a sublist
% 
%     * with indented subitem1
% 
%     * and a subitem2
% 
% 
%   * and perhaps an ordered sublist
% 
%    # first item
% 
%    # second item,
%       continuing on a new line
% 
% 
% *Here is a list with paragraph heading.* 
%   * item1
% 
%   * item2
% 
%% Here is a list with subsubsection heading
%   * item1
% 
%   * item2
% 
% !bquote
% Here are two lines that make up
% a block quote for testing _emphasized words_ and *boldface words*,
% also with hypens:
% _pre_-fix, post-_fix_, *pre*-fix, post-*fix*.
% !equote
% 
% Here are two references. Equation (ref{my:eq1}) is fine. Eq. (ref{my:eq1}) too.
% Even Equation (ref{my:eq1}) without the tilde.
% 
% 
%% Subsection 1
% 
% 
% % Refer to section/appendix etc. at the beginning of the line
% % and other special fix situations for HTML.
% 
% More text, with a reference back to
% the section "Section 1" and "Subsection 1", and further to the
% the sections "Subsection 1" and "URLs", which
% encourages you to do the tasks in "Problem 2: Flip a Coin" and "Exercise 10: Make references to projects and problems".
%  "Appendix: Just for testing; part I" and "Appendix: Just for testing; part II" are also nice elements.
% 
%% Test Section reference at beginning of line and after a sentence
% The section "Subsection 1" is fine.
% The section "URLs" too.
% 
% 
% % sphinx code-blocks: pycod=python cod=fortran cppcod=c++ sys=console
% 
%% Computer code
% Let's do some copying from files too. First from subroutine up to the very end,
% 
%        subroutine test()
%        integer i
%        real*8 r
%        r = 0
%        do i = 1, i
%           r = r + i
%        end do
%        return
%  C     END1
%  
%        program testme
%        call test()
%        return
% and then just the subroutine,
%  
%        subroutine test()
%        integer i
%        real*8 r
%        r = 0
%        do i = 1, i
%           r = r + i
%        end do
%        return
% and finally the complete file with a plain text verbatim environment
% (|envir=ccq|):
%  C     a comment
%  
%        subroutine test()
%        integer i
%        real*8 r
%        r = 0
%        do i = 1, i
%           r = r + i
%        end do
%        return
%  C     END1
%  
%        program testme
%        call test()
%        return
% 
% Testing other code environments. First Python:
% 
!bc
%  !bc pycod
%  def f(x):
%      return x+1
%  !ec
% which gets rendered as
% 
%  def f(x):
%      return x+1
% 
% Test paragraph and subsubsection headings before
% before code.
% 
% *Paragraph heading before code.* 
%  import sys
%  sys.path.insert(0, os.pardir)
% 
%% Subsubsection heading before code
%  def h(z):
%      return z+1
% 
% Here is a program that is supposed to be interactive via
% Python Online Tutorial, but that service is not accessible
% for the present format.
% 
%  class Line:
%      def __init__(self, a, b):
%          self.a, self.b = a, b
%  
%      def __call__(self, x):
%          a, b = self.a, self.b
%          return a*x + b
%  
%  line = Line(2, 1)
%  y = line(x=3)
%  print(y)
% 
% Some more Python code (actually specified as a sage cell, but
% such cells are not supported by this format).
% 
%  a = 2
%  b = 3
%  print('a+b:', a + b)
%  
%  # In a sage cell we can also plot
%  from matplotlib.pyplot import *
%  from numpy import *
%  x = linspace(0, 4*pi, 101)
%  y = exp(-0.1*x)*cos(x)
%  plot(x, y)
%  xlabel('x'); ylabel('y')
%  show()
% 
% 
% Then Cython (with -h option so it is hidden in html/sphinx):
% 
%  cpdef f(double x):
%      return x + 1
% 
% Standard Python shell sessions:
% 
%  >>> from numpy import linspace, sin
%  >>> # Some comment
%  >>> x = linspace(0, 2, 11)
%  >>> y = sin(x)
%  >>> y[0]
%  0
%  >>> import matplotlib.pyplot as plt
%  >>> plt.plot(x, y)
% 
% Similar IPython sessions:
% 
%  In [1]: from numpy import linspace, sin
%  In [2]: # Some comment
%  In [3]: x = linspace(0, 2, 11)
%  In [4]: y = sin(x)
%  In [5]: y[0]
%  Out[5]: 0
%  In [6]: import matplotlib.pyplot as plt
%  In [7]: plt.plot(x, y)
%  In [8]: a='multiple-\nline\noutput'
%  In [9]: a
%  Out[9]: 'multiple-\nline\noutput'
%  In [10]: print(a)
%  multiple-
%  line
%  output
% 
% Here is the interactive session again, but with |pyshell-t|.
% 
%  >>> from numpy import linspace, sin
%  >>> # Some comment
%  >>> x = linspace(0, 2, 11)
%  >>> y = sin(x)
%  >>> y[0]
%  0
%  >>> import matplotlib.pyplot as plt
%  >>> plt.plot(x, y)
% 
% % This one tests a + sign before a code environment
% C++:
%  #include <iostream>
%  
%  int main()
%  {
%     std::cout << "Sample output" << std::endl;
%     return 0
%  }
% % The next should get correctly typset in sphinx (cod is fcod)
% % It also tests emoji before code
% And a little bit of Fortran: :dizzy_face:
% 
!bc
%  !bc cod
%        subroutine midpt(x, length, a, b)
%        real*8 a, b, x
%        x = (a + b)/2
%        length = b - a
%        return
%        end
%  !ec
% which then is typeset as
% 
%        subroutine midpt(x, length, a, b)
%        real*8 a, b, x
%        x = (a + b)/2
%        length = b - a
%        return
%        end
% 
% HTML:
% 
%  <table>
%  <tr><td>Column 1</td><td>Column 2</td></tr>
%  <tr><td>0.67526 </td><td>0.92871 </td></tr>
%  <!-- comment -->
%  </table>
% 
% But inline HTML code is also important, like text that starts with
% |<a href="| (which can destroy the following text if not properly
% quoted).
% 
% Matlab with comments requires special typesetting:
% 
% Comment on the beginning of the line can be escaped by %%
if a > b
% Indented comment needs this trick
c = a + b
end
% 
% And here is a system call:
% 
%  Terminal> mkdir test
%  Terminal> cd test
%  Terminal> myprog -f
%  output1
%  output2
% 
% Any valid pygments lexer/language name can appear to, e.g.,
% 
!bc
%  !bc restructuredtext
%  =======
%  Heading
%  =======
%  
%  Some text.
%  !ec
% results in
% 
%  =======
%  Heading
%  =======
%  
%  Some text.
% 
% % Here goes hidden code.
% % Python can be treated by some formats, Fortran is always out.
% 
% 
% 
% Finally, |!bc do| supports highlighting of DocOnce source:
% 
%  ======= DocOnce test file =======
%  
%  ===== Computer code =====
%  
%  Inline verbatim code, as in `import numpy as np`, is allowed, as well as
%  code blocks:
%  
%  !bc pycod
%  from math import sin
%  
%  def f(x):
%      """Example on a function."""
%      return sin(x) + 1
%  
%  print(f(0))
%  !ec
%  
%  
%  ===== Mathematics =====
%  
%  Formulas can be inline, as in $\nabla\cdot\bm{u} = 0$, or typeset
%  as equations:
%  
%  !bt
%  \begin{align*}
%  \nabla\cdot\bm{u} &= 0,\\ 
%  \bm{u} &= \nabla\phi .
%  \end{align*}
%  !et
%  
%  === Subsubsection heading ===
%  
%  DocOnce files can have chapters, sections, subsections, and subsubsections.
%  
%  __Paragraph heading.__ Paragraphs may have headings.
% 
% It is time to test |verbatim inline font| especially with |a newline
% inside the text| and an exclamation mark at the end: |BEGIN|! For
% spellcheck, test |a verbatim expression| in |another| in a |third|.
% Also test exclamation mark as in |!bc| and |!ec| as well as |a != b|.
% Also test backslashes and braces like |\begin|, |\begin{enumerate}|,
% |\end{this}\end{that}|, and |{something \inside braces}|.
% 
% The following attempt to exemplify colored text does not work in
% format matlabnb.
% Here is some red color and an attempt to write with
% green color containing a linebreak
% code. Some formats will only display 
% this correctly when |html| 
% is the output format.
% But here some more running text is added which is not part of
% the previous blocks with line breaks.
% 
%% Running OS commands
%  Terminal> python -c 'print("Testing\noutput\nfrom\nPython.")'
%  Testing
%  output
%  from
%  Python.
% 
% 
%% Footnotes
% Here is a test of footnotes [^footnote], which are handy in text.
% They are used in different flavors, now in
% 
%  * list items (note below that footnotes work after math, verbatim, and URLs - bin fact old and emphasize too!)
% 
%  * even with math $\nabla^2u$[^math1]
% 
%  * and code |h[i] += 1|[^code]
%    (_must_ have space between inline code and footnote!)
% 
%  * and links <https://google.com>[^google-search]
% 
% which gives flexibility in writing.
% This is the third[^example-of-the-third-footnote] example.
% 
%   [^footnote]: Typesetting of the footnote depends on the format.
% Plain text does nothing, LaTeX removes the
% definition and inserts the footnote as part of the LaTeX text.
% reStructuredText and Sphinx employ a similar type of typesetting
% as Extended Markdown and DocOnce, and in HTML we keep the same
% syntax, just displayed properly in HTML.
% [^math1]: Math footnotes can be dangerous since it
% interferes with an exponent.
% [^code]: One-line footnote.
% 
% [^google-search]: <google.com> is perhaps the most famous
% web site today.
% 
% Here is some more text before a new definition of a footnote that was
% used above.
% 
% !bnotice Non-breaking space character
% This paragraph aims to test non-breaking space character <https://en.wikipedia.org/wiki/Non-breaking_space>, and a typical
% example where this is needed is in physical units: 7.4 km is traveled
% in $7.4/5.5\approx 1.345$ s.  Also check that a link <https://google.com> is
% not broken across lines (drag the browser window to test this).
% (On the other hand, the tilde is used in
% computer code, e.g., as in |[~x for x in y]| or in |y=~x|, and should
% of course remain a tilde in those contexts.)
% !enotice
% 
%% Subsection 2: Testing figures
% 
% 
% Test of figures. In particular we refer to Figure ref{fig:impact} in which
% there is a flow.
% 
% <<../doc/src/manual/fig/wave1D.png>>
% 
% Figures without captions are allowed and will be inlined.
% 
% <<../doc/src/manual/fig/wave1D.png>>
% 
% 
% 
% % Test multi-line caption in figure with sidecap=True
% 
% Here is figure ref{myfig} with a long (illegal) multi-line caption
% containing inline verbatim text:
% 
% <<../doc/src/manual/fig/wave1D.png>>
% 
% % Must be a blank line after MOVIE or FIGURE to detect this problem
% 
% Test URL as figure name:
% 
% <<https://raw.github.com/doconce/doconce/master/doc/src/blog/f_plot.png>>
% 
% 
% % Test wikimedia type of files that otherwise reside in subdirs
% 
% 
% *Remark.* Movies are tested in separate file |movies.do.txt|.
% 
% 
% % Somewhat challenging heading with latex math, \t, \n, ? and parenthesis
% 
%% The $\theta$ parameter (not $\nabla$?)
% 
% Functions do not always need to be advanced, here is one
% involving $\theta$:
!bc
%  def f(theta):
%      return theta**2
% 
% *More on $\theta$.* Here is more text following headline with math.
% 
% Newcommands must also be tested in this test report:
% $\frac{1}{2}$, ${1/2}$, $\pmb{x}$, $\frac{Du}{dt}$,
% both inline and in block:
% 
% $$\frac{Du}{dt} &= 0\nonumber \\  \frac{1}{2} &= {1/2} \\  \frac{1}{2}\pmb{x} &= \pmb{n}$$
% 
% Or with align with label and numbers:
% 
% $$\frac{Du}{dt} &= 0  \\  \frac{1}{2} &= {1/2} \\  \frac{1}{2}\pmb{x} &= \pmb{n}$$
% 
% 
% % Must test more complicated align and matrix compositions
% % where DocOnce inserts auto-numbered labels etc.
% 
% First one numbered (automatically):
% 
% $$\begin{pmatrix} G_2 + G_3 & -G_3 & -G_2 & 0 \\  -G_3 & G_3 + G_4 & 0 & -G_4 \\  -G_2 & 0 & G_1 + G_2 & 0 \\  0 & -G_4 & 0 & G_4 \end{pmatrix} &= \begin{pmatrix}  v_1 \\   v_2 \\   v_3 \\   v_4 \end{pmatrix} + \cdots   \\  \begin{pmatrix}  C_5 + C_6 & -C_6 & 0 & 0 \\   -C_6 & C_6 & 0 & 0 \\   0 & 0 & 0 & 0 \\   0 & 0 & 0 & 0 \end{pmatrix}   &= \frac{d}{dt}\begin{pmatrix}  v_1 \\   v_2 \\   v_3 \\   v_4 \end{pmatrix} + \begin{pmatrix}  0 \\   0 \\   0 \\   -i_0 \end{pmatrix} \nonumber  \end{align}$$
% 
% Second numbered (automatically):
% 
% $$\begin{pmatrix} G_1 + G_2\\  -G_3 & G_4 \end{pmatrix} &= \begin{pmatrix}  v_1 \\   v_2 \end{pmatrix} + \cdots\nonumber  \\  \left(\begin{array}{ll} y & 2\\  2 & 1 \end{array}\right) \left(\begin{array}{ll} 0 \\ x \end{array}\right) &= \begin{pmatrix} A \\ B \end{pmatrix}  \end{align}$$
% 
% Both numbered, with label by the user:
% 
% $$\begin{pmatrix} G_1 + G_2\\  -G_3 & G_4 \end{pmatrix} &= \begin{pmatrix}  v_1 \\   v_2 \end{pmatrix} + \cdots  \\   \left(\begin{array}{ll} y & 2\\  2 & 1 \end{array}\right) \left(\begin{array}{ll} 0 \\ x \end{array}\right) &= \begin{pmatrix} A \\ B \end{pmatrix} \end{align}$$
% Now we refer to Equations (mymatrix:eq1)-(mymatrix:eq2).
% 
%% Custom Environments
% 
% Here is an attempt to create a theorem environment via Mako
% (for counting theorems) and comment lines to help replacing lines in
% the |.tex| by proper begin-end LaTeX environments for theorems.
% Should look nice in most formats!
% 
% 
% 
% % begin theorem
% 
% *Theorem 5.* Let $a=1$ and $b=2$. Then $c=3$.
% % end theorem
% 
% % begin proof
% *Proof.* Since $c=a+b$, the result follows from straightforward addition.
% $\Diamond$
% % end proof
% 
% As we see, the proof of Theorem 5 is a modest
% achievement.
% 
% 
%% Tables
% 
% 
% % index with comma could fool sphinx
% 
% Let us take this table from the manual:
% 
% 
% <table border="1">
% <thead>
% <tr><th align="center">time</th> <th align="center">velocity</th> <th align="center">acceleration</th> </tr>
% </thead>
% <tbody>
% <tr><td align="left">   0.0     </td> <td align="right">   1.4186      </td> <td align="right">   -5.01           </td> </tr>
% <tr><td align="left">   2.0     </td> <td align="right">   1.376512    </td> <td align="right">   11.919          </td> </tr>
% <tr><td align="left">   4.0     </td> <td align="right">   1.1E+1      </td> <td align="right">   14.717624       </td> </tr>
% </tbody>
% </table>
% 
% The DocOnce source code reads
%  
%    |--------------------------------|
%    |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    |
%    |--------------------------------|
%  
% 
% Here is yet another table to test that we can handle more than
% one table:
% 
% <table border="1">
% <thead>
% <tr><th align="left">time</th> <th align="left">velocity</th> <th align="left">acceleration</th> </tr>
% </thead>
% <tbody>
% <tr><td align="left">   0.0     </td> <td align="left">   1.4186      </td> <td align="left">   -5.01           </td> </tr>
% <tr><td align="left">   1.0     </td> <td align="left">   1.376512    </td> <td align="left">   11.919          </td> </tr>
% <tr><td align="left">   3.0     </td> <td align="left">   1.1E+1      </td> <td align="left">   14.717624       </td> </tr>
% </tbody>
% </table>
% And one with math headings (that are expanded and must be treated
% accordingly), verbatim heading and entry, and no space around the pipe
% symbol:
% 
% <table border="1">
% <thead>
% <tr><th align="center">$i$</th> <th align="center">$h_i$ </th> <th align="center">$\bar T_i$</th> <th align="center">|L_i|</th> </tr>
% </thead>
% <tbody>
% <tr><td align="left">   0      </td> <td align="right">   0         </td> <td align="right">   288           </td> <td align="right">   -0.0065        </td> </tr>
% <tr><td align="left">   1      </td> <td align="right">   11,000    </td> <td align="right">   216           </td> <td align="right">   0.0            </td> </tr>
% <tr><td align="left">   2      </td> <td align="right">   20,000    </td> <td align="right">   216           </td> <td align="right">   0.001          </td> </tr>
% <tr><td align="left">   3      </td> <td align="right">   32,000    </td> <td align="right">   228           </td> <td align="right">   0.0028         </td> </tr>
% <tr><td align="left">   4      </td> <td align="right">   47,000    </td> <td align="right">   270           </td> <td align="right">   0.0            </td> </tr>
% <tr><td align="left">   5      </td> <td align="right">   51,000    </td> <td align="right">   270           </td> <td align="right">   -0.0028        </td> </tr>
% <tr><td align="left">   6      </td> <td align="right">   71,000    </td> <td align="right">   214           </td> <td align="right">   |NaN|    </td> </tr>
% </tbody>
% </table>
% And add one with verbatim headings (with underscores),
% and rows starting with ||-| because of a negative number,
% and ||| right before and after verbatim word (with no space):
% 
% <table border="1">
% <thead>
% <tr><th align="center">exact</th> <th align="center">|v_1|</th> <th align="center">$a_i$ + |v_2|</th> <th align="center">|verb_3_|</th> </tr>
% </thead>
% <tbody>
% <tr><td align="right">   9        </td> <td align="right">   9.62           </td> <td align="right">   5.57                   </td> <td align="right">   8.98               </td> </tr>
% <tr><td align="right">   -20      </td> <td align="right">   -23.39         </td> <td align="right">   -7.65                  </td> <td align="right">   -19.93             </td> </tr>
% <tr><td align="right">   10       </td> <td align="right">   17.74          </td> <td align="right">   -4.50                  </td> <td align="right">   9.96               </td> </tr>
% <tr><td align="right">   0        </td> <td align="right">   -9.19          </td> <td align="right">   4.13                   </td> <td align="right">   -0.26              </td> </tr>
% </tbody>
% </table>
% Pipe symbols in verbatim and math text in tables used to pose difficulties,
% but not
% anymore (except for plain text and matlabnb).
% 
% Here is a table with X alignment:
% 
% <table border="1">
% <thead>
% <tr><th align="center"> Type</th> <th align="center">                                                                                                           Description                                                                                                            </th> </tr>
% </thead>
% <tbody>
% <tr><td align="center">   X        </td> <td align="left">   Alignment character that is used for specifying a potentially very long text in a column in a table. It makes use of the |tabularx| package in LaTeX, otherwise (for other formats) it means |l| (centered alignment).    </td> </tr>
% <tr><td align="center">   l,r,c    </td> <td align="left">   standard alignment characters                                                                                                                                                                                                         </td> </tr>
% </tbody>
% </table>
% Finally, a table with math
% and URLs.
% 
% % Mako code to expand URLs in the table
% % (These types of tables did not work before Jan 2014)
% 
% 
% <table border="1">
% <tr></tr>
% <tbody>
% <tr><td align="center">   $\mathcal{L}=0$            </td> <td align="center">   080 <../doc/src/manual/mov/wave_frames/frame_0080.png>    </td> <td align="center">   085 <../doc/src/manual/mov/wave_frames/frame_0085.png>    </td> </tr>
% <tr><td align="center">   $a=b$                      </td> <td align="center">   090 <../doc/src/manual/mov/wave_frames/frame_0090.png>    </td> <td align="center">   095 <../doc/src/manual/mov/wave_frames/frame_0095.png>    </td> </tr>
% <tr><td align="center">   $\nabla\cdot\bm{u} =0 $    </td> <td align="center">   100 <../doc/src/manual/mov/wave_frames/frame_0100.png>    </td> <td align="center">   105 <../doc/src/manual/mov/wave_frames/frame_0105.png>    </td> </tr>
% </tbody>
% </table>
% 
%% A test of verbatim words in heading with subscript $a_i$: |my_file_v1| and |my_file_v2|
% 
% *Paragraph with verbatim and math: |my_file_v1.py| and |my_file_v2.py| define some math $a_{i-1}$.* Here is more |__verbatim__| code and
% some plain text on a new line.
% 
% % Test various types of headlines
%% *Just bold*
% 
% Some text.
% 
%% _Just emphasize_
% 
% Some text.
% 
%% |Just verbatim|
% 
% Some text.
% 
%% *Bold* beginning
% 
% Some text.
% 
%% _Emphasize_ beginning
% 
% Some text.
% 
%% |Verbatim| beginning
% 
% Some text.
% 
%% Maybe *bold end*
% 
% Some text.
% 
%% Maybe _emphasize end_
% 
% Some text.
% 
%% Maybe |verbatim end|
% 
% Some text.
% 
%% The middle has *bold* word
% 
% Some text.
% 
%% The middle has _emphasize_ word
% 
% Some text.
% 
%% The middle has |verbatim| word
% 
% Some text.
% 
% 
% *_Just emphasize_.* Some text.
% 
% 
% *|Just verbatim|.* Some text.
% 
% 
% *_Emphasize_ beginning.* Some text.
% 
% 
% *|Verbatim beginning|.* Some text.
% 
% 
% *Maybe _emphasize end_.* Some text.
% 
% 
% *Maybe |verbatim end|.* Some text.
% 
% 
% *The middle has _emphasize_ word.* Some text.
% 
% 
% *The middle has |verbatim| word.* Some text.
% 
% 
% *Ampersand.* We can test Hennes & Mauritz, often abbreviated H&M, but written
% as |Hennes & Mauritz| and |H & M|.
% A sole |&| must also work.
% % Note: substitutions must not occur inside verbatim, just in ordinary text.
% 
!bc
%  # Just to check that ampersand works in code blocks:
%  c = a & b
% 
% *Quotes.* Let us also add a test of quotes such as "double quotes, with numbers
% like 3.14 and newline/comma and hyphen (as in double-quote)"; written
% in the standard LaTeX-style that gives correct LaTeX formatting and
% ordinary double quotes for all non-LaTeX formats.  Here is another
% sentence that "caused" a bug in the past because double backtick
% quotes could imply verbatim text up to a verbatim word starting with
% period, like |.txt|.
% 
% More quotes to be tested for spellcheck:
% ("with parenthesis"), "with newline"
% and "with comma", "hyphen"-wise, and "period".
% 
% 
%% Bibliography test
% 
% Here is an example: [1] discussed propagation of
% large destructive water waves, [2] gave
% an overview of numerical methods for solving the Navier - Stokes equations,
% while the use of Backward Kolmogorov equations for analyzing
% random vibrations was investigated in [3].
% The book chapter [4] contains information on
% C++ software tools for programming multigrid methods. A real retro
% reference is [5] about a big FORTRAN package.
% Multiple references are also possible, e.g., see
% [1] [4].
% 
% We need to cite more than 10 papers to reproduce an old formatting
% problem with blanks in the keys in reST format:
% [6] [3] [7] [1]
% and
% [2] [8] [9] [10] [11] [12] [13]
% and all the work of
% [14] [4] [15] as well as
% old work [5] and [16], and the
% talk [17].
% Langtangen also had two thesis [18] [16]
% back in the days.
% More retro citations are
% the old ME-IN323 book [19] and the
% [20] OONSKI '94 paper.
% 
% 
% 
% 
% % --- begin exercise ---
% 
%% Example 1: Examples can be typeset as exercises
% 
% Examples can start with a subsection heading starting with |Example:|
% and then, with the command-line option |--examples_as_exercises| be
% typeset as exercises. This is useful if one has solution
% environments as part of the example.
% 
% 
% *a)* State some problem.
% 
% *Solution.* The answer to this subproblem can be written here.
% 
% *b)* State some other problem.
% 
% *Hint 1.* A hint can be given.
% 
% *Hint 2.* Maybe even another hint?
% 
% *Solution.* The answer to this other subproblem goes here,
% maybe over multiple doconce input lines.
% 
% % --- end exercise ---
% 
% 
%% User-defined environments
% 
% 
% 
% The example in the section "Example 1: A test function" demonstrates how to write a test function.
% That is, a special test function for a function |add| appears in
% the example in the section "Example 1: A test function".
% 
% 
% 
%% Example 1: A test function
% 
% Suppose we want to write a test function for checking the
% implementation of a Python function for addition.
% 
%  def add(a, b):
%      return a + b
%  
%  def test_add():
%      a = 1; b = 1
%      expected = a + b
%      computed = add(a, b)
%      assert expected == computed
% 
% 
% 
% 
% 
%% Example 2: Addition
% 
% We have
% 
% $$1 + 1 = 2$$
% or in tabular form:
% 
% <table border="1">
% <thead>
% <tr><th align="center">Problem</th> <th align="center">Result</th> </tr>
% </thead>
% <tbody>
% <tr><td align="center">   $1+1$      </td> <td align="center">   $2$       </td> </tr>
% </tbody>
% </table>
% 
% 
% !bnotice Highlight box!
% This environment is used to highlight something:
% 
% $$E = mc^2$$
% !enotice
% 
% 
% 
%% URLs
% 
% Testing of URLs: hpl's home page hpl <https://folk.uio.no/hpl>, or
% the entire URL if desired, <https://folk.uio.no/hpl>.  Here is a
% plain file link <testdoc.do.txt>, or <testdoc.do.txt>, or
% <testdoc.do.txt> or <testdoc.do.txt> or a link with
% newline <testdoc.do.txt>. Can test spaces with the link with word
% too: hpl <https://folk.uio.no/hpl> or hpl <https://folk.uio.no/hpl>. Also |file:///| works: link to a
% file <file:///home/hpl/vc/doconce/doc/demos/manual/manual.html> is
% fine to have. Moreover, "loose" URLs work, i.e., no quotes, just
% the plain URL as in <https://folk.uio.no/hpl>, if followed by space, comma,
% colon, semi-colon, question mark, exclamation mark, but not a period
% (which gets confused with the periods inside the URL).
% 
% Mail addresses can also be used: hpl@simula.no <mailto:hpl@simula.no>, or just a mail link <mailto:hpl@simula.no>, or a raw <mailto:hpl@simula.no>.
% 
% Here are some tough tests of URLs, especially for the |latex| format:
% Newton-Cotes <https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas> formulas
% and a good book <https://www.springer.com/mathematics/computational+science+%26+engineering/book/978-3-642-23098-1>. Need to test
% Newton-Cotes with percentage in URL too:
% <https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas>
% and <https://en.wikipedia.org/wiki/Newton-Cotes#Open_Newton.E2.80.93Cotes_formulae> which has a shebang.
% 
% For the |--device=paper| option it is important to test that URLs with
% monospace font link text get a footnote
% (unless the |--latex_no_program_footnotelink|
% is used), as in this reference to
% decay_mod <https://github.com/hplgit/INF5620/tree/gh-pages/src/decay/experiments/decay_mod.py>, ball1.py <https://tinyurl.com/pwyasaa/formulas.ball1.py>,
% and ball2.py <https://tinyurl.com/pwyasaa/formulas.ball2.py>.
% 
% 
% % Comments should be inserted outside paragraphs (because in the rst
% % format extra blanks make a paragraph break).
% 
% % Note that when there is no https: or file:, it can be a file link
% % if the link name is URL, url, "URL", or "url". Such files should,
% % if rst output is desired, but placed in a |_static*| folder.
% 
% More tough tests: repeated URLs whose footnotes when using the
% |--device=paper| option must be correct. We have
% google <https://google.com>, google <https://google.com>, and
% google <https://google.com>, which should result in exactly three
% footnotes.
% 
% 
% 
% % !split and check if these extra words are included properly in the comment
% 
%% LaTeX Mathematics
% 
% Here is an equation without label using backslash-bracket environment:
% $$a = b + c$$
% 
% or with number and label, as in Equation (my:eq1), using the equation environment:
% 
% $${\partial u\over\partial t} = \nabla^2 u$$
% 
% We can refer to this equation by Equation (my:eq1).
% 
% Here is a system without equation numbers, using the align-asterisk environment:
% 
% $$\begin{align*} \pmb{a} &= \pmb{q}\times\pmb{n} \\  b &= \nabla^2 u + \nabla^4 v \end{align*}$$
% 
% 
% 
% More mathematical typesetting is demonstrated in the coming exercises.
% 
% Below, we have "Problem 2: Flip a Coin" and "Project 4: Compute a Probability",
% as well as "Project 5: Explore Distributions of Random Circles" and "Project 11: References to Project ref{demo:ex:2} in a heading works for matlabnb", and in
% between there we have "Exercise 10: Make references to projects and problems".
% 
% 
%% Exercises
% 
% 
% 
% % --- begin exercise ---
% 
%% Problem 2: Flip a Coin
% 
% % keywords = random numbers; Monte Carlo simulation; ipynb
% 
% % Torture tests
% 
% 
% *a)* Make a program that simulates flipping a coin $N$ times.
% Print out "tail" or "head" for each flip and
% let the program count the number of heads.
% 
% % --- begin hint in exercise ---
% 
% *Hint 1.* Use |r = random.random()| and define head as |r <= 0.5|.
% 
% % --- end hint in exercise ---
% 
% % --- begin hint in exercise ---
% 
% *Hint 2.* Draw an integer among $\{1,2\}$ with
% |r = random.randint(1,2)| and define head when |r| is 1.
% 
% % --- end hint in exercise ---
% 
% 
% % --- begin answer of exercise ---
% *Answer.* If the |random.random()| function returns a number $<1/2$, let it be
% head, otherwise tail. Repeat this $N$ number of times.
% % --- end answer of exercise ---
% 
% 
% % --- begin solution of exercise ---
*Solution.*
%  import sys, random
%  N = int(sys.argv[1])
%  heads = 0
%  for i in range(N):
%      r = random.random()
%      if r <= 0.5:
%          heads += 1
%  print('Flipping a coin %d times gave %d heads' % (N, heads))
% % --- end solution of exercise ---
% 
% *b)* Vectorize the code in a) using boolean indexing.
% 
% Vectorized code can be written in many ways.
% Sometimes the code is less intuitive, sometimes not.
% At least there is not much to find in the section "Section 1".
% 
% *c)* Vectorize the code in a) using |numpy.sum|.
% 
% 
% % --- begin answer of exercise ---
% *Answer.* |np.sum(np.where(r <= 0.5, 1, 0))| or |np.sum(r <= 0.5)|.
% % --- end answer of exercise ---
% 
% In this latter subexercise, we have an
% example where the code is easy to read.
% 
% 
%% My remarks
% Remarks with such a subsubsection is treated as more text
% after the last subexercise. Test a list too:
% 
% # Mark 1.
% 
% # Mark 2.
% 
% Filenames: |flip_coin.py|, |flip_coin.pdf|.
% 
% % Closing remarks for this Problem
% 
%% Remarks
% These are the exercise remarks, appearing at the very end.
% 
% % solution files: mysol.txt, mysol_flip_coin.py, yet_another.file
% 
% % --- end exercise ---
% 
% 
%% Not an exercise
% 
% Should be possible to stick a normal section in the middle of many
% exercises.
% 
% 
% 
% % --- begin exercise ---
% 
%% Exercise 3: Test of plain text exercise
% 
% Very short exercise. What is the capital
% of Norway?
% Filename: |myexer1|.
% 
% % --- end exercise ---
% 
% 
% 
% 
% % --- begin exercise ---
% 
%% Project 4: Compute a Probability
% 
% % Minimalistic exercise
% 
% 
% What is the probability of getting a number between 0.5 and 0.6 when
% drawing uniformly distributed random numbers from the interval $[0,1)$?
% 
% 
% At the end we have a list because that caused problems in LaTeX
% in previous DocOnce versions:
% 
% # item1
% 
% # item2
% 
% % --- begin hint in exercise ---
% 
% *Hint.* To answer this question empirically, let a program
% draw $N$ such random numbers using Python's standard |random| module,
% count how many of them, $M$, that fall in the interval $(0.5,0.6)$, and
% compute the probability as $M/N$.
% 
% % --- end hint in exercise ---
% 
% % --- end exercise ---
% 
% 
% 
% 
% % --- begin exercise ---
% 
%% Project 5: Explore Distributions of Random Circles
% 
% % keywords = ipynb
% 
% The formula for a circle is given by
% 
% $$x &= x_0 + R\cos 2\pi t, \\  y &= y_0 + R\sin 2\pi t,$$
% where $R$ is the radius of the circle, $(x_0,y_0)$ is the
% center point, and $t$ is a parameter in the unit interval $[0,1]$.
% For any $t$, $(x,y)$ computed from Equations (circle:x)-(circle:y)
% is a point on the circle.
% The formula can be used to generate |n| points on a circle:
% 
%  import numpy as np
%  
%  def circle(R, x0, y0, n=501):
%      t = np.linspace(0, 1, n)
%      x = x0 + R*np.cos(2*np.pi*t)
%      y = y0 + R*np.sin(2*np.pi*t)
%      return x, y
%  
%  x, y = circle(2.0, 0, 0)
% 
% % Often in an exercise we have some comments about the solution
% % which we normally want to keep where they are.
% 
% The goal of this project is to draw $N$ circles with random
% center and radius. Plot each circle using the |circle| function
% above.
% 
% 
% *a)* Let $R$ be normally distributed and $(x_0,y_0)$ uniformly distributed.
% 
% % --- begin hint in exercise ---
% 
% *Hint.* Use the |numpy.random| module to draw the
% $x_0$, $y_0$, and $R$ quantities.
% 
% % --- end hint in exercise ---
% 
% 
% % --- begin answer of exercise ---
% *Answer.* Here goes the short answer to part a).
% % --- end answer of exercise ---
% 
% 
% % --- begin solution of exercise ---
% *Solution.* Here goes a full solution to part a).
% % --- end solution of exercise ---
% 
% *b)* Let $R$ be uniformly distributed and $(x_0,y_0)$ normally distributed.
% Filename: |norm|.
% 
% *c)* Let $R$ and $(x_0,y_0)$ be normally distributed.
% 
% 
% Filename: |circles|.
% 
% % Closing remarks for this Project
% 
%% Remarks
% At the very end of the exercise it may be appropriate to summarize
% and give some perspectives.
% 
% 
% % --- end exercise ---
% 
% 
% 
% 
% % --- begin exercise ---
% 
%% Exercise 6: Determine some Distance
% 
% Intro to this exercise. Questions are in subexercises below.
% 
% 
% % --- begin solution of exercise ---
% *Solution.* Here goes a full solution of the whole exercise.
% With some math $a=b$ in this solution:
% $$\hbox{math in solution: } a = b$$
% And code |a=b| in this solution:
!bc
%  a = b  # code in solution
% End of solution is here.
% 
% % --- end solution of exercise ---
% 
% 
% *a)* Subexercises are numbered a), b), etc.
% 
% % --- begin hint in exercise ---
% 
% *Hint 1.* First hint to subexercise a).
% With math $a=b$ in hint:
% 
% $$a=b.$$
% And with code (in plain verbatim) returning $x+1$ in hint:
% 
!bc
%  def func(x):
%      return x + 1  # with code in hint
% 
% % --- end hint in exercise ---
% 
% % --- begin hint in exercise ---
% 
% *Hint 2.* Second hint to subexercise a).
% 
% Test list in hint:
% 
% # item1
% 
% # item2
% 
% % --- end hint in exercise ---
% Filename: |subexer_a.pdf|.
% 
% 
% % --- begin answer of exercise ---
% *Answer.* Short answer to subexercise a).
% With math in answer: $a=b$.
% % --- end answer of exercise ---
% 
% *b)* Here goes the text for subexercise b).
% 
% 
% Some math $\cos^2 x + \sin^2 x = 1$ written one a single line:
% 
% $$\cos^2 x + \sin^2 x = 1 \thinspace .$$
% 
% % --- begin hint in exercise ---
% 
% *Hint.* A hint for this subexercise.
% 
% % --- end hint in exercise ---
% Filename: |subexer_b.pdf|.
% 
% 
% % --- begin solution of exercise ---
% *Solution.* Here goes the solution of this subexercise.
% % --- end solution of exercise ---
% 
% 
% 
% % No meaning in this weired test example:
% The text here belongs to the main (intro) part of the exercise. Need
% closing remarks to have text after subexercises.
% 
% Test list in exercise:
% 
% # item1
% 
% # item2
% % Closing remarks for this Exercise
% 
%% Remarks
% Some final closing remarks, e.g., summarizing the main findings
% and their implications in other problems can be made. These
% remarks will appear at the end of the typeset exercise.
% 
% 
% % --- end exercise ---
% 
% 
% 
% 
% % --- begin exercise ---
% 
%% Some exercise without the "Exercise:" prefix
% 
% % Another minimalistic exercise
% 
% Just some text. And some math saying that $e^0=1$ on a single line,
% to test that math block insertion is correct:
% 
% $$\exp{(0)} = 1$$
% 
% And a test that the code |lambda x: x+2| is correctly placed here:
% 
!bc
%  lambda x: x+2
% 
% 
% % Have some comments at the end of the exercise to see that
% % the Filename: ... is written correctly.
% % --- end exercise ---
% 
% 
% 
% 
% % --- begin exercise ---
% 
%% Exercise 8: Solution of differential equation
% 
% % --- begin quiz ---
% % --- quiz heading: SOlution of differential equation
% % --- previous heading type: exercise
% % --- keywords: ['derivatives', 'exponential function', 'equation, differential', 'differential equation']
% 
% % --- begin quiz question ---
% Given
% 
% $$\frac{dy}{dx} = -y(x),\quad y(0)=1$$
% What is the solution of this equation?
% % --- end quiz question ---
% % --- label: quiz:diff:eq1
% 
% 
% % --- begin quiz choice 1 (right) ---
% $y=e^{-y}$
% % --- end quiz choice 1 (right) ---
% 
% % --- begin quiz choice 2 (wrong) ---
% $y=e^{y}$
% % --- end quiz choice 2 (wrong) ---
% 
% % --- begin explanation of choice 2 ---
% Almost, but the sign is wrong (note the minus!).
% % --- end explanation of choice 2 ---
% 
% % --- begin quiz choice 3 (wrong) ---
%  from math import exp
%  def f(x):
%      return exp(x)
% % --- end quiz choice 3 (wrong) ---
% 
% % --- begin explanation of choice 3 ---
% Ooops, forgot a minus: |exp(-x)|, otherwise this Python code
% must be considered as a good answer. It is more natural,
% though, to write the solution to the problem
% in mathematical notation:
% 
% $$y(x) = e^{-y}.$$
% % --- end explanation of choice 3 ---
% 
% % --- begin quiz choice 4 (wrong) ---
% The solution cannot be found because there is a derivative in the equation.
% % --- end quiz choice 4 (wrong) ---
% 
% % --- begin explanation of choice 4 ---
% Equations with derivatives can be solved;
% they are termed _differential
% equations_.
% % --- end explanation of choice 4 ---
% 
% % --- begin quiz choice 5 (wrong) ---
% The equation is meaningless: an equation must be an equation
% for $x$ or $y$, not a function $y(x)$.
% % --- end quiz choice 5 (wrong) ---
% 
% % --- begin explanation of choice 5 ---
% Equations where the unknown is a function, as $y(x)$
% here, are called _differential equations_, and are solved by
% special techniques.
% % --- end explanation of choice 5 ---
% % --- end quiz ---
% 
% % --- end exercise ---
% 
% 
% 
% 
% % --- begin exercise ---
% 
%% Example 9: Just an example
% 
% % This example needs the --examples_as_exercises option, otherwise
% % it is just typeset as it is written.
% 
% 
% *a)* What is the capital of Norway?
% 
% *Answer.* Oslo.
% 
% % --- end exercise ---
% 
% 
%% Here goes another section
% 
% With some text, before we continue with exercises.
% 
%% More Exercises
% 
% 
% 
% % --- begin exercise ---
% 
%% Exercise 10: Make references to projects and problems
% 
% % Test comments not at the end only
% Pick a statement from "Project 5: Explore Distributions of Random Circles" or "Problem 2: Flip a Coin"
% and verify it.
% 
% Test list at the end of an exercise without other elements (like subexercise,
% hint, etc.):
% 
% # item1
% 
% # item2
% 
% Filename: |verify_formula.py|.
% 
% % --- end exercise ---
% 
% 
% 
% 
% % --- begin exercise ---
% 
%% Project 11: References to "Project 4: Compute a Probability" in a heading works for matlabnb
% 
% Refer to the previous exercise as "Exercise 10: Make references to projects and problems",
% the two before that as "Project 4: Compute a Probability" and "Project 5: Explore Distributions of Random Circles",
% and this one as "Project 11: References to Project ref{demo:ex:2} in a heading works for matlabnb".
% Filename: |selc_composed.pdf|.
% 
% % --- end exercise ---
% 
% 
%% References
% 
%  # *H. P. Langtangen and G. Pedersen*. 
%     Propagation of Large Destructive Waves,
%     _International Journal of Applied Mechanics and Engineering_,
%     7(1),
%     pp. 187-204,
%     2002.
% 
%  # *H. P. Langtangen, K.-A. Mardal and R. Winther*. 
%     Numerical Methods for Incompressible Viscous Flow,
%     _Advances in Water Resources_,
%     25,
%     pp. 1125-1146,
%     2002.
% 
%  # *H. P. Langtangen*. 
%     Numerical Solution of First Passage Problems in Random Vibrations,
%     _SIAM Journal of Scientific and Statistical Computing_,
%     15,
%     pp. 997-996,
%     1994.
% 
%  # *K.-A. Mardal, G. W. Zumbusch and H. P. Langtangen*. 
%     Software Tools for Multigrid Methods,
%     _Advanced Topics in Computational Partial Differential Equations -- Numerical Methods and Diffpack Programming_,
%     edited by *H. P. Langtangen and A. Tveito*,
%     Springer,
%     2003,
%     Edited book,
%     <http://some.where.org>.
% 
%  # *H. P. Langtangen*. 
%     The FEMDEQS Program System,
%     _Department of Mathematics, University of Oslo_,
%     1989,
%     <http://www.math.uio.no/old/days/hpl/femdeqs.pdf>.
% 
%  # *H. P. Langtangen*. 
%     Stochastic Breakthrough Time Analysis of an Enhanced Oil Recovery Process,
%     _SIAM Journal on Scientific Computing_,
%     13,
%     pp. 1394-1417,
%     1992.
% 
%  # *M. Mortensen, H. P. Langtangen and G. N. Wells*. 
%     A FEniCS-Based Programming Framework for Modeling Turbulent Flow by the Reynolds-Averaged Navier-Stokes Equations,
%     _Advances in Water Resources_,
%     34(9),
%     doi: 10.1016/j.advwatres.2011.02.013 <https://dx.doi.org/10.1016/j.advwatres.2011.02.013>,
%     2011.
% 
%  # *S. Glimsdal, G. Pedersen, K. Atakan, C. B. Harbitz, H. P. Langtangen and F. L\ovholt*. 
%     Propagation of the Dec. 26, 2004 Indian Ocean Tsunami: Effects of Dispersion and Source Characteristics,
%     _International Journal of Fluid Mechanics Research_,
%     33(1),
%     pp. 15-43,
%     2006.
% 
%  # *S. Rahman, J. Gorman, C. H. W. Barnes, D. A. Williams and H. P. Langtangen*. 
%     Numerical Investigation of a Piezoelectric Surface Acoustic Wave Interaction With a One-Dimensional Channel,
%     _Physical Review B: Condensed Matter and Materials Physics_,
%     74,
%     2006,
%     035308.
% 
% # *J. B. Haga, H. Osnes and H. P. Langtangen*. 
%     On the Causes of Pressure Oscillations in Low-Permeable and Low-Compressible Porous Media,
%     _International Journal of Analytical and Numerical Methods in Geomechanics_,
%     doi: 10.1002/nag.1062 <https://dx.doi.org/10.1002/nag.1062>,
%     2011,
%     <http://onlinelibrary.wiley.com/doi/10.1002/nag.1062/abstract>.
% 
% # *H. P. Langtangen*. 
%     _Computational Partial Differential Equations - Numerical Methods and Diffpack Programming_,
%     second edition,
%     _Texts in Computational Science and Engineering_,
%     Springer,
%     2003.
% 
% # *H. P. Langtangen*. 
%     _Python Scripting for Computational Science_,
%     third edition,
%     _Texts in Computational Science and Engineering_,
%     Springer,
%     2008.
% 
% # *H. P. Langtangen and G. Pedersen*. 
%     Finite Elements for the Boussinesq Wave Equations,
%     Waves and Non-linear Processes in Hydrodynamics,
%     edited by *J. Grue, B. Gjevik and J. E. Weber*,
%     Kluwer Academic Publishers,
%     pp. pp. 117-126,
%     1995,
%     <http://www.amazon.ca/Waves-Nonlinear-Processes-Hydrodynamics-John/dp/0792340310>.
% 
% # *H. P. Langtangen*. 
%     _A Primer on Scientific Programming With Python_,
%     third edition,
%     _Texts in Computational Science and Engineering_,
%     Springer,
%     2012.
% 
% # *P. V. Jeberg, H. P. Langtangen and C. B. Terp*. 
%     Optimization With Diffpack: Practical Example From Welding,
%     _Simula Research Laboratory_,
%     2004,
%     Internal report.
% 
% # *H. P. Langtangen*. 
%     Computational Methods for Two-Phase Flow in Oil Reservoirs,
%     Ph.D. Thesis,
%     Mechanics Division, Department of Mathematics, University of Oslo,
%     1989,
%     Dr. Scient. thesis..
% 
% # *H. P. Langtangen*. 
%     Computational Modeling of Huge Tsunamis From Asteroid Impacts,
%     2007,
%     Invited keynote lecture at the \emphInternational conference on Computational Science 2007 (ICCS'07), Beijing, China.
% 
% # *H. P. Langtangen*. 
%     Solution of the Navier-Stokes Equations With the Finite Element Method in Two and Three Dimensions,
%     M.Sc. Thesis,
%     Mechanics Division, Department of Mathematics, University of Oslo,
%     1985,
%     Cand.Scient. thesis.
% 
% # *H. P. Langtangen and A. Tveito*. 
%     Numerical Methods in Continuum Mechanics,
%     _Center for Industrial Research_,
%     1991,
%     Lecture notes for a course (ME-IN 324). 286 pages..
% 
% # *H. P. Langtangen*. 
%     Diffpack: Software for Partial Differential Equations,
%     _Proceedings of the Second Annual Object-Oriented Numerics Conference (OON-SKI'94), Sunriver, Oregon, USA_,
%     edited by *A. Vermeulen*,
%     1994.
% 
%% Appendix: Just for testing; part I
% 
% This is the first appendix.
% 
%% A subsection within an appendix
% 
% Some text.
% 
%% Appendix: Just for testing; part II
% 
% This is more stuff for an appendix.
% 
%% Appendix: Testing identical titles
% 
% Without label.
% 
% 
%% Appendix: Testing identical titles
% 
% With label.
% 
%% Appendix: Testing identical titles
% 
% What about inserting a quiz?
% 
% % --- begin quiz ---
% % --- new quiz page: Test of quizzes
% % --- quiz heading: Capital of Norway
% % --- previous heading type: subsection
% % --- keywords: ['capitals', 'basic intelligence', 'geography']
% 
% 
% % --- begin quiz question ---
% [Fundamental test:] What is the capital of Norway?
% % --- end quiz question ---
% 
% % --- begin quiz choice 1 (wrong) ---
% [Answer 1:] Stockholm
% % --- end quiz choice 1 (wrong) ---
% 
% % --- begin explanation of choice 1 ---
% Stockholm is the capital of Sweden.
% % --- end explanation of choice 1 ---
% 
% % --- begin quiz choice 2 (wrong) ---
% [Answer 2:] London
% % --- end quiz choice 2 (wrong) ---
% 
% % --- begin quiz choice 3 (right) ---
% [Answer 3:] Oslo
% % --- end quiz choice 3 (right) ---
% 
% % --- begin quiz choice 4 (wrong) ---
% Bergen
% % --- end quiz choice 4 (wrong) ---
% 
% % --- begin explanation of choice 4 ---
% Those from Bergen would claim so, but nobody else.
% % --- end explanation of choice 4 ---
% % --- end quiz ---
% 
% 
%% Appendix: Testing identical titles
% 
% Without label.
% 
% !bnotice Tip
% Here is a tip or hint box, typeset as a notice box.
% !enotice
% 
% 
% 
% Need a lot of text to surround the summary box.
% Version control systems allow you to record the history of files
% and share files among several computers and collaborators in a
% professional way. File changes on one computer are updated or
% merged with changes on another computer. Especially when working
% with programs or technical reports it is essential
% to have changes documented and to
% ensure that every computer and person involved in the project
% have the latest updates of the files.
% Greg Wilson' excellent Script for Introduction to Version Control <https://software-carpentry.org/2010/07/script-for-introduction-to-version-control/> provides a more detailed motivation why you will benefit greatly
% from using version control systems.
% 
% !bsummary
% *Bold remark:* Make some text with this summary.
% Much testing in this document, otherwise stupid content.
% Much testing in this document, otherwise stupid content.
% Much testing in this document, otherwise stupid content.
% Much testing in this document, otherwise stupid content.
% Much testing in this document, otherwise stupid content.
% Much testing in this document, otherwise stupid content.
% Much testing in this document, otherwise stupid content.
% Much testing in this document, otherwise stupid content.
% Much testing in this document, otherwise stupid content.
% !esummary
% 
% Projects that you want to share among several computers or project
% workers are today most conveniently stored at some web site "in the
% cloud" and updated through communication with that site. I strongly
% recommend you to use such sites for all serious programming and
% scientific writing work - and all other important files.
% 
% The simplest services for hosting project files are Dropbox <https://dropbox.com> and Google Drive <https://drive.google.com>.
% It is very easy to get started with these systems, and they allow you
% to share files among laptops and mobile units with as many users as
% you want. The systems offer a kind of version control in that the
% files are stored frequently (several times per minute), and you can go
% back to previous versions for the last 30 days. However, it is
% challenging  to find the right version from the past when there are
% so many of them.
% 
% More seriously, when several people may edit files simultaneously, it
% can be difficult detect who did what when, roll back to previous
% versions, and to manually merge the edits when these are
% incompatible. Then one needs more sophisticated tools than Dropbox or
% Google Drive: project hosting services with true version control
% systems.  The following text aims at providing you with the minimum
% information to started with such systems. Numerous other tutorials
% contain more comprehensive material and in-depth explanations of the
% concepts and tools.
% 
% The idea with project hosting services is that you have the files
% associated with a project in the cloud. Many people may share these
% files.  Every time you want to work on the project you explicitly
% update your version of the files, edit the files as you like, and
% synchronize the files with the "master version" at the site where the
% project is hosted.  If you at some point need to go back to a
% version of the files at some particular point in the past,
% this is an easy operation. You can also use tools to see
% what various people have done with the files in the various versions.
% 
% All these services are very similar. Below we describe how you get
% started with Bitbucket, GitHub, and Googlecode. Launchpad works very
% similarly to the latter three. All the project hosting services have
% excellent introductions available at their web sites, but the recipes
% below are much shorter and aim at getting you started as quickly as
% possible by concentrating on the most important need-to-know steps.
% The Git tutorials we refer to later in this document contain more
% detailed information and constitute of course very valuable readings
% when you use version control systems every day. The point now is
% to get started.
% 
% 
%% Appendix: Testing inline comments
% 
% % Names can be [ A-Za-z0-9_'+-]+
% 
% Projects that you want to share among several computers or project
% workers are today most conveniently stored at some web site "in the
% cloud" and updated through communication with that
% site. [hpl's semi opinion 1: not sure if in the cloud is
% understood by
% all.] I strongly recommend you to use such sites for all serious
% programming and scientific writing work - and all other important
% files.
% 
% The simplest services for hosting project files is Dropbox. [mp 2: Simply go to <https://dropbox.com> and watch the video. It explains
% how files, like |myfile.py|, perhaps containing much math, like
% $\partial u/\partial t$, are easily communicated between machines.] It
% is very easy to get started with Dropbox, and it allows you to share
% files among [hpl 3: laptops and mobile units -> computers, tablets,
% and phones].
% 
% % Test horizontal rule
% 
% ------
% 
% % Coments for editing
% 
% First[add 4: ,] consider a quantity $Q$. [edit 5: To this end, -> We note that]
% $Q>0$, because [del 6: a] negative [edit 7: quantity is -> quantities
% are] [del 8: just] negative. [add 9: This comes as no surprise.]
% 
% % Test tailored latex figure references with page number
% Let us refer to Figure ref{fig:impact} again.
% 
% Test references in a list:
% 
%  * "Section 1"
% 
%  * "Subsection 1"
% 
%  * ref{fig:impact}
% 
%% Appendix: Testing headings ending with |verbatim inline|
% 
% The point here is to test 1) |verbatim| code in headings, and 2)
% ending a heading with verbatim code as this triggers a special
% case in LaTeX.
% 
% We also test mdash---used as alternative to hyphen without spaces around,
% or in quotes:
% 
% !bquote
% _Fun is fun_.---Unknown.
% !equote
% 
% The ndash should also be tested - as in the Hanson - Nilson equations
% on page 277 - 278.
% 
% And finally, what about admons, quotes, and boxes? They are tested
% in a separate document: |admon.do.txt|.
% 
% [^example-of-the-third-footnote]: Not much to add here, but the footnote
% is at the end with only one newline.

************** File: testdoc.tmp *****************
label{subsec1}

idx{`somefunc` function}

# Refer to section/appendix etc. at the beginning of the line
# and other special fix situations for HTML.

More text, with a reference back to
Section ref{sec1} and ref{subsec1}, and further to the
sections    ref{subsec1} and ref{subsubsec:ex}, which
encourages you to do the tasks in the
Exercises ref{demo:ex:1} and ref{exer:some:formula}.
Appendices     ref{app1} and ref{app2} are also nice elements.

=== Test Section reference at beginning of line and after a sentence ===

Section ref{subsec1} is fine.
Section ref{subsubsec:ex} too.


# sphinx code-blocks: pycod=python cod=fortran cppcod=c++ sys=console

=== Computer code ===

Let's do some copying from files too. First from subroutine up to the very end,

@@@CODE ../doc/src/manual/__testcode.f fromto: subroutine@
===== Project: Compute a Probability =====

# Minimalistic exercise

label{demo:ex:2}

What is the probability of getting a number between 0.5 and 0.6 when
Could not find match for from regex "\*\s+\$.+normally"

************** File: .testdoc.exerinfo *****************
# Information about all exercises in the file testdoc.do.txt.
# The information can be loaded into a Python list of dicts by
#
# f = open('.testdoc.exerinfo', 'r')
# exer = eval(f.read())
#
[{'ans_docend': '',
  'answer': '',
  'chapter_exercise': None,
  'chapter_no': None,
  'chapter_title': None,
  'chapter_type': None,
  'closing_remarks': '',
  'file': None,
  'heading': '=====',
  'hints': [],
  'keywords': None,
  'label': 'Example',
  'no': 1,
  'sol_docend': '',
  'solution': '',
  'solution_file': None,
  'subex': [{'ans_docend': '',
             'answer': '',
             'file': None,
             'hints': [],
             'sol_docend': '',
             'solution': 'The answer to this subproblem can be written here.',
             'text': 'State some problem.'},
            {'ans_docend': '',
             'answer': '',
             'file': None,
             'hints': ['A hint can be given.', 'Maybe even another hint?'],
             'sol_docend': '',
             'solution': 'The answer to this other subproblem goes here,\n'
                         'maybe over multiple doconce input lines.',
             'text': 'State some other problem.'}],
  'text': 'Examples can start with a subsection heading starting with '
          '`Example:`\n'
          'and then, with the command-line option `--examples_as_exercises` '
          'be\n'
          'typeset as exercises. This is useful if one has solution\n'
          'environments as part of the example.',
  'title': 'Examples can be typeset as exercises',
  'type': 'Example',
  'type_visible': True},
 {'ans_docend': '',
  'answer': '',
  'chapter_exercise': None,
  'chapter_no': None,
  'chapter_title': None,
  'chapter_type': None,
  'closing_remarks': 'These are the exercise remarks, appearing at the very '
                     'end.',
  'file': ['flip_coin.py', 'flip_coin.pdf'],
  'heading': '=====',
  'hints': [],
  'keywords': ['random numbers', 'Monte Carlo simulation', 'ipynb'],
  'label': 'demo:ex:1',
  'no': 2,
  'sol_docend': '',
  'solution': '',
  'solution_file': ['mysol.txt', 'mysol_flip_coin.py', 'yet_another.file'],
  'subex': [{'ans_docend': '',
             'answer': 'If the `random.random()` function returns a number '
                       '$<1/2$, let it be\n'
                       'head, otherwise tail. Repeat this $N$ number of times.',
             'file': None,
             'hints': ['Use `r = random.random()` and define head as `r <= '
                       '0.5`.',
                       'Draw an integer among $\\{1,2\\}$ with\n'
                       '`r = random.randint(1,2)` and define head when `r` is '
                       '1.'],
             'sol_docend': '',
             'solution': '!bc pycod\n'
                         'import sys, random\n'
                         'N = int(sys.argv[1])\n'
                         'heads = 0\n'
                         'for i in range(N):\n'
                         '    r = random.random()\n'
                         '    if r <= 0.5:\n'
                         '        heads += 1\n'
                         "print('Flipping a coin %d times gave %d heads' % (N, "
                         'heads))\n'
                         '\n'
                         '!ec',
             'text': 'Make a program that simulates flipping a coin $N$ '
                     'times.\n'
                     "Print out ``tail'' or ``head'' for each flip and\n"
                     'let the program count the number of heads.'},
            {'aftertext': '\n'
                          'Vectorized code can be written in many ways.\n'
                          'Sometimes the code is less intuitive, sometimes '
                          'not.\n'
                          'At least there is not much to find in Section '
                          'ref{sec1}.\n',
             'ans_docend': '',
             'answer': '',
             'file': None,
             'hints': [],
             'sol_docend': '',
             'solution': '',
             'text': 'Vectorize the code in a) using boolean indexing.'},
            {'aftertext': '\n'
                          'In this latter subexercise, we have an\n'
                          'example where the code is easy to read.\n'
                          '\n'
                          '\n'
                          '=== My remarks ===\n'
                          '\n'
                          'Remarks with such a subsubsection is treated as '
                          'more text\n'
                          'after the last subexercise. Test a list too:\n'
                          '\n'
                          ' o Mark 1.\n'
                          ' o Mark 2.\n',
             'ans_docend': '',
             'answer': '`np.sum(np.where(r <= 0.5, 1, 0))` or `np.sum(r <= '
                       '0.5)`.',
             'file': None,
             'hints': [],
             'sol_docend': '',
             'solution': '',
             'text': 'Vectorize the code in a) using `numpy.sum`.'}],
  'text': '# Torture tests',
  'title': 'Flip a Coin',
  'type': 'Problem',
  'type_visible': True},
 {'ans_docend': '',
  'answer': '',
  'chapter_exercise': None,
  'chapter_no': None,
  'chapter_title': None,
  'chapter_type': None,
  'closing_remarks': '',
  'file': ['myexer1'],
  'heading': '=====',
  'hints': [],
  'keywords': None,
  'label': 'my:exer1',
  'no': 3,
  'sol_docend': '',
  'solution': '',
  'solution_file': None,
  'subex': [],
  'text': 'Very short exercise. What is the capital\nof Norway?',
  'title': 'Test of plain text exercise',
  'type': 'Exercise',
  'type_visible': True},
 {'ans_docend': '',
  'answer': '',
  'chapter_exercise': None,
  'chapter_no': None,
  'chapter_title': None,
  'chapter_type': None,
  'closing_remarks': '',
  'file': None,
  'heading': '=====',
  'hints': ['To answer this question empirically, let a program\n'
            "draw $N$ such random numbers using Python's standard `random` "
            'module,\n'
            'count how many of them, $M$, that fall in the interval '
            '$(0.5,0.6)$, and\n'
            'compute the probability as $M/N$.'],
  'keywords': None,
  'label': 'demo:ex:2',
  'no': 4,
  'sol_docend': '',
  'solution': '',
  'solution_file': None,
  'subex': [],
  'text': '# Minimalistic exercise\n'
          '\n'
          '\n'
          'What is the probability of getting a number between 0.5 and 0.6 '
          'when\n'
          'drawing uniformly distributed random numbers from the interval '
          '$[0,1)$?\n'
          '\n'
          '\n'
          'At the end we have a list because that caused problems in LaTeX\n'
          'in previous DocOnce versions:\n'
          '\n'
          ' o item1\n'
          ' o item2',
  'title': 'Compute a Probability',
  'type': 'Project',
  'type_visible': True},
 {'ans_docend': '',
  'answer': '',
  'chapter_exercise': None,
  'chapter_no': None,
  'chapter_title': None,
  'chapter_type': None,
  'closing_remarks': 'At the very end of the exercise it may be appropriate to '
                     'summarize\n'
                     'and give some perspectives.',
  'file': ['circles'],
  'heading': '=====',
  'hints': [],
  'keywords': ['ipynb'],
  'label': 'proj:circle1',
  'no': 5,
  'sol_docend': '',
  'solution': '',
  'solution_file': None,
  'subex': [{'ans_docend': '',
             'answer': 'Here goes the short answer to part a).',
             'file': None,
             'hints': ['Use the `numpy.random` module to draw the\n'
                       '$x_0$, $y_0$, and $R$ quantities.'],
             'sol_docend': '',
             'solution': 'Here goes a full solution to part a).',
             'text': 'Let $R$ be normally distributed and $(x_0,y_0)$ '
                     'uniformly distributed.'},
            {'ans_docend': '',
             'answer': '',
             'file': ['norm'],
             'hints': [],
             'sol_docend': '',
             'solution': '',
             'text': 'Let $R$ be uniformly distributed and $(x_0,y_0)$ '
                     'normally distributed.'},
            {'aftertext': '\n',
             'ans_docend': '',
             'answer': '',
             'file': None,
             'hints': [],
             'sol_docend': '',
             'solution': '',
             'text': 'Let $R$ and $(x_0,y_0)$ be normally distributed.'}],
  'text': 'The formula for a circle is given by\n'
          '\n'
          '!bt\n'
          '\\begin{align}\n'
          'x &= x_0 + R\\cos 2\\pi t,\n'
          'label{circle:x}\\\\ \n'
          'y &= y_0 + R\\sin 2\\pi t,\n'
          'label{circle:y}\n'
          '\\end{align}\n'
          '\n'
          '!et\n'
          'where $R$ is the radius of the circle, $(x_0,y_0)$ is the\n'
          'center point, and $t$ is a parameter in the unit interval $[0,1]$.\n'
          'For any $t$, $(x,y)$ computed from (ref{circle:x})-(ref{circle:y})\n'
          'is a point on the circle.\n'
          'The formula can be used to generate `n` points on a circle:\n'
          '\n'
          '!bc pypro\n'
          'import numpy as np\n'
          '\n'
          'def circle(R, x0, y0, n=501):\n'
          '    t = np.linspace(0, 1, n)\n'
          '    x = x0 + R*np.cos(2*np.pi*t)\n'
          '    y = y0 + R*np.sin(2*np.pi*t)\n'
          '    return x, y\n'
          '\n'
          'x, y = circle(2.0, 0, 0)\n'
          '\n'
          '!ec\n'
          '\n'
          '# Often in an exercise we have some comments about the solution\n'
          '# which we normally want to keep where they are.\n'
          '\n'
          'The goal of this project is to draw $N$ circles with random\n'
          'center and radius. Plot each circle using the `circle` function\n'
          'above.',
  'title': 'Explore Distributions of Random Circles',
  'type': 'Project',
  'type_visible': True},
 {'ans_docend': '',
  'answer': '',
  'chapter_exercise': None,
  'chapter_no': None,
  'chapter_title': None,
  'chapter_type': None,
  'closing_remarks': 'Some final closing remarks, e.g., summarizing the main '
                     'findings\n'
                     'and their implications in other problems can be made. '
                     'These\n'
                     'remarks will appear at the end of the typeset exercise.',
  'file': None,
  'heading': '=====',
  'hints': [],
  'keywords': None,
  'label': 'exer:dist',
  'no': 6,
  'sol_docend': '',
  'solution': 'Here goes a full solution of the whole exercise.\n'
              'With some math $a=b$ in this solution:\n'
              '!bt\n'
              '\\[ \\hbox{math in solution: } a = b \\]\n'
              '\n'
              '!et\n'
              'And code `a=b` in this solution:\n'
              '!bc\n'
              'a = b  # code in solution\n'
              '\n'
              '!ec \n'
              'End of solution is here.',
  'solution_file': None,
  'subex': [{'ans_docend': '',
             'answer': 'Short answer to subexercise a).\n'
                       'With math in answer: $a=b$.',
             'file': ['subexer_a.pdf'],
             'hints': ['First hint to subexercise a).\n'
                       'With math $a=b$ in hint:\n'
                       '\n'
                       '!bt\n'
                       '\\[ a=b. \\]\n'
                       '\n'
                       '!et\n'
                       'And with code (in plain verbatim) returning $x+1$ in '
                       'hint:\n'
                       '\n'
                       '!bc\n'
                       'def func(x):\n'
                       '    return x + 1  # with code in hint\n'
                       '\n'
                       '!ec',
                       'Second hint to subexercise a).\n'
                       '\n'
                       'Test list in hint:\n'
                       '\n'
                       ' o item1\n'
                       ' o item2'],
             'sol_docend': '',
             'solution': '',
             'text': 'Subexercises are numbered a), b), etc.'},
            {'aftertext': '\n'
                          '\n'
                          '\n'
                          '#  No meaning in this weired test example:\n'
                          'The text here belongs to the main (intro) part of '
                          'the exercise. Need\n'
                          'closing remarks to have text after subexercises.\n'
                          '\n'
                          'Test list in exercise:\n'
                          '\n'
                          ' o item1\n'
                          ' o item2\n'
                          '\n',
             'ans_docend': '',
             'answer': '',
             'file': ['subexer_b.pdf'],
             'hints': ['A hint for this subexercise.'],
             'sol_docend': '',
             'solution': 'Here goes the solution of this subexercise.',
             'text': 'Here goes the text for subexercise b).\n'
                     '\n'
                     '\n'
                     'Some math $\\cos^2 x + \\sin^2 x = 1$ written one a '
                     'single line:\n'
                     '\n'
                     '!bt\n'
                     '\\[ \\cos^2 x + \\sin^2 x = 1 \\thinspace .\\]\n'
                     '\n'
                     '!et'}],
  'text': 'Intro to this exercise. Questions are in subexercises below.',
  'title': 'Determine some Distance',
  'type': 'Exercise',
  'type_visible': True},
 {'ans_docend': '',
  'answer': '',
  'chapter_exercise': None,
  'chapter_no': None,
  'chapter_title': None,
  'chapter_type': None,
  'closing_remarks': '',
  'file': None,
  'heading': '=====',
  'hints': [],
  'keywords': None,
  'label': None,
  'no': 7,
  'sol_docend': '',
  'solution': '',
  'solution_file': None,
  'subex': [],
  'text': '# Another minimalistic exercise\n'
          '\n'
          'Just some text. And some math saying that $e^0=1$ on a single '
          'line,\n'
          'to test that math block insertion is correct:\n'
          '\n'
          '!bt\n'
          '\\[ \\exp{(0)} = 1 \\]\n'
          '\n'
          '!et\n'
          '\n'
          'And a test that the code `lambda x: x+2` is correctly placed here:\n'
          '\n'
          '!bc\n'
          'lambda x: x+2\n'
          '\n'
          '!ec ',
  'title': 'Some exercise without the "Exercise:" prefix',
  'type': 'Exercise',
  'type_visible': False},
 {'ans_docend': '',
  'answer': '',
  'chapter_exercise': None,
  'chapter_no': None,
  'chapter_title': None,
  'chapter_type': None,
  'closing_remarks': '',
  'file': None,
  'heading': '=====',
  'hints': [],
  'keywords': None,
  'label': 'sec:this:exer:de',
  'no': 8,
  'sol_docend': '',
  'solution': '',
  'solution_file': None,
  'subex': [],
  'text': '# --- begin quiz ---\n'
          '# --- quiz heading: SOlution of differential equation\n'
          '# --- previous heading type: exercise\n'
          "# --- keywords: ['derivatives', 'exponential function', 'equation, "
          "differential', 'differential equation']\n"
          '\n'
          '# --- begin quiz question ---\n'
          'Given\n'
          '\n'
          '!bt\n'
          '\\[ \\frac{dy}{dx} = -y(x),\\quad y(0)=1 \\]\n'
          '\n'
          '!et\n'
          'What is the solution of this equation?\n'
          '# --- end quiz question ---\n'
          '# --- label: quiz:diff:eq1\n'
          '\n'
          '\n'
          '# --- begin quiz choice 1 (right) ---\n'
          '$y=e^{-y}$\n'
          '# --- end quiz choice 1 (right) ---\n'
          '\n'
          '# --- begin quiz choice 2 (wrong) ---\n'
          '$y=e^{y}$\n'
          '# --- end quiz choice 2 (wrong) ---\n'
          '\n'
          '# --- begin explanation of choice 2 ---\n'
          'Almost, but the sign is wrong (note the minus!).\n'
          '# --- end explanation of choice 2 ---\n'
          '\n'
          '# --- begin quiz choice 3 (wrong) ---\n'
          '!bc pycod\n'
          'from math import exp\n'
          'def f(x):\n'
          '    return exp(x)\n'
          '\n'
          '!ec\n'
          '# --- end quiz choice 3 (wrong) ---\n'
          '\n'
          '# --- begin explanation of choice 3 ---\n'
          'Ooops, forgot a minus: `exp(-x)`, otherwise this Python code\n'
          'must be considered as a good answer. It is more natural,\n'
          'though, to write the solution to the problem\n'
          'in mathematical notation:\n'
          '\n'
          '!bt\n'
          '\\[ y(x) = e^{-y}.\\]\n'
          '\n'
          '!et\n'
          '# --- end explanation of choice 3 ---\n'
          '\n'
          '# --- begin quiz choice 4 (wrong) ---\n'
          'The solution cannot be found because there is a derivative in the '
          'equation.\n'
          '# --- end quiz choice 4 (wrong) ---\n'
          '\n'
          '# --- begin explanation of choice 4 ---\n'
          'Equations with derivatives can be solved;\n'
          'they are termed *differential\n'
          'equations*.\n'
          '# --- end explanation of choice 4 ---\n'
          '\n'
          '# --- begin quiz choice 5 (wrong) ---\n'
          'The equation is meaningless: an equation must be an equation\n'
          'for $x$ or $y$, not a function $y(x)$.\n'
          '# --- end quiz choice 5 (wrong) ---\n'
          '\n'
          '# --- begin explanation of choice 5 ---\n'
          'Equations where the unknown is a function, as $y(x)$\n'
          'here, are called *differential equations*, and are solved by\n'
          'special techniques.\n'
          '# --- end explanation of choice 5 ---\n'
          '# --- end quiz ---',
  'title': 'Solution of differential equation',
  'type': 'Exercise',
  'type_visible': True},
 {'ans_docend': '',
  'answer': '',
  'chapter_exercise': None,
  'chapter_no': None,
  'chapter_title': None,
  'chapter_type': None,
  'closing_remarks': '',
  'file': None,
  'heading': '=====',
  'hints': [],
  'keywords': None,
  'label': None,
  'no': 9,
  'sol_docend': '',
  'solution': '',
  'solution_file': None,
  'subex': [{'ans_docend': '',
             'answer': 'Oslo.',
             'file': None,
             'hints': [],
             'sol_docend': '',
             'solution': '',
             'text': 'What is the capital of Norway?'}],
  'text': '# This example needs the --examples_as_exercises option, otherwise\n'
          '# it is just typeset as it is written.',
  'title': 'Just an example',
  'type': 'Example',
  'type_visible': True},
 {'ans_docend': '',
  'answer': '',
  'chapter_exercise': None,
  'chapter_no': None,
  'chapter_title': None,
  'chapter_type': None,
  'closing_remarks': '',
  'file': ['verify_formula.py'],
  'heading': '=====',
  'hints': [],
  'keywords': None,
  'label': 'exer:some:formula',
  'no': 10,
  'sol_docend': '',
  'solution': '',
  'solution_file': None,
  'subex': [],
  'text': '# Test comments not at the end only\n'
          'Pick a statement from Project ref{proj:circle1} or Problem '
          'ref{demo:ex:1}\n'
          'and verify it.\n'
          '\n'
          'Test list at the end of an exercise without other elements (like '
          'subexercise,\n'
          'hint, etc.):\n'
          '\n'
          ' o item1\n'
          ' o item2',
  'title': 'Make references to projects and problems',
  'type': 'Exercise',
  'type_visible': True},
 {'ans_docend': '',
  'answer': '',
  'chapter_exercise': None,
  'chapter_no': None,
  'chapter_title': None,
  'chapter_type': None,
  'closing_remarks': '',
  'file': ['selc_composed.pdf'],
  'heading': '=====',
  'hints': [],
  'keywords': None,
  'label': 'exer:you',
  'no': 11,
  'sol_docend': '',
  'solution': '',
  'solution_file': None,
  'subex': [],
  'text': 'Refer to the previous exercise as Exercise ref{exer:some:formula},\n'
          'the two before that as Projects ref{demo:ex:2} and '
          'ref{proj:circle1},\n'
          'and this one as Project ref{exer:you}.',
  'title': 'References to Project ref{demo:ex:2} in a heading works for pandoc',
  'type': 'Project',
  'type_visible': True}]
************** File: tmp_encodings.txt *****************
iso-8859-1
iso-8859-1
iso-8859-1
iso-8859-1
iso-8859-1

************** File: html_template.do.txt *****************
DATE: today

===== This is a test of HTML templates =====

Note: When using HTML templates, the DocOnce file cannot have a title
(to avoid generating a header). It should neither have an author.

======= This is a 7 heading =======

Here is some code:
!bc pycod
class Diff:
    def __init__(self, f, h=1E-5):
        self.f = f
        self.h = float(h)

class Forward1(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (f(x+h) - f(x))/h
!ec

===== This is a 5 heading =====

The template can be any HTML file with header and footer and
three possible slots: *title*, *date* and *main*,
where *main* will become the DocOnce file (the main body of text),
*title* is the first heading in the DocOnce file, and
*date* is extracted from the DocOnce file (if present).



************** File: html_template1.html *****************
<! -- test template -->

<?xml version="1.0" encoding="utf-8" ?>
<html>
<head>

<style type="text/css">
    body {
      margin-top: 1.0em;
      <!-- background-color: #e1c931; -->
      background-color: #000000;
      font-family: Helvetica, Arial, FreeSans, san-serif;
      color: #000000;
    }
    #container {
      margin: 0 auto;
      width: 700px;
    }
    h1 { font-size: 1.8em; color: #1e36ce; margin-bottom: 3px; }
    h1 .small { font-size: 0.4em; }
    h1 a { text-decoration: none }
    h2 { font-size: 1.5em; color: #1e36ce; }
    h3 { text-align: left; color: #1e36ce; }
    h4 { text-align: left; color: #1e36ce; }
    a { color: #1e36ce; }
    .description { font-size: 1.2em; margin-bottom: 30px; margin-top: 30px; font-style: italic;}
    .download { float: right; }
    <!-- white on black: pre { background: #000; color: #fff; padding: 15px;} -->
    <!-- black on white: pre { background: #fff; color: #000; padding: 15px;} -->
    pre { background: #EDEDED; color: #000; padding: 15px;}
    <!-- https://www.december.com/html/spec/color0.html -->
    hr { border: 0; width: 80%; border-bottom: 1px solid #aaa}
    .footer { text-align:center; padding-top:30px; font-style: italic; }
</style>

<!-- Use MathJax to render mathematics -->
<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  TeX: {
     equationNumbers: {  autoNumber: "AMS"  },
     extensions: ["AMSmath.js"]
  }
});
</script>
<script type="text/javascript"
 src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>

</head>

<body bgcolor="white">

<title>This is a test of HTML templates</title>

<h4>Date: Jan 32, 2100</h4>

<!-- main body -->


<!-- tocinfo
{'highest level': 1,
 'sections': [('This is a test of HTML templates',
               2,
               None,
               'this-is-a-test-of-html-templates'),
              ('This is a 7 heading', 1, None, 'this-is-a-7-heading'),
              ('This is a 5 heading', 2, None, 'this-is-a-5-heading')]}
end of tocinfo -->


<!-- ------------------- main content ---------------------- -->

<p>

<br>

<h2 id="this-is-a-test-of-html-templates">This is a test of HTML templates </h2>

<p>
Note: When using HTML templates, the DocOnce file cannot have a title
(to avoid generating a header). It should neither have an author.

<h1 id="this-is-a-7-heading">This is a 7 heading </h1>

<p>
Here is some code:
<!-- begin verbatim block  pycod-->
<pre><code>class Diff:
    def __init__(self, f, h=1E-5):
        self.f = f
        self.h = float(h)

class Forward1(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (f(x+h) - f(x))/h
</code></pre>
<!-- end verbatim block -->

<h2 id="this-is-a-5-heading">This is a 5 heading </h2>

<p>
The template can be any HTML file with header and footer and
three possible slots: <em>title</em>, <em>date</em> and <em>main</em>,
where <em>main</em> will become the DocOnce file (the main body of text),
<em>title</em> is the first heading in the DocOnce file, and
<em>date</em> is extracted from the DocOnce file (if present).

<p>

<!-- ------------------- end of main content --------------- -->



<!-- end of main body -->
</body>
</html>


************** File: html_template.html *****************
<!-- Template for INF1100 web pages with University of Oslo web design -->

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html lang="no" xml:lang="no" xmlns="https://www.w3.org/1999/xhtml">
  <head>
   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   <!-- iPhone viewport -->
   <meta name="viewport" content="width=1020, user-scalable=yes" />


     <title>This is a test of HTML templates</title>

    <link rel="shortcut icon" type="image/vnd.microsoft.icon" href="https://www.uio.no/vrtx/decorating/resources/dist/images/favicon.ico" />
    <link type="text/css" rel="stylesheet" media="all" href="https://www.uio.no/vrtx/decorating/resources/dist/style/style.css" />

    <link type="text/css" rel="stylesheet" media="all" href="https://www.uio.no/vrtx/decorating/resources/dist/www.uio.no/logos/logos.css" />

    <link type="text/css" rel="stylesheet" media="print" href="https://www.uio.no/vrtx/decorating/resources/dist/style/print.css" />
    <link type="text/css" rel="stylesheet" media="handheld" href="https://www.uio.no/vrtx/decorating/resources/dist/style/handheld.css"/>

   <script type="text/javascript" src="https://www.uio.no/vrtx/__vrtx/static-resources/jquery/jquery-1.4.2.min.js"></script>

   <meta name="MSSmartTagsPreventParsing" content="true" />
   <meta http-equiv="imagetoolbar" content="no" />




          <script type="text/javascript" src="https://www.uio.no/vrtx/__vrtx/static-resources/js/share.js"></script>




  </head>


    <body class='faculty'  id="vrtx-structured-article">


    <!--stopindex-->
    <!-- Navigation start -->
    <ul id="hidnav">
      <li><a href="#globalnav">Hopp til global navigasjon</a></li>
      <li><a href="#main">Hopp til hovedinnholdet</a></li>

      <li><a href="#bottomnav">Hopp til bunnavigasjon</a></li>
      <li><a href="#footer">Hopp til kontaktinformasjon</a></li>
    </ul>
    <!-- Navigation end -->

    <!-- Page header starts -->
    <div id="head-globalnav">


     <!-- normal head -->


       <div id="head">

 	  <div id="logos">
	      <div id="uiologo" title="G&#229; til Universitetet i Oslo"><a href="https://www.uio.no"><span></span>Universitetet i Oslo</a></div>

              <!-- toppniv&#229; -->

	      <div id="facultylogo" title='G&#229; til Universitetet i Oslo'>
                <a href="/"><span></span>Universitetet i Oslo</a>
              </div>


	  </div>

	  <form class="searchform" method="get" action='/'>

	    <fieldset>
	      <label for="searchstring" class="searchstringlabel">S&#248;k i Universitetet i Oslo</label>
              <input type="hidden" name="vrtx" value="searchuio"/>
	      <input type="text" id="searchstring" name="query" value="" />
	      <button type="submit" class="searchsubmit"><span>S&oslash;k</span></button>
	    </fieldset>
	  </form>

	  <!-- head-menu -->
          <div id="head-menu">

              <ul class="ref-menu">

                 <!-- toppniv&#229; -->
                  <li><a href='/english'>English</a></li>


             </ul>

               <ul class="vrtx-uri-menu">

    <li class="for-ansatte">
  <a href="https://www.uio.no/for-ansatte/">For ansatte</a>
    </li>
  </ul>


          </div>
          <!-- head-menu -->
	</div>

        <!-- Global navigation start -->
	<div id="globalnav">

                <ul class="vrtx-tab-menu">

    <li class="root-folder parent-folder">
  <a href="https://www.uio.no/">Forsiden</a>
    </li>

    <li class="forskning">

  <a href="https://www.uio.no/forskning/">Forskning</a>
    </li>

    <li class="vrtx-active-item studier vrtx-current-item">
  <a href="https://www.uio.no/studier/">Studier</a>
    </li>

    <li class="livet-rundt-studiene">
  <a href="https://www.uio.no/livet-rundt-studiene/">Livet rundt studiene</a>

    </li>

    <li class="tjenester">
  <a href="https://www.uio.no/tjenester/">Tjenester og verkt&#248;y</a>
    </li>

    <li class="om">
  <a href="https://www.uio.no/om/">Om UiO</a>
    </li>

    <li class="personer">
  <a href="https://www.uio.no/personer/">Personer</a>
    </li>
  </ul>




        </div>
	<!-- Global navigation end -->

    </div>

    <!-- Page header end -->


    <div id="uiodoc">
        <!-- img-tag for print -->

           <!-- topp-/fakniv&#229; -->
            <img id="head-print" alt="print logo" src="https://www.uio.no/vrtx/decorating/resources/dist/www.uio.no/logos/faculty-small.png"/>



	<!-- Page content start -->
	<div id="main">
          <!--startindex-->

                     <!-- leftmenu (default) -->
            <!--stopindex-->
            <div id="left-main">
              <ul class="vrtx-breadcrumb-menu">
				<li class="vrtx-ancestor"> <a href="https://www.uio.no/studier/"><span>Studier</span></a> </li>
				<li class="vrtx-ancestor"> <a href="https://www.uio.no/studier/emner/"><span>Emner</span></a> </li>

				<li class="vrtx-ancestor"> <a href="https://www.uio.no/studier/emner/matnat/"><span>Matematikk og naturvitenskap</span></a> </li>
				<li class="vrtx-ancestor"> <a href="https://www.uio.no/studier/emner/matnat/ifi/"><span>Informatikk</span></a> </li>
				<li class="vrtx-parent" ><a href="https://www.uio.no/studier/emner/matnat/ifi/INF1100/"><span>INF1100</span></a>
    	<ul>
			<li class="vrtx-child"><a class="vrtx-marked" href="https://www.uio.no/studier/emner/matnat/ifi/INF1100/h12/"><span>H&#248;st 2012</span></a></li>

     	</ul>
   	 </li>
</ul>

            </div>
            <div id="right-main">
              <!--startindex-->


        <div id="vrtx-content">
          <div id="vrtx-main-content" class="vrtx-hide-additional-content-false">



<!-- tocinfo
{'highest level': 1,
 'sections': [('This is a test of HTML templates',
               2,
               None,
               'this-is-a-test-of-html-templates'),
              ('This is a 7 heading', 1, None, 'this-is-a-7-heading'),
              ('This is a 5 heading', 2, None, 'this-is-a-5-heading')]}
end of tocinfo -->


<!-- ------------------- main content ---------------------- -->

<p>

<br>

<h2 id="this-is-a-test-of-html-templates">This is a test of HTML templates </h2>

<p>
Note: When using HTML templates, the DocOnce file cannot have a title
(to avoid generating a header). It should neither have an author.

<h1 id="this-is-a-7-heading">This is a 7 heading </h1>

<p>
Here is some code:
<p>

<!-- code=python (!bc pycod) typeset with pygments style "emacs" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #AA22FF; font-weight: bold">class</span> <span style="color: #0000FF">Diff</span>:
    <span style="color: #AA22FF; font-weight: bold">def</span> <span style="color: #00A000">__init__</span>(<span style="color: #AA22FF">self</span>, f, h<span style="color: #666666">=1E-5</span>):
        <span style="color: #AA22FF">self</span><span style="color: #666666">.</span>f <span style="color: #666666">=</span> f
        <span style="color: #AA22FF">self</span><span style="color: #666666">.</span>h <span style="color: #666666">=</span> <span style="color: #AA22FF">float</span>(h)

<span style="color: #AA22FF; font-weight: bold">class</span> <span style="color: #0000FF">Forward1</span>(Diff):
    <span style="color: #AA22FF; font-weight: bold">def</span> <span style="color: #00A000">__call__</span>(<span style="color: #AA22FF">self</span>, x):
        f, h <span style="color: #666666">=</span> <span style="color: #AA22FF">self</span><span style="color: #666666">.</span>f, <span style="color: #AA22FF">self</span><span style="color: #666666">.</span>h
        <span style="color: #AA22FF; font-weight: bold">return</span> (f(x<span style="color: #666666">+</span>h) <span style="color: #666666">-</span> f(x))<span style="color: #666666">/</span>h
</pre></div>

<h2 id="this-is-a-5-heading">This is a 5 heading </h2>

<p>
The template can be any HTML file with header and footer and
three possible slots: <em>title</em>, <em>date</em> and <em>main</em>,
where <em>main</em> will become the DocOnce file (the main body of text),
<em>title</em> is the first heading in the DocOnce file, and
<em>date</em> is extracted from the DocOnce file (if present).

<p>

<!-- ------------------- end of main content --------------- -->


	    	<div class="vrtx-date-info">
	    	<span class="published-date-label">Publisert</span> <span class="published-date">Jan 32, 2100</span>

	    	</div>

            <div class="vrtx-social-components">

<!-- begin email a friend js -->
<script type="text/javascript" src="https://www.uio.no/vrtx/__vrtx/static-resources/js/email-a-friend.js"></script>
<!-- end email a friend js -->

<a class="vrtx-email-friend" href="https://www.uio.no/studier/emner/matnat/ifi/INF1100/h10/template.html?vrtx=email-a-friend" onclick="javascript:popup('https://www.uio.no/studier/emner/matnat/ifi/INF1100/h10/template.html?vrtx=email-a-friend'); return false">Tips en venn</a>

<div id="vrtx-share-component">
  <a href="#vrtx-share-link" id="vrtx-share-link" class="vrtx-share-link" name="vrtx-share-link">
  Del p&#229;...</a>
    <div id="vrtx-send-share">

      <div class="vrtx-send-inner">
        <div class="vrtx-share-top">
          <div class="vrtx-share-title">Del p&#229;...</div>
          <span><a href="#vrtx-share-link" class="vrtx-close-toolbox-send-share">
          Lukk</a></span>
        </div>
        <ul>
          <li><a href="https://www.facebook.com/share.php?u=http%3A%2F%2Fwww.uio.no%2Fstudier%2Femner%2Fmatnat%2Fifi%2FINF1100%2Fh10%2Ftemplate.html&amp;t=Template" target="_blank" class="facebook">

          Facebook</a></li>
          <li><a href="http://twitter.com/home?status=http%3A%2F%2Fwww.uio.no%2Fstudier%2Femner%2Fmatnat%2Fifi%2FINF1100%2Fh10%2Ftemplate.html" target="_blank" class="twitter">
          Twitter</a></li>
          <li><a href="http://del.icio.us/post?url=http%3A%2F%2Fwww.uio.no%2Fstudier%2Femner%2Fmatnat%2Fifi%2FINF1100%2Fh10%2Ftemplate.html&amp;title=Template" target="_blank" class="delicious">
          del.icio.us</a></li>
        </ul>
     </div>

    </div>
</div>
          	</div>
          </div>
        </div>

              <!--stopindex-->
            </div>

          <!--stopindex-->
         </div>
	<!-- Page content end -->

      <!-- Bottom navigation start -->
	<div id="bottomnav">
           <div id="breadcrumb-container">
	     <div id="vrtx-breadcrumb-start" class="breadcrumb">
	       <span class="vrtx-uio"><a href="https://www.uio.no">UiO</a> <span class="vrtx-breadcrumb-delimiter">&gt;</span></span>

                 <span class="vrtx-faculty"><a href="/">Universitetet i Oslo</a> <span class="vrtx-breadcrumb-delimiter">&gt;</span></span>


             </div>

<div id="vrtx-breadcrumb" class="breadcrumb">
      <span class="vrtx-breadcrumb-level-2"><a href="https://www.uio.no/studier/">Studier</a>
      	<span class="vrtx-breadcrumb-delimiter">&gt;</span>
      </span>
</div>



           </div>
           <div id="bottom-menu">



        <div class="vrtx-subfolder-menu">

          <div class="vrtx-group-1">
    <ul class="resultset-1">
      <li>
    <a href="https://www.uio.no/studier/program/">Studieprogrammer</a>
  <ul>
	          <li>
    <a href="https://www.uio.no/studier/program/litteratur-aarsenhet/">Allmenn litteraturvitenskap (&#229;rsenhet)</a>
          	</li>

	          <li>
    <a href="https://www.uio.no/studier/program/akks/">Antikk kultur og klassiske spr&#229;k (bachelor)</a>
          	</li>
	          <li>
    <a href="https://www.uio.no/studier/program/antikk/">Antikk kultur og klassisk tradisjon (bachelor)</a>
          	</li>
	          <li>
    <a href="https://www.uio.no/studier/program/antikk-master/">Antikk kultur og klassisk tradisjon (master - to &#229;r)</a>

          	</li>
	          <li>
    <a href="https://www.uio.no/studier/program/anvma-master/">Anvendt matematikk og mekanikk</a>
          	</li>
	    <li class="vrtx-more">
			<a href="https://www.uio.no/studier/program">Mer...</a>
		</li>
  </ul>

      </li>
  </ul>

    <ul class="resultset-2">
      <li>
    <a href="https://www.uio.no/studier/opptak/">Opptak</a>
  <ul>
	          <li>
    <a href="https://www.uio.no/studier/opptak/so/">S&#248;ke opptak</a>

          	</li>
	          <li>
    <a href="https://www.uio.no/studier/opptak/gsk/">Generell studiekompetanse (GSK)</a>
          	</li>
	          <li>
    <a href="https://www.uio.no/studier/opptak/realkompetanse/">Realkompetanse</a>
          	</li>
	          <li>

    <a href="https://www.uio.no/studier/opptak/spesielle-krav/">Spesielle opptakskrav</a>
          	</li>
	          <li>
    <a href="https://www.uio.no/studier/opptak/enkeltemner/">Enkeltemner</a>
          	</li>
  </ul>
      </li>
  </ul>


    <ul class="resultset-3">
      <li>
    <a href="https://www.uio.no/studier/admin/">Administrer dine studier</a>
  <ul>
	          <li>
    <a href="https://www.uio.no/studier/admin/semesterregistrering/">Registreringer hvert semester</a>
          	</li>
	          <li>

    <a href="https://www.uio.no/studier/admin/melding/">Frister for meldinger til undervisning og eksamen</a>
          	</li>
	          <li>
    <a href="https://www.uio.no/studier/admin/semesteravgift/">Betale semesteravgift</a>
          	</li>
	          <li>
    <a href="https://www.uio.no/studier/admin/kort/">Semesterkort og studiekort</a>

          	</li>
	          <li>
    <a href="https://www.uio.no/studier/admin/karakterutskrift/">Bestille karakterutskrift</a>
          	</li>
	    <li class="vrtx-more">
			<a href="https://www.uio.no/studier/admin">Mer...</a>
		</li>
  </ul>

      </li>
  </ul>

    <ul class="resultset-4">
      <li>
    <a href="https://www.uio.no/studier/emner/">Emner</a>
  <ul>
	          <li>
    <a href="https://www.uio.no/studier/emner/hf/">Humanistiske fag</a>

          	</li>
	          <li>
    <a href="https://www.uio.no/studier/emner/jus/">Jus</a>
          	</li>
	          <li>
    <a href="https://www.uio.no/studier/emner/matnat/">Matematikk og naturvitenskap</a>
          	</li>
	          <li>

    <a href="https://www.uio.no/studier/emner/medisin/">Medisin</a>
          	</li>
	          <li>
    <a href="https://www.uio.no/studier/emner/odont/">Odontologi</a>
          	</li>
	    <li class="vrtx-more">
			<a href="https://www.uio.no/studier/emner">Mer...</a>
		</li>

  </ul>
      </li>
  </ul>

    <ul class="resultset-5">
      <li>
    <a href="https://www.uio.no/studier/evu/">Etter- og videreutdanning</a>
  <ul>
	          <li>

    <a href="https://www.uio.no/studier/evu/kurs/">Studietilbud</a>
          	</li>
	          <li>
    <a href="https://www.uio.no/studier/evu/oppdrag/">Oppdragsundervisning</a>
          	</li>
	          <li>
    <a href="https://www.uio.no/studier/evu/erfaringsbasert-master/">Erfaringsbasert master</a>

          	</li>
  </ul>
      </li>
  </ul>

    <ul class="resultset-6">
      <li>
    <a href="https://www.uio.no/studier/studiestart/">Studiestart for nye studenter</a>
  <ul>

	          <li>
    <a href="https://www.uio.no/studier/studiestart/arrangementer/">Arrangementer</a>
          	</li>
	          <li>
    <a href="https://www.uio.no/studier/studiestart/fadderordning-for-nye-studenter/">Fadderordning for nye studenter</a>
          	</li>
	          <li>
    <a href="https://www.uio.no/studier/studiestart/fadderordningen/">Informasjon til fadderne</a>

          	</li>
  </ul>
      </li>
  </ul>

          </div>
          <div class="vrtx-group-2">
    <ul class="resultset-7">
      <li>
    <a href="https://www.uio.no/studier/tilrettelegging/">Har du spesielle behov?</a>

  <ul>
	          <li>
    <a href="https://www.uio.no/studier/tilrettelegging/adhd/">ADHD</a>
          	</li>
	          <li>
    <a href="https://www.uio.no/studier/tilrettelegging/asperger/">Asperger</a>
          	</li>
	          <li>

    <a href="https://www.uio.no/studier/tilrettelegging/bevegelseshemming/">Bevegelseshemming</a>
          	</li>
	          <li>
    <a href="https://www.uio.no/studier/tilrettelegging/dysleksi/">Dysleksi</a>
          	</li>
	          <li>
    <a href="https://www.uio.no/studier/tilrettelegging/kronisk-sydom/">Kronisk sykdom</a>

          	</li>
	    <li class="vrtx-more">
			<a href="https://www.uio.no/studier/tilrettelegging">Mer...</a>
		</li>
  </ul>
      </li>
  </ul>

    <ul class="resultset-8">
      <li>

    <a href="https://www.uio.no/studier/om/">Om studier</a>
  <ul>
	          <li>
    <a href="https://www.uio.no/studier/om/studier-og-grader/">Studiestruktur og grader</a>
          	</li>
	          <li>
    <a href="https://www.uio.no/studier/om/kvalitet/">Studiekvalitet</a>

          	</li>
	          <li>
    <a href="https://www.uio.no/studier/om/regelverk/">Lover og regler</a>
          	</li>
	          <li>
    <a href="https://www.uio.no/studier/om/godkjenning/">Godkjenning av utenlandsk utdanning</a>
          	</li>
	          <li>

    <a href="https://www.uio.no/studier/om/utvalg/">Komiteer og utvalg</a>
          	</li>
  </ul>
      </li>
  </ul>

    <ul class="resultset-9">
      <li>
    <a href="https://www.uio.no/studier/emnegrupper/">Emnegrupper</a>

  <ul>
	          <li>
    <a href="https://www.uio.no/studier/emnegrupper/hf/">Humanistiske fag</a>
          	</li>
	          <li>
    <a href="https://www.uio.no/studier/emnegrupper/jus/">Jus</a>
          	</li>
	          <li>

    <a href="https://www.uio.no/studier/emnegrupper/matnat/">Matematikk og naturvitenskap</a>
          	</li>
	          <li>
    <a href="https://www.uio.no/studier/emnegrupper/sv/">Samfunnsvitenskap</a>
          	</li>
	          <li>
    <a href="https://www.uio.no/studier/emnegrupper/teologi/">Teologi</a>

          	</li>
	    <li class="vrtx-more">
			<a href="https://www.uio.no/studier/emnegrupper">Mer...</a>
		</li>
  </ul>
      </li>
  </ul>

    <ul class="resultset-10">
      <li>

    <a href="https://www.uio.no/studier/ressurser/">L&#230;ringsressurser</a>
  <ul>
	          <li>
    <a href="https://www.uio.no/studier/ressurser/bibliotek-lesesaler/">Bibliotek, lesesaler og PC-stuer</a>
          	</li>
	          <li>
    <a href="https://www.uio.no/studier/ressurser/mifa/">Mangfold i fokus i akademia</a>

          	</li>
	          <li>
    <a href="https://www.uio.no/studier/ressurser/skrivehjelp/">Skrivehjelp</a>
          	</li>
	          <li>
    <a href="https://www.uio.no/studier/ressurser/spraak-tandem/">Spr&#229;k-tandem</a>
          	</li>
  </ul>

      </li>
  </ul>

    <ul class="resultset-11">
      <li>
    <a href="https://www.uio.no/studier/kontakt/">Kontakt oss</a>
      </li>
  </ul>

     </div>

        </div>



           </div>
        </div>
      <!-- Bottom navigation end -->
    </div>
    <!-- Page wrapper end -->
    <div id="footer-wrapper">

    <!-- Page footer start -->
      <div id="footer">
        <div id="footer-main" class="vcard">
	  <div class="institutelogo fn org"><span></span>Universitetet i Oslo : Universitetet i Oslo</div>


             <div class="adr visitor-adress">
  <span class="vrtx-label">N&#248;dnummer</span>
  <span>Ved brann, ulykker og alvorlige hendelser ring <br/>22 85 66 66</span>

</div>
<div class="adr mail-adress">
  <span class="vrtx-label">Adresse</span>
  <span class="post-office-box">Universitetet i Oslo</span>
  <span class="post-office-box">Boks 1072 Blindern</span>
  <span class="postal-code">0316</span>
  <span class="locality"> Oslo</span>

</div>
<div class="phone-fax-email">
  <span class="vrtx-label">Telefon og kontaktpunkter</span>
  <span class="tel">Sentralbord: 22 85 50 50</span>
  <a href="/om/kontaktinformasjon/">Kontaktpunkter UiO</a>
</div>




        </div>

        <div id="footer-admin">

          <ul class="unit-admin-links">
              <li>Ansvarlig for denne siden:</li>
              <li><a href="mailto:studieredaktor@admin.uio.no">Studieredakt&#248;r UiO</a></li>
          </ul>
          <ul class="vrtx-admin-links">
            <li><div class="vrtx-logout" id="vrtx-logout">
  <span class="vrtx-user">Lars Jahr R&#248;ine</span>
  <form id="logoutForm" action="https://www.uio.no/studier/emner/matnat/ifi/INF1100/h10/template.html?action=logout" method="post" style="display:inline;">

  <input type="hidden"
         name="csrf-prevention-token"
         value="c3ed5c2f65171c0952ab9b76819ef85843a0e40f" />
    <button type="submit" id="logoutAction" name="logoutAction">Logg ut</button>
  </form>
  <!-- Hide submit button, display a link instead: -->
  <script type="text/javascript" language="Javascript"><!--
	   	document.getElementById("logoutAction").style.display = "none";
		var logoutLink = document.createElement("a");
		logoutLink.setAttribute("href","javascript:document.getElementById('logoutForm').submit();");
		logoutLink.innerHTML = "Logg ut"

		var lp = document.createElement("span");
		lp.innerHTML = "( ";
		var rp = document.createElement("span");
		rp.innerHTML = " )";
		document.getElementById("vrtx-logout").appendChild(lp);
		document.getElementById("vrtx-logout").appendChild(logoutLink);
		document.getElementById("vrtx-logout").appendChild(rp);
		// -->
  </script>
</div>
</li>
            <li>

  <a id="vrtx-manage-url" class="vrtx-manage-url" href="https://www-adm.uio.no/studier/emner/matnat/ifi/INF1100/h10/template.html?vrtx=admin">Administrer dette dokumentet</a>
</li>
          </ul>
          <div id="cms">Drevet av <a href="https://www.uio.no/tjenester/it/web/vortex/">Vortex</a></div>
        </div>
      </div>
    <!-- Page footer end -->
   </div>

   <script type="text/javascript" src="https://www.uio.no/vrtx/__vrtx/static-resources/jquery/autocomplete/jquery.autocomplete.js"></script>
   <script type="text/javascript" src="https://www.uio.no/vrtx/decorating/resources/dist/script/jquery-syntax/jquery.syntax.min.js"></script>
   <script type="text/javascript" src="https://www.uio.no/vrtx/decorating/resources/dist/script/uio.js"></script>
   <script type="text/javascript">
      $(document).ready(function() {
        var emnerParams = {selectFirst:false, width:226, max:50, delay:75};
        emnerAutocomplete('course-search', 'emner', emnerParams);
        gotoEmnerAutocompleteSuggestion('course-search');

        var personerParams = {minChars:3, selectFirst:false, width:233, max:50, delay:200, cacheLength:0};
        personerAutocomplete('person-search', 'person', personerParams, '/');
        gotoPersonerAutocompleteSuggestion('person-search');

      });
   </script>

   <!-- Greybox for Email a friend / Tips en venn -->
   <script type="text/javascript">
     var GB_ROOT_DIR = "https://www.uio.no/vrtx/decorating/resources/dist/script/greybox/";
   </script>

   <script type="text/javascript" src="https://www.uio.no/vrtx/decorating/resources/dist/script/greybox/AJS-combined-min.js"></script>

   </body>
</html>



************** File: template1.html *****************
<! -- test template -->

<?xml version="1.0" encoding="utf-8" ?>
<html>
<head>

<style type="text/css">
    body {
      margin-top: 1.0em;
      <!-- background-color: #e1c931; -->
      background-color: #000000;
      font-family: Helvetica, Arial, FreeSans, san-serif;
      color: #000000;
    }
    #container {
      margin: 0 auto;
      width: 700px;
    }
    h1 { font-size: 1.8em; color: #1e36ce; margin-bottom: 3px; }
    h1 .small { font-size: 0.4em; }
    h1 a { text-decoration: none }
    h2 { font-size: 1.5em; color: #1e36ce; }
    h3 { text-align: left; color: #1e36ce; }
    h4 { text-align: left; color: #1e36ce; }
    a { color: #1e36ce; }
    .description { font-size: 1.2em; margin-bottom: 30px; margin-top: 30px; font-style: italic;}
    .download { float: right; }
    <!-- white on black: pre { background: #000; color: #fff; padding: 15px;} -->
    <!-- black on white: pre { background: #fff; color: #000; padding: 15px;} -->
    pre { background: #EDEDED; color: #000; padding: 15px;}
    <!-- https://www.december.com/html/spec/color0.html -->
    hr { border: 0; width: 80%; border-bottom: 1px solid #aaa}
    .footer { text-align:center; padding-top:30px; font-style: italic; }
</style>

<!-- Use MathJax to render mathematics -->
<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  TeX: {
     equationNumbers: {  autoNumber: "AMS"  },
     extensions: ["AMSmath.js"]
  }
});
</script>
<script type="text/javascript"
 src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>

</head>

<body bgcolor="white">

<title>%(title)s</title>


<h4>Date: %(date)s</h4>

<!-- main body -->

%(main)s


<!-- end of main body -->
</body>
</html>

************** File: author1.html *****************
<!--
Automatically generated HTML file from DocOnce source
(https://github.com/doconce/doconce/)
-->
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="DocOnce: https://github.com/doconce/doconce/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="description" content="Test of one author at one institution">

<title>Test of one author at one institution</title>


<style type="text/css">
/* blueish style */

/* Color definitions:  https://www.december.com/html/spec/color0.html
   CSS examples:       https://www.w3schools.com/css/css_examples.asp */

body {
  margin-top: 1.0em;
  background-color: #ffffff;
  font-family: Helvetica, Arial, FreeSans, san-serif;
  color: #000000;
}
h1 { font-size: 1.8em; color: #1e36ce; }
h2 { font-size: 1.6em; color: #1e36ce; }
h3 { font-size: 1.4em; color: #1e36ce; }
a { color: #1e36ce; text-decoration:none; }
tt { font-family: "Courier New", Courier; }
/* pre style removed because it will interfer with pygments */
p { text-indent: 0px; }
hr { border: 0; width: 80%; border-bottom: 1px solid #aaa}
p.caption { width: 80%; font-style: normal; text-align: left; }
hr.figure { border: 0; width: 80%; border-bottom: 1px solid #aaa}

div { text-align: justify; text-justify: inter-word; }
</style>


</head>

<!-- tocinfo
{'highest level': 0,
 'sections': [('Generalized References', 0, 'genrefs', 'genrefs'),
              ('Test of math', 0, None, 'test-of-math')]}
end of tocinfo -->

<body>



<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  TeX: {
     equationNumbers: {  autoNumber: "AMS"  },
     extensions: ["AMSmath.js", "AMSsymbols.js", "autobold.js", "color.js"]
  }
});
</script>
<script type="text/javascript" async
 src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>



    
<!-- ------------------- main content ---------------------- -->



<center><h1>Test of one author at one institution</h1></center>  <!-- document title -->

<p>
<!-- author(s): John Doe -->

<center>
<b>John Doe</b>  (<tt>doe at cyberspace.net</tt>)
</center>

<p>
<!-- institution -->

<center><b>Cyberspace Inc.</b></center>
<br>
<p>
<center><h4>Jan 32, 2100</h4></center> <!-- date -->
<br>
<p>
<!-- Externaldocument: testdoc -->

<p>

<center><h1 id="genrefs">Generalized References</h1></center> <hr>

<p>
Sometimes a series of individual documents may be assembled to one
large document. The assembly impacts how references to sections
are written: when referring to a section in the same document, a label
can be used, while references to sections in other documents are
written differently, sometimes involving a link (URL) and a citation.
Especially if both the individual documents and the large assembly document
are to exist side by side, a flexible way of referencing is needed.
For this purpose, DocOnce offers <em>generalized references</em> which allows
a reference to have two different formulations, one for internal
references and one for external references. Since LaTeX supports
references to labels in external documents via the <code>xr</code> package,
the generalized references in DocOnce has a syntax that may utilize
the <code>xr</code> feature in LaTeX.

<p>
The syntax of generalized references reads
<p>

<!-- code=text typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>ref[internal][cite][external]
</pre></div>
<p>
If all standard <code>ref</code> references (with curly braces)
in the text <code>internal</code> are references
to labels in the present document, the above <code>ref</code> command is replaced
by the text <code>internal</code>. Otherwise, if cite is non-empty and the format
is <code>latex</code> or <code>pdflatex</code> one assumes that the references in <code>internal</code>
are to external documents declared by a comment line <code>#
Externaldocuments: testdoc, mydoc</code> (usually after the title, authors,
and date). In this case the output text is <code>internal cite</code> and the
LaTeX package <code>xr</code> is used to handle the labels in the external documents.
When referring to a complete chapter (not a section in it), which
corresponds to a complete external document, it does not make sense
to write out <code>internal cite</code> since the <code>internal</code> reference is a
chapter number. In such cases, the <code>internal</code> syntax can be used,
and if the label is in another LaTeX document, the output is just <code>cite</code>.
For all
output formats other than <code>latex</code> and <code>pdflatex</code>, the <code>external</code>
text will be the output.

<p>
Here is an example on a specific generalized reference to a section
in a document:
<p>

<!-- code=text typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>As explained in
ref[Section ref{subsec:ex}][in &quot;Langtangen, 2012&quot;:
&quot;https://hplgit.github.io/doconce/test/demo_testdoc.html#subsec:ex&quot;
cite{testdoc:12}][a &quot;section&quot;:
&quot;https://hplgit.github.io/doconce/test/demo_testdoc.html#subsec:ex&quot; in
the document &quot;A Document for Testing DocOnce&quot;:
&quot;https://hplgit.github.io/doconce/test/demo_testdoc.html&quot;
cite{testdoc:12}], DocOnce documents may include tables.
</pre></div>
<p>
With <code>latex</code> or <code>pdflatex</code> as output, this translates to
<p>

<!-- code=text typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>As explained in
Section ref{subsec:ex}, DocOnce documents may include tables.
</pre></div>
<p>
if the label <code>{subsec:ex}</code> appears in the present DocOnce source, and
otherwise
<p>

<!-- code=text typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>As explained in
Section ref{subsec:ex} in &quot;Langtangen, 2012&quot;:
&quot;https://hplgit.github.io/doconce/test/demo_testdoc.html#subsec:ex&quot;
cite{testdoc:12}, DocOnce documents may include tables.
</pre></div>
<p>
In a format different from <code>latex</code> and <code>pdflatex</code>, the effective DocOnce
text becomes
<p>

<!-- code=text typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>As explained in
a &quot;section&quot;:
&quot;https://hplgit.github.io/doconce/test/demo_testdoc.html#subsec:ex&quot; in
the document &quot;A Document for Testing DocOnce&quot;:
&quot;https://hplgit.github.io/doconce/test/demo_testdoc.html&quot;
cite{testdoc:12}, DocOnce documents may include tables.
</pre></div>
<p>
The rendered text in the current format <code>html</code> becomes

<p>
<blockquote>
    As explained in
    a <a href="https://hplgit.github.io/doconce/test/demo_testdoc.html#subsec:ex" target="_self">section</a> in
    the document <a href="https://hplgit.github.io/doconce/test/demo_testdoc.html" target="_self">A Document for Testing DocOnce</a>
    <a href="#testdoc:12">[1]</a>, DocOnce documents may include tables.
</blockquote>


<p>
A reference to an entire external document, which is usually a chapter
if the reference is internal in the DocOnce source, applies the
<code>refch</code> syntax:

<p>

<!-- code=text typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>As explained in
refch[Chapter ref{ch:testdoc}][&quot;Langtangen, 2012&quot;:
&quot;https://hplgit.github.io/doconce/test/demo_testdoc.html&quot;
cite{testdoc:12}][the document
&quot;A Document for Testing DocOnce&quot;:
&quot;https://hplgit.github.io/doconce/test/demo_testdoc.html&quot;
cite{testdoc:12}], DocOnce documents may include tables.
</pre></div>
<p>
The output now if <code>ch:testdoc</code> is not a label in the document,
becomes in the <code>latex</code> and <code>pdflatex</code> case

<p>

<!-- code=text typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>As explained in
&quot;Langtangen, 2012&quot;:
&quot;https://hplgit.github.io/doconce/test/demo_testdoc.html&quot;
cite{testdoc:12}, DocOnce documents may include tables.
</pre></div>
<p>
That is, the internal reference <code>Chapter ...</code> is omitted since
it is not meaningful to refer to an external document as "Chapter".
The resulting rendered text in the current format <code>html</code> becomes

<p>
<blockquote>
    As explained in
    the document
    <a href="https://hplgit.github.io/doconce/test/demo_testdoc.html" target="_self">A Document for Testing DocOnce</a>
    <a href="#testdoc:12">[1]</a>, DocOnce documents may include tables.
</blockquote>


<p>
Note that LaTeX cannot
have links to local files, so a complete URL on the form
<code>https://...</code> must be used.

<p>
And here is another example with internal references only:

<p>

<!-- code=text typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>Generalized references are described in ref[Section ref{genrefs}][dummy1][
dummy2].
</pre></div>
<p>
The text is rendered to

<p>
<blockquote>
    Generalized references are described in
    the section <a href="#genrefs">Generalized References</a>.
</blockquote>


<p>

<center><h1 id="test-of-math">Test of math </h1></center> <hr>

<p>
<!-- Here we test the chapter heading to see if latex output then has -->
<!-- book style rather than article style. -->

<p>
Inline math, \( a=b \), is the only math in this document.

<p>
<!-- Need BIBFILE because of cite{} examples -->

<p>
<!-- begin bibliography -->

<ol>
 <li> <div id="testdoc:12"></div> <b>H. P. Langtangen</b>. 
    A Document for Testing Doconce,
    <em>Simula Research Laboratory</em>,
    2015,
    <a href="http://hplgit.github.io/doconce/test/demo_testdoc.html" target="_self"><tt>http://hplgit.github.io/doconce/test/demo_testdoc.html</tt></a>.</li>
</ol>

<!-- end bibliography -->

<!-- ------------------- end of main content --------------- -->


</body>
</html>
    


************** File: author1.p.tex *****************
%%
%% Automatically generated file from DocOnce source
%% (https://github.com/hplgit/doconce/)
%%
%%
% #ifdef PTEX2TEX_EXPLANATION
%%
%% The file follows the ptex2tex extended LaTeX format, see
%% ptex2tex: https://code.google.com/p/ptex2tex/
%%
%% Run
%%      ptex2tex myfile
%% or
%%      doconce ptex2tex myfile
%%
%% to turn myfile.p.tex into an ordinary LaTeX file myfile.tex.
%% (The ptex2tex program: https://code.google.com/p/ptex2tex)
%% Many preprocess options can be added to ptex2tex or doconce ptex2tex
%%
%%      ptex2tex -DMINTED myfile
%%      doconce ptex2tex myfile envir=minted
%%
%% ptex2tex will typeset code environments according to a global or local
%% .ptex2tex.cfg configure file. doconce ptex2tex will typeset code
%% according to options on the command line (just type doconce ptex2tex to
%% see examples). If doconce ptex2tex has envir=minted, it enables the
%% minted style without needing -DMINTED.
% #endif

% #define PREAMBLE

% #ifdef PREAMBLE
%-------------------- begin preamble ----------------------

\documentclass[%
oneside,                 % oneside: electronic viewing, twoside: printing
final,                   % draft: marks overfull hboxes, figures with paths
chapterprefix=true,      % "Chapter" word at beginning of each chapter
open=right,              % start new chapters on odd-numbered pages
10pt]{book}

\listfiles               %  print all files needed to compile this document

\usepackage{relsize,epsfig,makeidx,color,setspace,amsmath,amsfonts,amssymb}
\usepackage[table]{xcolor}
\usepackage{bm,ltablex,microtype}

\usepackage{graphicx}

\usepackage{ptex2tex}
% #ifdef MINTED
\usepackage{minted}
\usemintedstyle{default}
% #endif
\usepackage{fancyvrb}

\usepackage[T1]{fontenc}
%\usepackage[latin1]{inputenc}
\usepackage{ucs}
\usepackage[utf8x]{inputenc}

\usepackage{lmodern}         % Latin Modern fonts derived from Computer Modern

% Hyperlinks in PDF:
\definecolor{linkcolor}{rgb}{0,0,0.4}
\usepackage{hyperref}
\hypersetup{
    breaklinks=true,
    colorlinks=true,
    linkcolor=linkcolor,
    urlcolor=linkcolor,
    citecolor=black,
    filecolor=black,
    %filecolor=blue,
    pdfmenubar=true,
    pdftoolbar=true,
    bookmarksdepth=3   % Uncomment (and tweak) for PDF bookmarks with more levels than the TOC
    }
%\hyperbaseurl{}   % hyperlinks are relative to this root

\setcounter{tocdepth}{3}  % levels in table of contents

% prevent orhpans and widows
\clubpenalty = 10000
\widowpenalty = 10000

% Redefine double page clear to make it a blank page without headers
% (from BYUTextbook)
\makeatletter
\def\cleardoublepage{\clearpage\if@twoside \ifodd\c@page\else
\hbox{}
\thispagestyle{empty}
\newpage
\if@twocolumn\hbox{}\newpage\fi\fi\fi}
\makeatother
% These commands fiddle with the space left for page numbers in the TOC
% (from BYUTextbook)
\makeatletter
%\renewcommand{\@pnumwidth}{2em}
%\renewcommand{\@tocrmarg}{2.85em}
\makeatother

% Make sure blank even-numbered pages before new chapters are
% totally blank with no header
\newcommand{\clearemptydoublepage}{\clearpage{\pagestyle{empty}\cleardoublepage}}
%\let\cleardoublepage\clearemptydoublepage % caused error in the toc

% --- end of standard preamble for documents ---




% References to labels in external documents:
\usepackage{xr}

\externaldocument{testdoc}

% Add external .aux files to \listfiles list:
\makeatletter
\@addtofilelist{testdoc.aux}
\makeatother


% insert custom LaTeX commands...


\raggedbottom
\makeindex
\usepackage[totoc]{idxlayout}   % for index in the toc
\usepackage[nottoc]{tocbibind}  % for references/bibliography in the toc

%-------------------- end preamble ----------------------

\begin{document}

% matching end for #ifdef PREAMBLE
% #endif

\newcommand{\exercisesection}[1]{\subsection*{#1}}

\input{newcommands_bfmath}
\input{newcommands_replace}

% ------------------- main content ----------------------



% ----------------- title -------------------------

\thispagestyle{empty}

\begin{center}
{\LARGE\bf
\begin{spacing}{1.25}
Test of one author at one institution
\end{spacing}
}
\end{center}

% ----------------- author(s) -------------------------

\begin{center}
{\bf John Doe (\texttt{doe@cyberspace.net})}
\end{center}

    \begin{center}
% List of all institutions:
\centerline{{\small Cyberspace Inc.}}
\end{center}
    
% ----------------- end author(s) -------------------------

% --- begin date ---
\begin{center}
Jan 32, 2100
\end{center}
% --- end date ---

\vspace{1cm}


% Externaldocument: testdoc

\chapter{Generalized References}
\label{genrefs}

Sometimes a series of individual documents may be assembled to one
large document. The assembly impacts how references to sections
are written: when referring to a section in the same document, a label
can be used, while references to sections in other documents are
written differently, sometimes involving a link (URL) and a citation.
Especially if both the individual documents and the large assembly document
are to exist side by side, a flexible way of referencing is needed.
For this purpose, DocOnce offers \emph{generalized references} which allows
a reference to have two different formulations, one for internal
references and one for external references. Since {\LaTeX} supports
references to labels in external documents via the \texttt{xr} package,
the generalized references in DocOnce has a syntax that may utilize
the \texttt{xr} feature in {\LaTeX}.

The syntax of generalized references reads
\bccq
ref[internal][cite][external]
\eccq
If all standard \texttt{ref} references (with curly braces)
in the text \texttt{internal} are references
to labels in the present document, the above \texttt{ref} command is replaced
by the text \texttt{internal}. Otherwise, if cite is non-empty and the format
is \texttt{latex} or \texttt{pdflatex} one assumes that the references in \texttt{internal}
are to external documents declared by a comment line \Verb!# Externaldocuments: testdoc, mydoc! (usually after the title, authors,
and date). In this case the output text is \texttt{internal cite} and the
{\LaTeX} package \texttt{xr} is used to handle the labels in the external documents.
When referring to a complete chapter (not a section in it), which
corresponds to a complete external document, it does not make sense
to write out \texttt{internal cite} since the \texttt{internal} reference is a
chapter number. In such cases, the \texttt{internal} syntax can be used,
and if the label is in another {\LaTeX} document, the output is just \texttt{cite}.
For all
output formats other than \texttt{latex} and \texttt{pdflatex}, the \texttt{external}
text will be the output.

Here is an example on a specific generalized reference to a section
in a document:
\bccq
As explained in
ref[Section ref{subsec:ex}][in "Langtangen, 2012":
"https://hplgit.github.io/doconce/test/demo_testdoc.html#subsec:ex"
cite{testdoc:12}][a "section":
"https://hplgit.github.io/doconce/test/demo_testdoc.html#subsec:ex" in
the document "A Document for Testing DocOnce":
"https://hplgit.github.io/doconce/test/demo_testdoc.html"
cite{testdoc:12}], DocOnce documents may include tables.
\eccq
With \texttt{latex} or \texttt{pdflatex} as output, this translates to
\bccq
As explained in
Section ref{subsec:ex}, DocOnce documents may include tables.
\eccq
if the label \Verb!{subsec:ex}! appears in the present DocOnce source, and
otherwise
\bccq
As explained in
Section ref{subsec:ex} in "Langtangen, 2012":
"https://hplgit.github.io/doconce/test/demo_testdoc.html#subsec:ex"
cite{testdoc:12}, DocOnce documents may include tables.
\eccq
In a format different from \texttt{latex} and \texttt{pdflatex}, the effective DocOnce
text becomes
\bccq
As explained in
a "section":
"https://hplgit.github.io/doconce/test/demo_testdoc.html#subsec:ex" in
the document "A Document for Testing DocOnce":
"https://hplgit.github.io/doconce/test/demo_testdoc.html"
cite{testdoc:12}, DocOnce documents may include tables.
\eccq
The rendered text in the current format \texttt{latex} becomes


\begin{quote}
As explained in
Section~\ref{subsec:ex}in \href{{https://hplgit.github.io/doconce/test/demo_testdoc.html#subsec:ex}}{Langtangen, 2012}
\cite{testdoc:12}, DocOnce documents may include tables.
\end{quote}


A reference to an entire external document, which is usually a chapter
if the reference is internal in the DocOnce source, applies the
\texttt{refch} syntax:

\bccq
As explained in
refch[Chapter ref{ch:testdoc}]["Langtangen, 2012":
"https://hplgit.github.io/doconce/test/demo_testdoc.html"
cite{testdoc:12}][the document
"A Document for Testing DocOnce":
"https://hplgit.github.io/doconce/test/demo_testdoc.html"
cite{testdoc:12}], DocOnce documents may include tables.
\eccq
The output now if \texttt{ch:testdoc} is not a label in the document,
becomes in the \texttt{latex} and \texttt{pdflatex} case

\bccq
As explained in
"Langtangen, 2012":
"https://hplgit.github.io/doconce/test/demo_testdoc.html"
cite{testdoc:12}, DocOnce documents may include tables.
\eccq
That is, the internal reference \texttt{Chapter ...} is omitted since
it is not meaningful to refer to an external document as "Chapter".
The resulting rendered text in the current format \texttt{latex} becomes


\begin{quote}
As explained in
\href{{https://hplgit.github.io/doconce/test/demo_testdoc.html}}{Langtangen, 2012}
\cite{testdoc:12}, DocOnce documents may include tables.
\end{quote}


Note that {\LaTeX} cannot
have links to local files, so a complete URL on the form
\texttt{https://...} must be used.

And here is another example with internal references only:

\bccq
Generalized references are described in ref[Section ref{genrefs}][dummy1][
dummy2].
\eccq
The text is rendered to


\begin{quote}
Generalized references are described in
Section~\ref{genrefs}.
\end{quote}


\chapter{Test of math}

% Here we test the chapter heading to see if latex output then has
% book style rather than article style.

Inline math, $a=b$, is the only math in this document.

% Need BIBFILE because of \cite{} examples
\clearemptydoublepage


\bibliographystyle{plain}
\bibliography{papers}


% ------------------- end of main content ---------------

% #ifdef PREAMBLE
\end{document}
% #endif


************** File: author1.rst *****************
.. Automatically generated Sphinx-extended reStructuredText file from DocOnce source
   (https://github.com/hplgit/doconce/)

.. Document title:

Test of one author at one institution
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

:Authors: John Doe (doe at cyberspace.net)
:Date: Jan 32, 2100

.. Externaldocument: testdoc

.. _genrefs:

Generalized References
%%%%%%%%%%%%%%%%%%%%%%

Sometimes a series of individual documents may be assembled to one
large document. The assembly impacts how references to sections
are written: when referring to a section in the same document, a label
can be used, while references to sections in other documents are
written differently, sometimes involving a link (URL) and a citation.
Especially if both the individual documents and the large assembly document
are to exist side by side, a flexible way of referencing is needed.
For this purpose, DocOnce offers *generalized references* which allows
a reference to have two different formulations, one for internal
references and one for external references. Since LaTeX supports
references to labels in external documents via the ``xr`` package,
the generalized references in DocOnce has a syntax that may utilize
the ``xr`` feature in LaTeX.

The syntax of generalized references reads

.. code-block:: text

    ref[internal][cite][external]

If all standard ``ref`` references (with curly braces)
in the text ``internal`` are references
to labels in the present document, the above ``ref`` command is replaced
by the text ``internal``. Otherwise, if cite is non-empty and the format
is ``latex`` or ``pdflatex`` one assumes that the references in ``internal``
are to external documents declared by a comment line ``#
Externaldocuments: testdoc, mydoc`` (usually after the title, authors,
and date). In this case the output text is ``internal cite`` and the
LaTeX package ``xr`` is used to handle the labels in the external documents.
When referring to a complete chapter (not a section in it), which
corresponds to a complete external document, it does not make sense
to write out ``internal cite`` since the ``internal`` reference is a
chapter number. In such cases, the ``internal`` syntax can be used,
and if the label is in another LaTeX document, the output is just ``cite``.
For all
output formats other than ``latex`` and ``pdflatex``, the ``external``
text will be the output.

Here is an example on a specific generalized reference to a section
in a document:

.. code-block:: text

    As explained in
    ref[Section ref{subsec:ex}][in "Langtangen, 2012":
    "https://hplgit.github.io/doconce/test/demo_testdoc.html#subsec:ex"
    cite{testdoc:12}][a "section":
    "https://hplgit.github.io/doconce/test/demo_testdoc.html#subsec:ex" in
    the document "A Document for Testing DocOnce":
    "https://hplgit.github.io/doconce/test/demo_testdoc.html"
    cite{testdoc:12}], DocOnce documents may include tables.

With ``latex`` or ``pdflatex`` as output, this translates to

.. code-block:: text

    As explained in
    Section ref{subsec:ex}, DocOnce documents may include tables.

if the label ``{subsec:ex}`` appears in the present DocOnce source, and
otherwise

.. code-block:: text

    As explained in
    Section ref{subsec:ex} in "Langtangen, 2012":
    "https://hplgit.github.io/doconce/test/demo_testdoc.html#subsec:ex"
    cite{testdoc:12}, DocOnce documents may include tables.

In a format different from ``latex`` and ``pdflatex``, the effective DocOnce
text becomes

.. code-block:: text

    As explained in
    a "section":
    "https://hplgit.github.io/doconce/test/demo_testdoc.html#subsec:ex" in
    the document "A Document for Testing DocOnce":
    "https://hplgit.github.io/doconce/test/demo_testdoc.html"
    cite{testdoc:12}, DocOnce documents may include tables.

The rendered text in the current format ``sphinx`` becomes


..

    As explained in
    a `section <https://hplgit.github.io/doconce/test/demo_testdoc.html#subsec:ex>`__ in
    the document `A Document for Testing DocOnce <https://hplgit.github.io/doconce/test/demo_testdoc.html>`__
    [Ref1]_, DocOnce documents may include tables.



A reference to an entire external document, which is usually a chapter
if the reference is internal in the DocOnce source, applies the
``refch`` syntax:

.. code-block:: text

    As explained in
    refch[Chapter ref{ch:testdoc}]["Langtangen, 2012":
    "https://hplgit.github.io/doconce/test/demo_testdoc.html"
    cite{testdoc:12}][the document
    "A Document for Testing DocOnce":
    "https://hplgit.github.io/doconce/test/demo_testdoc.html"
    cite{testdoc:12}], DocOnce documents may include tables.

The output now if ``ch:testdoc`` is not a label in the document,
becomes in the ``latex`` and ``pdflatex`` case

.. code-block:: text

    As explained in
    "Langtangen, 2012":
    "https://hplgit.github.io/doconce/test/demo_testdoc.html"
    cite{testdoc:12}, DocOnce documents may include tables.

That is, the internal reference ``Chapter ...`` is omitted since
it is not meaningful to refer to an external document as "Chapter".
The resulting rendered text in the current format ``sphinx`` becomes


..

    As explained in
    the document
    `A Document for Testing DocOnce <https://hplgit.github.io/doconce/test/demo_testdoc.html>`__
    [Ref1]_, DocOnce documents may include tables.



Note that LaTeX cannot
have links to local files, so a complete URL on the form
``https://...`` must be used.

And here is another example with internal references only:

.. code-block:: text

    Generalized references are described in ref[Section ref{genrefs}][dummy1][
    dummy2].

The text is rendered to


..

    Generalized references are described in
    the section :ref:`genrefs`.



Test of math
%%%%%%%%%%%%

.. Here we test the chapter heading to see if latex output then has

.. book style rather than article style.

Inline math, :math:`a=b`, is the only math in this document.

.. Need BIBFILE because of cite{} examples

.. [Ref1]
   **H. P. Langtangen**. A Document for Testing Doconce,
   *Simula Research Laboratory*,
   `http://hplgit.github.io/doconce/test/demo_testdoc.html <http://hplgit.github.io/doconce/test/demo_testdoc.html>`_,
   2015.



************** File: author1.txt *****************
Test of one author at one institution
=====================================

John Doe [1] (doe@cyberspace.net)

[1] Cyberspace Inc.

Date: Jan 32, 2100

Generalized References
%%%%%%%%%%%%%%%%%%%%%%

Sometimes a series of individual documents may be assembled to one
large document. The assembly impacts how references to sections
are written: when referring to a section in the same document, a label
can be used, while references to sections in other documents are
written differently, sometimes involving a link (URL) and a citation.
Especially if both the individual documents and the large assembly document
are to exist side by side, a flexible way of referencing is needed.
For this purpose, DocOnce offers *generalized references* which allows
a reference to have two different formulations, one for internal
references and one for external references. Since LaTeX supports
references to labels in external documents via the xr package,
the generalized references in DocOnce has a syntax that may utilize
the xr feature in LaTeX.

The syntax of generalized references reads::

        ref[internal][cite][external]

If all standard ref references (with curly braces)
in the text internal are references
to labels in the present document, the above ref command is replaced
by the text internal. Otherwise, if cite is non-empty and the format
is latex or pdflatex one assumes that the references in internal
are to external documents declared by a comment line #
Externaldocuments: testdoc, mydoc (usually after the title, authors,
and date). In this case the output text is internal cite and the
LaTeX package xr is used to handle the labels in the external documents.
When referring to a complete chapter (not a section in it), which
corresponds to a complete external document, it does not make sense
to write out internal cite since the internal reference is a
chapter number. In such cases, the internal syntax can be used,
and if the label is in another LaTeX document, the output is just cite.
For all
output formats other than latex and pdflatex, the external
text will be the output.

Here is an example on a specific generalized reference to a section
in a document::

        As explained in
        ref[Section ref{subsec:ex}][in "Langtangen, 2012":
        "https://hplgit.github.io/doconce/test/demo_testdoc.html#subsec:ex"
        cite{testdoc:12}][a "section":
        "https://hplgit.github.io/doconce/test/demo_testdoc.html#subsec:ex" in
        the document "A Document for Testing DocOnce":
        "https://hplgit.github.io/doconce/test/demo_testdoc.html"
        cite{testdoc:12}], DocOnce documents may include tables.

With latex or pdflatex as output, this translates to::

        As explained in
        Section ref{subsec:ex}, DocOnce documents may include tables.

if the label {subsec:ex} appears in the present DocOnce source, and
otherwise::

        As explained in
        Section ref{subsec:ex} in "Langtangen, 2012":
        "https://hplgit.github.io/doconce/test/demo_testdoc.html#subsec:ex"
        cite{testdoc:12}, DocOnce documents may include tables.

In a format different from latex and pdflatex, the effective DocOnce
text becomes::

        As explained in
        a "section":
        "https://hplgit.github.io/doconce/test/demo_testdoc.html#subsec:ex" in
        the document "A Document for Testing DocOnce":
        "https://hplgit.github.io/doconce/test/demo_testdoc.html"
        cite{testdoc:12}, DocOnce documents may include tables.

The rendered text in the current format plain becomes

        As explained in
        a section (https://hplgit.github.io/doconce/test/demo_testdoc.html#subsec:ex) in
        the document A Document for Testing DocOnce (https://hplgit.github.io/doconce/test/demo_testdoc.html)
        [1], DocOnce documents may include tables.


A reference to an entire external document, which is usually a chapter
if the reference is internal in the DocOnce source, applies the
refch syntax::

        As explained in
        refch[Chapter ref{ch:testdoc}]["Langtangen, 2012":
        "https://hplgit.github.io/doconce/test/demo_testdoc.html"
        cite{testdoc:12}][the document
        "A Document for Testing DocOnce":
        "https://hplgit.github.io/doconce/test/demo_testdoc.html"
        cite{testdoc:12}], DocOnce documents may include tables.

The output now if ch:testdoc is not a label in the document,
becomes in the latex and pdflatex case::

        As explained in
        "Langtangen, 2012":
        "https://hplgit.github.io/doconce/test/demo_testdoc.html"
        cite{testdoc:12}, DocOnce documents may include tables.

That is, the internal reference Chapter ... is omitted since
it is not meaningful to refer to an external document as "Chapter".
The resulting rendered text in the current format plain becomes

        As explained in
        the document
        A Document for Testing DocOnce (https://hplgit.github.io/doconce/test/demo_testdoc.html)
        [1], DocOnce documents may include tables.


Note that LaTeX cannot
have links to local files, so a complete URL on the form
https://... must be used.

And here is another example with internal references only::

        Generalized references are described in ref[Section ref{genrefs}][dummy1][
        dummy2].

The text is rendered to

        Generalized references are described in
        the section "Generalized References".


Test of math
%%%%%%%%%%%%

Inline math, a=b, is the only math in this document.

 1. _H. P. Langtangen_. 
    A Document for Testing Doconce,
    *Simula Research Laboratory*,
    2015,
    http://hplgit.github.io/doconce/test/demo_testdoc.html.

************** File: author2_siamltex.tex *****************
%%
%% Automatically generated file from DocOnce source
%% (https://github.com/hplgit/doconce/)
%%
%%


%-------------------- begin preamble ----------------------

% Style: SIAM LaTeX2e
\documentclass[leqno,final]{siamltex}

\listfiles               %  print all files needed to compile this document

\usepackage{relsize,makeidx,color,setspace,amsmath,amsfonts,amssymb}
\usepackage[table]{xcolor}
\usepackage{bm,ltablex,microtype}

\usepackage[pdftex]{graphicx}

\usepackage[T1]{fontenc}
%\usepackage[latin1]{inputenc}
\usepackage{ucs}
\usepackage[utf8x]{inputenc}

\usepackage{lmodern}         % Latin Modern fonts derived from Computer Modern

% Hyperlinks in PDF:
\definecolor{linkcolor}{rgb}{0,0,0.4}
\usepackage{hyperref}
\hypersetup{
    breaklinks=true,
    colorlinks=true,
    linkcolor=linkcolor,
    urlcolor=linkcolor,
    citecolor=black,
    filecolor=black,
    %filecolor=blue,
    pdfmenubar=true,
    pdftoolbar=true,
    bookmarksdepth=3   % Uncomment (and tweak) for PDF bookmarks with more levels than the TOC
    }
%\hyperbaseurl{}   % hyperlinks are relative to this root

\setcounter{tocdepth}{2}  % levels in table of contents

% prevent orhpans and widows
\clubpenalty = 10000
\widowpenalty = 10000

% --- end of standard preamble for documents ---


% insert custom LaTeX commands...

\raggedbottom
\makeindex
\usepackage[totoc]{idxlayout}   % for index in the toc
\usepackage[nottoc]{tocbibind}  % for references/bibliography in the toc

%-------------------- end preamble ----------------------

\begin{document}

% matching end for #ifdef PREAMBLE

\newcommand{\exercisesection}[1]{\subsection*{#1}}

\input{newcommands_bfmath}
\input{newcommands_replace}

% ------------------- main content ----------------------



% ----------------- title -------------------------

\title{Yet Another Scientific Paper}

% ----------------- author(s) -------------------------

\author{Hans Petter Langtangen\thanks{Email: \texttt{hpl@simula.no}. Center for Biomedical Computing, Simula Research Laboratory and Department of Informatics, University of Oslo.}
\and Kaare Dump\thanks{Segfault, Cyberspace.}
\and A. Dummy Author
\and I. S. Overworked and Outburned\thanks{Inst1; Inst2, Somewhere; Third Inst, Elsewhere; and Fourth Inst.}
\and J. Doe\thanks{Email: \texttt{j\_doe@cyberspace.com}.}}

% ----------------- end author(s) -------------------------

% --- begin date ---
\begin{center}
Jan 32, 2100
\end{center}
% --- end date ---

\vspace{1cm}

\begin{abstract}
Here goes
a very short
abstract.
\end{abstract}


\begin{keywords}
test, doconce, paper, multiple authors.
\end{keywords}

%\tableofcontents  % not legal in SIAM latex style


\vspace{1cm} % after toc




\section{Introduction}

This is a test of a typical paper.

\section{Concluding remarks}

We need to test bibliography too, and for this purpose we need
a citation like \cite{Langtangen_1992c,Langtangen_1994a}.



\bibliographystyle{plain}
\bibliography{papers}


% ------------------- end of main content ---------------

\end{document}


************** File: author2_elsevier.tex *****************
%%
%% Automatically generated file from DocOnce source
%% (https://github.com/hplgit/doconce/)
%%
%%


%-------------------- begin preamble ----------------------

% Style: Elsvier LaTeX style
\documentclass[final]{elsarticle}

% Drop "Submitted to ..." line at the bottom of the first page
\makeatletter
\def\ps@pprintTitle{%
  \let\@oddhead\@empty
  \let\@evenhead\@empty
  \def\@oddfoot{\reset@font\hfil\thepage\hfil}
  \let\@evenfoot\@oddfoot
}
\makeatother

\listfiles               %  print all files needed to compile this document

\usepackage{relsize,makeidx,color,setspace,amsmath,amsfonts,amssymb}
\usepackage[table]{xcolor}
\usepackage{bm,ltablex,microtype}

\usepackage[pdftex]{graphicx}

\usepackage[T1]{fontenc}
%\usepackage[latin1]{inputenc}
\usepackage{ucs}
\usepackage[utf8x]{inputenc}

\usepackage{lmodern}         % Latin Modern fonts derived from Computer Modern

% Hyperlinks in PDF:
\definecolor{linkcolor}{rgb}{0,0,0.4}
\usepackage{hyperref}
\hypersetup{
    breaklinks=true,
    colorlinks=true,
    linkcolor=linkcolor,
    urlcolor=linkcolor,
    citecolor=black,
    filecolor=black,
    %filecolor=blue,
    pdfmenubar=true,
    pdftoolbar=true,
    bookmarksdepth=3   % Uncomment (and tweak) for PDF bookmarks with more levels than the TOC
    }
%\hyperbaseurl{}   % hyperlinks are relative to this root

\setcounter{tocdepth}{2}  % levels in table of contents

% prevent orhpans and widows
\clubpenalty = 10000
\widowpenalty = 10000

% --- end of standard preamble for documents ---


% insert custom LaTeX commands...

\raggedbottom
\makeindex
\usepackage[totoc]{idxlayout}   % for index in the toc
\usepackage[nottoc]{tocbibind}  % for references/bibliography in the toc

%-------------------- end preamble ----------------------

\begin{document}

% matching end for #ifdef PREAMBLE

\newcommand{\exercisesection}[1]{\subsection*{#1}}

\input{newcommands_bfmath}
\input{newcommands_replace}

% ------------------- main content ----------------------



% ----------------- title -------------------------

\begin{frontmatter}

\title{Yet Another Scientific Paper}

% ----------------- author(s) -------------------------

\author[inst1,inst2]{Hans Petter Langtangen}
\author[inst3]{Kaare Dump}
\author[]{A. Dummy Author}
\author[inst4,inst5,inst6,inst7]{I. S. Overworked and Outburned}
\author[]{J. Doe}\address[inst1]{Center for Biomedical Computing, Simula Research Laboratory}
\address[inst2]{Department of Informatics, University of Oslo}
\address[inst3]{Segfault, Cyberspace}
\address[inst4]{Inst1}
\address[inst5]{Inst2, Somewhere}
\address[inst6]{Third Inst, Elsewhere}
\address[inst7]{Fourth Inst}

% ----------------- end author(s) -------------------------

% --- begin date ---
\begin{center}
Jan 32, 2100
\end{center}
% --- end date ---

\vspace{1cm}

\begin{abstract}
Here goes
a very short
abstract.
\end{abstract}


\begin{keyword}
test \sep doconce \sep paper \sep multiple authors
\end{keyword}

\end{frontmatter}

%\linenumbers


%\tableofcontents


\vspace{1cm} % after toc




\section{Introduction}

This is a test of a typical paper.

\section{Concluding remarks}

We need to test bibliography too, and for this purpose we need
a citation like \cite{Langtangen_1992c,Langtangen_1994a}.



\bibliographystyle{plain}
\bibliography{papers}


% ------------------- end of main content ---------------

\end{document}


************** File: ._testdoc000.html *****************
<!--
Automatically generated HTML file from DocOnce source
(https://github.com/doconce/doconce/)
-->
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="DocOnce: https://github.com/doconce/doconce/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="description" content="A Document for Testing DocOnce">
<meta name="keywords" content="figures,movies,index with subindex,_boldface word_ in index,index with _boldface word_,index with _boldface word_ in subentry,double _boldface word_  _boldface word_ in subentry too,index, with comma, and one more">

<title>A Document for Testing DocOnce</title>


<link href="https://raw.github.com/doconce/doconce/master/bundled/html_styles/style_solarized_box/css/solarized_light_code.css" rel="stylesheet" type="text/css" title="light"/>
<script src="https://raw.github.com/doconce/doconce/master/bundled/html_styles/style_solarized_box/js/highlight.pack.js"></script>
<script>hljs.initHighlightingOnLoad();</script>

<style type="text/css">
body, td {font-size: 140%;}
h1 {font-size: 200%;}
h2 {font-size: 180%;}

/* solarized style */
body {
  margin:5;
  padding:0;
  border:0; /* Remove the border around the viewport in old versions of IE */
  width:100%;
  background: #fdf6e3;
  min-width:600px;	/* Minimum width of layout - remove if not required */
  font-family: Verdana, Helvetica, Arial, sans-serif;
  font-size: 1.0em;
  line-height: 1.3em;
  color: #657b83;
}
a { color: #859900; text-decoration: underline; }
a:hover, a:active { outline:none }
a, a:active, a:visited { color: #859900; }
a:hover { color: #268bd2; }
h1, h2, h3 { margin:.8em 0 .2em 0; padding:0; line-height: 125%; }
h2 { font-variant: small-caps; }
tt, code { font-family: monospace, sans-serif; box-shadow: none; }
hr { border: 0; width: 80%; border-bottom: 1px solid #aaa; }
p { text-indent: 0px; }
p.caption { width: 80%; font-style: normal; text-align: left; }
hr.figure { border: 0; width: 80%; border-bottom: 1px solid #aaa; }
.alert-text-small   { font-size: 80%;  }
.alert-text-large   { font-size: 130%; }
.alert-text-normal  { font-size: 90%;  }
.alert {
  padding:8px 35px 8px 14px; margin-bottom:18px;
  text-shadow:0 1px 0 rgba(255,255,255,0.5);
  border:1px solid #93a1a1;
  border-radius: 4px;
  -webkit-border-radius: 4px;
  -moz-border-radius: 4px;
  color: #555;
  background-color: #eee8d5;
  background-position: 10px 5px;
  background-repeat: no-repeat;
  background-size: 38px;
  padding-left: 55px;
  width: 75%;
 }
.alert-block {padding-top:14px; padding-bottom:14px}
.alert-block > p, .alert-block > ul {margin-bottom:1em}
.alert li {margin-top: 1em}
.alert-block p+p {margin-top:5px}
.alert-notice { background-image: url(https://raw.github.com/doconce/doconce/master/bundled/html_images/small_yellow_notice.png); }
.alert-summary  { background-image:url(https://raw.github.com/doconce/doconce/master/bundled/html_images/small_yellow_summary.png); }
.alert-warning { background-image: url(https://raw.github.com/doconce/doconce/master/bundled/html_images/small_yellow_warning.png); }
.alert-question {background-image:url(https://raw.github.com/doconce/doconce/master/bundled/html_images/small_yellow_question.png); }

div { text-align: justify; text-justify: inter-word; }
</style>


<script src="https://sagecell.sagemath.org/static/jquery.min.js"></script>
<script src="https://sagecell.sagemath.org/embedded_sagecell.js"></script>
<link rel="stylesheet" type="text/css" href="https://sagecell.sagemath.org/static/sagecell_embed.css">
<script>
$(function () {
    // Make the div with id 'mycell' a Sage cell
    sagecell.makeSagecell({inputLocation:  '#mycell',
                           template:       sagecell.templates.minimal,
                           evalButtonText: 'Activate'});
    // Make *any* div with class 'compute' a Sage cell
    sagecell.makeSagecell({inputLocation: 'div.compute',
                           evalButtonText: 'Evaluate'});
});
</script>




<!-- Tools for embedded Bokeh plots -->
<link rel="stylesheet"
      href="https://cdn.pydata.org/bokeh/release/bokeh-0.9.0.min.css"
      type="text/css" />
<script type="text/javascript"
	src="https://cdn.pydata.org/bokeh/release/bokeh-0.9.0.min.js">
</script>
<script type="text/javascript">
  Bokeh.set_log_level("info");
</script>


</head>

<!-- tocinfo
{'highest level': 1,
 'sections': [('Table of contents',
               1,
               'table_of_contents',
               'table_of_contents'),
              ('Section 1', 1, 'sec1', 'sec1'),
              ('Here is a list with subsubsection heading',
               3,
               None,
               'here-is-a-list-with-subsubsection-heading'),
              ('Subsection 1', 2, 'subsec1', 'subsec1'),
              ('Test Section reference at beginning of line and after a '
               'sentence',
               3,
               None,
               'test-section-reference-at-beginning-of-line-and-after-a-sentence'),
              ('Computer code', 3, None, 'computer-code'),
              ('Subsubsection heading before code',
               3,
               None,
               'subsubsection-heading-before-code'),
              ('Running OS commands', 3, None, 'running-os-commands'),
              ('Footnotes', 3, None, 'footnotes'),
              ('Subsection 2: Testing figures', 2, 'subsec:ex', 'subsec:ex'),
              ('The $\\theta$ parameter (not $\\nabla$?)',
               2,
               'decay:sec:theta',
               'decay:sec:theta'),
              ('Custom Environments', 2, None, 'custom-environments'),
              ('Tables', 2, 'subsec:table', 'subsec:table'),
              ('A test of verbatim words in heading with subscript $a_i$: '
               '`my_file_v1` and `my_file_v2`',
               2,
               None,
               'a-test-of-verbatim-words-in-heading-with-subscript-a_i-my_file_v1-and-my_file_v2'),
              ('_Just bold_', 2, None, '_just-bold_'),
              ('*Just emphasize*', 2, None, 'just-emphasize'),
              ('`Just verbatim`', 2, None, 'just-verbatim'),
              ('_Bold_ beginning', 2, None, '_bold_-beginning'),
              ('*Emphasize* beginning', 2, None, 'emphasize-beginning'),
              ('`Verbatim` beginning', 2, None, 'verbatim-beginning'),
              ('Maybe _bold end_', 2, None, 'maybe-_bold-end_'),
              ('Maybe *emphasize end*', 2, None, 'maybe-emphasize-end'),
              ('Maybe `verbatim end`', 2, None, 'maybe-verbatim-end'),
              ('The middle has _bold_ word',
               2,
               None,
               'the-middle-has-_bold_-word'),
              ('The middle has *emphasize* word',
               2,
               None,
               'the-middle-has-emphasize-word'),
              ('The middle has `verbatim` word',
               2,
               None,
               'the-middle-has-verbatim-word'),
              ('Bibliography test', 2, None, 'bibliography-test'),
              ('Example 1: Examples can be typeset as exercises',
               2,
               'Example',
               'Example'),
              ('User-defined environments',
               2,
               None,
               'user-defined-environments'),
              ('Example 1: A test function', 2, 'ex:test:1p1', 'ex:test:1p1'),
              ('Example 2: Addition', 2, 'ex:math:1p1', 'ex:math:1p1'),
              ('URLs', 2, 'subsubsec:ex', 'subsubsec:ex'),
              ('LaTeX Mathematics', 1, None, 'latex-mathematics'),
              ('Exercises', 1, None, 'exercises'),
              ('Problem 2: Flip a Coin', 2, 'demo:ex:1', 'demo:ex:1'),
              ('My remarks', 3, None, 'my-remarks'),
              ('Remarks', 3, None, 'remarks'),
              ('Not an exercise', 2, None, 'not-an-exercise'),
              ('Exercise 3: Test of plain text exercise',
               2,
               'my:exer1',
               'my:exer1'),
              ('Project 4: Compute a Probability', 2, 'demo:ex:2', 'demo:ex:2'),
              ('Project 5: Explore Distributions of Random Circles',
               2,
               'proj:circle1',
               'proj:circle1'),
              ('Remarks', 3, None, 'remarks'),
              ('Exercise 6: Determine some Distance',
               2,
               'exer:dist',
               'exer:dist'),
              ('Remarks', 3, None, 'remarks'),
              ('Some exercise without the "Exercise:" prefix',
               2,
               None,
               'some-exercise-without-the-exercise-prefix'),
              ('Exercise 8: Solution of differential equation',
               2,
               'sec:this:exer:de',
               'sec:this:exer:de'),
              ('Example 9: Just an example',
               2,
               None,
               'example-9-just-an-example'),
              ('Here goes another section',
               1,
               None,
               'here-goes-another-section'),
              ('More Exercises', 1, None, 'more-exercises'),
              ('Exercise 10: Make references to projects and problems',
               2,
               'exer:some:formula',
               'exer:some:formula'),
              ('Project 11: References in a headings do not work well in html',
               2,
               'exer:you',
               'exer:you'),
              ('References', 1, None, 'references'),
              ('Appendix: Just for testing; part I', 1, 'app1', 'app1'),
              ('A subsection within an appendix',
               2,
               None,
               'a-subsection-within-an-appendix'),
              ('Appendix: Just for testing; part II', 1, 'app2', 'app2'),
              ('Appendix: Testing identical titles',
               2,
               None,
               'appendix-testing-identical-titles'),
              ('Appendix: Testing identical titles',
               2,
               'test:title:id1',
               'test:title:id1'),
              ('Appendix: Testing identical titles',
               2,
               'test:title:id2',
               'test:title:id2'),
              ('Appendix: Testing identical titles',
               2,
               None,
               'appendix-testing-identical-titles'),
              ('Appendix: Testing inline comments',
               2,
               None,
               'appendix-testing-inline-comments'),
              ('Appendix: Testing headings ending with `verbatim inline`',
               2,
               None,
               'appendix-testing-headings-ending-with-verbatim-inline')]}
end of tocinfo -->

<body>



<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  TeX: {
     equationNumbers: {  autoNumber: "none"  },
     extensions: ["AMSmath.js", "AMSsymbols.js", "autobold.js", "color.js"]
  }
});
</script>
<script type="text/javascript" async
 src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>



    
<a name="part0000"></a>
<!-- ------------------- main content ---------------------- -->



<center><h1>A Document for Testing DocOnce</h1></center>  <!-- document title -->

<p>
<!-- author(s): Hans Petter Langtangen, Kaare Dump, A. Dummy Author, I. S. Overworked and Outburned, and J. Doe -->

<center>
<b>Hans Petter Langtangen</b> [1, 2] (<tt>hpl at simula.no</tt>)
</center>

<center>
<b>Kaare Dump</b> [3]
</center>

<center>
<b>A. Dummy Author</b> 
</center>

<center>
<b>I. S. Overworked and Outburned</b> [4, 5, 6, 7]
</center>

<center>
<b>J. Doe</b>  (<tt>j_doe at cyberspace.com</tt>)
</center>

<p>
<!-- institution(s) -->

<center>[1] <b>Center for Biomedical Computing, Simula Research Laboratory</b></center>
<center>[2] <b>Department of Informatics, University of Oslo</b></center>
<center>[3] <b>Segfault, Cyberspace</b></center>
<center>[4] <b>Inst1</b></center>
<center>[5] <b>Inst2, Somewhere</b></center>
<center>[6] <b>Third Inst, Elsewhere</b></center>
<center>[7] <b>Fourth Inst</b></center>
<br>
<p>
<center><h4>Jan 32, 2100</h4></center> <!-- date -->
<br>

<h1 id="table_of_contents">Table of contents</h2>

<p>
<a href="._testdoc001.html#sec1"> Section 1 </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc001.html#subsec1"> Subsection 1 </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc001.html#subsec:ex"> Subsection 2: Testing figures </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc001.html#decay:sec:theta"> The \( \theta \) parameter (not \( \nabla \)?) </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc001.html#custom-environments"> Custom Environments </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc001.html#subsec:table"> Tables </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc001.html#a-test-of-verbatim-words-in-heading-with-subscript-a_i-my_file_v1-and-my_file_v2"> A test of verbatim words in heading with subscript \( a_i \): <code>my_file_v1</code> and <code>my_file_v2</code> </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc001.html#_just-bold_"> <b>Just bold</b> </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc001.html#just-emphasize"> <em>Just emphasize</em> </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc001.html#just-verbatim"> <code>Just verbatim</code> </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc001.html#_bold_-beginning"> <b>Bold</b> beginning </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc001.html#emphasize-beginning"> <em>Emphasize</em> beginning </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc001.html#verbatim-beginning"> <code>Verbatim</code> beginning </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc001.html#maybe-_bold-end_"> Maybe <b>bold end</b> </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc001.html#maybe-emphasize-end"> Maybe <em>emphasize end</em> </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc001.html#maybe-verbatim-end"> Maybe <code>verbatim end</code> </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc001.html#the-middle-has-<b>bold</b>-word"> The middle has <b>bold</b> word </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc001.html#the-middle-has-emphasize-word"> The middle has <em>emphasize</em> word </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc001.html#the-middle-has-verbatim-word"> The middle has <code>verbatim</code> word </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc001.html#bibliography-test"> Bibliography test </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc001.html#Example"> Example 1: Examples can be typeset as exercises </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc001.html#user-defined-environments"> User-defined environments </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc001.html#ex:test:1p1"> Example 1: A test function </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc001.html#ex:math:1p1"> Example 2: Addition </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc001.html#subsubsec:ex"> URLs </a><br>
<a href="._testdoc002.html#latex-mathematics"> LaTeX Mathematics </a><br>
<a href="._testdoc002.html#exercises"> Exercises </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc002.html#demo:ex:1"> Problem 2: Flip a Coin </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc002.html#not-an-exercise"> Not an exercise </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc002.html#my:exer1"> Exercise 3: Test of plain text exercise </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc002.html#demo:ex:2"> Project 4: Compute a Probability </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc002.html#proj:circle1"> Project 5: Explore Distributions of Random Circles </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc002.html#exer:dist"> Exercise 6: Determine some Distance </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc002.html#some-exercise-without-the-exercise-prefix"> Some exercise without the "Exercise:" prefix </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc002.html#sec:this:exer:de"> Exercise 8: Solution of differential equation </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc002.html#example-9-just-an-example"> Example 9: Just an example </a><br>
<a href="._testdoc002.html#here-goes-another-section"> Here goes another section </a><br>
<a href="._testdoc002.html#more-exercises"> More Exercises </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc002.html#exer:some:formula"> Exercise 10: Make references to projects and problems </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc002.html#exer:you"> Project 11: References in a headings do not work well in html </a><br>
<a href="._testdoc002.html#references"> References </a><br>
<a href="._testdoc002.html#app1"> Appendix: Just for testing; part I </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc002.html#a-subsection-within-an-appendix"> A subsection within an appendix </a><br>
<a href="._testdoc002.html#app2"> Appendix: Just for testing; part II </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc003.html#appendix-testing-identical-titles"> Appendix: Testing identical titles </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc002.html#test:title:id1"> Appendix: Testing identical titles </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc002.html#test:title:id2"> Appendix: Testing identical titles </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc003.html#appendix-testing-identical-titles"> Appendix: Testing identical titles </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc003.html#appendix-testing-inline-comments"> Appendix: Testing inline comments </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc003.html#appendix-testing-headings-ending-with-verbatim-inline"> Appendix: Testing headings ending with <code>verbatim inline</code> </a><br>
</p>
<p>
<p>
<!-- begin bottom navigation -->
<table style="width: 100%"><tr><td>
</td><td>
\
<div style="text-align: right;"><a href="._testdoc001.html"><img src="https://hplgit.github.io/doconce/bundled/html_images/next2.png" border=0 alt="Next &raquo;"></a></div>
</td></tr></table>
<!-- end bottom navigation -->
</p>

<!-- ------------------- end of main content --------------- -->

<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.js"></script>


</body>
</html>

************** File: ._testdoc001.html *****************
<!--
Automatically generated HTML file from DocOnce source
(https://github.com/doconce/doconce/)
-->
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="DocOnce: https://github.com/doconce/doconce/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="description" content="A Document for Testing DocOnce">
<meta name="keywords" content="figures,movies,index with subindex,_boldface word_ in index,index with _boldface word_,index with _boldface word_ in subentry,double _boldface word_  _boldface word_ in subentry too,index, with comma, and one more">

<title>A Document for Testing DocOnce</title>


<link href="https://raw.github.com/doconce/doconce/master/bundled/html_styles/style_solarized_box/css/solarized_light_code.css" rel="stylesheet" type="text/css" title="light"/>
<script src="https://raw.github.com/doconce/doconce/master/bundled/html_styles/style_solarized_box/js/highlight.pack.js"></script>
<script>hljs.initHighlightingOnLoad();</script>

<style type="text/css">
body, td {font-size: 140%;}
h1 {font-size: 200%;}
h2 {font-size: 180%;}

/* solarized style */
body {
  margin:5;
  padding:0;
  border:0; /* Remove the border around the viewport in old versions of IE */
  width:100%;
  background: #fdf6e3;
  min-width:600px;	/* Minimum width of layout - remove if not required */
  font-family: Verdana, Helvetica, Arial, sans-serif;
  font-size: 1.0em;
  line-height: 1.3em;
  color: #657b83;
}
a { color: #859900; text-decoration: underline; }
a:hover, a:active { outline:none }
a, a:active, a:visited { color: #859900; }
a:hover { color: #268bd2; }
h1, h2, h3 { margin:.8em 0 .2em 0; padding:0; line-height: 125%; }
h2 { font-variant: small-caps; }
tt, code { font-family: monospace, sans-serif; box-shadow: none; }
hr { border: 0; width: 80%; border-bottom: 1px solid #aaa; }
p { text-indent: 0px; }
p.caption { width: 80%; font-style: normal; text-align: left; }
hr.figure { border: 0; width: 80%; border-bottom: 1px solid #aaa; }
.alert-text-small   { font-size: 80%;  }
.alert-text-large   { font-size: 130%; }
.alert-text-normal  { font-size: 90%;  }
.alert {
  padding:8px 35px 8px 14px; margin-bottom:18px;
  text-shadow:0 1px 0 rgba(255,255,255,0.5);
  border:1px solid #93a1a1;
  border-radius: 4px;
  -webkit-border-radius: 4px;
  -moz-border-radius: 4px;
  color: #555;
  background-color: #eee8d5;
  background-position: 10px 5px;
  background-repeat: no-repeat;
  background-size: 38px;
  padding-left: 55px;
  width: 75%;
 }
.alert-block {padding-top:14px; padding-bottom:14px}
.alert-block > p, .alert-block > ul {margin-bottom:1em}
.alert li {margin-top: 1em}
.alert-block p+p {margin-top:5px}
.alert-notice { background-image: url(https://raw.github.com/doconce/doconce/master/bundled/html_images/small_yellow_notice.png); }
.alert-summary  { background-image:url(https://raw.github.com/doconce/doconce/master/bundled/html_images/small_yellow_summary.png); }
.alert-warning { background-image: url(https://raw.github.com/doconce/doconce/master/bundled/html_images/small_yellow_warning.png); }
.alert-question {background-image:url(https://raw.github.com/doconce/doconce/master/bundled/html_images/small_yellow_question.png); }

div { text-align: justify; text-justify: inter-word; }
</style>


<script src="https://sagecell.sagemath.org/static/jquery.min.js"></script>
<script src="https://sagecell.sagemath.org/embedded_sagecell.js"></script>
<link rel="stylesheet" type="text/css" href="https://sagecell.sagemath.org/static/sagecell_embed.css">
<script>
$(function () {
    // Make the div with id 'mycell' a Sage cell
    sagecell.makeSagecell({inputLocation:  '#mycell',
                           template:       sagecell.templates.minimal,
                           evalButtonText: 'Activate'});
    // Make *any* div with class 'compute' a Sage cell
    sagecell.makeSagecell({inputLocation: 'div.compute',
                           evalButtonText: 'Evaluate'});
});
</script>




<!-- Tools for embedded Bokeh plots -->
<link rel="stylesheet"
      href="https://cdn.pydata.org/bokeh/release/bokeh-0.9.0.min.css"
      type="text/css" />
<script type="text/javascript"
	src="https://cdn.pydata.org/bokeh/release/bokeh-0.9.0.min.js">
</script>
<script type="text/javascript">
  Bokeh.set_log_level("info");
</script>


</head>

<!-- tocinfo
{'highest level': 1,
 'sections': [('Table of contents',
               1,
               'table_of_contents',
               'table_of_contents'),
              ('Section 1', 1, 'sec1', 'sec1'),
              ('Here is a list with subsubsection heading',
               3,
               None,
               'here-is-a-list-with-subsubsection-heading'),
              ('Subsection 1', 2, 'subsec1', 'subsec1'),
              ('Test Section reference at beginning of line and after a '
               'sentence',
               3,
               None,
               'test-section-reference-at-beginning-of-line-and-after-a-sentence'),
              ('Computer code', 3, None, 'computer-code'),
              ('Subsubsection heading before code',
               3,
               None,
               'subsubsection-heading-before-code'),
              ('Running OS commands', 3, None, 'running-os-commands'),
              ('Footnotes', 3, None, 'footnotes'),
              ('Subsection 2: Testing figures', 2, 'subsec:ex', 'subsec:ex'),
              ('The $\\theta$ parameter (not $\\nabla$?)',
               2,
               'decay:sec:theta',
               'decay:sec:theta'),
              ('Custom Environments', 2, None, 'custom-environments'),
              ('Tables', 2, 'subsec:table', 'subsec:table'),
              ('A test of verbatim words in heading with subscript $a_i$: '
               '`my_file_v1` and `my_file_v2`',
               2,
               None,
               'a-test-of-verbatim-words-in-heading-with-subscript-a_i-my_file_v1-and-my_file_v2'),
              ('_Just bold_', 2, None, '_just-bold_'),
              ('*Just emphasize*', 2, None, 'just-emphasize'),
              ('`Just verbatim`', 2, None, 'just-verbatim'),
              ('_Bold_ beginning', 2, None, '_bold_-beginning'),
              ('*Emphasize* beginning', 2, None, 'emphasize-beginning'),
              ('`Verbatim` beginning', 2, None, 'verbatim-beginning'),
              ('Maybe _bold end_', 2, None, 'maybe-_bold-end_'),
              ('Maybe *emphasize end*', 2, None, 'maybe-emphasize-end'),
              ('Maybe `verbatim end`', 2, None, 'maybe-verbatim-end'),
              ('The middle has _bold_ word',
               2,
               None,
               'the-middle-has-_bold_-word'),
              ('The middle has *emphasize* word',
               2,
               None,
               'the-middle-has-emphasize-word'),
              ('The middle has `verbatim` word',
               2,
               None,
               'the-middle-has-verbatim-word'),
              ('Bibliography test', 2, None, 'bibliography-test'),
              ('Example 1: Examples can be typeset as exercises',
               2,
               'Example',
               'Example'),
              ('User-defined environments',
               2,
               None,
               'user-defined-environments'),
              ('Example 1: A test function', 2, 'ex:test:1p1', 'ex:test:1p1'),
              ('Example 2: Addition', 2, 'ex:math:1p1', 'ex:math:1p1'),
              ('URLs', 2, 'subsubsec:ex', 'subsubsec:ex'),
              ('LaTeX Mathematics', 1, None, 'latex-mathematics'),
              ('Exercises', 1, None, 'exercises'),
              ('Problem 2: Flip a Coin', 2, 'demo:ex:1', 'demo:ex:1'),
              ('My remarks', 3, None, 'my-remarks'),
              ('Remarks', 3, None, 'remarks'),
              ('Not an exercise', 2, None, 'not-an-exercise'),
              ('Exercise 3: Test of plain text exercise',
               2,
               'my:exer1',
               'my:exer1'),
              ('Project 4: Compute a Probability', 2, 'demo:ex:2', 'demo:ex:2'),
              ('Project 5: Explore Distributions of Random Circles',
               2,
               'proj:circle1',
               'proj:circle1'),
              ('Remarks', 3, None, 'remarks'),
              ('Exercise 6: Determine some Distance',
               2,
               'exer:dist',
               'exer:dist'),
              ('Remarks', 3, None, 'remarks'),
              ('Some exercise without the "Exercise:" prefix',
               2,
               None,
               'some-exercise-without-the-exercise-prefix'),
              ('Exercise 8: Solution of differential equation',
               2,
               'sec:this:exer:de',
               'sec:this:exer:de'),
              ('Example 9: Just an example',
               2,
               None,
               'example-9-just-an-example'),
              ('Here goes another section',
               1,
               None,
               'here-goes-another-section'),
              ('More Exercises', 1, None, 'more-exercises'),
              ('Exercise 10: Make references to projects and problems',
               2,
               'exer:some:formula',
               'exer:some:formula'),
              ('Project 11: References in a headings do not work well in html',
               2,
               'exer:you',
               'exer:you'),
              ('References', 1, None, 'references'),
              ('Appendix: Just for testing; part I', 1, 'app1', 'app1'),
              ('A subsection within an appendix',
               2,
               None,
               'a-subsection-within-an-appendix'),
              ('Appendix: Just for testing; part II', 1, 'app2', 'app2'),
              ('Appendix: Testing identical titles',
               2,
               None,
               'appendix-testing-identical-titles'),
              ('Appendix: Testing identical titles',
               2,
               'test:title:id1',
               'test:title:id1'),
              ('Appendix: Testing identical titles',
               2,
               'test:title:id2',
               'test:title:id2'),
              ('Appendix: Testing identical titles',
               2,
               None,
               'appendix-testing-identical-titles'),
              ('Appendix: Testing inline comments',
               2,
               None,
               'appendix-testing-inline-comments'),
              ('Appendix: Testing headings ending with `verbatim inline`',
               2,
               None,
               'appendix-testing-headings-ending-with-verbatim-inline')]}
end of tocinfo -->

<body>



<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  TeX: {
     equationNumbers: {  autoNumber: "none"  },
     extensions: ["AMSmath.js", "AMSsymbols.js", "autobold.js", "color.js"]
  }
});
</script>
<script type="text/javascript" async
 src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>



    
<a name="part0001"></a>
<!-- !split -->

<p>
The format of this document is
plain, homemade HTML (from DocOnce).

<p>
<b>Abstract.</b> This is a document with many test constructions for doconce syntax.
It was used heavily for the development and kept for testing
numerous constructions, also special and less common cases.

<p>
And exactly for test purposes we have an extra line here, which
is part of the abstract.

<p>
<!-- Cannot demonstrate chapter headings since abstract and chapter -->
<!-- are mutually exclusive in LaTeX -->

<h1 id="sec1">Section 1</h1>

<p>
Here is a nested list:

<p><table border="0">

  </tr><p><tr><td valign='top'><img src="https://hplgit.github.io/doconce/bundled/html_images/bullet_red2.png"></td><td> item1</li>
  </tr><p><tr><td valign='top'><img src="https://hplgit.github.io/doconce/bundled/html_images/bullet_red2.png"></td><td> item2</li>
  </tr><p><tr><td valign='top'><img src="https://hplgit.github.io/doconce/bundled/html_images/bullet_red2.png"></td><td> item3 which continues
    on the next line to test that feature</li>
  </tr><p><tr><td valign='top'><img src="https://hplgit.github.io/doconce/bundled/html_images/bullet_red2.png"></td><td> and a sublist</li>

<p><table border="0">

    </tr><p><tr><td valign='top'><img src="https://hplgit.github.io/doconce/bundled/html_images/bullet_green2.png"></td><td> with indented subitem1</li>
    </tr><p><tr><td valign='top'><img src="https://hplgit.github.io/doconce/bundled/html_images/bullet_green2.png"></td><td> and a subitem2</li>
</td></tr></table>


  </tr><p><tr><td valign='top'><img src="https://hplgit.github.io/doconce/bundled/html_images/bullet_red2.png"></td><td> and perhaps an ordered sublist

<ol type="a"></li>
   </tr><p><tr><td valign='top'><img src="https://hplgit.github.io/doconce/bundled/html_images/bullet_red2.png"></td><td> first item</li>
   </tr><p><tr><td valign='top'><img src="https://hplgit.github.io/doconce/bundled/html_images/bullet_red2.png"></td><td> second item,
      continuing on a new line</li>
</ol>

</td></tr></table>


<b>Here is a list with paragraph heading.</b>

<p><table border="0">

  </tr><p><tr><td valign='top'><img src="https://hplgit.github.io/doconce/bundled/html_images/bullet_red2.png"></td><td> item1</li>
  </tr><p><tr><td valign='top'><img src="https://hplgit.github.io/doconce/bundled/html_images/bullet_red2.png"></td><td> item2</li>
</td></tr></table>


<h3 id="here-is-a-list-with-subsubsection-heading">Here is a list with subsubsection heading </h3>

<p><table border="0">

  </tr><p><tr><td valign='top'><img src="https://hplgit.github.io/doconce/bundled/html_images/bullet_red2.png"></td><td> item1</li>
  </tr><p><tr><td valign='top'><img src="https://hplgit.github.io/doconce/bundled/html_images/bullet_red2.png"></td><td> item2</li>
</td></tr></table>


<blockquote>
    Here are two lines that make up
    a block quote for testing <em>emphasized words</em> and <b>boldface words</b>,
    also with hypens:
    <em>pre</em>-fix, post-<em>fix</em>, <b>pre</b>-fix, post-<b>fix</b>.
</blockquote>


<p>
Here are two references. Equation&nbsp;<a href="._testdoc002.html#mjx-eqn-12">(12)</a> is fine. Eq.&nbsp;<a href="._testdoc002.html#mjx-eqn-12">(12)</a> too.
Even Equation <a href="._testdoc002.html#mjx-eqn-12">(12)</a> without the tilde.
This equation appears in another part if this document is split.

<p>
Let us add a paragraph to
test that HTML,
with WordPress
(<code>--wordpress</code> option)
can handle linebreaks
<em>correctly</em>,
even when lines begin with
<b>bold words</b> and
<code>verbatim words</code> in
<font color="red">red color</font>, and
<a href="https://google.com" target="_self">links</a> as well as math:
\( 1+1=2 \).

<p>
Test also that <em>emphasize</em>
at the end of line, and <b>bold</b>
works, as well as <font color="blue">color</font>
and <a href="https://google.com" target="_self">links2</a>
and <code>verbatim</code>
as well.

<h2 id="subsec1">Subsection 1</h2>

<p>
<!-- Refer to section/appendix etc. at the beginning of the line -->
<!-- and other special fix situations for HTML. -->

<p>
More text, with a reference back to
the section <a href="#sec1">Section 1</a> and <a href="#subsec1">Subsection 1</a>, and further to the
the sections <a href="#subsec1">Subsection 1</a> and <a href="#subsubsec:ex">URLs</a>, which
encourages you to do the tasks in <a href="._testdoc002.html#demo:ex:1">Problem 2: Flip a Coin</a> and <a href="._testdoc002.html#exer:some:formula">Exercise 10: Make references to projects and problems</a>.
 <a href="._testdoc002.html#app1">Appendix: Just for testing; part I</a> and <a href="._testdoc002.html#app2">Appendix: Just for testing; part II</a> are also nice elements.

<h3 id="test-section-reference-at-beginning-of-line-and-after-a-sentence">Test Section reference at beginning of line and after a sentence </h3>

<p>
The section <a href="#subsec1">Subsection 1</a> is fine.
The section <a href="#subsubsec:ex">URLs</a> too.

<p>
<!-- sphinx code-blocks: pycod=python cod=fortran cppcod=c++ sys=console -->

<h3 id="computer-code">Computer code </h3>

<p>
Let's do some copying from files too. First from subroutine up to the very end,

<p>

<!-- code=fortran (!bc fcod) typeset with pygments style "perldoc" -->
<table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;"> 1</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;"> 2</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;"> 3</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;"> 4</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;"> 5</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;"> 6</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;"> 7</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;"> 8</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;"> 9</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">10</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">11</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">12</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">13</span></pre></div></td><td class="code"><div class="highlight" style="background: #eeeedd"><pre style="line-height: 125%;"><span></span>      <span style="color: #8B008B; font-weight: bold">subroutine </span>test()
      <span style="color: #00688B; font-weight: bold">integer </span>i
      <span style="color: #00688B; font-weight: bold">real</span>*<span style="color: #B452CD">8</span> r
      r = <span style="color: #B452CD">0</span>
      <span style="color: #8B008B; font-weight: bold">do </span>i = <span style="color: #B452CD">1</span>, i
         r = r + i
      <span style="color: #8B008B; font-weight: bold">end do</span>
<span style="color: #8B008B; font-weight: bold">      return</span>
C     END1

      <span style="color: #8B008B; font-weight: bold">program </span>testme
      <span style="color: #8B008B; font-weight: bold">call </span>test()
      <span style="color: #8B008B; font-weight: bold">return</span>
</pre></div>
</td></tr></table><p>
and then just the subroutine,
<p>

<!-- code=fortran (!bc fcod) typeset with pygments style "perldoc" -->
<table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">1</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">2</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">3</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">4</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">5</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">6</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">7</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">8</span></pre></div></td><td class="code"><div class="highlight" style="background: #eeeedd"><pre style="line-height: 125%;"><span></span>      <span style="color: #8B008B; font-weight: bold">subroutine </span>test()
      <span style="color: #00688B; font-weight: bold">integer </span>i
      <span style="color: #00688B; font-weight: bold">real</span>*<span style="color: #B452CD">8</span> r
      r = <span style="color: #B452CD">0</span>
      <span style="color: #8B008B; font-weight: bold">do </span>i = <span style="color: #B452CD">1</span>, i
         r = r + i
      <span style="color: #8B008B; font-weight: bold">end do</span>
<span style="color: #8B008B; font-weight: bold">      return</span>
</pre></div>
</td></tr></table><p>
and finally the complete file with a plain text verbatim environment
(<code>envir=ccq</code>):
<p>

<!-- code=text (!bc ccq) typeset with pygments style "perldoc" -->
<blockquote>
<table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;"> 1</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;"> 2</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;"> 3</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;"> 4</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;"> 5</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;"> 6</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;"> 7</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;"> 8</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;"> 9</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">10</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">11</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">12</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">13</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">14</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">15</span></pre></div></td><td class="code"><div class="highlight" style="background: #eeeedd"><pre style="line-height: 125%;"><span></span>C     a comment

      subroutine test()
      integer i
      real*8 r
      r = 0
      do i = 1, i
         r = r + i
      end do
      return
C     END1

      program testme
      call test()
      return
</pre></div>
</td></tr></table></blockquote><p>
Testing other code environments. First Python:

<p>

<!-- code=text typeset with pygments style "perldoc" -->
<table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">1</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">2</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">3</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">4</span></pre></div></td><td class="code"><div class="highlight" style="background: #eeeedd"><pre style="line-height: 125%;"><span></span>!bc pycod
def f(x):
    return x+1
!ec
</pre></div>
</td></tr></table><p>
which gets rendered as

<p>

<!-- code=python (!bc pycod) typeset with pygments style "perldoc" -->
<table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">1</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">2</span></pre></div></td><td class="code"><div class="highlight" style="background: #eeeedd"><pre style="line-height: 125%;"><span></span><span style="color: #8B008B; font-weight: bold">def</span> <span style="color: #008b45">f</span>(x):
    <span style="color: #8B008B; font-weight: bold">return</span> x+<span style="color: #B452CD">1</span>
</pre></div>
</td></tr></table><p>
Test paragraph and subsubsection headings before
before code.

<p>
<b>Paragraph heading before code.</b>

<p>

<!-- code=python (!bc pycod) typeset with pygments style "perldoc" -->
<table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">1</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">2</span></pre></div></td><td class="code"><div class="highlight" style="background: #eeeedd"><pre style="line-height: 125%;"><span></span><span style="color: #8B008B; font-weight: bold">import</span> <span style="color: #008b45; text-decoration: underline">sys</span>
sys.path.insert(<span style="color: #B452CD">0</span>, os.pardir)
</pre></div>
</td></tr></table><h3 id="subsubsection-heading-before-code">Subsubsection heading before code </h3>

<p>

<!-- code=python (!bc pycod) typeset with pygments style "perldoc" -->
<table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">1</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">2</span></pre></div></td><td class="code"><div class="highlight" style="background: #eeeedd"><pre style="line-height: 125%;"><span></span><span style="color: #8B008B; font-weight: bold">def</span> <span style="color: #008b45">h</span>(z):
    <span style="color: #8B008B; font-weight: bold">return</span> z+<span style="color: #B452CD">1</span>
</pre></div>
</td></tr></table><p>
Now a complete program to be shown via Python Online Tutorial:

<p>

<iframe width="950" height="500" frameborder="0"
        src="https://pythontutor.com/iframe-embed.html#code=class+Line%3A%0A++++def+__init__%28self%2C+a%2C+b%29%3A%0A++++++++self.a%2C+self.b+%3D+a%2C+b%0A%0A++++def+__call__%28self%2C+x%29%3A%0A++++++++a%2C+b+%3D+self.a%2C+self.b%0A++++++++return+a%2Ax+%2B+b%0A%0Aline+%3D+Line%282%2C+1%29%0Ay+%3D+line%28x%3D3%29%0Aprint%28y%29&py=2&curInstr=0&cumulative=false">
</iframe>
<p>
Some more Python code (actually specified as a sage cell, but
such cells are not supported by this format).

<p>


<div class="compute"><script type="text/x-sage">
a = 2
b = 3
print('a+b:', a + b)

# In a sage cell we can also plot
from matplotlib.pyplot import *
from numpy import *
x = linspace(0, 4*pi, 101)
y = exp(-0.1*x)*cos(x)
plot(x, y)
xlabel('x'); ylabel('y')
show()

</script></div>
<p>
Then Cython (with -h option so it is hidden in html/sphinx):

<p>

<!-- code=cython (!bc cycod-h) typeset with pygments style "perldoc" -->

<script type="text/javascript">
function show_hide_code9(){
  $("#code9").toggle();
}
</script>
<button type="button" onclick="show_hide_code9()">Show/hide code</button>
<div id="code9" style="display:none">
<table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">1</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">2</span></pre></div></td><td class="code"><div class="highlight" style="background: #eeeedd"><pre style="line-height: 125%;"><span></span><span style="color: #8B008B; font-weight: bold">cpdef</span> <span style="color: #008b45">f</span>(double x):
    <span style="color: #8B008B; font-weight: bold">return</span> x + <span style="color: #B452CD">1</span>
</pre></div>
</td></tr></table>
</div>
<p>
Standard Python shell sessions:

<p>

<!-- code=python (!bc pyshell) typeset with pygments style "perldoc" -->
<table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">1</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">2</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">3</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">4</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">5</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">6</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">7</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">8</span></pre></div></td><td class="code"><div class="highlight" style="background: #eeeedd"><pre style="line-height: 125%;"><span></span>&gt;&gt;&gt; <span style="color: #8B008B; font-weight: bold">from</span> <span style="color: #008b45; text-decoration: underline">numpy</span> <span style="color: #8B008B; font-weight: bold">import</span> linspace, sin
&gt;&gt;&gt; <span style="color: #228B22"># Some comment</span>
&gt;&gt;&gt; x = linspace(<span style="color: #B452CD">0</span>, <span style="color: #B452CD">2</span>, <span style="color: #B452CD">11</span>)
&gt;&gt;&gt; y = sin(x)
&gt;&gt;&gt; y[<span style="color: #B452CD">0</span>]
<span style="color: #B452CD">0</span>
&gt;&gt;&gt; <span style="color: #8B008B; font-weight: bold">import</span> <span style="color: #008b45; text-decoration: underline">matplotlib.pyplot</span> <span style="color: #8B008B; font-weight: bold">as</span> <span style="color: #008b45; text-decoration: underline">plt</span>
&gt;&gt;&gt; plt.plot(x, y)
</pre></div>
</td></tr></table><p>
Similar IPython sessions:

<p>

<!-- code=ipy (!bc ipy) typeset with pygments style "perldoc" -->
<table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;"> 1</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;"> 2</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;"> 3</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;"> 4</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;"> 5</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;"> 6</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;"> 7</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;"> 8</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;"> 9</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">10</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">11</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">12</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">13</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">14</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">15</span></pre></div></td><td class="code"><div class="highlight" style="background: #eeeedd"><pre style="line-height: 125%;"><span></span><span style="color: #555555">In [1]: </span><span style="color: #8B008B; font-weight: bold">from</span> <span style="color: #008b45; text-decoration: underline">numpy</span> <span style="color: #8B008B; font-weight: bold">import</span> linspace, sin
<span style="color: #555555">In [2]: </span><span style="color: #228B22"># Some comment</span>
<span style="color: #555555">In [3]: </span>x = linspace(<span style="color: #B452CD">0</span>, <span style="color: #B452CD">2</span>, <span style="color: #B452CD">11</span>)
<span style="color: #555555">In [4]: </span>y = sin(x)
<span style="color: #555555">In [5]: </span>y[<span style="color: #B452CD">0</span>]
<span style="color: #000080; font-weight: bold">Out[5]: </span><span style="color: #888888">0</span>
<span style="color: #555555">In [6]: </span><span style="color: #8B008B; font-weight: bold">import</span> <span style="color: #008b45; text-decoration: underline">matplotlib.pyplot</span> <span style="color: #8B008B; font-weight: bold">as</span> <span style="color: #008b45; text-decoration: underline">plt</span>
<span style="color: #555555">In [7]: </span>plt.plot(x, y)
<span style="color: #555555">In [8]: </span>a=<span style="color: #CD5555">&#39;multiple-\nline\noutput&#39;</span>
<span style="color: #555555">In [9]: </span>a
<span style="color: #000080; font-weight: bold">Out[9]: </span><span style="color: #888888">&#39;multiple-\nline\noutput&#39;</span>
<span style="color: #555555">In [10]: </span><span style="color: #658b00">print</span>(a)
<span style="color: #888888">multiple-</span>
<span style="color: #888888">line</span>
<span style="color: #888888">output</span>
</pre></div>
</td></tr></table><p>
Here is the interactive session again, but with <code>pyshell-t</code>.

<p>

<!-- code=python (!bc pyshell) typeset with pygments style "perldoc" -->
<table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">1</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">2</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">3</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">4</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">5</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">6</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">7</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">8</span></pre></div></td><td class="code"><div class="highlight" style="background: #eeeedd"><pre style="line-height: 125%;"><span></span>&gt;&gt;&gt; <span style="color: #8B008B; font-weight: bold">from</span> <span style="color: #008b45; text-decoration: underline">numpy</span> <span style="color: #8B008B; font-weight: bold">import</span> linspace, sin
&gt;&gt;&gt; <span style="color: #228B22"># Some comment</span>
&gt;&gt;&gt; x = linspace(<span style="color: #B452CD">0</span>, <span style="color: #B452CD">2</span>, <span style="color: #B452CD">11</span>)
&gt;&gt;&gt; y = sin(x)
&gt;&gt;&gt; y[<span style="color: #B452CD">0</span>]
<span style="color: #B452CD">0</span>
&gt;&gt;&gt; <span style="color: #8B008B; font-weight: bold">import</span> <span style="color: #008b45; text-decoration: underline">matplotlib.pyplot</span> <span style="color: #8B008B; font-weight: bold">as</span> <span style="color: #008b45; text-decoration: underline">plt</span>
&gt;&gt;&gt; plt.plot(x, y)
</pre></div>
</td></tr></table><p>
<!-- This one tests a + sign before a code environment -->
C++:
<p>

<!-- code=c++ (!bc cpppro) typeset with pygments style "perldoc" -->
<table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">1</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">2</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">3</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">4</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">5</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">6</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">7</span></pre></div></td><td class="code"><div class="highlight" style="background: #eeeedd"><pre style="line-height: 125%;"><span></span><span style="color: #1e889b">#include</span> <span style="color: #228B22">&lt;iostream&gt;</span><span style="color: #1e889b"></span>

<span style="color: #00688B; font-weight: bold">int</span> <span style="color: #008b45">main</span>()
{
   std::cout &lt;&lt; <span style="color: #CD5555">&quot;Sample output&quot;</span> &lt;&lt; std::endl;
   <span style="color: #8B008B; font-weight: bold">return</span> <span style="color: #B452CD">0</span>
}
</pre></div>
</td></tr></table><p>
<!-- The next should get correctly typset in sphinx (cod is fcod) -->
<!-- It also tests emoji before code -->
And a little bit of Fortran: <img src="https://raw.githubusercontent.com/hplgit/doconce/master/bundled/emoji/png/dizzy_face.png" width="22px" height="22px" align="center">

<p>

<!-- code=text typeset with pygments style "perldoc" -->
<table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">1</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">2</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">3</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">4</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">5</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">6</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">7</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">8</span></pre></div></td><td class="code"><div class="highlight" style="background: #eeeedd"><pre style="line-height: 125%;"><span></span>!bc cod
      subroutine midpt(x, length, a, b)
      real*8 a, b, x
      x = (a + b)/2
      length = b - a
      return
      end
!ec
</pre></div>
</td></tr></table><p>
which then is typeset as

<p>

<!-- code=text (!bc cod) typeset with pygments style "perldoc" -->
<table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">1</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">2</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">3</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">4</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">5</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">6</span></pre></div></td><td class="code"><div class="highlight" style="background: #eeeedd"><pre style="line-height: 125%;"><span></span>      subroutine midpt(x, length, a, b)
      real*8 a, b, x
      x = (a + b)/2
      length = b - a
      return
      end
</pre></div>
</td></tr></table><p>
HTML:

<p>

<!-- code=html (!bc htmlcod) typeset with pygments style "perldoc" -->
<table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">1</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">2</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">3</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">4</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">5</span></pre></div></td><td class="code"><div class="highlight" style="background: #eeeedd"><pre style="line-height: 125%;"><span></span>&lt;<span style="color: #8B008B; font-weight: bold">table</span>&gt;
&lt;<span style="color: #8B008B; font-weight: bold">tr</span>&gt;&lt;<span style="color: #8B008B; font-weight: bold">td</span>&gt;Column 1&lt;/<span style="color: #8B008B; font-weight: bold">td</span>&gt;&lt;<span style="color: #8B008B; font-weight: bold">td</span>&gt;Column 2&lt;/<span style="color: #8B008B; font-weight: bold">td</span>&gt;&lt;/<span style="color: #8B008B; font-weight: bold">tr</span>&gt;
&lt;<span style="color: #8B008B; font-weight: bold">tr</span>&gt;&lt;<span style="color: #8B008B; font-weight: bold">td</span>&gt;0.67526 &lt;/<span style="color: #8B008B; font-weight: bold">td</span>&gt;&lt;<span style="color: #8B008B; font-weight: bold">td</span>&gt;0.92871 &lt;/<span style="color: #8B008B; font-weight: bold">td</span>&gt;&lt;/<span style="color: #8B008B; font-weight: bold">tr</span>&gt;
<span style="color: #228B22">&lt;!-- comment --&gt;</span>
&lt;/<span style="color: #8B008B; font-weight: bold">table</span>&gt;
</pre></div>
</td></tr></table><p>
But inline HTML code is also important, like text that starts with
<code>&lt;a href=&quot;</code> (which can destroy the following text if not properly
quoted).

<p>
Matlab with comments requires special typesetting:

<p>

<!-- code=matlab (!bc mcod) typeset with pygments style "perldoc" -->
<table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">1</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">2</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">3</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">4</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">5</span></pre></div></td><td class="code"><div class="highlight" style="background: #eeeedd"><pre style="line-height: 125%;"><span></span><span style="color: #228B22">% Comment on the beginning of the line can be escaped by %%</span>
<span style="color: #8B008B; font-weight: bold">if</span> a &gt; b
  <span style="color: #228B22">% Indented comment needs this trick</span>
  c = a + b
<span style="color: #8B008B; font-weight: bold">end</span>
</pre></div>
</td></tr></table><p>
And here is a system call:

<p>

<!-- code=text (!bc sys) typeset with pygments style "perldoc" -->
<table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">1</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">2</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">3</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">4</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">5</span></pre></div></td><td class="code"><div class="highlight" style="background: #eeeedd"><pre style="line-height: 125%;"><span></span>Terminal&gt; mkdir test
Terminal&gt; cd test
Terminal&gt; myprog -f
output1
output2
</pre></div>
</td></tr></table><p>
Any valid pygments lexer/language name can appear to, e.g.,

<p>

<!-- code=text typeset with pygments style "perldoc" -->
<table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">1</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">2</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">3</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">4</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">5</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">6</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">7</span></pre></div></td><td class="code"><div class="highlight" style="background: #eeeedd"><pre style="line-height: 125%;"><span></span>!bc restructuredtext
=======
Heading
=======

Some text.
!ec
</pre></div>
</td></tr></table><p>
results in

<p>

<!-- code=restructuredtext (!bc restructuredtext) typeset with pygments style "perldoc" -->
<table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">1</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">2</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">3</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">4</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">5</span></pre></div></td><td class="code"><div class="highlight" style="background: #eeeedd"><pre style="line-height: 125%;"><span></span><span style="color: #000080; font-weight: bold">=======</span>
<span style="color: #000080; font-weight: bold">Heading</span>
<span style="color: #000080; font-weight: bold">=======</span>

Some text.
</pre></div>
</td></tr></table><p>
<!-- Here goes hidden code. -->
<!-- Python can be treated by some formats, Fortran is always out. -->

<p>
Finally, <code>!bc do</code> supports highlighting of DocOnce source:

<p>

<!-- code=doconce (!bc do) typeset with pygments style "perldoc" -->
<table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;"> 1</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;"> 2</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;"> 3</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;"> 4</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;"> 5</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;"> 6</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;"> 7</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;"> 8</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;"> 9</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">10</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">11</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">12</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">13</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">14</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">15</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">16</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">17</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">18</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">19</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">20</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">21</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">22</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">23</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">24</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">25</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">26</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">27</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">28</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">29</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">30</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">31</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">32</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">33</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">34</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">35</span></pre></div></td><td class="code"><div class="highlight" style="background: #eeeedd"><pre style="line-height: 125%;"><span></span><span style="color: #000080; font-weight: bold">======= DocOnce test file =======</span>

<span style="color: #000080; font-weight: bold">===== Computer code =====</span>

Inline verbatim code, as in `import numpy as np`, is allowed, as well as
code blocks:

!bc pycod
from math import sin

def f(x):
    &quot;&quot;&quot;Example on a function.&quot;&quot;&quot;
    return sin(x) + 1

print(f(0))
!ec


<span style="color: #000080; font-weight: bold">===== Mathematics =====</span>

Formulas can be inline, as in $\nabla\cdot\boldsymbol{u} = 0$, or typeset
as equations:

!bt
<span style="color: #658b00">\begin{align*}</span>
\nabla\cdot\boldsymbol{u} &amp;= 0,\\ 
\boldsymbol{u} &amp;= \nabla\phi .
<span style="color: #658b00">\end{align*}</span>
!et

<span style="color: #000080; font-weight: bold">=== Subsubsection heading ===</span>

DocOnce files can have chapters, sections, subsections, and subsubsections.

<span style="color: #800080; font-weight: bold">__Paragraph heading.__</span> Paragraphs may have headings.
</pre></div>
</td></tr></table><p>
It is time to test <code>verbatim inline font</code> especially with <code>a newline
inside the text</code> and an exclamation mark at the end: <code>BEGIN</code>! For
spellcheck, test <code>a verbatim expression</code> in <code>another</code> in a <code>third</code>.
Also test exclamation mark as in <code>!bc</code> and <code>!ec</code> as well as <code>a != b</code>.
Also test backslashes and braces like <code>\begin</code>, <code>\begin{enumerate}</code>,
<code>\end{this}\end{that}</code>, and <code>{something \inside braces}</code>.

<p>
Here is some <font color="red">red color</font> and an attempt to write <font color="green">with
green color containing a linebreak<br />
code.</font> Some formats will only display <br />
this correctly when <code>html</code> <br />
is the output format.
But here some more running text is added which is not part of
the previous blocks with line breaks.

<h3 id="running-os-commands">Running OS commands </h3>

<p>

<!-- code=text (!bc sys) typeset with pygments style "perldoc" -->
<table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">1</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">2</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">3</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">4</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">5</span></pre></div></td><td class="code"><div class="highlight" style="background: #eeeedd"><pre style="line-height: 125%;"><span></span>Terminal&gt; python -c &#39;print(&quot;Testing\noutput\nfrom\nPython.&quot;)&#39;
Testing
output
from
Python.
</pre></div>
</td></tr></table><h3 id="footnotes">Footnotes </h3>

<p>
Here is a test of footnotes [<a id="link_footnote_1" href="#def_footnote_1">1</a>], which are handy in text.
They are used in different flavors, now in

<p><table border="0">

 </tr><p><tr><td valign='top'><img src="https://hplgit.github.io/doconce/bundled/html_images/bullet_red2.png"></td><td> list items (note below that footnotes work after math, verbatim, and URLs - bin fact old and emphasize too!)</li>
 </tr><p><tr><td valign='top'><img src="https://hplgit.github.io/doconce/bundled/html_images/bullet_red2.png"></td><td> even with math \( \nabla^2u \) [<a id="link_footnote_2" href="#def_footnote_2">2</a>]</li>
 </tr><p><tr><td valign='top'><img src="https://hplgit.github.io/doconce/bundled/html_images/bullet_red2.png"></td><td> and code <code>h[i] += 1</code> [<a id="link_footnote_3" href="#def_footnote_3">3</a>]
   (<em>must</em> have space between inline code and footnote!)</li>
 </tr><p><tr><td valign='top'><img src="https://hplgit.github.io/doconce/bundled/html_images/bullet_red2.png"></td><td> and <a href="https://google.com" target="_self">links</a> [<a id="link_footnote_4" href="#def_footnote_4">4</a>]</li>
</td></tr></table>


which gives flexibility in writing.
This is the third [<a id="link_footnote_5" href="#def_footnote_5">5</a>] example.

<p id="def_footnote_1"><a href="#link_footnote_1"><b>1:</b></a> Typesetting of the footnote depends on the format.
Plain text does nothing, LaTeX removes the
definition and inserts the footnote as part of the LaTeX text.
reStructuredText and Sphinx employ a similar type of typesetting
as Extended Markdown and DocOnce, and in HTML we keep the same
syntax, just displayed properly in HTML.</p>

<p id="def_footnote_2"><a href="#link_footnote_2"><b>2:</b></a> Math footnotes can be dangerous since it
interferes with an exponent.</p>

<p id="def_footnote_3"><a href="#link_footnote_3"><b>3:</b></a> One-line footnote.</p>

<p id="def_footnote_4"><a href="#link_footnote_4"><b>4:</b></a> <a href="google.com" target="_self"><tt>google.com</tt></a> is perhaps the most famous
web site today.</p>

<p>
Here is some more text before a new definition of a footnote that was
used above.

<p>
<div class="alert alert-block alert-notice alert-text-normal">
<b>Non-breaking space character</b>
<p>
This paragraph aims to test <a href="https://en.wikipedia.org/wiki/Non-breaking_space" target="_self">non-breaking space character</a>, and a typical
example where this is needed is in physical units: 7.4&nbsp;km is traveled
in&nbsp;\( 7.4/5.5\approx 1.345 \)&nbsp;s.  Also check that a&nbsp;<a href="https://google.com" target="_self">link</a>&nbsp;is
not broken across lines (drag the browser window to test this).
(On the other hand, the tilde is used in
computer code, e.g., as in <code>[~x for x in y]</code> or in <code>y=~x</code>, and should
of course remain a tilde in those contexts.)
</div>


<h2 id="subsec:ex">Subsection 2: Testing figures</h2>

<p>
Test of figures. In particular we refer to Figure <a href="#fig:impact">1</a> in which
there is a flow.

<p>
<center> <!-- figure label: --> <div id="fig:impact"></div> <!-- FIGURE -->
<hr class="figure">
<center><p class="caption">Figure 1:  Visualization <b>of</b> a <em>wave</em>.  <!-- caption label: fig:impact --> </p></center>
<p><img src="../doc/src/manual/fig/wave1D.png" align="bottom" width=200></p>
</center>

<p>
Figures without captions are allowed and will be inlined.

<p>
<br /><br /><center><p><img src="../doc/src/manual/fig/wave1D.png" align="bottom" width=200></p></center><br /><br />

<p>
<!-- Test multi-line caption in figure with sidecap=True -->

<p>
Here is figure <a href="#myfig">2</a> with a long (illegal) multi-line caption
containing inline verbatim text:

<p>
<center> <!-- figure label: --> <div id="myfig"></div> <!-- FIGURE -->
<hr class="figure">
<table><tr>
<td><img src="../doc/src/manual/fig/wave1D.png" align="bottom" width=500></td>
<td><p class="caption">Figure 2:  A long caption spanning several lines and containing verbatim words like <code>my_file_v1</code> and <code>my_file_v2</code> as well as math with subscript as in \( t_{i+1} \).  <!-- caption label: myfig --> </p></td>
</tr></table>
</center>

<p>
<!-- Must be a blank line after MOVIE or FIGURE to detect this problem -->

<p>
Test URL as figure name:

<p>
<br /><br /><center><p><img src="https://raw.github.com/doconce/doconce/master/doc/src/blog/f_plot.png" align="bottom" width=500></p></center><br /><br />

<p>
Test SVG figure:

<p>
<br /><br /><center><p><img src="https://openclipart.org/people/jpneok/junebug.svg" align="bottom" width=200></p></center><br /><br />

<p>
<!-- Test wikimedia type of files that otherwise reside in subdirs -->

<p>
HTML output may feature Bokeh plots:

<p>
<br /><br /><center><p>
<!-- Bokeh plot -->
<script type="text/javascript">
            Bokeh.$(function() {
                var modelid = "dc6ef912-b325-4c34-996a-cdeb5aa4d7c1";
                var modeltype = "PlotContext";
                var elementid = "ffba6087-a45a-46eb-9368-11527f1f0a34";
                Bokeh.logger.info("Realizing plot:")
                Bokeh.logger.info(" - modeltype: PlotContext");
                Bokeh.logger.info(" - modelid: dc6ef912-b325-4c34-996a-cdeb5aa4d7c1");
                Bokeh.logger.info(" - elementid: ffba6087-a45a-46eb-9368-11527f1f0a34");
                var all_models = [{"attributes": {"line_color": {"value": "#1f77b4"}, "line_alpha": {"value": 1.0}, "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "y": {"field": "y"}, "x": {"field": "x"}, "id": "f55b6039-f6a1-48ce-be42-ce4e37ec18de"}, "type": "Line", "id": "f55b6039-f6a1-48ce-be42-ce4e37ec18de"}, {"attributes": {"tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "mantissas": [2, 5, 10], "id": "d8f3c08e-df44-47cd-ab00-9391128fc8ba", "num_minor_ticks": 5}, "type": "BasicTicker", "id": "d8f3c08e-df44-47cd-ab00-9391128fc8ba"}, {"attributes": {"column_names": ["x", "y"], "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "selected": {"2d": {"indices": []}, "1d": {"indices": []}, "0d": {"indices": [], "flag": false}}, "callback": null, "data": {"y": [0.0, 1.0, 8.0, 27.0], "x": [0.0, 1.0, 2.0, 3.0]}, "id": "51fd7aaa-934d-4dab-97d6-7be6eea30d89"}, "type": "ColumnDataSource", "id": "51fd7aaa-934d-4dab-97d6-7be6eea30d89"}, {"attributes": {"plot": {"subtype": "Figure", "type": "Plot", "id": "bac26888-fe18-4833-afe3-61e241eed748"}, "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "id": "8a41a3f3-b32f-4813-bc9d-78656dd129b0"}, "type": "ResizeTool", "id": "8a41a3f3-b32f-4813-bc9d-78656dd129b0"}, {"attributes": {"plot": {"subtype": "Figure", "type": "Plot", "id": "bac26888-fe18-4833-afe3-61e241eed748"}, "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "id": "734545fc-60c1-4271-bc10-b2b490266002"}, "type": "HelpTool", "id": "734545fc-60c1-4271-bc10-b2b490266002"}, {"attributes": {"names": [], "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "id": "294cc5ee-f95b-4023-8b38-eb845e408397", "renderers": []}, "type": "DataRange1d", "id": "294cc5ee-f95b-4023-8b38-eb845e408397"}, {"attributes": {"plot": {"subtype": "Figure", "type": "Plot", "id": "bac26888-fe18-4833-afe3-61e241eed748"}, "dimensions": ["width", "height"], "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "id": "26f46aa8-dc6f-4265-84dd-4525866c89d0"}, "type": "PanTool", "id": "26f46aa8-dc6f-4265-84dd-4525866c89d0"}, {"attributes": {"plot": {"subtype": "Figure", "type": "Plot", "id": "bac26888-fe18-4833-afe3-61e241eed748"}, "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "formatter": {"type": "BasicTickFormatter", "id": "a1aa95e9-9b48-4736-8854-fd7faf6b25ed"}, "ticker": {"type": "BasicTicker", "id": "71a73f31-ff56-477b-83da-62dfb4cb7d93"}, "id": "6980f350-9b3e-40f2-9ebb-d8a349a0207e"}, "type": "LinearAxis", "id": "6980f350-9b3e-40f2-9ebb-d8a349a0207e"}, {"attributes": {"plot": {"subtype": "Figure", "type": "Plot", "id": "bac26888-fe18-4833-afe3-61e241eed748"}, "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "id": "2de49bc5-9815-4275-a6de-e81ef1840cbe"}, "type": "ResetTool", "id": "2de49bc5-9815-4275-a6de-e81ef1840cbe"}, {"attributes": {"tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "mantissas": [2, 5, 10], "id": "71a73f31-ff56-477b-83da-62dfb4cb7d93", "num_minor_ticks": 5}, "type": "BasicTicker", "id": "71a73f31-ff56-477b-83da-62dfb4cb7d93"}, {"attributes": {"plot": {"subtype": "Figure", "type": "Plot", "id": "bac26888-fe18-4833-afe3-61e241eed748"}, "dimensions": ["width", "height"], "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "id": "d242820f-6005-4e2d-aaca-d2a19392726a"}, "type": "BoxZoomTool", "id": "d242820f-6005-4e2d-aaca-d2a19392726a"}, {"attributes": {"doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "id": "a1aa95e9-9b48-4736-8854-fd7faf6b25ed", "tags": []}, "type": "BasicTickFormatter", "id": "a1aa95e9-9b48-4736-8854-fd7faf6b25ed"}, {"subtype": "Figure", "type": "Plot", "id": "bac26888-fe18-4833-afe3-61e241eed748", "attributes": {"x_range": {"type": "DataRange1d", "id": "294cc5ee-f95b-4023-8b38-eb845e408397"}, "right": [], "tags": [], "tools": [{"type": "PanTool", "id": "26f46aa8-dc6f-4265-84dd-4525866c89d0"}, {"type": "WheelZoomTool", "id": "747f14a5-9f75-417c-8168-fb0a0ae3aa11"}, {"type": "BoxZoomTool", "id": "d242820f-6005-4e2d-aaca-d2a19392726a"}, {"type": "PreviewSaveTool", "id": "0c4a0cdc-08d4-4019-b03a-c03954d8f00a"}, {"type": "ResizeTool", "id": "8a41a3f3-b32f-4813-bc9d-78656dd129b0"}, {"type": "ResetTool", "id": "2de49bc5-9815-4275-a6de-e81ef1840cbe"}, {"type": "HelpTool", "id": "734545fc-60c1-4271-bc10-b2b490266002"}], "title": "Bokeh test", "extra_y_ranges": {}, "renderers": [{"type": "LinearAxis", "id": "6980f350-9b3e-40f2-9ebb-d8a349a0207e"}, {"type": "Grid", "id": "4765692c-4f39-462b-91c6-28b2f2981e00"}, {"type": "LinearAxis", "id": "ade0b05a-7b91-42dd-98de-74fb64acf6f7"}, {"type": "Grid", "id": "b9b421c8-77f3-4e7e-826b-ac6bf659b06a"}, {"type": "GlyphRenderer", "id": "2880ba24-eb39-4b26-b4fc-475578d6fd4c"}], "extra_x_ranges": {}, "below": [{"type": "LinearAxis", "id": "6980f350-9b3e-40f2-9ebb-d8a349a0207e"}], "tool_events": {"type": "ToolEvents", "id": "1695660e-4ea6-4d6d-9921-0d71ad942082"}, "above": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "y_range": {"type": "DataRange1d", "id": "c973a007-1e1b-45a1-a7ba-d05f16dfaad0"}, "id": "bac26888-fe18-4833-afe3-61e241eed748", "left": [{"type": "LinearAxis", "id": "ade0b05a-7b91-42dd-98de-74fb64acf6f7"}]}}, {"attributes": {"names": [], "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "id": "c973a007-1e1b-45a1-a7ba-d05f16dfaad0", "renderers": []}, "type": "DataRange1d", "id": "c973a007-1e1b-45a1-a7ba-d05f16dfaad0"}, {"attributes": {"tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "id": "dc6ef912-b325-4c34-996a-cdeb5aa4d7c1", "children": [{"subtype": "Figure", "type": "Plot", "id": "bac26888-fe18-4833-afe3-61e241eed748"}]}, "type": "PlotContext", "id": "dc6ef912-b325-4c34-996a-cdeb5aa4d7c1"}, {"attributes": {"line_color": {"value": "#1f77b4"}, "line_alpha": {"value": 0.1}, "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "y": {"field": "y"}, "x": {"field": "x"}, "id": "af17e0b1-cd09-4529-b97b-aefe6bff3ee2"}, "type": "Line", "id": "af17e0b1-cd09-4529-b97b-aefe6bff3ee2"}, {"attributes": {"plot": {"subtype": "Figure", "type": "Plot", "id": "bac26888-fe18-4833-afe3-61e241eed748"}, "dimensions": ["width", "height"], "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "id": "747f14a5-9f75-417c-8168-fb0a0ae3aa11"}, "type": "WheelZoomTool", "id": "747f14a5-9f75-417c-8168-fb0a0ae3aa11"}, {"attributes": {"plot": {"subtype": "Figure", "type": "Plot", "id": "bac26888-fe18-4833-afe3-61e241eed748"}, "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "formatter": {"type": "BasicTickFormatter", "id": "e6be9566-7576-4bac-a09f-bf95a818d7f8"}, "ticker": {"type": "BasicTicker", "id": "d8f3c08e-df44-47cd-ab00-9391128fc8ba"}, "id": "ade0b05a-7b91-42dd-98de-74fb64acf6f7"}, "type": "LinearAxis", "id": "ade0b05a-7b91-42dd-98de-74fb64acf6f7"}, {"attributes": {"plot": {"subtype": "Figure", "type": "Plot", "id": "bac26888-fe18-4833-afe3-61e241eed748"}, "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "dimension": 1, "ticker": {"type": "BasicTicker", "id": "d8f3c08e-df44-47cd-ab00-9391128fc8ba"}, "id": "b9b421c8-77f3-4e7e-826b-ac6bf659b06a"}, "type": "Grid", "id": "b9b421c8-77f3-4e7e-826b-ac6bf659b06a"}, {"attributes": {"nonselection_glyph": {"type": "Line", "id": "af17e0b1-cd09-4529-b97b-aefe6bff3ee2"}, "data_source": {"type": "ColumnDataSource", "id": "51fd7aaa-934d-4dab-97d6-7be6eea30d89"}, "name": null, "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "selection_glyph": null, "id": "2880ba24-eb39-4b26-b4fc-475578d6fd4c", "glyph": {"type": "Line", "id": "f55b6039-f6a1-48ce-be42-ce4e37ec18de"}}, "type": "GlyphRenderer", "id": "2880ba24-eb39-4b26-b4fc-475578d6fd4c"}, {"attributes": {"plot": {"subtype": "Figure", "type": "Plot", "id": "bac26888-fe18-4833-afe3-61e241eed748"}, "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "dimension": 0, "ticker": {"type": "BasicTicker", "id": "71a73f31-ff56-477b-83da-62dfb4cb7d93"}, "id": "4765692c-4f39-462b-91c6-28b2f2981e00"}, "type": "Grid", "id": "4765692c-4f39-462b-91c6-28b2f2981e00"}, {"attributes": {"plot": {"subtype": "Figure", "type": "Plot", "id": "bac26888-fe18-4833-afe3-61e241eed748"}, "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "id": "0c4a0cdc-08d4-4019-b03a-c03954d8f00a"}, "type": "PreviewSaveTool", "id": "0c4a0cdc-08d4-4019-b03a-c03954d8f00a"}, {"attributes": {"geometries": [], "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "id": "1695660e-4ea6-4d6d-9921-0d71ad942082"}, "type": "ToolEvents", "id": "1695660e-4ea6-4d6d-9921-0d71ad942082"}, {"attributes": {"doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "id": "e6be9566-7576-4bac-a09f-bf95a818d7f8", "tags": []}, "type": "BasicTickFormatter", "id": "e6be9566-7576-4bac-a09f-bf95a818d7f8"}];
                Bokeh.load_models(all_models);
                var model = Bokeh.Collections(modeltype).get(modelid);
                var view = new model.default_view({model: model, el: '#ffba6087-a45a-46eb-9368-11527f1f0a34'});
                Bokeh.index[modelid] = view
            });
        </script>
<div class="plotdiv" id="ffba6087-a45a-46eb-9368-11527f1f0a34"></div></p></center><br /><br />

<p>
<b>Remark.</b>
Movies are tested in separate file <code>movies.do.txt</code>.

<p>
<!-- Somewhat challenging heading with latex math, \t, \n, ? and parenthesis -->

<h2 id="decay:sec:theta">The \( \theta \) parameter (not \( \nabla \)?)</h2>

<p>
Functions do not always need to be advanced, here is one
involving \( \theta \):
<p>

<!-- code=text typeset with pygments style "perldoc" -->
<table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">1</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">2</span></pre></div></td><td class="code"><div class="highlight" style="background: #eeeedd"><pre style="line-height: 125%;"><span></span>def f(theta):
    return theta**2
</pre></div>
</td></tr></table><p>
<b>More on \( \theta \).</b>
Here is more text following headline with math.

<p>
Newcommands must also be tested in this test report:
\( \frac{1}{2} \), \( {1/2} \), \( \pmb{x} \), \( \frac{Du}{dt} \),
both inline and in block:

$$
\begin{align}
\frac{Du}{dt} &= 0\nonumber
\\ 
\frac{1}{2} &= {1/2}
\tag{1}\\ 
\frac{1}{2}\pmb{x} &= \pmb{n}
\tag{2}
\end{align}
$$

<p>
Or with align with label and numbers:

$$
\begin{align}
\frac{Du}{dt} &= 0
\tag{3}
\\ 
\frac{1}{2} &= {1/2}
\tag{4}\\ 
\frac{1}{2}\pmb{x} &= \pmb{n}
\tag{5}
\end{align}
$$

<p>
<!-- Must test more complicated align and matrix compositions -->
<!-- where DocOnce inserts auto-numbered labels etc. -->

<p>
First one numbered (automatically):

$$
\begin{align}
\begin{pmatrix}
G_2 + G_3 & -G_3 & -G_2 & 0 \\ 
-G_3 & G_3 + G_4 & 0 & -G_4 \\ 
-G_2 & 0 & G_1 + G_2 & 0 \\ 
0 & -G_4 & 0 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
 v_1 \\ 
 v_2 \\ 
 v_3 \\ 
 v_4
\end{pmatrix}
+ \cdots  \tag{6}
\\ 
\begin{pmatrix}
 C_5 + C_6 & -C_6 & 0 & 0 \\ 
 -C_6 & C_6 & 0 & 0 \\ 
 0 & 0 & 0 & 0 \\ 
 0 & 0 & 0 & 0
\end{pmatrix}
  &= \frac{d}{dt}\begin{pmatrix}
 v_1 \\ 
 v_2 \\ 
 v_3 \\ 
 v_4
\end{pmatrix} +
\begin{pmatrix}
 0 \\ 
 0 \\ 
 0 \\ 
 -i_0
\end{pmatrix}
\nonumber
\tag{7}
\end{align}$$

<p>
Second numbered (automatically):

$$
\begin{align}
\begin{pmatrix}
G_1 + G_2\\ 
-G_3 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
 v_1 \\ 
 v_2
\end{pmatrix}
+ \cdots\nonumber
\tag{8}
\\ 
\left(\begin{array}{ll}
y & 2\\ 
2 & 1
\end{array}\right)
\left(\begin{array}{ll}
0 \\ x
\end{array}\right)
&= \begin{pmatrix}
A \\ B
\end{pmatrix}
\tag{9}
\end{align}$$

<p>
Both numbered, with label by the user:

$$
\begin{align}
\begin{pmatrix}
G_1 + G_2\\ 
-G_3 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
 v_1 \\ 
 v_2
\end{pmatrix}
+ \cdots \tag{10}
\\ 
\tag{11}
\left(\begin{array}{ll}
y & 2\\ 
2 & 1
\end{array}\right)
\left(\begin{array}{ll}
0 \\ x
\end{array}\right)
&= \begin{pmatrix}
A \\ B
\end{pmatrix}
\end{align}$$

Now we refer to <a href="#mjx-eqn-10">(10)</a>-<a href="#mjx-eqn-11">(11)</a>.

<h2 id="custom-environments">Custom Environments </h2>

<p>
Here is an attempt to create a theorem environment via Mako
(for counting theorems) and comment lines to help replacing lines in
the <code>.tex</code> by proper begin-end LaTeX environments for theorems.
Should look nice in most formats!

<p>
<!-- begin theorem -->
<div id="theorem:fundamental1"></div>

<p>
<b>Theorem 5.</b>
Let \( a=1 \) and \( b=2 \). Then \( c=3 \).
<!-- end theorem -->

<p>
<!-- begin proof -->
<b>Proof.</b>
Since \( c=a+b \), the result follows from straightforward addition.
\( \Diamond \)
<!-- end proof -->

<p>
As we see, the proof of Theorem 5 is a modest
achievement.

<h2 id="subsec:table">Tables</h2>

<p>
<!-- index with comma could fool sphinx -->

<p>
Let us take this table from the manual:

<p>
<table border="1">
<thead>
<tr><th align="center">time</th> <th align="center">velocity</th> <th align="center">acceleration</th> </tr>
</thead>
<tbody>
<tr><td align="left">   0.0     </td> <td align="right">   1.4186      </td> <td align="right">   -5.01           </td> </tr>
<tr><td align="left">   2.0     </td> <td align="right">   1.376512    </td> <td align="right">   11.919          </td> </tr>
<tr><td align="left">   4.0     </td> <td align="right">   1.1E+1      </td> <td align="right">   14.717624       </td> </tr>
</tbody>
</table>
<p>
The DocOnce source code reads
<p>

<!-- code=text (!bc ccq) typeset with pygments style "perldoc" -->
<blockquote>
<table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">1</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">2</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">3</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">4</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">5</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">6</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">7</span></pre></div></td><td class="code"><div class="highlight" style="background: #eeeedd"><pre style="line-height: 125%;"><span></span>  |--------------------------------|
  |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>
</td></tr></table></blockquote><p>
Here is yet another table to test that we can handle more than
one table:

<p>
<table border="1">
<thead>
<tr><th align="left">time</th> <th align="left">velocity</th> <th align="left">acceleration</th> </tr>
</thead>
<tbody>
<tr><td align="left">   0.0     </td> <td align="left">   1.4186      </td> <td align="left">   -5.01           </td> </tr>
<tr><td align="left">   1.0     </td> <td align="left">   1.376512    </td> <td align="left">   11.919          </td> </tr>
<tr><td align="left">   3.0     </td> <td align="left">   1.1E+1      </td> <td align="left">   14.717624       </td> </tr>
</tbody>
</table>
<p>
And one with math headings (that are expanded and must be treated
accordingly), verbatim heading and entry, and no space around the pipe
symbol:

<p>
<table border="1">
<thead>
<tr><td align="center">\( i \)</td> <td align="center">\( h_i \)</td> <td align="center">\( \bar T_i \)</td> <td align="center"><code>L_i</code></td> </tr>
</thead>
<tbody>
<tr><td align="left">   0          </td> <td align="right">   0            </td> <td align="right">   288               </td> <td align="right">   -0.0065             </td> </tr>
<tr><td align="left">   1          </td> <td align="right">   11,000       </td> <td align="right">   216               </td> <td align="right">   0.0                 </td> </tr>
<tr><td align="left">   2          </td> <td align="right">   20,000       </td> <td align="right">   216               </td> <td align="right">   0.001               </td> </tr>
<tr><td align="left">   3          </td> <td align="right">   32,000       </td> <td align="right">   228               </td> <td align="right">   0.0028              </td> </tr>
<tr><td align="left">   4          </td> <td align="right">   47,000       </td> <td align="right">   270               </td> <td align="right">   0.0                 </td> </tr>
<tr><td align="left">   5          </td> <td align="right">   51,000       </td> <td align="right">   270               </td> <td align="right">   -0.0028             </td> </tr>
<tr><td align="left">   6          </td> <td align="right">   71,000       </td> <td align="right">   214               </td> <td align="right">   <code>NaN</code>    </td> </tr>
</tbody>
</table>
<p>
And add one with verbatim headings (with underscores),
and rows starting with <code>|-</code> because of a negative number,
and <code>|</code> right before and after verbatim word (with no space):

<p>
<table border="1">
<thead>
<tr><th align="center">exact</th> <td align="center"><code>v_1</code></td> <td align="center">\( a_i \) + <code>v_2</code></td> <td align="center"><code>verb_3_</code></td> </tr>
</thead>
<tbody>
<tr><td align="right">   9        </td> <td align="right">   9.62                </td> <td align="right">   5.57                            </td> <td align="right">   8.98                    </td> </tr>
<tr><td align="right">   -20      </td> <td align="right">   -23.39              </td> <td align="right">   -7.65                           </td> <td align="right">   -19.93                  </td> </tr>
<tr><td align="right">   10       </td> <td align="right">   17.74               </td> <td align="right">   -4.50                           </td> <td align="right">   9.96                    </td> </tr>
<tr><td align="right">   0        </td> <td align="right">   -9.19               </td> <td align="right">   4.13                            </td> <td align="right">   -0.26                   </td> </tr>
</tbody>
</table>
<p>
Pipe symbols in verbatim and math text in tables used to pose difficulties,
but not
anymore:

<p>
<table border="1">
<thead>
<tr><td align="center">   \( S \)   </td> <th align="center">        command         </th> </tr>
</thead>
<tbody>
<tr><td align="left">   $ ||a_0|| $      </td> <td align="right">   <code>norm|length</code>    </td> </tr>
<tr><td align="left">   \( x\cap y \)    </td> <td align="right">   <code>x|y</code>            </td> </tr>
</tbody>
</table>
<p>
Here is a table with X alignment:

<p>
<table border="1">
<thead>
<tr><th align="center"> Type</th> <th align="center">                                                                                                                Description                                                                                                                 </th> </tr>
</thead>
<tbody>
<tr><td align="center">   X        </td> <td align="left">   Alignment character that is used for specifying a potentially very long text in a column in a table. It makes use of the <code>tabularx</code> package in LaTeX, otherwise (for other formats) it means <code>l</code> (centered alignment).    </td> </tr>
<tr><td align="center">   l,r,c    </td> <td align="left">   standard alignment characters                                                                                                                                                                                                                   </td> </tr>
</tbody>
</table>
<p>
Finally, a table with math
(<code>bm</code> that expands to <code>boldsymbol</code>, was tricky, but
cleanly handled now)
and URLs.

<p>
<!-- Mako code to expand URLs in the table -->
<!-- (These types of tables did not work before Jan 2014) -->

<p>
<table border="1">
<tr></tr>
<tbody>
<tr><td align="center">   \( \mathcal{L}=0 \)                    </td> <td align="center">   <a href="../doc/src/manual/mov/wave_frames/frame_0080.png"><img src="../doc/src/manual/mov/wave_frames/frame_0080.png" width="300"></a>    </td> <td align="center">   <a href="../doc/src/manual/mov/wave_frames/frame_0085.png"><img src="../doc/src/manual/mov/wave_frames/frame_0085.png" width="300"></a>    </td> </tr>
<tr><td align="center">   \( a=b \)                              </td> <td align="center">   <a href="../doc/src/manual/mov/wave_frames/frame_0090.png"><img src="../doc/src/manual/mov/wave_frames/frame_0090.png" width="300"></a>    </td> <td align="center">   <a href="../doc/src/manual/mov/wave_frames/frame_0095.png"><img src="../doc/src/manual/mov/wave_frames/frame_0095.png" width="300"></a>    </td> </tr>
<tr><td align="center">   \( \nabla\cdot\boldsymbol{u} =0  \)    </td> <td align="center">   <a href="../doc/src/manual/mov/wave_frames/frame_0100.png"><img src="../doc/src/manual/mov/wave_frames/frame_0100.png" width="300"></a>    </td> <td align="center">   <a href="../doc/src/manual/mov/wave_frames/frame_0105.png"><img src="../doc/src/manual/mov/wave_frames/frame_0105.png" width="300"></a>    </td> </tr>
</tbody>
</table>

<h2 id="a-test-of-verbatim-words-in-heading-with-subscript-a_i-my_file_v1-and-my_file_v2">A test of verbatim words in heading with subscript \( a_i \): <code>my_file_v1</code> and <code>my_file_v2</code> </h2>

<p>
<b>Paragraph with verbatim and math: <code>my_file_v1.py</code> and <code>my_file_v2.py</code> define some math \( a_{i-1} \).</b>
Here is more <code>__verbatim__</code> code and
some plain text on a new line.

<p>
<!-- Test various types of headlines -->

<h2 id="_just-bold_"><b>Just bold</b> </h2>

<p>
Some text.

<h2 id="just-emphasize"><em>Just emphasize</em> </h2>

<p>
Some text.

<h2 id="just-verbatim"><code>Just verbatim</code> </h2>

<p>
Some text.

<h2 id="_bold_-beginning"><b>Bold</b> beginning </h2>

<p>
Some text.

<h2 id="emphasize-beginning"><em>Emphasize</em> beginning </h2>

<p>
Some text.

<h2 id="verbatim-beginning"><code>Verbatim</code> beginning </h2>

<p>
Some text.

<h2 id="maybe-_bold-end_">Maybe <b>bold end</b> </h2>

<p>
Some text.

<h2 id="maybe-emphasize-end">Maybe <em>emphasize end</em> </h2>

<p>
Some text.

<h2 id="maybe-verbatim-end">Maybe <code>verbatim end</code> </h2>

<p>
Some text.

<h2 id="the-middle-has-<b>bold</b>-word">The middle has <b>bold</b> word </h2>

<p>
Some text.

<h2 id="the-middle-has-emphasize-word">The middle has <em>emphasize</em> word </h2>

<p>
Some text.

<h2 id="the-middle-has-verbatim-word">The middle has <code>verbatim</code> word </h2>

<p>
Some text.

<p>
<b><em>Just emphasize</em>.</b>
Some text.

<p>
<b><code>Just verbatim</code>.</b>
Some text.

<p>
<b><em>Emphasize</em> beginning.</b>
Some text.

<p>
<b><code>Verbatim beginning</code>.</b>
Some text.

<p>
<b>Maybe <em>emphasize end</em>.</b>
Some text.

<p>
<b>Maybe <code>verbatim end</code>.</b>
Some text.

<p>
<b>The middle has <em>emphasize</em> word.</b>
Some text.

<p>
<b>The middle has <code>verbatim</code> word.</b>
Some text.

<p>
<b>Ampersand.</b>
We can test Hennes &amp; Mauritz, often abbreviated H&amp;M, but written
as <code>Hennes & Mauritz</code> and <code>H & M</code>.
A sole <code>&</code> must also work.
<!-- Note: substitutions must not occur inside verbatim, just in ordinary text. -->

<p>

<!-- code=text typeset with pygments style "perldoc" -->
<table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">1</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">2</span></pre></div></td><td class="code"><div class="highlight" style="background: #eeeedd"><pre style="line-height: 125%;"><span></span># Just to check that ampersand works in code blocks:
c = a &amp; b
</pre></div>
</td></tr></table><p>
<b>Quotes.</b>
Let us also add a test of quotes such as &quot;double quotes, with numbers
like 3.14 and newline/comma and hyphen (as in double-quote)&quot;; written
in the standard LaTeX-style that gives correct LaTeX formatting and
ordinary double quotes for all non-LaTeX formats.  Here is another
sentence that &quot;caused&quot; a bug in the past because double backtick
quotes could imply verbatim text up to a verbatim word starting with
period, like <code>.txt</code>.

<p>
More quotes to be tested for spellcheck:
(&quot;with parenthesis&quot;), &quot;with newline&quot;
and &quot;with comma&quot;, &quot;hyphen&quot;-wise, and &quot;period&quot;.

<h2 id="bibliography-test">Bibliography test </h2>

<p>
Here is an example: <a href="._testdoc002.html#Langtangen_Pedersen_2002">[1]</a> discussed propagation of
large destructive water waves, <a href="._testdoc002.html#Langtangen_et_al_2002">[2]</a> gave
an overview of numerical methods for solving the Navier&ndash;Stokes equations,
while the use of Backward Kolmogorov equations for analyzing
random vibrations was investigated in <a href="._testdoc002.html#Langtangen_1994a">[3]</a>.
The book chapter <a href="._testdoc002.html#Mardal_et_al_2003a">[4]</a> contains information on
C++ software tools for programming multigrid methods. A real retro
reference is <a href="._testdoc002.html#Langtangen_1988d">[5]</a> about a big FORTRAN package.
Multiple references are also possible, e.g., see
<a href="._testdoc002.html#Langtangen_Pedersen_2002">[1]</a> <a href="._testdoc002.html#Mardal_et_al_2003a">[4]</a>.

<p>
We need to cite more than 10 papers to reproduce an old formatting
problem with blanks in the keys in reST format:
<a href="._testdoc002.html#Langtangen_1992c">[6]</a> <a href="._testdoc002.html#Langtangen_1994a">[3]</a> <a href="._testdoc002.html#Mortensen_et_al_2011">[7]</a> <a href="._testdoc002.html#Langtangen_Pedersen_2002">[1]</a>
and
<a href="._testdoc002.html#Langtangen_et_al_2002">[2]</a> <a href="._testdoc002.html#Glimsdal_et_al_20006">[8]</a> <a href="._testdoc002.html#Rahman_et_al_2006b">[9]</a> <a href="._testdoc002.html#Haga_et_al_2011a">[10]</a> <a href="._testdoc002.html#Langtangen_2003a">[11]</a> <a href="._testdoc002.html#Langtangen_2008a">[12]</a> <a href="._testdoc002.html#Langtangen:95">[13]</a>
and all the work of
<a href="._testdoc002.html#Langtangen_2012">[14]</a> <a href="._testdoc002.html#Mardal_et_al_2003a">[4]</a> <a href="._testdoc002.html#Jeberg_et_al_2004">[15]</a> as well as
old work <a href="._testdoc002.html#Langtangen_1988d">[5]</a> and <a href="._testdoc002.html#Langtangen_1989e">[16]</a>, and the
talk <a href="._testdoc002.html#Langtangen_talk_2007a">[17]</a>.
Langtangen also had two thesis <a href="._testdoc002.html#Langtangen:85">[18]</a> <a href="._testdoc002.html#Langtangen_1989e">[16]</a>
back in the days.
More retro citations are
the old ME-IN323 book <a href="._testdoc002.html#Langtangen:91">[19]</a> and the
<a href="._testdoc002.html#Langtangen:94b">[20]</a> OONSKI '94 paper.

<p>
<!-- --- begin exercise --- -->

<h2 id="Example">Example 1: Examples can be typeset as exercises</h2>

<p>
Examples can start with a subsection heading starting with <code>Example:</code>
and then, with the command-line option <code>--examples_as_exercises</code> be
typeset as exercises. This is useful if one has solution
environments as part of the example.

<p>
<b>a)</b>
State some problem.

<p>
<b>Solution.</b>
The answer to this subproblem can be written here.

<p>
<b>b)</b>
State some other problem.

<p>
<b>Hint 1.</b>
A hint can be given.

<p>
<b>Hint 2.</b>
Maybe even another hint?

<p>
<b>Solution.</b>
The answer to this other subproblem goes here,
maybe over multiple doconce input lines.

<p>
<!-- --- end exercise --- -->

<h2 id="user-defined-environments">User-defined environments </h2>

<p>
The example in the section <a href="#ex:test:1p1">Example 1: A test function</a> demonstrates how to write a test function.
That is, a special test function for a function <code>add</code> appears in
the example in the section <a href="#ex:test:1p1">Example 1: A test function</a>.

<h2 id="ex:test:1p1">Example 1: A test function</h2>

<p>
Suppose we want to write a test function for checking the
implementation of a Python function for addition.

<p>

<!-- code=python (!bc pycod) typeset with pygments style "perldoc" -->
<table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">1</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">2</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">3</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">4</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">5</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">6</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">7</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">8</span></pre></div></td><td class="code"><div class="highlight" style="background: #eeeedd"><pre style="line-height: 125%;"><span></span><span style="color: #8B008B; font-weight: bold">def</span> <span style="color: #008b45">add</span>(a, b):
    <span style="color: #8B008B; font-weight: bold">return</span> a + b

<span style="color: #8B008B; font-weight: bold">def</span> <span style="color: #008b45">test_add</span>():
    a = <span style="color: #B452CD">1</span>; b = <span style="color: #B452CD">1</span>
    expected = a + b
    computed = add(a, b)
    <span style="color: #8B008B; font-weight: bold">assert</span> expected == computed
</pre></div>
</td></tr></table><h2 id="ex:math:1p1">Example 2: Addition</h2>

<p>
We have

$$ 1 + 1 = 2 $$

or in tabular form:

<p>
<table border="1">
<thead>
<tr><th align="center"> Problem </th> <th align="center"> Result</th> </tr>
</thead>
<tbody>
<tr><td align="center">   \( 1+1 \)    </td> <td align="center">   \( 2 \)    </td> </tr>
</tbody>
</table>
<p>
<div style="width: 60%; padding: 10px; border: 1px solid #000;
 border-radius: 4px; box-shadow: 8px 8px 5px #888888;
 background: #cce5ff;">
 <b>Highlight box!</b><hr>
This environment is used to highlight something:

$$ E = mc^2 $$

</div>

<h2 id="subsubsec:ex">URLs</h2>

<p>
Testing of URLs: hpl's home page <a href="https://folk.uio.no/hpl" target="_self">hpl</a>, or
the entire URL if desired, <a href="https://folk.uio.no/hpl" target="_self"><tt>https://folk.uio.no/hpl</tt></a>.  Here is a
plain file link <a href="testdoc.do.txt" target="_self"><tt>testdoc.do.txt</tt></a>, or <a href="testdoc.do.txt" target="_self"><tt>testdoc.do.txt</tt></a>, or
<a href="testdoc.do.txt" target="_self"><tt>testdoc.do.txt</tt></a> or <a href="testdoc.do.txt" target="_self"><tt>testdoc.do.txt</tt></a> or <a href="testdoc.do.txt" target="_self">a link with
newline</a>. Can test spaces with the link with word
too: <a href="https://folk.uio.no/hpl" target="_self">hpl</a> or <a href="https://folk.uio.no/hpl" target="_self">hpl</a>. Also <code>file:///</code> works: <a href="file:///home/hpl/vc/doconce/doc/demos/manual/manual.html" target="_self">link to a
file</a> is
fine to have. Moreover, &quot;loose&quot; URLs work, i.e., no quotes, just
the plain URL as in <a href="https://folk.uio.no/hpl" target="_self"><tt>https://folk.uio.no/hpl</tt></a>, if followed by space, comma,
colon, semi-colon, question mark, exclamation mark, but not a period
(which gets confused with the periods inside the URL).

<p>
Mail addresses can also be used: <a href="mailto:hpl@simula.no" target="_self"><tt>hpl@simula.no</tt></a>, or just a <a href="mailto:hpl@simula.no" target="_self">mail link</a>, or a raw <a href="mailto:hpl@simula.no" target="_self"><tt>mailto:hpl@simula.no</tt></a>.

<p>
Here are some tough tests of URLs, especially for the <code>latex</code> format:
<a href="https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas" target="_self">Newton-Cotes</a> formulas
and a <a href="https://www.springer.com/mathematics/computational+science+%26+engineering/book/978-3-642-23098-1" target="_self">good book</a>. Need to test
Newton-Cotes with percentage in URL too:
<a href="https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas" target="_self"><tt>https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas</tt></a>
and <a href="https://en.wikipedia.org/wiki/Newton-Cotes#Open_Newton.E2.80.93Cotes_formulae" target="_self"><tt>https://en.wikipedia.org/wiki/Newton-Cotes#Open_Newton.E2.80.93Cotes_formulae</tt></a> which has a shebang.

<p>
For the <code>--device=paper</code> option it is important to test that URLs with
monospace font link text get a footnote
(unless the <code>--latex_no_program_footnotelink</code>
is used), as in this reference to
<a href="https://github.com/hplgit/INF5620/tree/gh-pages/src/decay/experiments/decay_mod.py" target="_self"><tt>decay_mod</tt></a>, <a href="https://tinyurl.com/pwyasaa/formulas.ball1.py" target="_self"><tt>ball1.py</tt></a>,
and <a href="https://tinyurl.com/pwyasaa/formulas.ball2.py" target="_self"><tt>ball2.py</tt></a>.

<p>
<!-- Comments should be inserted outside paragraphs (because in the rst -->
<!-- format extra blanks make a paragraph break). -->

<p>
<!-- Note that when there is no https: or file:, it can be a file link -->
<!-- if the link name is URL, url, "URL", or "url". Such files should, -->
<!-- if rst output is desired, but placed in a <code>_static*</code> folder. -->

<p>
More tough tests: repeated URLs whose footnotes when using the
<code>--device=paper</code> option must be correct. We have
<a href="https://google.com" target="_self">google</a>, <a href="https://google.com" target="_self">google</a>, and
<a href="https://google.com" target="_self">google</a>, which should result in exactly three
footnotes.

<p>
<p>
<!-- begin bottom navigation -->
<table style="width: 100%"><tr><td>
\
<div style="text-align: left;"><a href="._testdoc000.html"><img src="https://hplgit.github.io/doconce/bundled/html_images/prev2.png" border=0 alt="&laquo; Previous"></a></div>
</td><td>
\
<div style="text-align: right;"><a href="._testdoc002.html"><img src="https://hplgit.github.io/doconce/bundled/html_images/next2.png" border=0 alt="Next &raquo;"></a></div>
</td></tr></table>
<!-- end bottom navigation -->
</p>

<!-- ------------------- end of main content --------------- -->

<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.js"></script>


</body>
</html>

************** File: ._testdoc002.html *****************
<!--
Automatically generated HTML file from DocOnce source
(https://github.com/doconce/doconce/)
-->
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="DocOnce: https://github.com/doconce/doconce/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="description" content="A Document for Testing DocOnce">
<meta name="keywords" content="figures,movies,index with subindex,_boldface word_ in index,index with _boldface word_,index with _boldface word_ in subentry,double _boldface word_  _boldface word_ in subentry too,index, with comma, and one more">

<title>A Document for Testing DocOnce</title>


<link href="https://raw.github.com/doconce/doconce/master/bundled/html_styles/style_solarized_box/css/solarized_light_code.css" rel="stylesheet" type="text/css" title="light"/>
<script src="https://raw.github.com/doconce/doconce/master/bundled/html_styles/style_solarized_box/js/highlight.pack.js"></script>
<script>hljs.initHighlightingOnLoad();</script>

<style type="text/css">
body, td {font-size: 140%;}
h1 {font-size: 200%;}
h2 {font-size: 180%;}

/* solarized style */
body {
  margin:5;
  padding:0;
  border:0; /* Remove the border around the viewport in old versions of IE */
  width:100%;
  background: #fdf6e3;
  min-width:600px;	/* Minimum width of layout - remove if not required */
  font-family: Verdana, Helvetica, Arial, sans-serif;
  font-size: 1.0em;
  line-height: 1.3em;
  color: #657b83;
}
a { color: #859900; text-decoration: underline; }
a:hover, a:active { outline:none }
a, a:active, a:visited { color: #859900; }
a:hover { color: #268bd2; }
h1, h2, h3 { margin:.8em 0 .2em 0; padding:0; line-height: 125%; }
h2 { font-variant: small-caps; }
tt, code { font-family: monospace, sans-serif; box-shadow: none; }
hr { border: 0; width: 80%; border-bottom: 1px solid #aaa; }
p { text-indent: 0px; }
p.caption { width: 80%; font-style: normal; text-align: left; }
hr.figure { border: 0; width: 80%; border-bottom: 1px solid #aaa; }
.alert-text-small   { font-size: 80%;  }
.alert-text-large   { font-size: 130%; }
.alert-text-normal  { font-size: 90%;  }
.alert {
  padding:8px 35px 8px 14px; margin-bottom:18px;
  text-shadow:0 1px 0 rgba(255,255,255,0.5);
  border:1px solid #93a1a1;
  border-radius: 4px;
  -webkit-border-radius: 4px;
  -moz-border-radius: 4px;
  color: #555;
  background-color: #eee8d5;
  background-position: 10px 5px;
  background-repeat: no-repeat;
  background-size: 38px;
  padding-left: 55px;
  width: 75%;
 }
.alert-block {padding-top:14px; padding-bottom:14px}
.alert-block > p, .alert-block > ul {margin-bottom:1em}
.alert li {margin-top: 1em}
.alert-block p+p {margin-top:5px}
.alert-notice { background-image: url(https://raw.github.com/doconce/doconce/master/bundled/html_images/small_yellow_notice.png); }
.alert-summary  { background-image:url(https://raw.github.com/doconce/doconce/master/bundled/html_images/small_yellow_summary.png); }
.alert-warning { background-image: url(https://raw.github.com/doconce/doconce/master/bundled/html_images/small_yellow_warning.png); }
.alert-question {background-image:url(https://raw.github.com/doconce/doconce/master/bundled/html_images/small_yellow_question.png); }

div { text-align: justify; text-justify: inter-word; }
</style>


<script src="https://sagecell.sagemath.org/static/jquery.min.js"></script>
<script src="https://sagecell.sagemath.org/embedded_sagecell.js"></script>
<link rel="stylesheet" type="text/css" href="https://sagecell.sagemath.org/static/sagecell_embed.css">
<script>
$(function () {
    // Make the div with id 'mycell' a Sage cell
    sagecell.makeSagecell({inputLocation:  '#mycell',
                           template:       sagecell.templates.minimal,
                           evalButtonText: 'Activate'});
    // Make *any* div with class 'compute' a Sage cell
    sagecell.makeSagecell({inputLocation: 'div.compute',
                           evalButtonText: 'Evaluate'});
});
</script>




<!-- Tools for embedded Bokeh plots -->
<link rel="stylesheet"
      href="https://cdn.pydata.org/bokeh/release/bokeh-0.9.0.min.css"
      type="text/css" />
<script type="text/javascript"
	src="https://cdn.pydata.org/bokeh/release/bokeh-0.9.0.min.js">
</script>
<script type="text/javascript">
  Bokeh.set_log_level("info");
</script>


</head>

<!-- tocinfo
{'highest level': 1,
 'sections': [('Table of contents',
               1,
               'table_of_contents',
               'table_of_contents'),
              ('Section 1', 1, 'sec1', 'sec1'),
              ('Here is a list with subsubsection heading',
               3,
               None,
               'here-is-a-list-with-subsubsection-heading'),
              ('Subsection 1', 2, 'subsec1', 'subsec1'),
              ('Test Section reference at beginning of line and after a '
               'sentence',
               3,
               None,
               'test-section-reference-at-beginning-of-line-and-after-a-sentence'),
              ('Computer code', 3, None, 'computer-code'),
              ('Subsubsection heading before code',
               3,
               None,
               'subsubsection-heading-before-code'),
              ('Running OS commands', 3, None, 'running-os-commands'),
              ('Footnotes', 3, None, 'footnotes'),
              ('Subsection 2: Testing figures', 2, 'subsec:ex', 'subsec:ex'),
              ('The $\\theta$ parameter (not $\\nabla$?)',
               2,
               'decay:sec:theta',
               'decay:sec:theta'),
              ('Custom Environments', 2, None, 'custom-environments'),
              ('Tables', 2, 'subsec:table', 'subsec:table'),
              ('A test of verbatim words in heading with subscript $a_i$: '
               '`my_file_v1` and `my_file_v2`',
               2,
               None,
               'a-test-of-verbatim-words-in-heading-with-subscript-a_i-my_file_v1-and-my_file_v2'),
              ('_Just bold_', 2, None, '_just-bold_'),
              ('*Just emphasize*', 2, None, 'just-emphasize'),
              ('`Just verbatim`', 2, None, 'just-verbatim'),
              ('_Bold_ beginning', 2, None, '_bold_-beginning'),
              ('*Emphasize* beginning', 2, None, 'emphasize-beginning'),
              ('`Verbatim` beginning', 2, None, 'verbatim-beginning'),
              ('Maybe _bold end_', 2, None, 'maybe-_bold-end_'),
              ('Maybe *emphasize end*', 2, None, 'maybe-emphasize-end'),
              ('Maybe `verbatim end`', 2, None, 'maybe-verbatim-end'),
              ('The middle has _bold_ word',
               2,
               None,
               'the-middle-has-_bold_-word'),
              ('The middle has *emphasize* word',
               2,
               None,
               'the-middle-has-emphasize-word'),
              ('The middle has `verbatim` word',
               2,
               None,
               'the-middle-has-verbatim-word'),
              ('Bibliography test', 2, None, 'bibliography-test'),
              ('Example 1: Examples can be typeset as exercises',
               2,
               'Example',
               'Example'),
              ('User-defined environments',
               2,
               None,
               'user-defined-environments'),
              ('Example 1: A test function', 2, 'ex:test:1p1', 'ex:test:1p1'),
              ('Example 2: Addition', 2, 'ex:math:1p1', 'ex:math:1p1'),
              ('URLs', 2, 'subsubsec:ex', 'subsubsec:ex'),
              ('LaTeX Mathematics', 1, None, 'latex-mathematics'),
              ('Exercises', 1, None, 'exercises'),
              ('Problem 2: Flip a Coin', 2, 'demo:ex:1', 'demo:ex:1'),
              ('My remarks', 3, None, 'my-remarks'),
              ('Remarks', 3, None, 'remarks'),
              ('Not an exercise', 2, None, 'not-an-exercise'),
              ('Exercise 3: Test of plain text exercise',
               2,
               'my:exer1',
               'my:exer1'),
              ('Project 4: Compute a Probability', 2, 'demo:ex:2', 'demo:ex:2'),
              ('Project 5: Explore Distributions of Random Circles',
               2,
               'proj:circle1',
               'proj:circle1'),
              ('Remarks', 3, None, 'remarks'),
              ('Exercise 6: Determine some Distance',
               2,
               'exer:dist',
               'exer:dist'),
              ('Remarks', 3, None, 'remarks'),
              ('Some exercise without the "Exercise:" prefix',
               2,
               None,
               'some-exercise-without-the-exercise-prefix'),
              ('Exercise 8: Solution of differential equation',
               2,
               'sec:this:exer:de',
               'sec:this:exer:de'),
              ('Example 9: Just an example',
               2,
               None,
               'example-9-just-an-example'),
              ('Here goes another section',
               1,
               None,
               'here-goes-another-section'),
              ('More Exercises', 1, None, 'more-exercises'),
              ('Exercise 10: Make references to projects and problems',
               2,
               'exer:some:formula',
               'exer:some:formula'),
              ('Project 11: References in a headings do not work well in html',
               2,
               'exer:you',
               'exer:you'),
              ('References', 1, None, 'references'),
              ('Appendix: Just for testing; part I', 1, 'app1', 'app1'),
              ('A subsection within an appendix',
               2,
               None,
               'a-subsection-within-an-appendix'),
              ('Appendix: Just for testing; part II', 1, 'app2', 'app2'),
              ('Appendix: Testing identical titles',
               2,
               None,
               'appendix-testing-identical-titles'),
              ('Appendix: Testing identical titles',
               2,
               'test:title:id1',
               'test:title:id1'),
              ('Appendix: Testing identical titles',
               2,
               'test:title:id2',
               'test:title:id2'),
              ('Appendix: Testing identical titles',
               2,
               None,
               'appendix-testing-identical-titles'),
              ('Appendix: Testing inline comments',
               2,
               None,
               'appendix-testing-inline-comments'),
              ('Appendix: Testing headings ending with `verbatim inline`',
               2,
               None,
               'appendix-testing-headings-ending-with-verbatim-inline')]}
end of tocinfo -->

<body>



<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  TeX: {
     equationNumbers: {  autoNumber: "none"  },
     extensions: ["AMSmath.js", "AMSsymbols.js", "autobold.js", "color.js"]
  }
});
</script>
<script type="text/javascript" async
 src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>



    
<a name="part0002"></a>
<!-- !split and check if these extra words are included properly in the comment -->

<h1 id="latex-mathematics">LaTeX Mathematics </h1>

<p>
Here is an equation without label using backslash-bracket environment:
$$ a = b + c $$

<p>
or with number and label, as in <a href="#mjx-eqn-12">(12)</a>, using the equation environment:

$$
\begin{equation}
{\partial u\over\partial t} = \nabla^2 u \tag{12}
\end{equation}
$$

<p>
We can refer to this equation by <a href="#mjx-eqn-12">(12)</a>.

<p>
Here is a system without equation numbers, using the align-asterisk environment:

$$
\begin{align*}
\pmb{a} &= \pmb{q}\times\pmb{n} \\ 
b &= \nabla^2 u + \nabla^4 v
\end{align*}
$$

<p>
And here is a system of equations with labels in an align environment:

$$
\begin{align}
a &= q + 4 + 5+ 6 \tag{13} \\ 
b &= \nabla^2 u + \nabla^4 x \tag{14}
\end{align}

$$

We can refer to <a href="#mjx-eqn-13">(13)</a>-<a href="#mjx-eqn-14">(14)</a>. They are a bit simpler than
the Navier&ndash;Stokes equations. And test LaTeX hyphen in <code>CG-2</code>.
Also test \( a_{i-j} \) as well as \( kx-wt \).

<p>
Testing <code>alignat</code> environment:

$$
\begin{alignat}{2}
a &= q + 4 + 5+ 6\qquad & \mbox{for } q\geq 0 \tag{15} \\ 
b &= \nabla^2 u + \nabla^4 x & x\in\Omega \tag{16}
\end{alignat}
$$

<p>
More mathematical typesetting is demonstrated in the coming exercises.

<p>
Below, we have <a href="#demo:ex:1">Problem 2: Flip a Coin</a> and <a href="#demo:ex:2">Project 4: Compute a Probability</a>,
as well as <a href="#proj:circle1">Project 5: Explore Distributions of Random Circles</a> and <a href="#exer:you">Project 11: References in a headings do not work well in html</a>, and in
between there we have <a href="#exer:some:formula">Exercise 10: Make references to projects and problems</a>.

<h1 id="exercises">Exercises </h1>

<p>
<!-- --- begin exercise --- -->

<h2 id="demo:ex:1">Problem 2: Flip a Coin</h2>
<!-- keywords = random numbers; Monte Carlo simulation; ipynb -->

<p>
<!-- Torture tests -->

<p>
<b>a)</b>
Make a program that simulates flipping a coin \( N \) times.
Print out &quot;tail&quot; or &quot;head&quot; for each flip and
let the program count the number of heads.

<p>
<!-- --- begin hint in exercise --- -->

<p>
<b>Hint 1.</b>
Use <code>r = random.random()</code> and define head as <code>r &lt;= 0.5</code>.

<p>
<!-- --- end hint in exercise --- -->

<p>
<!-- --- begin hint in exercise --- -->

<p>
<b>Hint 2.</b>
Draw an integer among \( \{1,2\} \) with
<code>r = random.randint(1,2)</code> and define head when <code>r</code> is 1.

<p>
<!-- --- end hint in exercise --- -->

<p>
<!-- --- begin answer of exercise --- -->
<b>Answer.</b>
If the <code>random.random()</code> function returns a number \( < 1/2 \), let it be
head, otherwise tail. Repeat this \( N \) number of times.
<!-- --- end answer of exercise --- -->

<p>

<p>
<b>b)</b>
Vectorize the code in a) using boolean indexing.

<p>
Vectorized code can be written in many ways.
Sometimes the code is less intuitive, sometimes not.
At least there is not much to find in the section <a href="._testdoc001.html#sec1">Section 1</a>.

<p>
<b>c)</b>
Vectorize the code in a) using <code>numpy.sum</code>.

<p>
<!-- --- begin answer of exercise --- -->
<b>Answer.</b>
<code>np.sum(np.where(r &lt;= 0.5, 1, 0))</code> or <code>np.sum(r &lt;= 0.5)</code>.
<!-- --- end answer of exercise --- -->

<p>
In this latter subexercise, we have an
example where the code is easy to read.

<h3 id="my-remarks">My remarks </h3>

<p>
Remarks with such a subsubsection is treated as more text
after the last subexercise. Test a list too:

<ol>
</tr><p><tr><td valign='top'><img src="https://hplgit.github.io/doconce/bundled/html_images/bullet_red2.png"></td><td> Mark 1.</li>
</tr><p><tr><td valign='top'><img src="https://hplgit.github.io/doconce/bundled/html_images/bullet_red2.png"></td><td> Mark 2.</li>
</ol>

Filenames: <code>flip_coin.py</code>, <code>flip_coin.pdf</code>.

<p>
<!-- Closing remarks for this Problem -->

<h3 id="remarks">Remarks </h3>

<p>
These are the exercise remarks, appearing at the very end.

<p>
<!-- solution files: mysol.txt, mysol_flip_coin.py, yet_another.file -->

<p>
<!-- --- end exercise --- -->

<h2 id="not-an-exercise">Not an exercise </h2>

<p>
Should be possible to stick a normal section in the middle of many
exercises.

<p>
<!-- --- begin exercise --- -->

<h2 id="my:exer1">Exercise 3: Test of plain text exercise</h2>

<p>
Very short exercise. What is the capital
of Norway?
Filename: <code>myexer1</code>.

<p>
<!-- --- end exercise --- -->

<p>
<!-- --- begin exercise --- -->

<h2 id="demo:ex:2">Project 4: Compute a Probability</h2>

<p>
<!-- Minimalistic exercise -->

<p>
What is the probability of getting a number between 0.5 and 0.6 when
drawing uniformly distributed random numbers from the interval \( [0,1) \)?

<p>
At the end we have a list because that caused problems in LaTeX
in previous DocOnce versions:

<ol>
</tr><p><tr><td valign='top'><img src="https://hplgit.github.io/doconce/bundled/html_images/bullet_red2.png"></td><td> item1</li>
</tr><p><tr><td valign='top'><img src="https://hplgit.github.io/doconce/bundled/html_images/bullet_red2.png"></td><td> item2</li>
</ol>

<!-- --- begin hint in exercise --- -->

<p>
<b>Hint.</b>
To answer this question empirically, let a program
draw \( N \) such random numbers using Python's standard <code>random</code> module,
count how many of them, \( M \), that fall in the interval \( (0.5,0.6) \), and
compute the probability as \( M/N \).

<p>
<!-- --- end hint in exercise --- -->

<p>
<!-- --- end exercise --- -->

<p>
<!-- --- begin exercise --- -->

<h2 id="proj:circle1">Project 5: Explore Distributions of Random Circles</h2>
<!-- keywords = ipynb -->

<p>
The formula for a circle is given by

$$
\begin{align}
x &= x_0 + R\cos 2\pi t,
\tag{17}\\ 
y &= y_0 + R\sin 2\pi t,
\tag{18}
\end{align}
$$

where \( R \) is the radius of the circle, \( (x_0,y_0) \) is the
center point, and \( t \) is a parameter in the unit interval \( [0,1] \).
For any \( t \), \( (x,y) \) computed from <a href="#mjx-eqn-17">(17)</a>-<a href="#mjx-eqn-18">(18)</a>
is a point on the circle.
The formula can be used to generate <code>n</code> points on a circle:

<p>

<!-- code=python (!bc pypro) typeset with pygments style "perldoc" -->
<table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">1</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">2</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">3</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">4</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">5</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">6</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">7</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">8</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">9</span></pre></div></td><td class="code"><div class="highlight" style="background: #eeeedd"><pre style="line-height: 125%;"><span></span><span style="color: #8B008B; font-weight: bold">import</span> <span style="color: #008b45; text-decoration: underline">numpy</span> <span style="color: #8B008B; font-weight: bold">as</span> <span style="color: #008b45; text-decoration: underline">np</span>

<span style="color: #8B008B; font-weight: bold">def</span> <span style="color: #008b45">circle</span>(R, x0, y0, n=<span style="color: #B452CD">501</span>):
    t = np.linspace(<span style="color: #B452CD">0</span>, <span style="color: #B452CD">1</span>, n)
    x = x0 + R*np.cos(<span style="color: #B452CD">2</span>*np.pi*t)
    y = y0 + R*np.sin(<span style="color: #B452CD">2</span>*np.pi*t)
    <span style="color: #8B008B; font-weight: bold">return</span> x, y

x, y = circle(<span style="color: #B452CD">2.0</span>, <span style="color: #B452CD">0</span>, <span style="color: #B452CD">0</span>)
</pre></div>
</td></tr></table><p>
<!-- Often in an exercise we have some comments about the solution -->
<!-- which we normally want to keep where they are. -->

<p>
The goal of this project is to draw \( N \) circles with random
center and radius. Plot each circle using the <code>circle</code> function
above.

<p>
<b>a)</b>
Let \( R \) be normally distributed and \( (x_0,y_0) \) uniformly distributed.

<p>
<!-- --- begin hint in exercise --- -->

<p>
<b>Hint.</b>
Use the <code>numpy.random</code> module to draw the
\( x_0 \), \( y_0 \), and \( R \) quantities.

<p>
<!-- --- end hint in exercise --- -->

<p>
<!-- --- begin answer of exercise --- -->
<b>Answer.</b>
Here goes the short answer to part a).
<!-- --- end answer of exercise --- -->

<p>

<p>
<b>b)</b>
Let \( R \) be uniformly distributed and \( (x_0,y_0) \) normally distributed.
Filename: <code>norm</code>.

<p>
<b>c)</b>
Let \( R \) and \( (x_0,y_0) \) be normally distributed.

<p>
Filename: <code>circles</code>.

<p>
<!-- Closing remarks for this Project -->

<h3 id="remarks">Remarks </h3>

<p>
At the very end of the exercise it may be appropriate to summarize
and give some perspectives.

<p>
<!-- --- end exercise --- -->

<p>
<!-- --- begin exercise --- -->

<h2 id="exer:dist">Exercise 6: Determine some Distance</h2>

<p>
Intro to this exercise. Questions are in subexercises below.

<p>

<p>
<b>a)</b>
Subexercises are numbered a), b), etc.

<p>
<!-- --- begin hint in exercise --- -->

<p>
<b>Hint 1.</b>
First hint to subexercise a).
With math \( a=b \) in hint:

$$ a=b. $$

And with code (in plain verbatim) returning \( x+1 \) in hint:

<p>

<!-- code=text typeset with pygments style "perldoc" -->
<table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">1</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">2</span></pre></div></td><td class="code"><div class="highlight" style="background: #eeeedd"><pre style="line-height: 125%;"><span></span>def func(x):
    return x + 1  # with code in hint
</pre></div>
</td></tr></table><p>
<!-- --- end hint in exercise --- -->

<p>
<!-- --- begin hint in exercise --- -->

<p>
<b>Hint 2.</b>
Second hint to subexercise a).

<p>
Test list in hint:

<ol>
</tr><p><tr><td valign='top'><img src="https://hplgit.github.io/doconce/bundled/html_images/bullet_red2.png"></td><td> item1</li>
</tr><p><tr><td valign='top'><img src="https://hplgit.github.io/doconce/bundled/html_images/bullet_red2.png"></td><td> item2</li>
</ol>

<!-- --- end hint in exercise --- -->
Filename: <code>subexer_a.pdf</code>.

<p>
<!-- --- begin answer of exercise --- -->
<b>Answer.</b>
Short answer to subexercise a).
With math in answer: \( a=b \).
<!-- --- end answer of exercise --- -->

<p>
<b>b)</b>
Here goes the text for subexercise b).

<p>
Some math \( \cos^2 x + \sin^2 x = 1 \) written one a single line:

$$ \cos^2 x + \sin^2 x = 1 \thinspace .$$

<p>
<!-- --- begin hint in exercise --- -->

<p>
<b>Hint.</b>
A hint for this subexercise.

<p>
<!-- --- end hint in exercise --- -->
Filename: <code>subexer_b.pdf</code>.

<p>

<p>
<!-- No meaning in this weired test example: -->
The text here belongs to the main (intro) part of the exercise. Need
closing remarks to have text after subexercises.

<p>
Test list in exercise:

<ol>
</tr><p><tr><td valign='top'><img src="https://hplgit.github.io/doconce/bundled/html_images/bullet_red2.png"></td><td> item1</li>
</tr><p><tr><td valign='top'><img src="https://hplgit.github.io/doconce/bundled/html_images/bullet_red2.png"></td><td> item2
<!-- Closing remarks for this Exercise --></li>
</ol>

<h3 id="remarks">Remarks </h3>

<p>
Some final closing remarks, e.g., summarizing the main findings
and their implications in other problems can be made. These
remarks will appear at the end of the typeset exercise.

<p>
<!-- --- end exercise --- -->

<p>
<!-- --- begin exercise --- -->

<h2 id="some-exercise-without-the-exercise-prefix">Some exercise without the "Exercise:" prefix </h2>

<p>
<!-- Another minimalistic exercise -->

<p>
Just some text. And some math saying that \( e^0=1 \) on a single line,
to test that math block insertion is correct:

$$ \exp{(0)} = 1 $$

<p>
And a test that the code <code>lambda x: x+2</code> is correctly placed here:

<p>

<!-- code=text typeset with pygments style "perldoc" -->
<table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">1</span></pre></div></td><td class="code"><div class="highlight" style="background: #eeeedd"><pre style="line-height: 125%;"><span></span>lambda x: x+2
</pre></div>
</td></tr></table><p>
<!-- Have some comments at the end of the exercise to see that -->
<!-- the Filename: ... is written correctly. -->
<!-- --- end exercise --- -->

<p>
<!-- --- begin exercise --- -->

<h2 id="sec:this:exer:de">Exercise 8: Solution of differential equation</h2>

<p>
<!-- begin quiz -->
Given

$$ \frac{dy}{dx} = -y(x),\quad y(0)=1 $$

What is the solution of this equation?</p>

<p><div title="Right! "><b>Choice A:</b>
\( y=e^{-y} \)
</div></p>

<p><div title="Wrong! Almost, but the sign is wrong (note the minus!)."><b>Choice B:</b>
\( y=e^{y} \)
</div></p>

<p><div title="Wrong! "><b>Choice C:</b>
<p>

<!-- code=python (!bc pycod) typeset with pygments style "perldoc" -->
<table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">1</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">2</span>
<span style="color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px;">3</span></pre></div></td><td class="code"><div class="highlight" style="background: #eeeedd"><pre style="line-height: 125%;"><span></span><span style="color: #8B008B; font-weight: bold">from</span> <span style="color: #008b45; text-decoration: underline">math</span> <span style="color: #8B008B; font-weight: bold">import</span> exp
<span style="color: #8B008B; font-weight: bold">def</span> <span style="color: #008b45">f</span>(x):
    <span style="color: #8B008B; font-weight: bold">return</span> exp(x)
</pre></div>
</td></tr></table><p>
</div></p>

<p><div title="Wrong! Equations with derivatives can be solved; they are termed  differential equations ."><b>Choice D:</b>
The solution cannot be found because there is a derivative in the equation.
</div></p>

<p><div title="Wrong! Equations where the unknown is a function, as \( y(x) \) here, are called  differential equations , and are solved by special techniques."><b>Choice E:</b>
The equation is meaningless: an equation must be an equation
for \( x \) or \( y \), not a function \( y(x) \).
</div></p>
<hr>
<!-- end quiz -->


<p>
<!-- --- end exercise --- -->

<p>
<!-- --- begin exercise --- -->

<h2 id="example-9-just-an-example">Example 9: Just an example </h2>

<p>
<!-- This example needs the --examples_as_exercises option, otherwise -->
<!-- it is just typeset as it is written. -->

<p>
<b>a)</b>
What is the capital of Norway?

<p>
<b>Answer.</b>
Oslo.

<p>
<!-- --- end exercise --- -->

<h1 id="here-goes-another-section">Here goes another section </h1>

<p>
With some text, before we continue with exercises.

<h1 id="more-exercises">More Exercises </h1>

<p>
<!-- --- begin exercise --- -->

<h2 id="exer:some:formula">Exercise 10: Make references to projects and problems</h2>

<p>
<!-- Test comments not at the end only -->
Pick a statement from <a href="#proj:circle1">Project 5: Explore Distributions of Random Circles</a> or <a href="#demo:ex:1">Problem 2: Flip a Coin</a>
and verify it.

<p>
Test list at the end of an exercise without other elements (like subexercise,
hint, etc.):

<ol>
</tr><p><tr><td valign='top'><img src="https://hplgit.github.io/doconce/bundled/html_images/bullet_red2.png"></td><td> item1</li>
</tr><p><tr><td valign='top'><img src="https://hplgit.github.io/doconce/bundled/html_images/bullet_red2.png"></td><td> item2</li>
</ol>

Filename: <code>verify_formula.py</code>.

<p>
<!-- --- end exercise --- -->

<p>
<!-- --- begin exercise --- -->

<h2 id="exer:you">Project 11: References in a headings do not work well in html</h2>

<p>
Refer to the previous exercise as <a href="#exer:some:formula">Exercise 10: Make references to projects and problems</a>,
the two before that as <a href="#demo:ex:2">Project 4: Compute a Probability</a> and <a href="#proj:circle1">Project 5: Explore Distributions of Random Circles</a>,
and this one as <a href="#exer:you">Project 11: References in a headings do not work well in html</a>.
Filename: <code>selc_composed.pdf</code>.

<p>
<!-- --- end exercise --- -->

<h1 id="references">References </h1>

<p>
<!-- begin bibliography -->

<ol>
 </tr><p><tr><td valign='top'><img src="https://hplgit.github.io/doconce/bundled/html_images/bullet_red2.png"></td><td> <div id="Langtangen_Pedersen_2002"></div> <b>H. P. Langtangen and G. Pedersen</b>. 
    Propagation of Large Destructive Waves,
    <em>International Journal of Applied Mechanics and Engineering</em>,
    7(1),
    pp. 187-204,
    2002.</li>
 </tr><p><tr><td valign='top'><img src="https://hplgit.github.io/doconce/bundled/html_images/bullet_red2.png"></td><td> <div id="Langtangen_et_al_2002"></div> <b>H. P. Langtangen, K.-A. Mardal and R. Winther</b>. 
    Numerical Methods for Incompressible Viscous Flow,
    <em>Advances in Water Resources</em>,
    25,
    pp. 1125-1146,
    2002.</li>
 </tr><p><tr><td valign='top'><img src="https://hplgit.github.io/doconce/bundled/html_images/bullet_red2.png"></td><td> <div id="Langtangen_1994a"></div> <b>H. P. Langtangen</b>. 
    Numerical Solution of First Passage Problems in Random Vibrations,
    <em>SIAM Journal of Scientific and Statistical Computing</em>,
    15,
    pp. 997-996,
    1994.</li>
 </tr><p><tr><td valign='top'><img src="https://hplgit.github.io/doconce/bundled/html_images/bullet_red2.png"></td><td> <div id="Mardal_et_al_2003a"></div> <b>K.-A. Mardal, G. W. Zumbusch and H. P. Langtangen</b>. 
    Software Tools for Multigrid Methods,
    <em>Advanced Topics in Computational Partial Differential Equations -- Numerical Methods and Diffpack Programming</em>,
    edited by <b>H. P. Langtangen and A. Tveito</b>,
    Springer,
    2003,
    Edited book,
    <a href="http://some.where.org" target="_self"><tt>http://some.where.org</tt></a>.</li>
 </tr><p><tr><td valign='top'><img src="https://hplgit.github.io/doconce/bundled/html_images/bullet_red2.png"></td><td> <div id="Langtangen_1988d"></div> <b>H. P. Langtangen</b>. 
    The FEMDEQS Program System,
    <em>Department of Mathematics, University of Oslo</em>,
    1989,
    <a href="http://www.math.uio.no/old/days/hpl/femdeqs.pdf" target="_self"><tt>http://www.math.uio.no/old/days/hpl/femdeqs.pdf</tt></a>.</li>
 </tr><p><tr><td valign='top'><img src="https://hplgit.github.io/doconce/bundled/html_images/bullet_red2.png"></td><td> <div id="Langtangen_1992c"></div> <b>H. P. Langtangen</b>. 
    Stochastic Breakthrough Time Analysis of an Enhanced Oil Recovery Process,
    <em>SIAM Journal on Scientific Computing</em>,
    13,
    pp. 1394-1417,
    1992.</li>
 </tr><p><tr><td valign='top'><img src="https://hplgit.github.io/doconce/bundled/html_images/bullet_red2.png"></td><td> <div id="Mortensen_et_al_2011"></div> <b>M. Mortensen, H. P. Langtangen and G. N. Wells</b>. 
    A FEniCS-Based Programming Framework for Modeling Turbulent Flow by the Reynolds-Averaged Navier-Stokes Equations,
    <em>Advances in Water Resources</em>,
    34(9),
    <a href="https://dx.doi.org/10.1016/j.advwatres.2011.02.013" target="_self">doi: 10.1016/j.advwatres.2011.02.013</a>,
    2011.</li>
 </tr><p><tr><td valign='top'><img src="https://hplgit.github.io/doconce/bundled/html_images/bullet_red2.png"></td><td> <div id="Glimsdal_et_al_20006"></div> <b>S. Glimsdal, G. Pedersen, K. Atakan, C. B. Harbitz, H. P. Langtangen and F. L\ovholt</b>. 
    Propagation of the Dec.&nbsp;26, 2004 Indian Ocean Tsunami: Effects of Dispersion and Source Characteristics,
    <em>International Journal of Fluid Mechanics Research</em>,
    33(1),
    pp. 15-43,
    2006.</li>
 </tr><p><tr><td valign='top'><img src="https://hplgit.github.io/doconce/bundled/html_images/bullet_red2.png"></td><td> <div id="Rahman_et_al_2006b"></div> <b>S. Rahman, J. Gorman, C. H. W. Barnes, D. A. Williams and H. P. Langtangen</b>. 
    Numerical Investigation of a Piezoelectric Surface Acoustic Wave Interaction With a One-Dimensional Channel,
    <em>Physical Review B: Condensed Matter and Materials Physics</em>,
    74,
    2006,
    035308.</li>
</tr><p><tr><td valign='top'><img src="https://hplgit.github.io/doconce/bundled/html_images/bullet_red2.png"></td><td> <div id="Haga_et_al_2011a"></div> <b>J. B. Haga, H. Osnes and H. P. Langtangen</b>. 
    On the Causes of Pressure Oscillations in Low-Permeable and Low-Compressible Porous Media,
    <em>International Journal of Analytical and Numerical Methods in Geomechanics</em>,
    <a href="https://dx.doi.org/10.1002/nag.1062" target="_self">doi: 10.1002/nag.1062</a>,
    2011,
    <a href="http://onlinelibrary.wiley.com/doi/10.1002/nag.1062/abstract" target="_self"><tt>http://onlinelibrary.wiley.com/doi/10.1002/nag.1062/abstract</tt></a>.</li>
</tr><p><tr><td valign='top'><img src="https://hplgit.github.io/doconce/bundled/html_images/bullet_red2.png"></td><td> <div id="Langtangen_2003a"></div> <b>H. P. Langtangen</b>. 
    <em>Computational Partial Differential Equations - Numerical Methods and Diffpack Programming</em>,
    second edition,
    <em>Texts in Computational Science and Engineering</em>,
    Springer,
    2003.</li>
</tr><p><tr><td valign='top'><img src="https://hplgit.github.io/doconce/bundled/html_images/bullet_red2.png"></td><td> <div id="Langtangen_2008a"></div> <b>H. P. Langtangen</b>. 
    <em>Python Scripting for Computational Science</em>,
    third edition,
    <em>Texts in Computational Science and Engineering</em>,
    Springer,
    2008.</li>
</tr><p><tr><td valign='top'><img src="https://hplgit.github.io/doconce/bundled/html_images/bullet_red2.png"></td><td> <div id="Langtangen:95"></div> <b>H. P. Langtangen and G. Pedersen</b>. 
    Finite Elements for the Boussinesq Wave Equations,
    Waves and Non-linear Processes in Hydrodynamics,
    edited by <b>J. Grue, B. Gjevik and J. E. Weber</b>,
    Kluwer Academic Publishers,
    pp. pp. 117-126,
    1995,
    <a href="http://www.amazon.ca/Waves-Nonlinear-Processes-Hydrodynamics-John/dp/0792340310" target="_self"><tt>http://www.amazon.ca/Waves-Nonlinear-Processes-Hydrodynamics-John/dp/0792340310</tt></a>.</li>
</tr><p><tr><td valign='top'><img src="https://hplgit.github.io/doconce/bundled/html_images/bullet_red2.png"></td><td> <div id="Langtangen_2012"></div> <b>H. P. Langtangen</b>. 
    <em>A Primer on Scientific Programming With Python</em>,
    third edition,
    <em>Texts in Computational Science and Engineering</em>,
    Springer,
    2012.</li>
</tr><p><tr><td valign='top'><img src="https://hplgit.github.io/doconce/bundled/html_images/bullet_red2.png"></td><td> <div id="Jeberg_et_al_2004"></div> <b>P. V. Jeberg, H. P. Langtangen and C. B. Terp</b>. 
    Optimization With Diffpack: Practical Example From Welding,
    <em>Simula Research Laboratory</em>,
    2004,
    Internal report.</li>
</tr><p><tr><td valign='top'><img src="https://hplgit.github.io/doconce/bundled/html_images/bullet_red2.png"></td><td> <div id="Langtangen_1989e"></div> <b>H. P. Langtangen</b>. 
    Computational Methods for Two-Phase Flow in Oil Reservoirs,
    Ph.D. Thesis,
    Mechanics Division, Department of Mathematics, University of Oslo,
    1989,
    Dr.&nbsp;Scient.&nbsp;thesis..</li>
</tr><p><tr><td valign='top'><img src="https://hplgit.github.io/doconce/bundled/html_images/bullet_red2.png"></td><td> <div id="Langtangen_talk_2007a"></div> <b>H. P. Langtangen</b>. 
    Computational Modeling of Huge Tsunamis From Asteroid Impacts,
    2007,
    Invited keynote lecture at the \emphInternational conference on Computational Science 2007 (ICCS'07), Beijing, China.</li>
</tr><p><tr><td valign='top'><img src="https://hplgit.github.io/doconce/bundled/html_images/bullet_red2.png"></td><td> <div id="Langtangen:85"></div> <b>H. P. Langtangen</b>. 
    Solution of the Navier-Stokes Equations With the Finite Element Method in Two and Three Dimensions,
    M.Sc. Thesis,
    Mechanics Division, Department of Mathematics, University of Oslo,
    1985,
    Cand.Scient. thesis.</li>
</tr><p><tr><td valign='top'><img src="https://hplgit.github.io/doconce/bundled/html_images/bullet_red2.png"></td><td> <div id="Langtangen:91"></div> <b>H. P. Langtangen and A. Tveito</b>. 
    Numerical Methods in Continuum Mechanics,
    <em>Center for Industrial Research</em>,
    1991,
    Lecture notes for a course (ME-IN 324). 286 pages..</li>
</tr><p><tr><td valign='top'><img src="https://hplgit.github.io/doconce/bundled/html_images/bullet_red2.png"></td><td> <div id="Langtangen:94b"></div> <b>H. P. Langtangen</b>. 
    Diffpack: Software for Partial Differential Equations,
    <em>Proceedings of the Second Annual Object-Oriented Numerics Conference (OON-SKI'94), Sunriver, Oregon, USA</em>,
    edited by <b>A. Vermeulen</b>,
    1994.</li>
</ol>

<!-- end bibliography -->

<h1 id="app1">Appendix: Just for testing; part I</h1>

<p>
This is the first appendix.

<h2 id="a-subsection-within-an-appendix">A subsection within an appendix </h2>

<p>
Some text.

<h1 id="app2">Appendix: Just for testing; part II</h1>

<p>
This is more stuff for an appendix.

<h2 id="appendix-testing-identical-titles">Appendix: Testing identical titles </h2>

<p>
Without label.

<h2 id="test:title:id1">Appendix: Testing identical titles</h2>

<p>
With label.

<h2 id="test:title:id2">Appendix: Testing identical titles</h2>

<p>
What about inserting a quiz?

<p>
<p>
<!-- begin bottom navigation -->
<table style="width: 100%"><tr><td>
\
<div style="text-align: left;"><a href="._testdoc001.html"><img src="https://hplgit.github.io/doconce/bundled/html_images/prev2.png" border=0 alt="&laquo; Previous"></a></div>
</td><td>
\
<div style="text-align: right;"><a href="._testdoc003.html"><img src="https://hplgit.github.io/doconce/bundled/html_images/next2.png" border=0 alt="Next &raquo;"></a></div>
</td></tr></table>
<!-- end bottom navigation -->
</p>

<!-- ------------------- end of main content --------------- -->

<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.js"></script>


</body>
</html>

************** File: ._testdoc003.html *****************
<!--
Automatically generated HTML file from DocOnce source
(https://github.com/doconce/doconce/)
-->
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="DocOnce: https://github.com/doconce/doconce/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="description" content="A Document for Testing DocOnce">
<meta name="keywords" content="figures,movies,index with subindex,_boldface word_ in index,index with _boldface word_,index with _boldface word_ in subentry,double _boldface word_  _boldface word_ in subentry too,index, with comma, and one more">

<title>A Document for Testing DocOnce</title>


<link href="https://raw.github.com/doconce/doconce/master/bundled/html_styles/style_solarized_box/css/solarized_light_code.css" rel="stylesheet" type="text/css" title="light"/>
<script src="https://raw.github.com/doconce/doconce/master/bundled/html_styles/style_solarized_box/js/highlight.pack.js"></script>
<script>hljs.initHighlightingOnLoad();</script>

<style type="text/css">
body, td {font-size: 140%;}
h1 {font-size: 200%;}
h2 {font-size: 180%;}

/* solarized style */
body {
  margin:5;
  padding:0;
  border:0; /* Remove the border around the viewport in old versions of IE */
  width:100%;
  background: #fdf6e3;
  min-width:600px;	/* Minimum width of layout - remove if not required */
  font-family: Verdana, Helvetica, Arial, sans-serif;
  font-size: 1.0em;
  line-height: 1.3em;
  color: #657b83;
}
a { color: #859900; text-decoration: underline; }
a:hover, a:active { outline:none }
a, a:active, a:visited { color: #859900; }
a:hover { color: #268bd2; }
h1, h2, h3 { margin:.8em 0 .2em 0; padding:0; line-height: 125%; }
h2 { font-variant: small-caps; }
tt, code { font-family: monospace, sans-serif; box-shadow: none; }
hr { border: 0; width: 80%; border-bottom: 1px solid #aaa; }
p { text-indent: 0px; }
p.caption { width: 80%; font-style: normal; text-align: left; }
hr.figure { border: 0; width: 80%; border-bottom: 1px solid #aaa; }
.alert-text-small   { font-size: 80%;  }
.alert-text-large   { font-size: 130%; }
.alert-text-normal  { font-size: 90%;  }
.alert {
  padding:8px 35px 8px 14px; margin-bottom:18px;
  text-shadow:0 1px 0 rgba(255,255,255,0.5);
  border:1px solid #93a1a1;
  border-radius: 4px;
  -webkit-border-radius: 4px;
  -moz-border-radius: 4px;
  color: #555;
  background-color: #eee8d5;
  background-position: 10px 5px;
  background-repeat: no-repeat;
  background-size: 38px;
  padding-left: 55px;
  width: 75%;
 }
.alert-block {padding-top:14px; padding-bottom:14px}
.alert-block > p, .alert-block > ul {margin-bottom:1em}
.alert li {margin-top: 1em}
.alert-block p+p {margin-top:5px}
.alert-notice { background-image: url(https://raw.github.com/doconce/doconce/master/bundled/html_images/small_yellow_notice.png); }
.alert-summary  { background-image:url(https://raw.github.com/doconce/doconce/master/bundled/html_images/small_yellow_summary.png); }
.alert-warning { background-image: url(https://raw.github.com/doconce/doconce/master/bundled/html_images/small_yellow_warning.png); }
.alert-question {background-image:url(https://raw.github.com/doconce/doconce/master/bundled/html_images/small_yellow_question.png); }

div { text-align: justify; text-justify: inter-word; }
</style>


<script src="https://sagecell.sagemath.org/static/jquery.min.js"></script>
<script src="https://sagecell.sagemath.org/embedded_sagecell.js"></script>
<link rel="stylesheet" type="text/css" href="https://sagecell.sagemath.org/static/sagecell_embed.css">
<script>
$(function () {
    // Make the div with id 'mycell' a Sage cell
    sagecell.makeSagecell({inputLocation:  '#mycell',
                           template:       sagecell.templates.minimal,
                           evalButtonText: 'Activate'});
    // Make *any* div with class 'compute' a Sage cell
    sagecell.makeSagecell({inputLocation: 'div.compute',
                           evalButtonText: 'Evaluate'});
});
</script>




<!-- Tools for embedded Bokeh plots -->
<link rel="stylesheet"
      href="https://cdn.pydata.org/bokeh/release/bokeh-0.9.0.min.css"
      type="text/css" />
<script type="text/javascript"
	src="https://cdn.pydata.org/bokeh/release/bokeh-0.9.0.min.js">
</script>
<script type="text/javascript">
  Bokeh.set_log_level("info");
</script>


</head>

<!-- tocinfo
{'highest level': 1,
 'sections': [('Table of contents',
               1,
               'table_of_contents',
               'table_of_contents'),
              ('Section 1', 1, 'sec1', 'sec1'),
              ('Here is a list with subsubsection heading',
               3,
               None,
               'here-is-a-list-with-subsubsection-heading'),
              ('Subsection 1', 2, 'subsec1', 'subsec1'),
              ('Test Section reference at beginning of line and after a '
               'sentence',
               3,
               None,
               'test-section-reference-at-beginning-of-line-and-after-a-sentence'),
              ('Computer code', 3, None, 'computer-code'),
              ('Subsubsection heading before code',
               3,
               None,
               'subsubsection-heading-before-code'),
              ('Running OS commands', 3, None, 'running-os-commands'),
              ('Footnotes', 3, None, 'footnotes'),
              ('Subsection 2: Testing figures', 2, 'subsec:ex', 'subsec:ex'),
              ('The $\\theta$ parameter (not $\\nabla$?)',
               2,
               'decay:sec:theta',
               'decay:sec:theta'),
              ('Custom Environments', 2, None, 'custom-environments'),
              ('Tables', 2, 'subsec:table', 'subsec:table'),
              ('A test of verbatim words in heading with subscript $a_i$: '
               '`my_file_v1` and `my_file_v2`',
               2,
               None,
               'a-test-of-verbatim-words-in-heading-with-subscript-a_i-my_file_v1-and-my_file_v2'),
              ('_Just bold_', 2, None, '_just-bold_'),
              ('*Just emphasize*', 2, None, 'just-emphasize'),
              ('`Just verbatim`', 2, None, 'just-verbatim'),
              ('_Bold_ beginning', 2, None, '_bold_-beginning'),
              ('*Emphasize* beginning', 2, None, 'emphasize-beginning'),
              ('`Verbatim` beginning', 2, None, 'verbatim-beginning'),
              ('Maybe _bold end_', 2, None, 'maybe-_bold-end_'),
              ('Maybe *emphasize end*', 2, None, 'maybe-emphasize-end'),
              ('Maybe `verbatim end`', 2, None, 'maybe-verbatim-end'),
              ('The middle has _bold_ word',
               2,
               None,
               'the-middle-has-_bold_-word'),
              ('The middle has *emphasize* word',
               2,
               None,
               'the-middle-has-emphasize-word'),
              ('The middle has `verbatim` word',
               2,
               None,
               'the-middle-has-verbatim-word'),
              ('Bibliography test', 2, None, 'bibliography-test'),
              ('Example 1: Examples can be typeset as exercises',
               2,
               'Example',
               'Example'),
              ('User-defined environments',
               2,
               None,
               'user-defined-environments'),
              ('Example 1: A test function', 2, 'ex:test:1p1', 'ex:test:1p1'),
              ('Example 2: Addition', 2, 'ex:math:1p1', 'ex:math:1p1'),
              ('URLs', 2, 'subsubsec:ex', 'subsubsec:ex'),
              ('LaTeX Mathematics', 1, None, 'latex-mathematics'),
              ('Exercises', 1, None, 'exercises'),
              ('Problem 2: Flip a Coin', 2, 'demo:ex:1', 'demo:ex:1'),
              ('My remarks', 3, None, 'my-remarks'),
              ('Remarks', 3, None, 'remarks'),
              ('Not an exercise', 2, None, 'not-an-exercise'),
              ('Exercise 3: Test of plain text exercise',
               2,
               'my:exer1',
               'my:exer1'),
              ('Project 4: Compute a Probability', 2, 'demo:ex:2', 'demo:ex:2'),
              ('Project 5: Explore Distributions of Random Circles',
               2,
               'proj:circle1',
               'proj:circle1'),
              ('Remarks', 3, None, 'remarks'),
              ('Exercise 6: Determine some Distance',
               2,
               'exer:dist',
               'exer:dist'),
              ('Remarks', 3, None, 'remarks'),
              ('Some exercise without the "Exercise:" prefix',
               2,
               None,
               'some-exercise-without-the-exercise-prefix'),
              ('Exercise 8: Solution of differential equation',
               2,
               'sec:this:exer:de',
               'sec:this:exer:de'),
              ('Example 9: Just an example',
               2,
               None,
               'example-9-just-an-example'),
              ('Here goes another section',
               1,
               None,
               'here-goes-another-section'),
              ('More Exercises', 1, None, 'more-exercises'),
              ('Exercise 10: Make references to projects and problems',
               2,
               'exer:some:formula',
               'exer:some:formula'),
              ('Project 11: References in a headings do not work well in html',
               2,
               'exer:you',
               'exer:you'),
              ('References', 1, None, 'references'),
              ('Appendix: Just for testing; part I', 1, 'app1', 'app1'),
              ('A subsection within an appendix',
               2,
               None,
               'a-subsection-within-an-appendix'),
              ('Appendix: Just for testing; part II', 1, 'app2', 'app2'),
              ('Appendix: Testing identical titles',
               2,
               None,
               'appendix-testing-identical-titles'),
              ('Appendix: Testing identical titles',
               2,
               'test:title:id1',
               'test:title:id1'),
              ('Appendix: Testing identical titles',
               2,
               'test:title:id2',
               'test:title:id2'),
              ('Appendix: Testing identical titles',
               2,
               None,
               'appendix-testing-identical-titles'),
              ('Appendix: Testing inline comments',
               2,
               None,
               'appendix-testing-inline-comments'),
              ('Appendix: Testing headings ending with `verbatim inline`',
               2,
               None,
               'appendix-testing-headings-ending-with-verbatim-inline')]}
end of tocinfo -->

<body>



<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  TeX: {
     equationNumbers: {  autoNumber: "none"  },
     extensions: ["AMSmath.js", "AMSsymbols.js", "autobold.js", "color.js"]
  }
});
</script>
<script type="text/javascript" async
 src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>



    
<a name="part0003"></a>
<!-- !split -->
<h2>Test of quizzes</h2>

<!-- begin quiz -->
<hr>
<p>
<b>Fundamental test:</b> What is the capital of Norway?</p>

<p><div title="Wrong! Stockholm is the capital of Sweden."><b>Answer 1:</b>
Stockholm
</div></p>

<p><div title="Wrong! "><b>Answer 2:</b>
London
</div></p>

<p><div title="Right! "><b>Answer 3:</b>
Oslo
</div></p>

<p><div title="Wrong! Those from Bergen would claim so, but nobody else."><b>Choice D:</b>
Bergen
</div></p>
<hr>
<!-- end quiz -->


<h2 id="appendix-testing-identical-titles">Appendix: Testing identical titles </h2>

<p>
Without label.

<p>
<div class="alert alert-block alert-notice alert-text-normal">
<b>Tip</b>
<p>
Here is a tip or hint box, typeset as a notice box.
</div>


<p>
Need a lot of text to surround the summary box.
Version control systems allow you to record the history of files
and share files among several computers and collaborators in a
professional way. File changes on one computer are updated or
merged with changes on another computer. Especially when working
with programs or technical reports it is essential
to have changes documented and to
ensure that every computer and person involved in the project
have the latest updates of the files.
Greg Wilson' excellent <a href="https://software-carpentry.org/2010/07/script-for-introduction-to-version-control/" target="_self">Script for Introduction to Version Control</a> provides a more detailed motivation why you will benefit greatly
from using version control systems.

<p>
<div class="alert alert-block alert-summary alert-text-normal">
<b>Summary</b>
<p>
<b>Bold remark:</b> Make some text with this summary.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
</div>


<p>
Projects that you want to share among several computers or project
workers are today most conveniently stored at some web site "in the
cloud" and updated through communication with that site. I strongly
recommend you to use such sites for all serious programming and
scientific writing work - and all other important files.

<p>
The simplest services for hosting project files are <a href="https://dropbox.com" target="_self">Dropbox</a> and <a href="https://drive.google.com" target="_self">Google Drive</a>.
It is very easy to get started with these systems, and they allow you
to share files among laptops and mobile units with as many users as
you want. The systems offer a kind of version control in that the
files are stored frequently (several times per minute), and you can go
back to previous versions for the last 30 days. However, it is
challenging  to find the right version from the past when there are
so many of them.

<p>
More seriously, when several people may edit files simultaneously, it
can be difficult detect who did what when, roll back to previous
versions, and to manually merge the edits when these are
incompatible. Then one needs more sophisticated tools than Dropbox or
Google Drive: project hosting services with true version control
systems.  The following text aims at providing you with the minimum
information to started with such systems. Numerous other tutorials
contain more comprehensive material and in-depth explanations of the
concepts and tools.

<p>
The idea with project hosting services is that you have the files
associated with a project in the cloud. Many people may share these
files.  Every time you want to work on the project you explicitly
update your version of the files, edit the files as you like, and
synchronize the files with the "master version" at the site where the
project is hosted.  If you at some point need to go back to a
version of the files at some particular point in the past,
this is an easy operation. You can also use tools to see
what various people have done with the files in the various versions.

<p>
All these services are very similar. Below we describe how you get
started with Bitbucket, GitHub, and Googlecode. Launchpad works very
similarly to the latter three. All the project hosting services have
excellent introductions available at their web sites, but the recipes
below are much shorter and aim at getting you started as quickly as
possible by concentrating on the most important need-to-know steps.
The Git tutorials we refer to later in this document contain more
detailed information and constitute of course very valuable readings
when you use version control systems every day. The point now is
to get started.

<h2 id="appendix-testing-inline-comments">Appendix: Testing inline comments </h2>

<p>
<!-- Names can be [ A-Za-z0-9_'+-]+ -->

<p>
Projects that you want to share among several computers or project
workers are today most conveniently stored at some web site "in the
cloud" and updated through communication with that
site. 
<!-- begin inline comment -->
<font color="red">(<b>hpl's semi opinion 1</b>: not sure if in the cloud is understood by all.)</font>
<!-- end inline comment -->
 I strongly recommend you to use such sites for all serious
programming and scientific writing work - and all other important
files.

<p>
The simplest services for hosting project files is Dropbox. 
<!-- begin inline comment -->
<font color="red">(<b>mp 2</b>: Simply go to <a href="https://dropbox.com" target="_self"><tt>https://dropbox.com</tt></a> and watch the video. It explains how files, like <code>myfile.py</code>, perhaps containing much math, like \( \partial u/\partial t \), are easily communicated between machines.)</font>
<!-- end inline comment -->
 It
is very easy to get started with Dropbox, and it allows you to share
files among  <font color="red">(<b>hpl 3</b>:)</font> <del> laptops and mobile units </del> <font color="red">computers, tablets, and phones</font>.

<p>
<!-- Test horizontal rule -->

<p>
<hr>

<p>
<!-- Coments for editing -->

<p>
First<font color="red">, (<b>edit 4</b>: add comma)</font> consider a quantity \( Q \).  <font color="red">(<b>edit 5</b>:)</font> <del> To this end, </del> <font color="red">We note that</font>
\( Q>0 \), because  <font color="red">(<b>edit 6</b>:)</font> <del> a </del> negative  <font color="red">(<b>edit 7</b>:)</font> <del> quantity is </del> <font color="red">quantities are</font>  <font color="red">(<b>edit 8</b>:)</font> <del> just </del> negative.  <font color="red">(<b>edit 9</b>:) This comes as no surprise.</font>

<p>
<!-- Test tailored latex figure references with page number -->
Let us refer to Figure <a href="._testdoc001.html#fig:impact">1</a> again.

<p>
Test references in a list:

<p><table border="0">

 </tr><p><tr><td valign='top'><img src="https://hplgit.github.io/doconce/bundled/html_images/bullet_red2.png"></td><td> <a href="._testdoc001.html#sec1">Section 1</a></li>
 </tr><p><tr><td valign='top'><img src="https://hplgit.github.io/doconce/bundled/html_images/bullet_red2.png"></td><td> <a href="._testdoc001.html#subsec1">Subsection 1</a></li>
 </tr><p><tr><td valign='top'><img src="https://hplgit.github.io/doconce/bundled/html_images/bullet_red2.png"></td><td> <a href="._testdoc001.html#fig:impact">1</a></li>
</td></tr></table>


<h2 id="appendix-testing-headings-ending-with-verbatim-inline">Appendix: Testing headings ending with <code>verbatim inline</code> </h2>

<p>
The point here is to test 1) <code>verbatim</code> code in headings, and 2)
ending a heading with verbatim code as this triggers a special
case in LaTeX.

<p>
We also test mdash&mdash;used as alternative to hyphen without spaces around,
or in quotes:

<p>
<blockquote>
    <em>Fun is fun</em>.&mdash;Unknown.
</blockquote>


<p>
The ndash should also be tested &ndash; as in the Hanson&ndash;Nilson equations
on page 277&ndash;278.

<p>
And finally, what about admons, quotes, and boxes? They are tested
in a separate document: <code>admon.do.txt</code>.

<p id="def_footnote_5"><a href="._testdoc001.html#link_footnote_5"><b>5:</b></a> Not much to add here, but the footnote
is at the end with only one newline.</p>

<p>
<!-- begin bottom navigation -->
<table style="width: 100%"><tr><td>
\
<div style="text-align: left;"><a href="._testdoc002.html"><img src="https://hplgit.github.io/doconce/bundled/html_images/prev2.png" border=0 alt="&laquo; Previous"></a></div>
</td><td>
</td></tr></table>
<!-- end bottom navigation -->
</p>

<!-- ------------------- end of main content --------------- -->

<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.js"></script>


</body>
</html>

************** File: testdoc_wordpress.html *****************
<!--
Automatically generated HTML file from DocOnce source (https://github.com/doconce/doconce/)
-->
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="DocOnce: https://github.com/doconce/doconce/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="description" content="A Document for Testing DocOnce">
<meta name="keywords" content="figures,movies,index with subindex,_boldface word_ in index,index with _boldface word_,index with _boldface word_ in subentry,double _boldface word_  _boldface word_ in subentry too,index, with comma, and one more">

<title>A Document for Testing DocOnce</title>


<style type="text/css">
/* blueish style */

/* Color definitions:  https://www.december.com/html/spec/color0.html
   CSS examples:       https://www.w3schools.com/css/css_examples.asp */

body {
  margin-top: 1.0em;
  background-color: #ffffff;
  font-family: Helvetica, Arial, FreeSans, san-serif;
  color: #000000;
}
h1 { font-size: 1.8em; color: #1e36ce; }
h2 { font-size: 1.6em; color: #1e36ce; }
h3 { font-size: 1.4em; color: #1e36ce; }
a { color: #1e36ce; text-decoration:none; }
tt { font-family: "Courier New", Courier; }
/* pre style removed because it will interfer with pygments */
p { text-indent: 0px; }
hr { border: 0; width: 80%; border-bottom: 1px solid #aaa}
p.caption { width: 80%; font-style: normal; text-align: left; }
hr.figure { border: 0; width: 80%; border-bottom: 1px solid #aaa}
.alert-text-small   { font-size: 80%;  }
.alert-text-large   { font-size: 130%; }
.alert-text-normal  { font-size: 90%;  }
.alert {
  padding:8px 35px 8px 14px; margin-bottom:18px;
  text-shadow:0 1px 0 rgba(255,255,255,0.5);
  border:1px solid #bababa;
  border-radius: 4px;
  -webkit-border-radius: 4px;
  -moz-border-radius: 4px;
  color: #555;
  background-color: #f8f8f8;
  background-position: 10px 5px;
  background-repeat: no-repeat;
  background-size: 38px;
  padding-left: 55px;
  width: 75%;
 }
.alert-block {padding-top:14px; padding-bottom:14px}
.alert-block > p, .alert-block > ul {margin-bottom:1em}
.alert li {margin-top: 1em}
.alert-block p+p {margin-top:5px}
.alert-notice { background-image: url(https://raw.github.com/doconce/doconce/master/bundled/html_images/small_gray_notice.png); }
.alert-summary  { background-image:url(https://raw.github.com/doconce/doconce/master/bundled/html_images/small_gray_summary.png); }
.alert-warning { background-image: url(https://raw.github.com/doconce/doconce/master/bundled/html_images/small_gray_warning.png); }
.alert-question {background-image:url(https://raw.github.com/doconce/doconce/master/bundled/html_images/small_gray_question.png); }

div { text-align: justify; text-justify: inter-word; }
</style>


<script src="https://sagecell.sagemath.org/static/jquery.min.js"></script>
<script src="https://sagecell.sagemath.org/embedded_sagecell.js"></script>
<link rel="stylesheet" type="text/css" href="https://sagecell.sagemath.org/static/sagecell_embed.css">
<script>
$(function () {
    // Make the div with id 'mycell' a Sage cell
    sagecell.makeSagecell({inputLocation:  '#mycell',
                           template:       sagecell.templates.minimal,
                           evalButtonText: 'Activate'});
    // Make *any* div with class 'compute' a Sage cell
    sagecell.makeSagecell({inputLocation: 'div.compute',
                           evalButtonText: 'Evaluate'});
});
</script>



</head>



<body>

    




<center><h1>A Document for Testing DocOnce</h1></center>

<p>


<center>
<b>Hans Petter Langtangen</b> [1, 2] (<tt>hpl at simula.no</tt>)
</center>

<center>
<b>Kaare Dump</b> [3]
</center>

<center>
<b>A. Dummy Author</b> 
</center>

<center>
<b>I. S. Overworked and Outburned</b> [4, 5, 6, 7]
</center>

<center>
<b>J. Doe</b>  (<tt>j_doe at cyberspace.com</tt>)
</center>

<p>


<center>[1] <b>Center for Biomedical Computing, Simula Research Laboratory</b></center>
<center>[2] <b>Department of Informatics, University of Oslo</b></center>
<center>[3] <b>Segfault, Cyberspace</b></center>
<center>[4] <b>Inst1</b></center>
<center>[5] <b>Inst2, Somewhere</b></center>
<center>[6] <b>Third Inst, Elsewhere</b></center>
<center>[7] <b>Fourth Inst</b></center>
<br>
<p>
<center><h4>Jan 32, 2100</h4></center> 
<br>

<h1 id="table_of_contents">Table of contents</h2>

<p>
<a href="#sec1"> Section 1 </a><br>
&nbsp; &nbsp; &nbsp; <a href="#subsec1"> Subsection 1 </a><br>
&nbsp; &nbsp; &nbsp; <a href="#subsec:ex"> Subsection 2: Testing figures </a><br>
&nbsp; &nbsp; &nbsp; <a href="#decay:sec:theta"> The $latex \theta$ parameter (not $latex \nabla$?) </a><br>
&nbsp; &nbsp; &nbsp; <a href="#custom-environments"> Custom Environments </a><br>
&nbsp; &nbsp; &nbsp; <a href="#subsec:table"> Tables </a><br>
&nbsp; &nbsp; &nbsp; <a href="#a-test-of-verbatim-words-in-heading-with-subscript-a_i-my_file_v1-and-my_file_v2"> A test of verbatim words in heading with subscript $latex a_i$: <code>my_file_v1</code> and <code>my_file_v2</code> </a><br>
&nbsp; &nbsp; &nbsp; <a href="#_just-bold_"> <b>Just bold</b> </a><br>
&nbsp; &nbsp; &nbsp; <a href="#just-emphasize"> <em>Just emphasize</em> </a><br>
&nbsp; &nbsp; &nbsp; <a href="#just-verbatim"> <code>Just verbatim</code> </a><br>
&nbsp; &nbsp; &nbsp; <a href="#_bold_-beginning"> <b>Bold</b> beginning </a><br>
&nbsp; &nbsp; &nbsp; <a href="#emphasize-beginning"> <em>Emphasize</em> beginning </a><br>
&nbsp; &nbsp; &nbsp; <a href="#verbatim-beginning"> <code>Verbatim</code> beginning </a><br>
&nbsp; &nbsp; &nbsp; <a href="#maybe-_bold-end_"> Maybe <b>bold end</b> </a><br>
&nbsp; &nbsp; &nbsp; <a href="#maybe-emphasize-end"> Maybe <em>emphasize end</em> </a><br>
&nbsp; &nbsp; &nbsp; <a href="#maybe-verbatim-end"> Maybe <code>verbatim end</code> </a><br>
&nbsp; &nbsp; &nbsp; <a href="#the-middle-has-<b>bold</b>-word"> The middle has <b>bold</b> word </a><br>
&nbsp; &nbsp; &nbsp; <a href="#the-middle-has-emphasize-word"> The middle has <em>emphasize</em> word </a><br>
&nbsp; &nbsp; &nbsp; <a href="#the-middle-has-verbatim-word"> The middle has <code>verbatim</code> word </a><br>
&nbsp; &nbsp; &nbsp; <a href="#bibliography-test"> Bibliography test </a><br>
&nbsp; &nbsp; &nbsp; <a href="#Example"> Example 1: Examples can be typeset as exercises </a><br>
&nbsp; &nbsp; &nbsp; <a href="#user-defined-environments"> User-defined environments </a><br>
&nbsp; &nbsp; &nbsp; <a href="#ex:test:1p1"> Example 1: A test function </a><br>
&nbsp; &nbsp; &nbsp; <a href="#ex:math:1p1"> Example 2: Addition </a><br>
&nbsp; &nbsp; &nbsp; <a href="#subsubsec:ex"> URLs </a><br>
<a href="#latex-mathematics"> LaTeX Mathematics </a><br>
<a href="#exercises"> Exercises </a><br>
&nbsp; &nbsp; &nbsp; <a href="#demo:ex:1"> Problem 2: Flip a Coin </a><br>
&nbsp; &nbsp; &nbsp; <a href="#not-an-exercise"> Not an exercise </a><br>
&nbsp; &nbsp; &nbsp; <a href="#my:exer1"> Exercise 3: Test of plain text exercise </a><br>
&nbsp; &nbsp; &nbsp; <a href="#demo:ex:2"> Project 4: Compute a Probability </a><br>
&nbsp; &nbsp; &nbsp; <a href="#proj:circle1"> Project 5: Explore Distributions of Random Circles </a><br>
&nbsp; &nbsp; &nbsp; <a href="#exer:dist"> Exercise 6: Determine some Distance </a><br>
&nbsp; &nbsp; &nbsp; <a href="#some-exercise-without-the-exercise-prefix"> Some exercise without the "Exercise:" prefix </a><br>
&nbsp; &nbsp; &nbsp; <a href="#sec:this:exer:de"> Exercise 8: Solution of differential equation </a><br>
&nbsp; &nbsp; &nbsp; <a href="#example-9-just-an-example"> Example 9: Just an example </a><br>
<a href="#here-goes-another-section"> Here goes another section </a><br>
<a href="#more-exercises"> More Exercises </a><br>
&nbsp; &nbsp; &nbsp; <a href="#exer:some:formula"> Exercise 10: Make references to projects and problems </a><br>
&nbsp; &nbsp; &nbsp; <a href="#exer:you"> Project 11: References in a headings do not work well in html </a><br>
<a href="#references"> References </a><br>
<a href="#app1"> Appendix: Just for testing; part I </a><br>
&nbsp; &nbsp; &nbsp; <a href="#a-subsection-within-an-appendix"> A subsection within an appendix </a><br>
<a href="#app2"> Appendix: Just for testing; part II </a><br>
&nbsp; &nbsp; &nbsp; <a href="#appendix-testing-identical-titles"> Appendix: Testing identical titles </a><br>
&nbsp; &nbsp; &nbsp; <a href="#test:title:id1"> Appendix: Testing identical titles </a><br>
&nbsp; &nbsp; &nbsp; <a href="#test:title:id2"> Appendix: Testing identical titles </a><br>
&nbsp; &nbsp; &nbsp; <a href="#appendix-testing-identical-titles"> Appendix: Testing identical titles </a><br>
&nbsp; &nbsp; &nbsp; <a href="#appendix-testing-inline-comments"> Appendix: Testing inline comments </a><br>
&nbsp; &nbsp; &nbsp; <a href="#appendix-testing-headings-ending-with-verbatim-inline"> Appendix: Testing headings ending with <code>verbatim inline</code> </a><br>
</p>
<p>
The format of this document is plain, homemade HTML (from DocOnce).

<p>
<b>Abstract.</b> This is a document with many test constructions for doconce syntax. It was used heavily for the development and kept for testing numerous constructions, also special and less common cases.

<p>
And exactly for test purposes we have an extra line here, which is part of the abstract.

<h1 id="sec1">Section 1</h1>

<p>
Here is a nested list:

<ul>
  <li> item1</li>
  <li> item2</li>
  <li> item3 which continues     on the next line to test that feature</li>
  <li> and a sublist</li>

<ul>
    <li> with indented subitem1</li>
    <li> and a subitem2</li>
</ul>

  <li> and perhaps an ordered sublist  <ol type="a"></li>
   <li> first item</li>
   <li> second item,       continuing on a new line</li>
</ol>

</ul>

<b>Here is a list with paragraph heading.</b>

<ul>
  <li> item1</li>
  <li> item2</li>
</ul>

<h3 id="here-is-a-list-with-subsubsection-heading">Here is a list with subsubsection heading </h3>

<ul>
  <li> item1</li>
  <li> item2</li>
</ul>

<blockquote>
    Here are two lines that make up a block quote for testing <em>emphasized words</em> and <b>boldface words</b>, also with hypens: <em>pre</em>-fix, post-<em>fix</em>, <b>pre</b>-fix, post-<b>fix</b>.
</blockquote>


<p>
Here are two references. Equation&nbsp;<b>(REF to equation my:eq1 not supported)</b> is fine. Eq.&nbsp;<b>(REF to equation my:eq1 not supported)</b> too. Even Equation <b>(REF to equation my:eq1 not supported)</b> without the tilde. This equation appears in another part if this document is split.

<p>
Let us add a paragraph to test that HTML, with WordPress (<code>--wordpress</code> option) can handle linebreaks <em>correctly</em>, even when lines begin with <b>bold words</b> and <code>verbatim words</code> in <font color="red">red color</font>, and <a href="https://google.com" target="_blank">links</a> as well as math: $latex 1+1=2$.

<p>
Test also that <em>emphasize</em> at the end of line, and <b>bold</b> works, as well as <font color="blue">color</font> and <a href="https://google.com" target="_blank">links2</a> and <code>verbatim</code> as well.

<h2 id="subsec1">Subsection 1</h2>

<p>
More text, with a reference back to the section <a href="#sec1">Section 1</a> and <a href="#subsec1">Subsection 1</a>, and further to the the sections <a href="#subsec1">Subsection 1</a> and <a href="#subsubsec:ex">URLs</a>, which encourages you to do the tasks in <a href="#demo:ex:1">Problem 2: Flip a Coin</a> and <a href="#exer:some:formula">Exercise 10: Make references to projects and problems</a>.  <a href="#app1">Appendix: Just for testing; part I</a> and <a href="#app2">Appendix: Just for testing; part II</a> are also nice elements.

<h3 id="test-section-reference-at-beginning-of-line-and-after-a-sentence">Test Section reference at beginning of line and after a sentence </h3>

<p>
The section <a href="#subsec1">Subsection 1</a> is fine. The section <a href="#subsubsec:ex">URLs</a> too.

<h3 id="computer-code">Computer code </h3>

<p>
Let's do some copying from files too. First from subroutine up to the very end,

<p>


<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>      <span style="color: #008000; font-weight: bold">subroutine </span>test()
      <span style="color: #B00040">integer </span>i
      <span style="color: #B00040">real</span><span style="color: #666666">*8</span> r
      r <span style="color: #666666">=</span> <span style="color: #666666">0</span>
      <span style="color: #008000; font-weight: bold">do </span>i <span style="color: #666666">=</span> <span style="color: #666666">1</span>, i
         r <span style="color: #666666">=</span> r <span style="color: #666666">+</span> i
      <span style="color: #008000; font-weight: bold">end do</span>
<span style="color: #008000; font-weight: bold">      return</span>
C     END1

      <span style="color: #008000; font-weight: bold">program </span>testme
      <span style="color: #008000; font-weight: bold">call </span>test()
      <span style="color: #008000; font-weight: bold">return</span>
</pre></div>
<p>
and then just the subroutine,
<p>


<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>      <span style="color: #008000; font-weight: bold">subroutine </span>test()
      <span style="color: #B00040">integer </span>i
      <span style="color: #B00040">real</span><span style="color: #666666">*8</span> r
      r <span style="color: #666666">=</span> <span style="color: #666666">0</span>
      <span style="color: #008000; font-weight: bold">do </span>i <span style="color: #666666">=</span> <span style="color: #666666">1</span>, i
         r <span style="color: #666666">=</span> r <span style="color: #666666">+</span> i
      <span style="color: #008000; font-weight: bold">end do</span>
<span style="color: #008000; font-weight: bold">      return</span>
</pre></div>
<p>
and finally the complete file with a plain text verbatim environment (<code>envir=ccq</code>):
<p>


<blockquote>
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>C     a comment

      subroutine test()
      integer i
      real*8 r
      r = 0
      do i = 1, i
         r = r + i
      end do
      return
C     END1

      program testme
      call test()
      return
</pre></div>
</blockquote><p>
Testing other code environments. First Python:

<p>


<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>!bc pycod
def f(x):
    return x+1
!ec
</pre></div>
<p>
which gets rendered as

<p>


<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">f</span>(x):
    <span style="color: #008000; font-weight: bold">return</span> x<span style="color: #666666">+1</span>
</pre></div>
<p>
Test paragraph and subsubsection headings before before code.

<p>
<b>Paragraph heading before code.</b>

<p>


<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">import</span> <span style="color: #0000FF; font-weight: bold">sys</span>
sys<span style="color: #666666">.</span>path<span style="color: #666666">.</span>insert(<span style="color: #666666">0</span>, os<span style="color: #666666">.</span>pardir)
</pre></div>

<h3 id="subsubsection-heading-before-code">Subsubsection heading before code </h3>

<p>


<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">h</span>(z):
    <span style="color: #008000; font-weight: bold">return</span> z<span style="color: #666666">+1</span>
</pre></div>
<p>
Now a complete program to be shown via Python Online Tutorial:

<p>

<iframe width="950" height="500" frameborder="0"
        src="https://pythontutor.com/iframe-embed.html#code=class+Line%3A%0A++++def+__init__%28self%2C+a%2C+b%29%3A%0A++++++++self.a%2C+self.b+%3D+a%2C+b%0A%0A++++def+__call__%28self%2C+x%29%3A%0A++++++++a%2C+b+%3D+self.a%2C+self.b%0A++++++++return+a%2Ax+%2B+b%0A%0Aline+%3D+Line%282%2C+1%29%0Ay+%3D+line%28x%3D3%29%0Aprint%28y%29&py=2&curInstr=0&cumulative=false">
</iframe>
<p>
Some more Python code (actually specified as a sage cell, but such cells are not supported by this format).

<p>


<div class="compute"><script type="text/x-sage">
a = 2
b = 3
print('a+b:', a + b)

# In a sage cell we can also plot
from matplotlib.pyplot import *
from numpy import *
x = linspace(0, 4*pi, 101)
y = exp(-0.1*x)*cos(x)
plot(x, y)
xlabel('x'); ylabel('y')
show()

</script></div>
<p>
Then Cython (with -h option so it is hidden in html/sphinx):

<p>



<script type="text/javascript">
function show_hide_code9(){
  $("#code9").toggle();
}
</script>
<button type="button" onclick="show_hide_code9()">Show/hide code</button>
<div id="code9" style="display:none">
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">cpdef</span> <span style="color: #0000FF">f</span>(double x):
    <span style="color: #008000; font-weight: bold">return</span> x <span style="color: #666666">+</span> <span style="color: #666666">1</span>
</pre></div>

</div>
<p>
Standard Python shell sessions:

<p>


<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #666666">&gt;&gt;&gt;</span> <span style="color: #008000; font-weight: bold">from</span> <span style="color: #0000FF; font-weight: bold">numpy</span> <span style="color: #008000; font-weight: bold">import</span> linspace, sin
<span style="color: #666666">&gt;&gt;&gt;</span> <span style="color: #408080; font-style: italic"># Some comment</span>
<span style="color: #666666">&gt;&gt;&gt;</span> x <span style="color: #666666">=</span> linspace(<span style="color: #666666">0</span>, <span style="color: #666666">2</span>, <span style="color: #666666">11</span>)
<span style="color: #666666">&gt;&gt;&gt;</span> y <span style="color: #666666">=</span> sin(x)
<span style="color: #666666">&gt;&gt;&gt;</span> y[<span style="color: #666666">0</span>]
<span style="color: #666666">0</span>
<span style="color: #666666">&gt;&gt;&gt;</span> <span style="color: #008000; font-weight: bold">import</span> <span style="color: #0000FF; font-weight: bold">matplotlib.pyplot</span> <span style="color: #008000; font-weight: bold">as</span> <span style="color: #0000FF; font-weight: bold">plt</span>
<span style="color: #666666">&gt;&gt;&gt;</span> plt<span style="color: #666666">.</span>plot(x, y)
</pre></div>
<p>
Similar IPython sessions:

<p>


<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #000080; font-weight: bold">In [1]: </span><span style="color: #008000; font-weight: bold">from</span> <span style="color: #0000FF; font-weight: bold">numpy</span> <span style="color: #008000; font-weight: bold">import</span> linspace, sin
<span style="color: #000080; font-weight: bold">In [2]: </span><span style="color: #408080; font-style: italic"># Some comment</span>
<span style="color: #000080; font-weight: bold">In [3]: </span>x <span style="color: #666666">=</span> linspace(<span style="color: #666666">0</span>, <span style="color: #666666">2</span>, <span style="color: #666666">11</span>)
<span style="color: #000080; font-weight: bold">In [4]: </span>y <span style="color: #666666">=</span> sin(x)
<span style="color: #000080; font-weight: bold">In [5]: </span>y[<span style="color: #666666">0</span>]
<span style="color: #000080; font-weight: bold">Out[5]: </span><span style="color: #888888">0</span>
<span style="color: #000080; font-weight: bold">In [6]: </span><span style="color: #008000; font-weight: bold">import</span> <span style="color: #0000FF; font-weight: bold">matplotlib.pyplot</span> <span style="color: #008000; font-weight: bold">as</span> <span style="color: #0000FF; font-weight: bold">plt</span>
<span style="color: #000080; font-weight: bold">In [7]: </span>plt<span style="color: #666666">.</span>plot(x, y)
<span style="color: #000080; font-weight: bold">In [8]: </span>a<span style="color: #666666">=</span><span style="color: #BA2121">&#39;multiple-</span><span style="color: #BB6622; font-weight: bold">\n</span><span style="color: #BA2121">line</span><span style="color: #BB6622; font-weight: bold">\n</span><span style="color: #BA2121">output&#39;</span>
<span style="color: #000080; font-weight: bold">In [9]: </span>a
<span style="color: #000080; font-weight: bold">Out[9]: </span><span style="color: #888888">&#39;multiple-\nline\noutput&#39;</span>
<span style="color: #000080; font-weight: bold">In [10]: </span><span style="color: #008000">print</span>(a)
<span style="color: #888888">multiple-</span>
<span style="color: #888888">line</span>
<span style="color: #888888">output</span>
</pre></div>
<p>
Here is the interactive session again, but with <code>pyshell-t</code>.

<p>


<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #666666">&gt;&gt;&gt;</span> <span style="color: #008000; font-weight: bold">from</span> <span style="color: #0000FF; font-weight: bold">numpy</span> <span style="color: #008000; font-weight: bold">import</span> linspace, sin
<span style="color: #666666">&gt;&gt;&gt;</span> <span style="color: #408080; font-style: italic"># Some comment</span>
<span style="color: #666666">&gt;&gt;&gt;</span> x <span style="color: #666666">=</span> linspace(<span style="color: #666666">0</span>, <span style="color: #666666">2</span>, <span style="color: #666666">11</span>)
<span style="color: #666666">&gt;&gt;&gt;</span> y <span style="color: #666666">=</span> sin(x)
<span style="color: #666666">&gt;&gt;&gt;</span> y[<span style="color: #666666">0</span>]
<span style="color: #666666">0</span>
<span style="color: #666666">&gt;&gt;&gt;</span> <span style="color: #008000; font-weight: bold">import</span> <span style="color: #0000FF; font-weight: bold">matplotlib.pyplot</span> <span style="color: #008000; font-weight: bold">as</span> <span style="color: #0000FF; font-weight: bold">plt</span>
<span style="color: #666666">&gt;&gt;&gt;</span> plt<span style="color: #666666">.</span>plot(x, y)
</pre></div>
<p>

C++:
<p>


<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #BC7A00">#include</span> <span style="color: #408080; font-style: italic">&lt;iostream&gt;</span><span style="color: #BC7A00"></span>

<span style="color: #B00040">int</span> <span style="color: #0000FF">main</span>()
{
   std<span style="color: #666666">::</span>cout <span style="color: #666666">&lt;&lt;</span> <span style="color: #BA2121">&quot;Sample output&quot;</span> <span style="color: #666666">&lt;&lt;</span> std<span style="color: #666666">::</span>endl;
   <span style="color: #008000; font-weight: bold">return</span> <span style="color: #666666">0</span>
}
</pre></div>
<p>


And a little bit of Fortran: <img src="https://raw.githubusercontent.com/hplgit/doconce/master/bundled/emoji/png/dizzy_face.png" width="22px" height="22px" align="center">

<p>


<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>!bc cod
      subroutine midpt(x, length, a, b)
      real*8 a, b, x
      x = (a + b)/2
      length = b - a
      return
      end
!ec
</pre></div>
<p>
which then is typeset as

<p>


<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>      subroutine midpt(x, length, a, b)
      real*8 a, b, x
      x = (a + b)/2
      length = b - a
      return
      end
</pre></div>
<p>
HTML:

<p>


<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>&lt;<span style="color: #008000; font-weight: bold">table</span>&gt;
&lt;<span style="color: #008000; font-weight: bold">tr</span>&gt;&lt;<span style="color: #008000; font-weight: bold">td</span>&gt;Column 1&lt;/<span style="color: #008000; font-weight: bold">td</span>&gt;&lt;<span style="color: #008000; font-weight: bold">td</span>&gt;Column 2&lt;/<span style="color: #008000; font-weight: bold">td</span>&gt;&lt;/<span style="color: #008000; font-weight: bold">tr</span>&gt;
&lt;<span style="color: #008000; font-weight: bold">tr</span>&gt;&lt;<span style="color: #008000; font-weight: bold">td</span>&gt;0.67526 &lt;/<span style="color: #008000; font-weight: bold">td</span>&gt;&lt;<span style="color: #008000; font-weight: bold">td</span>&gt;0.92871 &lt;/<span style="color: #008000; font-weight: bold">td</span>&gt;&lt;/<span style="color: #008000; font-weight: bold">tr</span>&gt;
<span style="color: #408080; font-style: italic">&lt;!-- comment --&gt;</span>
&lt;/<span style="color: #008000; font-weight: bold">table</span>&gt;
</pre></div>
<p>
But inline HTML code is also important, like text that starts with <code>&lt;a href=&quot;</code> (which can destroy the following text if not properly quoted).

<p>
Matlab with comments requires special typesetting:

<p>


<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #408080; font-style: italic">% Comment on the beginning of the line can be escaped by %%</span>
<span style="color: #008000; font-weight: bold">if</span> a <span style="color: #666666">&gt;</span> b
  <span style="color: #408080; font-style: italic">% Indented comment needs this trick</span>
  c = a <span style="color: #666666">+</span> b
<span style="color: #008000; font-weight: bold">end</span>
</pre></div>
<p>
And here is a system call:

<p>


<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>Terminal&gt; mkdir test
Terminal&gt; cd test
Terminal&gt; myprog -f
output1
output2
</pre></div>
<p>
Any valid pygments lexer/language name can appear to, e.g.,

<p>


<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>!bc restructuredtext
=======
Heading
=======

Some text.
!ec
</pre></div>
<p>
results in

<p>


<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #000080; font-weight: bold">=======</span>
<span style="color: #000080; font-weight: bold">Heading</span>
<span style="color: #000080; font-weight: bold">=======</span>

Some text.
</pre></div>
<p>
Finally, <code>!bc do</code> supports highlighting of DocOnce source:

<p>


<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #000080; font-weight: bold">======= DocOnce test file =======</span>

<span style="color: #000080; font-weight: bold">===== Computer code =====</span>

Inline verbatim code, as in `import numpy as np`, is allowed, as well as
code blocks:

!bc pycod
from math import sin

def f(x):
    &quot;&quot;&quot;Example on a function.&quot;&quot;&quot;
    return sin(x) + 1

print(f(0))
!ec


<span style="color: #000080; font-weight: bold">===== Mathematics =====</span>

Formulas can be inline, as in $\nabla\cdot\boldsymbol{u} = 0$, or typeset
as equations:

!bt
<span style="color: #008000">\begin{align*}</span>
\nabla\cdot\boldsymbol{u} &amp;= 0,\\ 
\boldsymbol{u} &amp;= \nabla\phi .
<span style="color: #008000">\end{align*}</span>
!et

<span style="color: #000080; font-weight: bold">=== Subsubsection heading ===</span>

DocOnce files can have chapters, sections, subsections, and subsubsections.

<span style="color: #800080; font-weight: bold">__Paragraph heading.__</span> Paragraphs may have headings.
</pre></div>
<p>
It is time to test <code>verbatim inline font</code> especially with <code>a newline inside the text</code> and an exclamation mark at the end: <code>BEGIN</code>! For spellcheck, test <code>a verbatim expression</code> in <code>another</code> in a <code>third</code>. Also test exclamation mark as in <code>!bc</code> and <code>!ec</code> as well as <code>a != b</code>. Also test backslashes and braces like <code>\begin</code>, <code>\begin{enumerate}</code>, <code>\end{this}\end{that}</code>, and <code>{something \inside braces}</code>.

<p>
Here is some <font color="red">red color</font> and an attempt to write <font color="green">with green color containing a linebreak<br />
code.</font> Some formats will only display <br />
this correctly when <code>html</code> <br />
is the output format. But here some more running text is added which is not part of the previous blocks with line breaks.

<h3 id="running-os-commands">Running OS commands </h3>

<p>


<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>Terminal&gt; python -c &#39;print(&quot;Testing\noutput\nfrom\nPython.&quot;)&#39;
Testing
output
from
Python.
</pre></div>

<h3 id="footnotes">Footnotes </h3>

<p>
Here is a test of footnotes [<a id="link_footnote_1" href="#def_footnote_1">1</a>], which are handy in text. They are used in different flavors, now in

<ul>
 <li> list items (note below that footnotes work after math, verbatim, and URLs - bin fact old and emphasize too!)</li>
 <li> even with math $latex \nabla^2u$ [<a id="link_footnote_2" href="#def_footnote_2">2</a>]</li>
 <li> and code <code>h[i] += 1</code> [<a id="link_footnote_3" href="#def_footnote_3">3</a>]    (<em>must</em> have space between inline code and footnote!)</li>
 <li> and <a href="https://google.com" target="_blank">links</a> [<a id="link_footnote_4" href="#def_footnote_4">4</a>]</li>
</ul>

which gives flexibility in writing. This is the third [<a id="link_footnote_5" href="#def_footnote_5">5</a>] example.

<p id="def_footnote_1"><a href="#link_footnote_1"><b>1:</b></a> Typesetting of the footnote depends on the format. Plain text does nothing, LaTeX removes the definition and inserts the footnote as part of the LaTeX text. reStructuredText and Sphinx employ a similar type of typesetting as Extended Markdown and DocOnce, and in HTML we keep the same syntax, just displayed properly in HTML.</p>

<p id="def_footnote_2"><a href="#link_footnote_2"><b>2:</b></a> Math footnotes can be dangerous since it interferes with an exponent.</p>

<p id="def_footnote_3"><a href="#link_footnote_3"><b>3:</b></a> One-line footnote.</p>

<p id="def_footnote_4"><a href="#link_footnote_4"><b>4:</b></a> <a href="google.com" target="_blank"><tt>google.com</tt></a> is perhaps the most famous web site today.</p>

<p>
Here is some more text before a new definition of a footnote that was used above.

<p>
<div class="alert alert-block alert-notice alert-text-normal">
<b>Non-breaking space character</b>
<p>
This paragraph aims to test <a href="https://en.wikipedia.org/wiki/Non-breaking_space" target="_blank">non-breaking space character</a>, and a typical example where this is needed is in physical units: 7.4&nbsp;km is traveled in&nbsp;$latex 7.4/5.5\approx 1.345$&nbsp;s.  Also check that a&nbsp;<a href="https://google.com" target="_blank">link</a>&nbsp;is not broken across lines (drag the browser window to test this). (On the other hand, the tilde is used in computer code, e.g., as in <code>[~x for x in y]</code> or in <code>y=~x</code>, and should of course remain a tilde in those contexts.)
</div>


<h2 id="subsec:ex">Subsection 2: Testing figures</h2>

<p>
Test of figures. In particular we refer to Figure <a href="#fig:impact">1</a> in which there is a flow.

<p>
<center>  <div id="fig:impact"></div> 
<hr class="figure">
<center><p class="caption">Figure 1:  Visualization <b>of</b> a <em>wave</em>.   </p></center>
<p><img src="https://raw.github.com/hplgit/doconce/master/test/../doc/src/manual/fig/wave1D.html" align="bottom" width=200></p>
</center>

<p>
Figures without captions are allowed and will be inlined.

<p>
<br /><br /><center><p><img src="https://raw.github.com/hplgit/doconce/master/test/../doc/src/manual/fig/wave1D.html" align="bottom" width=200></p></center><br /><br />

<p>
Here is figure <a href="#myfig">2</a> with a long (illegal) multi-line caption containing inline verbatim text:

<p>
<center>  <div id="myfig"></div> 
<hr class="figure">
<table><tr>
<td><img src="https://raw.github.com/hplgit/doconce/master/test/../doc/src/manual/fig/wave1D.png" align="bottom" width=500></td>
<td><p class="caption">Figure 2:  A long caption spanning several lines and containing verbatim words like <code>my_file_v1</code> and <code>my_file_v2</code> as well as math with subscript as in $latex t_{i+1}$.   </p></td>
</tr></table>
</center>

<p>
Test URL as figure name:

<p>
<br /><br /><center><p><img src="https://raw.github.com/doconce/doconce/master/doc/src/blog/f_plot.png" align="bottom" width=500></p></center><br /><br />

<p>
Test SVG figure:

<p>
<br /><br /><center><p><img src="https://openclipart.org/people/jpneok/junebug.svg" align="bottom" width=200></p></center><br /><br />

<p>
HTML output may feature Bokeh plots:

<p>
<br /><br /><center><p><img src="https://raw.github.com/hplgit/doconce/master/test/bokeh_test.html" align="bottom" ></p></center><br /><br />

<p>
<b>Remark.</b> Movies are tested in separate file <code>movies.do.txt</code>.

<h2 id="decay:sec:theta">The $latex \theta$ parameter (not $latex \nabla$?)</h2>

<p>
Functions do not always need to be advanced, here is one involving $latex \theta$:
<p>


<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>def f(theta):
    return theta**2
</pre></div>
<p>
<b>More on $latex \theta$.</b> Here is more text following headline with math.

<p>
Newcommands must also be tested in this test report: $latex \frac{1}{2}$, $latex {1/2}$, $latex \pmb{x}$, $latex \frac{Du}{dt}$, both inline and in block:

<p>

$latex 
\frac{Du}{dt} = 0\nonumber
 $

$latex  
\frac{1}{2} = {1/2}
 $

$latex  
\frac{1}{2}\pmb{x} = \pmb{n}

 $

<p>
Or with align with label and numbers:

<p>

$latex 
\frac{Du}{dt} = 0

 $

$latex  
\frac{1}{2} = {1/2}
 $

$latex  
\frac{1}{2}\pmb{x} = \pmb{n}

 $

<p>
First one numbered (automatically):

<p>

$latex 
\begin{pmatrix}
G_2 + G_3  -G_3  -G_2  0  $

$latex  
-G_3  G_3 + G_4  0  -G_4  $

$latex  
-G_2  0  G_1 + G_2  0  $

$latex  
0  -G_4  0  G_4
\end{pmatrix}
=
\begin{pmatrix}
 v_1  $

$latex  
 v_2  $

$latex  
 v_3  $

$latex  
 v_4
\end{pmatrix}
+ \cdots  
 $

$latex  
\begin{pmatrix}
 C_5 + C_6  -C_6  0  0  $

$latex  
 -C_6  C_6  0  0  $

$latex  
 0  0  0  0  $

$latex  
 0  0  0  0
\end{pmatrix}
  = \frac{d}{dt}\begin{pmatrix}
 v_1  $

$latex  
 v_2  $

$latex  
 v_3  $

$latex  
 v_4
\end{pmatrix} +
\begin{pmatrix}
 0  $

$latex  
 0  $

$latex  
 0  $

$latex  
 -i_0
\end{pmatrix}
\nonumber

 $

<p>
Second numbered (automatically):

<p>

$latex 
\begin{pmatrix}
G_1 + G_2 $

$latex  
-G_3  G_4
\end{pmatrix}
=
\begin{pmatrix}
 v_1  $

$latex  
 v_2
\end{pmatrix}
+ \cdots\nonumber

 $

$latex  
\left(\begin{array}{ll}
y  2 $

$latex  
2  1
\end{array}\right)
\left(\begin{array}{ll}
0  $

$latex  x
\end{array}\right)
= \begin{pmatrix}
A  $

$latex  B
\end{pmatrix}

 $

<p>
Both numbered, with label by the user:

<p>

$latex 
\begin{pmatrix}
G_1 + G_2 $

$latex  
-G_3  G_4
\end{pmatrix}
=
\begin{pmatrix}
 v_1  $

$latex  
 v_2
\end{pmatrix}
+ \cdots 
 $

$latex  

\left(\begin{array}{ll}
y  2 $

$latex  
2  1
\end{array}\right)
\left(\begin{array}{ll}
0  $

$latex  x
\end{array}\right)
= \begin{pmatrix}
A  $

$latex  B
\end{pmatrix}
 $

Now we refer to <b>(REF to equation mymatrix:eq1 not supported)</b>-<b>(REF to equation mymatrix:eq2 not supported)</b>.

<h2 id="custom-environments">Custom Environments </h2>

<p>
Here is an attempt to create a theorem environment via Mako (for counting theorems) and comment lines to help replacing lines in the <code>.tex</code> by proper begin-end LaTeX environments for theorems. Should look nice in most formats!

<p>

<div id="theorem:fundamental1"></div>

<p>
<b>Theorem 5.</b> Let $latex a=1$ and $latex b=2$. Then $latex c=3$.

<p>

<b>Proof.</b> Since $latex c=a+b$, the result follows from straightforward addition. $latex latex \Diamond$

<p>
As we see, the proof of Theorem 5 is a modest achievement.

<h2 id="subsec:table">Tables</h2>

<p>
Let us take this table from the manual:

<p>
<table border="1">
<thead>
<tr><th align="center">time</th> <th align="center">velocity</th> <th align="center">acceleration</th> </tr>
</thead>
<tbody>
<tr><td align="left">   0.0     </td> <td align="right">   1.4186      </td> <td align="right">   -5.01           </td> </tr>
<tr><td align="left">   2.0     </td> <td align="right">   1.376512    </td> <td align="right">   11.919          </td> </tr>
<tr><td align="left">   4.0     </td> <td align="right">   1.1E+1      </td> <td align="right">   14.717624       </td> </tr>
</tbody>
</table>
<p>
The DocOnce source code reads
<p>


<blockquote>
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>  |--------------------------------|
  |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>
</blockquote><p>
Here is yet another table to test that we can handle more than one table:

<p>
<table border="1">
<thead>
<tr><th align="left">time</th> <th align="left">velocity</th> <th align="left">acceleration</th> </tr>
</thead>
<tbody>
<tr><td align="left">   0.0     </td> <td align="left">   1.4186      </td> <td align="left">   -5.01           </td> </tr>
<tr><td align="left">   1.0     </td> <td align="left">   1.376512    </td> <td align="left">   11.919          </td> </tr>
<tr><td align="left">   3.0     </td> <td align="left">   1.1E+1      </td> <td align="left">   14.717624       </td> </tr>
</tbody>
</table>
<p>
And one with math headings (that are expanded and must be treated accordingly), verbatim heading and entry, and no space around the pipe symbol:

<p>
<table border="1">
<thead>
<tr><th align="center">$latex i$</th> <th align="center">$latex h_i$</th> <th align="center">$latex \bar T_i$</th> <td align="center"><code>L_i</code></td> </tr>
</thead>
<tbody>
<tr><td align="left">   0            </td> <td align="right">   0              </td> <td align="right">   288                 </td> <td align="right">   -0.0065             </td> </tr>
<tr><td align="left">   1            </td> <td align="right">   11,000         </td> <td align="right">   216                 </td> <td align="right">   0.0                 </td> </tr>
<tr><td align="left">   2            </td> <td align="right">   20,000         </td> <td align="right">   216                 </td> <td align="right">   0.001               </td> </tr>
<tr><td align="left">   3            </td> <td align="right">   32,000         </td> <td align="right">   228                 </td> <td align="right">   0.0028              </td> </tr>
<tr><td align="left">   4            </td> <td align="right">   47,000         </td> <td align="right">   270                 </td> <td align="right">   0.0                 </td> </tr>
<tr><td align="left">   5            </td> <td align="right">   51,000         </td> <td align="right">   270                 </td> <td align="right">   -0.0028             </td> </tr>
<tr><td align="left">   6            </td> <td align="right">   71,000         </td> <td align="right">   214                 </td> <td align="right">   <code>NaN</code>    </td> </tr>
</tbody>
</table>
<p>
And add one with verbatim headings (with underscores), and rows starting with <code>|-</code> because of a negative number, and <code>|</code> right before and after verbatim word (with no space):

<p>
<table border="1">
<thead>
<tr><th align="center">exact</th> <td align="center"><code>v_1</code></td> <td align="center">$latex a_i$ + <code>v_2</code></td> <td align="center"><code>verb_3_</code></td> </tr>
</thead>
<tbody>
<tr><td align="right">   9        </td> <td align="right">   9.62                </td> <td align="right">   5.57                              </td> <td align="right">   8.98                    </td> </tr>
<tr><td align="right">   -20      </td> <td align="right">   -23.39              </td> <td align="right">   -7.65                             </td> <td align="right">   -19.93                  </td> </tr>
<tr><td align="right">   10       </td> <td align="right">   17.74               </td> <td align="right">   -4.50                             </td> <td align="right">   9.96                    </td> </tr>
<tr><td align="right">   0        </td> <td align="right">   -9.19               </td> <td align="right">   4.13                              </td> <td align="right">   -0.26                   </td> </tr>
</tbody>
</table>
<p>
Pipe symbols in verbatim and math text in tables used to pose difficulties, but not anymore:

<p>
<table border="1">
<thead>
<tr><th align="center">   $latex S$   </th> <th align="center">        command         </th> </tr>
</thead>
<tbody>
<tr><td align="left">   $ ||a_0|| $        </td> <td align="right">   <code>norm|length</code>    </td> </tr>
<tr><td align="left">   $latex x\cap y$    </td> <td align="right">   <code>x|y</code>            </td> </tr>
</tbody>
</table>
<p>
Here is a table with X alignment:

<p>
<table border="1">
<thead>
<tr><th align="center"> Type</th> <th align="center">                                                                                                                Description                                                                                                                 </th> </tr>
</thead>
<tbody>
<tr><td align="center">   X        </td> <td align="left">   Alignment character that is used for specifying a potentially very long text in a column in a table. It makes use of the <code>tabularx</code> package in LaTeX, otherwise (for other formats) it means <code>l</code> (centered alignment).    </td> </tr>
<tr><td align="center">   l,r,c    </td> <td align="left">   standard alignment characters                                                                                                                                                                                                                   </td> </tr>
</tbody>
</table>
<p>
Finally, a table with math (<code>bm</code> that expands to <code>boldsymbol</code>, was tricky, but cleanly handled now) and URLs.

<p>
<table border="1">
<tr></tr>
<tbody>
<tr><td align="center">   $latex \mathcal{L}=0$                    </td> <td align="center">   <a href="../doc/src/manual/mov/wave_frames/frame_0080.png"><img src="../doc/src/manual/mov/wave_frames/frame_0080.png" width="300"></a>    </td> <td align="center">   <a href="../doc/src/manual/mov/wave_frames/frame_0085.png"><img src="../doc/src/manual/mov/wave_frames/frame_0085.png" width="300"></a>    </td> </tr>
<tr><td align="center">   $latex a=b$                              </td> <td align="center">   <a href="../doc/src/manual/mov/wave_frames/frame_0090.png"><img src="../doc/src/manual/mov/wave_frames/frame_0090.png" width="300"></a>    </td> <td align="center">   <a href="../doc/src/manual/mov/wave_frames/frame_0095.png"><img src="../doc/src/manual/mov/wave_frames/frame_0095.png" width="300"></a>    </td> </tr>
<tr><td align="center">   $latex \nabla\cdot\boldsymbol{u} =0 $    </td> <td align="center">   <a href="../doc/src/manual/mov/wave_frames/frame_0100.png"><img src="../doc/src/manual/mov/wave_frames/frame_0100.png" width="300"></a>    </td> <td align="center">   <a href="../doc/src/manual/mov/wave_frames/frame_0105.png"><img src="../doc/src/manual/mov/wave_frames/frame_0105.png" width="300"></a>    </td> </tr>
</tbody>
</table>

<h2 id="a-test-of-verbatim-words-in-heading-with-subscript-a_i-my_file_v1-and-my_file_v2">A test of verbatim words in heading with subscript $latex a_i$: <code>my_file_v1</code> and <code>my_file_v2</code> </h2>

<p>
<b>Paragraph with verbatim and math: <code>my_file_v1.py</code> and <code>my_file_v2.py</code> define some math $latex a_{i-1}$.</b> Here is more <code>__verbatim__</code> code and some plain text on a new line.

<h2 id="_just-bold_"><b>Just bold</b> </h2>

<p>
Some text.

<h2 id="just-emphasize"><em>Just emphasize</em> </h2>

<p>
Some text.

<h2 id="just-verbatim"><code>Just verbatim</code> </h2>

<p>
Some text.

<h2 id="_bold_-beginning"><b>Bold</b> beginning </h2>

<p>
Some text.

<h2 id="emphasize-beginning"><em>Emphasize</em> beginning </h2>

<p>
Some text.

<h2 id="verbatim-beginning"><code>Verbatim</code> beginning </h2>

<p>
Some text.

<h2 id="maybe-_bold-end_">Maybe <b>bold end</b> </h2>

<p>
Some text.

<h2 id="maybe-emphasize-end">Maybe <em>emphasize end</em> </h2>

<p>
Some text.

<h2 id="maybe-verbatim-end">Maybe <code>verbatim end</code> </h2>

<p>
Some text.

<h2 id="the-middle-has-<b>bold</b>-word">The middle has <b>bold</b> word </h2>

<p>
Some text.

<h2 id="the-middle-has-emphasize-word">The middle has <em>emphasize</em> word </h2>

<p>
Some text.

<h2 id="the-middle-has-verbatim-word">The middle has <code>verbatim</code> word </h2>

<p>
Some text.

<p>
<b><em>Just emphasize</em>.</b> Some text.

<p>
<b><code>Just verbatim</code>.</b> Some text.

<p>
<b><em>Emphasize</em> beginning.</b> Some text.

<p>
<b><code>Verbatim beginning</code>.</b> Some text.

<p>
<b>Maybe <em>emphasize end</em>.</b> Some text.

<p>
<b>Maybe <code>verbatim end</code>.</b> Some text.

<p>
<b>The middle has <em>emphasize</em> word.</b> Some text.

<p>
<b>The middle has <code>verbatim</code> word.</b> Some text.

<p>
<b>Ampersand.</b> We can test Hennes &amp; Mauritz, often abbreviated H&amp;M, but written as <code>Hennes & Mauritz</code> and <code>H & M</code>. A sole <code>&</code> must also work.

<p>


<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span># Just to check that ampersand works in code blocks:
c = a &amp; b
</pre></div>
<p>
<b>Quotes.</b> Let us also add a test of quotes such as &quot;double quotes, with numbers like 3.14 and newline/comma and hyphen (as in double-quote)&quot;; written in the standard LaTeX-style that gives correct LaTeX formatting and ordinary double quotes for all non-LaTeX formats.  Here is another sentence that &quot;caused&quot; a bug in the past because double backtick quotes could imply verbatim text up to a verbatim word starting with period, like <code>.txt</code>.

<p>
More quotes to be tested for spellcheck: (&quot;with parenthesis&quot;), &quot;with newline&quot; and &quot;with comma&quot;, &quot;hyphen&quot;-wise, and &quot;period&quot;.

<h2 id="bibliography-test">Bibliography test </h2>

<p>
Here is an example: <a href="#Langtangen_Pedersen_2002">[1]</a> discussed propagation of large destructive water waves, <a href="#Langtangen_et_al_2002">[2]</a> gave an overview of numerical methods for solving the Navier&ndash;Stokes equations, while the use of Backward Kolmogorov equations for analyzing random vibrations was investigated in <a href="#Langtangen_1994a">[3]</a>. The book chapter <a href="#Mardal_et_al_2003a">[4]</a> contains information on C++ software tools for programming multigrid methods. A real retro reference is <a href="#Langtangen_1988d">[5]</a> about a big FORTRAN package. Multiple references are also possible, e.g., see <a href="#Langtangen_Pedersen_2002">[1]</a> <a href="#Mardal_et_al_2003a">[4]</a>.

<p>
We need to cite more than 10 papers to reproduce an old formatting problem with blanks in the keys in reST format: <a href="#Langtangen_1992c">[6]</a> <a href="#Langtangen_1994a">[3]</a> <a href="#Mortensen_et_al_2011">[7]</a> <a href="#Langtangen_Pedersen_2002">[1]</a> and <a href="#Langtangen_et_al_2002">[2]</a> <a href="#Glimsdal_et_al_20006">[8]</a> <a href="#Rahman_et_al_2006b">[9]</a> <a href="#Haga_et_al_2011a">[10]</a> <a href="#Langtangen_2003a">[11]</a> <a href="#Langtangen_2008a">[12]</a> <a href="#Langtangen:95">[13]</a> and all the work of <a href="#Langtangen_2012">[14]</a> <a href="#Mardal_et_al_2003a">[4]</a> <a href="#Jeberg_et_al_2004">[15]</a> as well as old work <a href="#Langtangen_1988d">[5]</a> and <a href="#Langtangen_1989e">[16]</a>, and the talk <a href="#Langtangen_talk_2007a">[17]</a>. Langtangen also had two thesis <a href="#Langtangen:85">[18]</a> <a href="#Langtangen_1989e">[16]</a> back in the days. More retro citations are the old ME-IN323 book <a href="#Langtangen:91">[19]</a> and the <a href="#Langtangen:94b">[20]</a> OONSKI '94 paper.

<h2 id="Example">Example 1: Examples can be typeset as exercises</h2>

<p>
Examples can start with a subsection heading starting with <code>Example:</code> and then, with the command-line option <code>--examples_as_exercises</code> be typeset as exercises. This is useful if one has solution environments as part of the example.

<p>
<b>a)</b> State some problem.

<p>
<b>Solution.</b> The answer to this subproblem can be written here.

<p>
<b>b)</b> State some other problem.

<p>
<b>Hint 1.</b> A hint can be given.

<p>
<b>Hint 2.</b> Maybe even another hint?

<p>
<b>Solution.</b> The answer to this other subproblem goes here, maybe over multiple doconce input lines.

<h2 id="user-defined-environments">User-defined environments </h2>

<p>
The example in the section <a href="#ex:test:1p1">Example 1: A test function</a> demonstrates how to write a test function. That is, a special test function for a function <code>add</code> appears in the example in the section <a href="#ex:test:1p1">Example 1: A test function</a>.

<h2 id="ex:test:1p1">Example 1: A test function</h2>

<p>
Suppose we want to write a test function for checking the implementation of a Python function for addition.

<p>


<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">add</span>(a, b):
    <span style="color: #008000; font-weight: bold">return</span> a <span style="color: #666666">+</span> b

<span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">test_add</span>():
    a <span style="color: #666666">=</span> <span style="color: #666666">1</span>; b <span style="color: #666666">=</span> <span style="color: #666666">1</span>
    expected <span style="color: #666666">=</span> a <span style="color: #666666">+</span> b
    computed <span style="color: #666666">=</span> add(a, b)
    <span style="color: #008000; font-weight: bold">assert</span> expected <span style="color: #666666">==</span> computed
</pre></div>

<h2 id="ex:math:1p1">Example 2: Addition</h2>

<p>
We have

<p>

$latex  1 + 1 = 2  $


or in tabular form:

<p>
<table border="1">
<thead>
<tr><th align="center">  Problem  </th> <th align="center">  Result </th> </tr>
</thead>
<tbody>
<tr><td align="center">   $latex 1+1$    </td> <td align="center">   $latex 2$    </td> </tr>
</tbody>
</table>
<p>
<div style="width: 60%; padding: 10px; border: 1px solid #000;
 border-radius: 4px; box-shadow: 8px 8px 5px #888888;
 background: #cce5ff;">
 <b>Highlight box!</b><hr>
This environment is used to highlight something:

<p>

$latex  E = mc^2  $


</div>

<h2 id="subsubsec:ex">URLs</h2>

<p>
Testing of URLs: hpl's home page <a href="https://folk.uio.no/hpl" target="_blank">hpl</a>, or the entire URL if desired, <a href="https://folk.uio.no/hpl" target="_blank"><tt>https://folk.uio.no/hpl</tt></a>.  Here is a plain file link <a href="testdoc.do.txt" target="_blank"><tt>testdoc.do.txt</tt></a>, or <a href="testdoc.do.txt" target="_blank"><tt>testdoc.do.txt</tt></a>, or <a href="testdoc.do.txt" target="_blank"><tt>testdoc.do.txt</tt></a> or <a href="testdoc.do.txt" target="_blank"><tt>testdoc.do.txt</tt></a> or <a href="testdoc.do.txt" target="_blank">a link with newline</a>. Can test spaces with the link with word too: <a href="https://folk.uio.no/hpl" target="_blank">hpl</a> or <a href="https://folk.uio.no/hpl" target="_blank">hpl</a>. Also <code>file:///</code> works: <a href="file:///home/hpl/vc/doconce/doc/demos/manual/manual.html" target="_blank">link to a file</a> is fine to have. Moreover, &quot;loose&quot; URLs work, i.e., no quotes, just the plain URL as in <a href="https://folk.uio.no/hpl" target="_blank"><tt>https://folk.uio.no/hpl</tt></a>, if followed by space, comma, colon, semi-colon, question mark, exclamation mark, but not a period (which gets confused with the periods inside the URL).

<p>
Mail addresses can also be used: <a href="mailto:hpl@simula.no" target="_blank"><tt>hpl@simula.no</tt></a>, or just a <a href="mailto:hpl@simula.no" target="_blank">mail link</a>, or a raw <a href="mailto:hpl@simula.no" target="_blank"><tt>mailto:hpl@simula.no</tt></a>.

<p>
Here are some tough tests of URLs, especially for the <code>latex</code> format: <a href="https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas" target="_blank">Newton-Cotes</a> formulas and a <a href="https://www.springer.com/mathematics/computational+science+%26+engineering/book/978-3-642-23098-1" target="_blank">good book</a>. Need to test Newton-Cotes with percentage in URL too: <a href="https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas" target="_blank"><tt>https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas</tt></a> and <a href="https://en.wikipedia.org/wiki/Newton-Cotes#Open_Newton.E2.80.93Cotes_formulae" target="_blank"><tt>https://en.wikipedia.org/wiki/Newton-Cotes#Open_Newton.E2.80.93Cotes_formulae</tt></a> which has a shebang.

<p>
For the <code>--device=paper</code> option it is important to test that URLs with monospace font link text get a footnote (unless the <code>--latex_no_program_footnotelink</code> is used), as in this reference to <a href="https://github.com/hplgit/INF5620/tree/gh-pages/src/decay/experiments/decay_mod.py" target="_blank"><tt>decay_mod</tt></a>, <a href="https://tinyurl.com/pwyasaa/formulas.ball1.py" target="_blank"><tt>ball1.py</tt></a>, and <a href="https://tinyurl.com/pwyasaa/formulas.ball2.py" target="_blank"><tt>ball2.py</tt></a>.

<p>
More tough tests: repeated URLs whose footnotes when using the <code>--device=paper</code> option must be correct. We have <a href="https://google.com" target="_blank">google</a>, <a href="https://google.com" target="_blank">google</a>, and <a href="https://google.com" target="_blank">google</a>, which should result in exactly three footnotes.

<h1 id="latex-mathematics">LaTeX Mathematics </h1>

<p>
Here is an equation without label using backslash-bracket environment:

$latex  a = b + c  $

<p>
or with number and label, as in <b>(REF to equation my:eq1 not supported)</b>, using the equation environment:

<p>

$latex 
{\partial u\over\partial t} = \nabla^2 u 
 $

<p>
We can refer to this equation by <b>(REF to equation my:eq1 not supported)</b>.

<p>
Here is a system without equation numbers, using the align-asterisk environment:

<p>

$latex 
\pmb{a} = \pmb{q}\times\pmb{n}  $

$latex  
b = \nabla^2 u + \nabla^4 v
 $

<p>
And here is a system of equations with labels in an align environment:

<p>

$latex 
a = q + 4 + 5+ 6   $

$latex  
b = \nabla^2 u + \nabla^4 x 
 $



We can refer to <b>(REF to equation eq1 not supported)</b>-<b>(REF to equation eq2 not supported)</b>. They are a bit simpler than the Navier&ndash;Stokes equations. And test LaTeX hyphen in <code>CG-2</code>. Also test $latex a_{i-j}$ as well as $latex kx-wt$.

<p>
Testing <code>alignat</code> environment:

<p>

\begin{alignat}{2}
a = q + 4 + 5+ 6\qquad  \mbox{for } q\geq 0   $

$latex  
b = \nabla^2 u + \nabla^4 x  x\in\Omega 
\end{alignat}

<p>
More mathematical typesetting is demonstrated in the coming exercises.

<p>
Below, we have <a href="#demo:ex:1">Problem 2: Flip a Coin</a> and <a href="#demo:ex:2">Project 4: Compute a Probability</a>, as well as <a href="#proj:circle1">Project 5: Explore Distributions of Random Circles</a> and <a href="#exer:you">Project 11: References in a headings do not work well in html</a>, and in between there we have <a href="#exer:some:formula">Exercise 10: Make references to projects and problems</a>.

<h1 id="exercises">Exercises </h1>

<h2 id="demo:ex:1">Problem 2: Flip a Coin</h2>

<p>
<b>a)</b> Make a program that simulates flipping a coin $latex N$ times. Print out &quot;tail&quot; or &quot;head&quot; for each flip and let the program count the number of heads.

<p>
<b>Hint 1.</b> Use <code>r = random.random()</code> and define head as <code>r &lt;= 0.5</code>.

<p>
<b>Hint 2.</b> Draw an integer among $latex \{1,2\}$ with <code>r = random.randint(1,2)</code> and define head when <code>r</code> is 1.

<p>

<b>Answer.</b> If the <code>random.random()</code> function returns a number $latex <1/2$, let it be head, otherwise tail. Repeat this $latex N$ number of times.

<p>

<b>Solution.</b>
<p>


<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">import</span> <span style="color: #0000FF; font-weight: bold">sys</span><span style="color: #666666">,</span> <span style="color: #0000FF; font-weight: bold">random</span>
N <span style="color: #666666">=</span> <span style="color: #008000">int</span>(sys<span style="color: #666666">.</span>argv[<span style="color: #666666">1</span>])
heads <span style="color: #666666">=</span> <span style="color: #666666">0</span>
<span style="color: #008000; font-weight: bold">for</span> i <span style="color: #AA22FF; font-weight: bold">in</span> <span style="color: #008000">range</span>(N):
    r <span style="color: #666666">=</span> random<span style="color: #666666">.</span>random()
    <span style="color: #008000; font-weight: bold">if</span> r <span style="color: #666666">&lt;=</span> <span style="color: #666666">0.5</span>:
        heads <span style="color: #666666">+=</span> <span style="color: #666666">1</span>
<span style="color: #008000">print</span>(<span style="color: #BA2121">&#39;Flipping a coin </span><span style="color: #BB6688; font-weight: bold">%d</span><span style="color: #BA2121"> times gave </span><span style="color: #BB6688; font-weight: bold">%d</span><span style="color: #BA2121"> heads&#39;</span> <span style="color: #666666">%</span> (N, heads))
</pre></div>
<p>
<b>b)</b> Vectorize the code in a) using boolean indexing.

<p>
Vectorized code can be written in many ways. Sometimes the code is less intuitive, sometimes not. At least there is not much to find in the section <a href="#sec1">Section 1</a>.

<p>
<b>c)</b> Vectorize the code in a) using <code>numpy.sum</code>.

<p>

<b>Answer.</b> <code>np.sum(np.where(r &lt;= 0.5, 1, 0))</code> or <code>np.sum(r &lt;= 0.5)</code>.

<p>
In this latter subexercise, we have an example where the code is easy to read.

<h3 id="my-remarks">My remarks </h3>

<p>
Remarks with such a subsubsection is treated as more text after the last subexercise. Test a list too:

<ol>
<li> Mark 1.</li>
<li> Mark 2.</li>
</ol>

Filenames: <code>flip_coin.py</code>, <code>flip_coin.pdf</code>.

<h3 id="remarks">Remarks </h3>

<p>
These are the exercise remarks, appearing at the very end.

<h2 id="not-an-exercise">Not an exercise </h2>

<p>
Should be possible to stick a normal section in the middle of many exercises.

<h2 id="my:exer1">Exercise 3: Test of plain text exercise</h2>

<p>
Very short exercise. What is the capital of Norway? Filename: <code>myexer1</code>.

<h2 id="demo:ex:2">Project 4: Compute a Probability</h2>

<p>
What is the probability of getting a number between 0.5 and 0.6 when drawing uniformly distributed random numbers from the interval $latex [0,1)$?

<p>
At the end we have a list because that caused problems in LaTeX in previous DocOnce versions:

<ol>
<li> item1</li>
<li> item2</li>
</ol>

<p>
<b>Hint.</b> To answer this question empirically, let a program draw $latex N$ such random numbers using Python's standard <code>random</code> module, count how many of them, $latex M$, that fall in the interval $latex (0.5,0.6)$, and compute the probability as $latex M/N$.

<h2 id="proj:circle1">Project 5: Explore Distributions of Random Circles</h2>

<p>
The formula for a circle is given by

<p>

$latex 
x = x_0 + R\cos 2\pi t,
 $

$latex  
y = y_0 + R\sin 2\pi t,

 $


where $latex R$ is the radius of the circle, $latex (x_0,y_0)$ is the center point, and $latex t$ is a parameter in the unit interval $latex [0,1]$. For any $latex t$, $latex (x,y)$ computed from <b>(REF to equation circle:x not supported)</b>-<b>(REF to equation circle:y not supported)</b> is a point on the circle. The formula can be used to generate <code>n</code> points on a circle:

<p>


<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">import</span> <span style="color: #0000FF; font-weight: bold">numpy</span> <span style="color: #008000; font-weight: bold">as</span> <span style="color: #0000FF; font-weight: bold">np</span>

<span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">circle</span>(R, x0, y0, n<span style="color: #666666">=501</span>):
    t <span style="color: #666666">=</span> np<span style="color: #666666">.</span>linspace(<span style="color: #666666">0</span>, <span style="color: #666666">1</span>, n)
    x <span style="color: #666666">=</span> x0 <span style="color: #666666">+</span> R<span style="color: #666666">*</span>np<span style="color: #666666">.</span>cos(<span style="color: #666666">2*</span>np<span style="color: #666666">.</span>pi<span style="color: #666666">*</span>t)
    y <span style="color: #666666">=</span> y0 <span style="color: #666666">+</span> R<span style="color: #666666">*</span>np<span style="color: #666666">.</span>sin(<span style="color: #666666">2*</span>np<span style="color: #666666">.</span>pi<span style="color: #666666">*</span>t)
    <span style="color: #008000; font-weight: bold">return</span> x, y

x, y <span style="color: #666666">=</span> circle(<span style="color: #666666">2.0</span>, <span style="color: #666666">0</span>, <span style="color: #666666">0</span>)
</pre></div>
<p>
The goal of this project is to draw $latex N$ circles with random center and radius. Plot each circle using the <code>circle</code> function above.

<p>
<b>a)</b> Let $latex R$ be normally distributed and $latex (x_0,y_0)$ uniformly distributed.

<p>
<b>Hint.</b> Use the <code>numpy.random</code> module to draw the $latex x_0$, $latex y_0$, and $latex R$ quantities.

<p>

<b>Answer.</b> Here goes the short answer to part a).

<p>

<b>Solution.</b> Here goes a full solution to part a).

<p>
<b>b)</b> Let $latex R$ be uniformly distributed and $latex (x_0,y_0)$ normally distributed. Filename: <code>norm</code>.

<p>
<b>c)</b> Let $latex R$ and $latex (x_0,y_0)$ be normally distributed.

<p>
Filename: <code>circles</code>.

<h3 id="remarks">Remarks </h3>

<p>
At the very end of the exercise it may be appropriate to summarize and give some perspectives.

<h2 id="exer:dist">Exercise 6: Determine some Distance</h2>

<p>
Intro to this exercise. Questions are in subexercises below.

<p>

<b>Solution.</b> Here goes a full solution of the whole exercise. With some math $latex a=b$ in this solution:

$latex  \hbox{math in solution: } a = b  $


And code <code>a=b</code> in this solution:
<p>


<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>a = b  # code in solution
</pre></div>
<p>
End of solution is here.

<p>
<b>a)</b> Subexercises are numbered a), b), etc.

<p>
<b>Hint 1.</b> First hint to subexercise a). With math $latex a=b$ in hint:

<p>

$latex  a=b.  $


And with code (in plain verbatim) returning $latex x+1$ in hint:

<p>


<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>def func(x):
    return x + 1  # with code in hint
</pre></div>
<p>
<b>Hint 2.</b> Second hint to subexercise a).

<p>
Test list in hint:

<ol>
<li> item1</li>
<li> item2</li>
</ol>


Filename: <code>subexer_a.pdf</code>.

<p>

<b>Answer.</b> Short answer to subexercise a). With math in answer: $latex a=b$.

<p>
<b>b)</b> Here goes the text for subexercise b).

<p>
Some math $latex \cos^2 x + \sin^2 x = 1$ written one a single line:

<p>

$latex  \cos^2 x + \sin^2 x = 1 \thinspace . $

<p>
<b>Hint.</b> A hint for this subexercise.

<p>

Filename: <code>subexer_b.pdf</code>.

<p>

<b>Solution.</b> Here goes the solution of this subexercise.

<p>

The text here belongs to the main (intro) part of the exercise. Need closing remarks to have text after subexercises.

<p>
Test list in exercise:

<ol>
<li> item1</li>
<li> item2 </li>
</ol>

<h3 id="remarks">Remarks </h3>

<p>
Some final closing remarks, e.g., summarizing the main findings and their implications in other problems can be made. These remarks will appear at the end of the typeset exercise.

<h2 id="some-exercise-without-the-exercise-prefix">Some exercise without the "Exercise:" prefix </h2>

<p>
Just some text. And some math saying that $latex e^0=1$ on a single line, to test that math block insertion is correct:

<p>

$latex  \exp{(0)} = 1  $

<p>
And a test that the code <code>lambda x: x+2</code> is correctly placed here:

<p>


<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>lambda x: x+2
</pre></div>

<h2 id="sec:this:exer:de">Exercise 8: Solution of differential equation</h2>

<p>

Given

<p>

$latex  \frac{dy}{dx} = -y(x),\quad y(0)=1  $


What is the solution of this equation?

<p>

$latex y=e^{-y}$

<p>

$latex y=e^{y}$

<p>

Almost, but the sign is wrong (note the minus!).

<p>


<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">from</span> <span style="color: #0000FF; font-weight: bold">math</span> <span style="color: #008000; font-weight: bold">import</span> exp
<span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">f</span>(x):
    <span style="color: #008000; font-weight: bold">return</span> exp(x)
</pre></div>
<p>

Ooops, forgot a minus: <code>exp(-x)</code>, otherwise this Python code must be considered as a good answer. It is more natural, though, to write the solution to the problem in mathematical notation:

<p>

$latex  y(x) = e^{-y}. $

<p>

The solution cannot be found because there is a derivative in the equation.

<p>

Equations with derivatives can be solved; they are termed <em>differential equations</em>.

<p>

The equation is meaningless: an equation must be an equation for $latex x$ or $latex y$, not a function $latex y(x)$.

<p>

Equations where the unknown is a function, as $latex y(x)$ here, are called <em>differential equations</em>, and are solved by special techniques.

<h2 id="example-9-just-an-example">Example 9: Just an example </h2>

<p>
<b>a)</b> What is the capital of Norway?

<p>
<b>Answer.</b> Oslo.

<h1 id="here-goes-another-section">Here goes another section </h1>

<p>
With some text, before we continue with exercises.

<h1 id="more-exercises">More Exercises </h1>

<h2 id="exer:some:formula">Exercise 10: Make references to projects and problems</h2>

<p>

Pick a statement from <a href="#proj:circle1">Project 5: Explore Distributions of Random Circles</a> or <a href="#demo:ex:1">Problem 2: Flip a Coin</a> and verify it.

<p>
Test list at the end of an exercise without other elements (like subexercise, hint, etc.):

<ol>
<li> item1</li>
<li> item2</li>
</ol>

Filename: <code>verify_formula.py</code>.

<h2 id="exer:you">Project 11: References in a headings do not work well in html</h2>

<p>
Refer to the previous exercise as <a href="#exer:some:formula">Exercise 10: Make references to projects and problems</a>, the two before that as <a href="#demo:ex:2">Project 4: Compute a Probability</a> and <a href="#proj:circle1">Project 5: Explore Distributions of Random Circles</a>, and this one as <a href="#exer:you">Project 11: References in a headings do not work well in html</a>. Filename: <code>selc_composed.pdf</code>.

<h1 id="references">References </h1>

<ol>
 <li> <div id="Langtangen_Pedersen_2002"></div> <b>H. P. Langtangen and G. Pedersen</b>.      Propagation of Large Destructive Waves,     <em>International Journal of Applied Mechanics and Engineering</em>,     7(1),     pp. 187-204,     2002.</li>
 <li> <div id="Langtangen_et_al_2002"></div> <b>H. P. Langtangen, K.-A. Mardal and R. Winther</b>.      Numerical Methods for Incompressible Viscous Flow,     <em>Advances in Water Resources</em>,     25,     pp. 1125-1146,     2002.</li>
 <li> <div id="Langtangen_1994a"></div> <b>H. P. Langtangen</b>.      Numerical Solution of First Passage Problems in Random Vibrations,     <em>SIAM Journal of Scientific and Statistical Computing</em>,     15,     pp. 997-996,     1994.</li>
 <li> <div id="Mardal_et_al_2003a"></div> <b>K.-A. Mardal, G. W. Zumbusch and H. P. Langtangen</b>.      Software Tools for Multigrid Methods,     <em>Advanced Topics in Computational Partial Differential Equations -- Numerical Methods and Diffpack Programming</em>,     edited by <b>H. P. Langtangen and A. Tveito</b>,     Springer,     2003,     Edited book,     <a href="http://some.where.org" target="_blank"><tt>http://some.where.org</tt></a>.</li>
 <li> <div id="Langtangen_1988d"></div> <b>H. P. Langtangen</b>.      The FEMDEQS Program System,     <em>Department of Mathematics, University of Oslo</em>,     1989,     <a href="http://www.math.uio.no/old/days/hpl/femdeqs.pdf" target="_blank"><tt>http://www.math.uio.no/old/days/hpl/femdeqs.pdf</tt></a>.</li>
 <li> <div id="Langtangen_1992c"></div> <b>H. P. Langtangen</b>.      Stochastic Breakthrough Time Analysis of an Enhanced Oil Recovery Process,     <em>SIAM Journal on Scientific Computing</em>,     13,     pp. 1394-1417,     1992.</li>
 <li> <div id="Mortensen_et_al_2011"></div> <b>M. Mortensen, H. P. Langtangen and G. N. Wells</b>.      A FEniCS-Based Programming Framework for Modeling Turbulent Flow by the Reynolds-Averaged Navier-Stokes Equations,     <em>Advances in Water Resources</em>,     34(9),     <a href="https://dx.doi.org/10.1016/j.advwatres.2011.02.013" target="_blank">doi: 10.1016/j.advwatres.2011.02.013</a>,     2011.</li>
 <li> <div id="Glimsdal_et_al_20006"></div> <b>S. Glimsdal, G. Pedersen, K. Atakan, C. B. Harbitz, H. P. Langtangen and F. L\ovholt</b>.      Propagation of the Dec.&nbsp;26, 2004 Indian Ocean Tsunami: Effects of Dispersion and Source Characteristics,     <em>International Journal of Fluid Mechanics Research</em>,     33(1),     pp. 15-43,     2006.</li>
 <li> <div id="Rahman_et_al_2006b"></div> <b>S. Rahman, J. Gorman, C. H. W. Barnes, D. A. Williams and H. P. Langtangen</b>.      Numerical Investigation of a Piezoelectric Surface Acoustic Wave Interaction With a One-Dimensional Channel,     <em>Physical Review B: Condensed Matter and Materials Physics</em>,     74,     2006,     035308.</li>
<li> <div id="Haga_et_al_2011a"></div> <b>J. B. Haga, H. Osnes and H. P. Langtangen</b>.      On the Causes of Pressure Oscillations in Low-Permeable and Low-Compressible Porous Media,     <em>International Journal of Analytical and Numerical Methods in Geomechanics</em>,     <a href="https://dx.doi.org/10.1002/nag.1062" target="_blank">doi: 10.1002/nag.1062</a>,     2011,     <a href="http://onlinelibrary.wiley.com/doi/10.1002/nag.1062/abstract" target="_blank"><tt>http://onlinelibrary.wiley.com/doi/10.1002/nag.1062/abstract</tt></a>.</li>
<li> <div id="Langtangen_2003a"></div> <b>H. P. Langtangen</b>.     <em>Computational Partial Differential Equations - Numerical Methods and Diffpack Programming</em>,     second edition,     <em>Texts in Computational Science and Engineering</em>,     Springer,     2003.</li>
<li> <div id="Langtangen_2008a"></div> <b>H. P. Langtangen</b>.     <em>Python Scripting for Computational Science</em>,     third edition,     <em>Texts in Computational Science and Engineering</em>,     Springer,     2008.</li>
<li> <div id="Langtangen:95"></div> <b>H. P. Langtangen and G. Pedersen</b>.      Finite Elements for the Boussinesq Wave Equations,     Waves and Non-linear Processes in Hydrodynamics,     edited by <b>J. Grue, B. Gjevik and J. E. Weber</b>,     Kluwer Academic Publishers,     pp. pp. 117-126,     1995,     <a href="http://www.amazon.ca/Waves-Nonlinear-Processes-Hydrodynamics-John/dp/0792340310" target="_blank"><tt>http://www.amazon.ca/Waves-Nonlinear-Processes-Hydrodynamics-John/dp/0792340310</tt></a>.</li>
<li> <div id="Langtangen_2012"></div> <b>H. P. Langtangen</b>.     <em>A Primer on Scientific Programming With Python</em>,     third edition,     <em>Texts in Computational Science and Engineering</em>,     Springer,     2012.</li>
<li> <div id="Jeberg_et_al_2004"></div> <b>P. V. Jeberg, H. P. Langtangen and C. B. Terp</b>.      Optimization With Diffpack: Practical Example From Welding,     <em>Simula Research Laboratory</em>,     2004,     Internal report.</li>
<li> <div id="Langtangen_1989e"></div> <b>H. P. Langtangen</b>.      Computational Methods for Two-Phase Flow in Oil Reservoirs,     Ph.D. Thesis,     Mechanics Division, Department of Mathematics, University of Oslo,     1989,     Dr.&nbsp;Scient.&nbsp;thesis..</li>
<li> <div id="Langtangen_talk_2007a"></div> <b>H. P. Langtangen</b>.      Computational Modeling of Huge Tsunamis From Asteroid Impacts,     2007,     Invited keynote lecture at the \emphInternational conference on Computational Science 2007 (ICCS'07), Beijing, China.</li>
<li> <div id="Langtangen:85"></div> <b>H. P. Langtangen</b>.      Solution of the Navier-Stokes Equations With the Finite Element Method in Two and Three Dimensions,     M.Sc. Thesis,     Mechanics Division, Department of Mathematics, University of Oslo,     1985,     Cand.Scient. thesis.</li>
<li> <div id="Langtangen:91"></div> <b>H. P. Langtangen and A. Tveito</b>.      Numerical Methods in Continuum Mechanics,     <em>Center for Industrial Research</em>,     1991,     Lecture notes for a course (ME-IN 324). 286 pages..</li>
<li> <div id="Langtangen:94b"></div> <b>H. P. Langtangen</b>.      Diffpack: Software for Partial Differential Equations,     <em>Proceedings of the Second Annual Object-Oriented Numerics Conference (OON-SKI'94), Sunriver, Oregon, USA</em>,     edited by <b>A. Vermeulen</b>,     1994.</li>
</ol>

<h1 id="app1">Appendix: Just for testing; part I</h1>

<p>
This is the first appendix.

<h2 id="a-subsection-within-an-appendix">A subsection within an appendix </h2>

<p>
Some text.

<h1 id="app2">Appendix: Just for testing; part II</h1>

<p>
This is more stuff for an appendix.

<h2 id="appendix-testing-identical-titles">Appendix: Testing identical titles </h2>

<p>
Without label.

<h2 id="test:title:id1">Appendix: Testing identical titles</h2>

<p>
With label.

<h2 id="test:title:id2">Appendix: Testing identical titles</h2>

<p>
What about inserting a quiz?

<p>

[Fundamental test:] What is the capital of Norway?

<p>

[Answer 1:] Stockholm

<p>

Stockholm is the capital of Sweden.

<p>

[Answer 2:] London

<p>

[Answer 3:] Oslo

<p>

Bergen

<p>

Those from Bergen would claim so, but nobody else.

<h2 id="appendix-testing-identical-titles">Appendix: Testing identical titles </h2>

<p>
Without label.

<p>
<div class="alert alert-block alert-notice alert-text-normal">
<b>Tip</b>
<p>
Here is a tip or hint box, typeset as a notice box.
</div>


<p>
Need a lot of text to surround the summary box. Version control systems allow you to record the history of files and share files among several computers and collaborators in a professional way. File changes on one computer are updated or merged with changes on another computer. Especially when working with programs or technical reports it is essential to have changes documented and to ensure that every computer and person involved in the project have the latest updates of the files. Greg Wilson' excellent <a href="https://software-carpentry.org/2010/07/script-for-introduction-to-version-control/" target="_blank">Script for Introduction to Version Control</a> provides a more detailed motivation why you will benefit greatly from using version control systems.

<p>
<div class="alert alert-block alert-summary alert-text-normal">
<b>Summary</b>
<p>
<b>Bold remark:</b> Make some text with this summary. Much testing in this document, otherwise stupid content. Much testing in this document, otherwise stupid content. Much testing in this document, otherwise stupid content. Much testing in this document, otherwise stupid content. Much testing in this document, otherwise stupid content. Much testing in this document, otherwise stupid content. Much testing in this document, otherwise stupid content. Much testing in this document, otherwise stupid content. Much testing in this document, otherwise stupid content.
</div>


<p>
Projects that you want to share among several computers or project workers are today most conveniently stored at some web site "in the cloud" and updated through communication with that site. I strongly recommend you to use such sites for all serious programming and scientific writing work - and all other important files.

<p>
The simplest services for hosting project files are <a href="https://dropbox.com" target="_blank">Dropbox</a> and <a href="https://drive.google.com" target="_blank">Google Drive</a>. It is very easy to get started with these systems, and they allow you to share files among laptops and mobile units with as many users as you want. The systems offer a kind of version control in that the files are stored frequently (several times per minute), and you can go back to previous versions for the last 30 days. However, it is challenging  to find the right version from the past when there are so many of them.

<p>
More seriously, when several people may edit files simultaneously, it can be difficult detect who did what when, roll back to previous versions, and to manually merge the edits when these are incompatible. Then one needs more sophisticated tools than Dropbox or Google Drive: project hosting services with true version control systems.  The following text aims at providing you with the minimum information to started with such systems. Numerous other tutorials contain more comprehensive material and in-depth explanations of the concepts and tools.

<p>
The idea with project hosting services is that you have the files associated with a project in the cloud. Many people may share these files.  Every time you want to work on the project you explicitly update your version of the files, edit the files as you like, and synchronize the files with the "master version" at the site where the project is hosted.  If you at some point need to go back to a version of the files at some particular point in the past, this is an easy operation. You can also use tools to see what various people have done with the files in the various versions.

<p>
All these services are very similar. Below we describe how you get started with Bitbucket, GitHub, and Googlecode. Launchpad works very similarly to the latter three. All the project hosting services have excellent introductions available at their web sites, but the recipes below are much shorter and aim at getting you started as quickly as possible by concentrating on the most important need-to-know steps. The Git tutorials we refer to later in this document contain more detailed information and constitute of course very valuable readings when you use version control systems every day. The point now is to get started.

<h2 id="appendix-testing-inline-comments">Appendix: Testing inline comments </h2>

<p>
Projects that you want to share among several computers or project workers are today most conveniently stored at some web site "in the cloud" and updated through communication with that site. 

<font color="red">(<b>hpl's semi opinion 1</b>: not sure if in the cloud is understood by all.)</font>

 I strongly recommend you to use such sites for all serious programming and scientific writing work - and all other important files.

<p>
The simplest services for hosting project files is Dropbox. 

<font color="red">(<b>mp 2</b>: Simply go to <a href="https://dropbox.com" target="_blank"><tt>https://dropbox.com</tt></a> and watch the video. It explains how files, like <code>myfile.py</code>, perhaps containing much math, like $latex \partial u/\partial t$, are easily communicated between machines.)</font>

 It is very easy to get started with Dropbox, and it allows you to share files among  <font color="red">(<b>hpl 3</b>:)</font> <del> laptops and mobile units </del> <font color="red">computers, tablets, and phones</font>.

<p>
<hr>

<p>
First<font color="red">, (<b>edit 4</b>: add comma)</font> consider a quantity $latex Q$.  <font color="red">(<b>edit 5</b>:)</font> <del> To this end, </del> <font color="red">We note that</font> $latex Q>0$, because  <font color="red">(<b>edit 6</b>:)</font> <del> a </del> negative  <font color="red">(<b>edit 7</b>:)</font> <del> quantity is </del> <font color="red">quantities are</font>  <font color="red">(<b>edit 8</b>:)</font> <del> just </del> negative.  <font color="red">(<b>edit 9</b>:) This comes as no surprise.</font>

<p>

Let us refer to Figure <a href="#fig:impact">1</a> again.

<p>
Test references in a list:

<ul>
 <li> <a href="#sec1">Section 1</a></li>
 <li> <a href="#subsec1">Subsection 1</a></li>
 <li> <a href="#fig:impact">1</a></li>
</ul>

<h2 id="appendix-testing-headings-ending-with-verbatim-inline">Appendix: Testing headings ending with <code>verbatim inline</code> </h2>

<p>
The point here is to test 1) <code>verbatim</code> code in headings, and 2) ending a heading with verbatim code as this triggers a special case in LaTeX.

<p>
We also test mdash&mdash;used as alternative to hyphen without spaces around, or in quotes:

<p>
<blockquote>
    <em>Fun is fun</em>.&mdash;Unknown.
</blockquote>


<p>
The ndash should also be tested &ndash; as in the Hanson&ndash;Nilson equations on page 277&ndash;278.

<p>
And finally, what about admons, quotes, and boxes? They are tested in a separate document: <code>admon.do.txt</code>.

<p id="def_footnote_5"><a href="#link_footnote_5"><b>5:</b></a> Not much to add here, but the footnote is at the end with only one newline.</p>



<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.js"></script>


<center style="font-size:80%">
  Made with <a href="https://github.com/hplgit/doconce">DocOnce</a>
</center>


</body>
</html>
    

************** File: testdoc_no_solutions.html *****************
<!--
Automatically generated HTML file from DocOnce source
(https://github.com/doconce/doconce/)
-->
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="DocOnce: https://github.com/doconce/doconce/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="description" content="A Document for Testing DocOnce">
<meta name="keywords" content="figures,movies,index with subindex,_boldface word_ in index,index with _boldface word_,index with _boldface word_ in subentry,double _boldface word_  _boldface word_ in subentry too,index, with comma, and one more">

<title>A Document for Testing DocOnce</title>


<style type="text/css">
/* blueish style */

/* Color definitions:  https://www.december.com/html/spec/color0.html
   CSS examples:       https://www.w3schools.com/css/css_examples.asp */

body {
  margin-top: 1.0em;
  background-color: #ffffff;
  font-family: Helvetica, Arial, FreeSans, san-serif;
  color: #000000;
}
h1 { font-size: 1.8em; color: #1e36ce; }
h2 { font-size: 1.6em; color: #1e36ce; }
h3 { font-size: 1.4em; color: #1e36ce; }
a { color: #1e36ce; text-decoration:none; }
tt { font-family: "Courier New", Courier; }
/* pre style removed because it will interfer with pygments */
p { text-indent: 0px; }
hr { border: 0; width: 80%; border-bottom: 1px solid #aaa}
p.caption { width: 80%; font-style: normal; text-align: left; }
hr.figure { border: 0; width: 80%; border-bottom: 1px solid #aaa}
.alert-text-small   { font-size: 80%;  }
.alert-text-large   { font-size: 130%; }
.alert-text-normal  { font-size: 90%;  }
.alert {
  padding:8px 35px 8px 14px; margin-bottom:18px;
  text-shadow:0 1px 0 rgba(255,255,255,0.5);
  border:1px solid #bababa;
  border-radius: 4px;
  -webkit-border-radius: 4px;
  -moz-border-radius: 4px;
  color: #555;
  background-color: #f8f8f8;
  background-position: 10px 5px;
  background-repeat: no-repeat;
  background-size: 38px;
  padding-left: 55px;
  width: 75%;
 }
.alert-block {padding-top:14px; padding-bottom:14px}
.alert-block > p, .alert-block > ul {margin-bottom:1em}
.alert li {margin-top: 1em}
.alert-block p+p {margin-top:5px}
.alert-notice { background-image: url(https://raw.github.com/doconce/doconce/master/bundled/html_images/small_gray_notice.png); }
.alert-summary  { background-image:url(https://raw.github.com/doconce/doconce/master/bundled/html_images/small_gray_summary.png); }
.alert-warning { background-image: url(https://raw.github.com/doconce/doconce/master/bundled/html_images/small_gray_warning.png); }
.alert-question {background-image:url(https://raw.github.com/doconce/doconce/master/bundled/html_images/small_gray_question.png); }

div { text-align: justify; text-justify: inter-word; }
</style>

<style type="text/css">

#share-buttons img {
width: 35px;
padding: 5px;
border: 0;
box-shadow: 0;
display: inline;
}

</style>
</center>


<script src="https://sagecell.sagemath.org/static/jquery.min.js"></script>
<script src="https://sagecell.sagemath.org/embedded_sagecell.js"></script>
<link rel="stylesheet" type="text/css" href="https://sagecell.sagemath.org/static/sagecell_embed.css">
<script>
$(function () {
    // Make the div with id 'mycell' a Sage cell
    sagecell.makeSagecell({inputLocation:  '#mycell',
                           template:       sagecell.templates.minimal,
                           evalButtonText: 'Activate'});
    // Make *any* div with class 'compute' a Sage cell
    sagecell.makeSagecell({inputLocation: 'div.compute',
                           evalButtonText: 'Evaluate'});
});
</script>




<!-- Tools for embedded Bokeh plots -->
<link rel="stylesheet"
      href="https://cdn.pydata.org/bokeh/release/bokeh-0.9.0.min.css"
      type="text/css" />
<script type="text/javascript"
	src="https://cdn.pydata.org/bokeh/release/bokeh-0.9.0.min.js">
</script>
<script type="text/javascript">
  Bokeh.set_log_level("info");
</script>


</head>

<!-- tocinfo
{'highest level': 1,
 'sections': [('Table of contents',
               1,
               'table_of_contents',
               'table_of_contents'),
              ('Section 1', 1, 'sec1', 'sec1'),
              ('Here is a list with subsubsection heading',
               3,
               None,
               'here-is-a-list-with-subsubsection-heading'),
              ('Subsection 1', 2, 'subsec1', 'subsec1'),
              ('Test Section reference at beginning of line and after a '
               'sentence',
               3,
               None,
               'test-section-reference-at-beginning-of-line-and-after-a-sentence'),
              ('Computer code', 3, None, 'computer-code'),
              ('Subsubsection heading before code',
               3,
               None,
               'subsubsection-heading-before-code'),
              ('Running OS commands', 3, None, 'running-os-commands'),
              ('Footnotes', 3, None, 'footnotes'),
              ('Subsection 2: Testing figures', 2, 'subsec:ex', 'subsec:ex'),
              ('The $\\theta$ parameter (not $\\nabla$?)',
               2,
               'decay:sec:theta',
               'decay:sec:theta'),
              ('Custom Environments', 2, None, 'custom-environments'),
              ('Tables', 2, 'subsec:table', 'subsec:table'),
              ('A test of verbatim words in heading with subscript $a_i$: '
               '`my_file_v1` and `my_file_v2`',
               2,
               None,
               'a-test-of-verbatim-words-in-heading-with-subscript-a_i-my_file_v1-and-my_file_v2'),
              ('_Just bold_', 2, None, '_just-bold_'),
              ('*Just emphasize*', 2, None, 'just-emphasize'),
              ('`Just verbatim`', 2, None, 'just-verbatim'),
              ('_Bold_ beginning', 2, None, '_bold_-beginning'),
              ('*Emphasize* beginning', 2, None, 'emphasize-beginning'),
              ('`Verbatim` beginning', 2, None, 'verbatim-beginning'),
              ('Maybe _bold end_', 2, None, 'maybe-_bold-end_'),
              ('Maybe *emphasize end*', 2, None, 'maybe-emphasize-end'),
              ('Maybe `verbatim end`', 2, None, 'maybe-verbatim-end'),
              ('The middle has _bold_ word',
               2,
               None,
               'the-middle-has-_bold_-word'),
              ('The middle has *emphasize* word',
               2,
               None,
               'the-middle-has-emphasize-word'),
              ('The middle has `verbatim` word',
               2,
               None,
               'the-middle-has-verbatim-word'),
              ('Bibliography test', 2, None, 'bibliography-test'),
              ('Example 1: Examples can be typeset as exercises',
               2,
               'Example',
               'Example'),
              ('User-defined environments',
               2,
               None,
               'user-defined-environments'),
              ('Example 1: A test function', 2, 'ex:test:1p1', 'ex:test:1p1'),
              ('Example 2: Addition', 2, 'ex:math:1p1', 'ex:math:1p1'),
              ('URLs', 2, 'subsubsec:ex', 'subsubsec:ex'),
              ('LaTeX Mathematics', 1, None, 'latex-mathematics'),
              ('Exercises', 1, None, 'exercises'),
              ('Problem 2: Flip a Coin', 2, 'demo:ex:1', 'demo:ex:1'),
              ('My remarks', 3, None, 'my-remarks'),
              ('Remarks', 3, None, 'remarks'),
              ('Not an exercise', 2, None, 'not-an-exercise'),
              ('Exercise 3: Test of plain text exercise',
               2,
               'my:exer1',
               'my:exer1'),
              ('Project 4: Compute a Probability', 2, 'demo:ex:2', 'demo:ex:2'),
              ('Project 5: Explore Distributions of Random Circles',
               2,
               'proj:circle1',
               'proj:circle1'),
              ('Remarks', 3, None, 'remarks'),
              ('Exercise 6: Determine some Distance',
               2,
               'exer:dist',
               'exer:dist'),
              ('Remarks', 3, None, 'remarks'),
              ('Some exercise without the "Exercise:" prefix',
               2,
               None,
               'some-exercise-without-the-exercise-prefix'),
              ('Exercise 8: Solution of differential equation',
               2,
               'sec:this:exer:de',
               'sec:this:exer:de'),
              ('Example 9: Just an example',
               2,
               None,
               'example-9-just-an-example'),
              ('Here goes another section',
               1,
               None,
               'here-goes-another-section'),
              ('More Exercises', 1, None, 'more-exercises'),
              ('Exercise 10: Make references to projects and problems',
               2,
               'exer:some:formula',
               'exer:some:formula'),
              ('Project 11: References in a headings do not work well in html',
               2,
               'exer:you',
               'exer:you'),
              ('Answers and Solutions',
               1,
               'ch:answerssolutions',
               'ch:answerssolutions'),
              ('Example 1: Examples can be typeset as exercises',
               2,
               None,
               'example-1-examples-can-be-typeset-as-exercises'),
              ('Problem 2: Flip a Coin', 2, None, 'problem-2-flip-a-coin'),
              ('Project 5: Explore Distributions of Random Circles',
               2,
               None,
               'project-5-explore-distributions-of-random-circles'),
              ('Exercise 6: Determine some Distance',
               2,
               None,
               'exercise-6-determine-some-distance'),
              ('Example 9: Just an example',
               2,
               None,
               'example-9-just-an-example'),
              ('References', 1, None, 'references'),
              ('Appendix: Just for testing; part I', 1, 'app1', 'app1'),
              ('A subsection within an appendix',
               2,
               None,
               'a-subsection-within-an-appendix'),
              ('Appendix: Just for testing; part II', 1, 'app2', 'app2'),
              ('Appendix: Testing identical titles',
               2,
               None,
               'appendix-testing-identical-titles'),
              ('Appendix: Testing identical titles',
               2,
               'test:title:id1',
               'test:title:id1'),
              ('Appendix: Testing identical titles',
               2,
               'test:title:id2',
               'test:title:id2'),
              ('Appendix: Testing identical titles',
               2,
               None,
               'appendix-testing-identical-titles'),
              ('Appendix: Testing inline comments',
               2,
               None,
               'appendix-testing-inline-comments'),
              ('Appendix: Testing headings ending with `verbatim inline`',
               2,
               None,
               'appendix-testing-headings-ending-with-verbatim-inline')]}
end of tocinfo -->

<body>



<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  TeX: {
     equationNumbers: {  autoNumber: "AMS"  },
     extensions: ["AMSmath.js", "AMSsymbols.js", "autobold.js", "color.js"]
  }
});
</script>
<script type="text/javascript" async
 src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>



    
<!-- ------------------- main content ---------------------- -->



<center><h1>A Document for Testing DocOnce</h1></center>  <!-- document title -->

<p>
<!-- author(s): Hans Petter Langtangen, Kaare Dump, A. Dummy Author, I. S. Overworked and Outburned, and J. Doe -->

<center>
<b>Hans Petter Langtangen</b> [1, 2] (<tt>hpl at simula.no</tt>)
</center>

<center>
<b>Kaare Dump</b> [3]
</center>

<center>
<b>A. Dummy Author</b> 
</center>

<center>
<b>I. S. Overworked and Outburned</b> [4, 5, 6, 7]
</center>

<center>
<b>J. Doe</b>  (<tt>j_doe at cyberspace.com</tt>)
</center>

<p>
<!-- institution(s) -->

<center>[1] <b>Center for Biomedical Computing, Simula Research Laboratory</b></center>
<center>[2] <b>Department of Informatics, University of Oslo</b></center>
<center>[3] <b>Segfault, Cyberspace</b></center>
<center>[4] <b>Inst1</b></center>
<center>[5] <b>Inst2, Somewhere</b></center>
<center>[6] <b>Third Inst, Elsewhere</b></center>
<center>[7] <b>Fourth Inst</b></center>
<br>
<p>
<center><h4>Jan 32, 2100</h4></center> <!-- date -->
<br>

<h1 id="table_of_contents">Table of contents</h2>

<p>
<a href="#sec1"> Section 1 </a><br>
&nbsp; &nbsp; &nbsp; <a href="#subsec1"> Subsection 1 </a><br>
&nbsp; &nbsp; &nbsp; <a href="#subsec:ex"> Subsection 2: Testing figures </a><br>
&nbsp; &nbsp; &nbsp; <a href="#decay:sec:theta"> The \( \theta \) parameter (not \( \nabla \)?) </a><br>
&nbsp; &nbsp; &nbsp; <a href="#custom-environments"> Custom Environments </a><br>
&nbsp; &nbsp; &nbsp; <a href="#subsec:table"> Tables </a><br>
&nbsp; &nbsp; &nbsp; <a href="#a-test-of-verbatim-words-in-heading-with-subscript-a_i-my_file_v1-and-my_file_v2"> A test of verbatim words in heading with subscript \( a_i \): <code>my_file_v1</code> and <code>my_file_v2</code> </a><br>
&nbsp; &nbsp; &nbsp; <a href="#_just-bold_"> <b>Just bold</b> </a><br>
&nbsp; &nbsp; &nbsp; <a href="#just-emphasize"> <em>Just emphasize</em> </a><br>
&nbsp; &nbsp; &nbsp; <a href="#just-verbatim"> <code>Just verbatim</code> </a><br>
&nbsp; &nbsp; &nbsp; <a href="#_bold_-beginning"> <b>Bold</b> beginning </a><br>
&nbsp; &nbsp; &nbsp; <a href="#emphasize-beginning"> <em>Emphasize</em> beginning </a><br>
&nbsp; &nbsp; &nbsp; <a href="#verbatim-beginning"> <code>Verbatim</code> beginning </a><br>
&nbsp; &nbsp; &nbsp; <a href="#maybe-_bold-end_"> Maybe <b>bold end</b> </a><br>
&nbsp; &nbsp; &nbsp; <a href="#maybe-emphasize-end"> Maybe <em>emphasize end</em> </a><br>
&nbsp; &nbsp; &nbsp; <a href="#maybe-verbatim-end"> Maybe <code>verbatim end</code> </a><br>
&nbsp; &nbsp; &nbsp; <a href="#the-middle-has-<b>bold</b>-word"> The middle has <b>bold</b> word </a><br>
&nbsp; &nbsp; &nbsp; <a href="#the-middle-has-emphasize-word"> The middle has <em>emphasize</em> word </a><br>
&nbsp; &nbsp; &nbsp; <a href="#the-middle-has-verbatim-word"> The middle has <code>verbatim</code> word </a><br>
&nbsp; &nbsp; &nbsp; <a href="#bibliography-test"> Bibliography test </a><br>
&nbsp; &nbsp; &nbsp; <a href="#Example"> Example 1: Examples can be typeset as exercises </a><br>
&nbsp; &nbsp; &nbsp; <a href="#user-defined-environments"> User-defined environments </a><br>
&nbsp; &nbsp; &nbsp; <a href="#ex:test:1p1"> Example 1: A test function </a><br>
&nbsp; &nbsp; &nbsp; <a href="#ex:math:1p1"> Example 2: Addition </a><br>
&nbsp; &nbsp; &nbsp; <a href="#subsubsec:ex"> URLs </a><br>
<a href="#latex-mathematics"> LaTeX Mathematics </a><br>
<a href="#exercises"> Exercises </a><br>
&nbsp; &nbsp; &nbsp; <a href="#demo:ex:1"> Problem 2: Flip a Coin </a><br>
&nbsp; &nbsp; &nbsp; <a href="#not-an-exercise"> Not an exercise </a><br>
&nbsp; &nbsp; &nbsp; <a href="#my:exer1"> Exercise 3: Test of plain text exercise </a><br>
&nbsp; &nbsp; &nbsp; <a href="#demo:ex:2"> Project 4: Compute a Probability </a><br>
&nbsp; &nbsp; &nbsp; <a href="#proj:circle1"> Project 5: Explore Distributions of Random Circles </a><br>
&nbsp; &nbsp; &nbsp; <a href="#exer:dist"> Exercise 6: Determine some Distance </a><br>
&nbsp; &nbsp; &nbsp; <a href="#some-exercise-without-the-exercise-prefix"> Some exercise without the "Exercise:" prefix </a><br>
&nbsp; &nbsp; &nbsp; <a href="#sec:this:exer:de"> Exercise 8: Solution of differential equation </a><br>
&nbsp; &nbsp; &nbsp; <a href="#example-9-just-an-example"> Example 9: Just an example </a><br>
<a href="#here-goes-another-section"> Here goes another section </a><br>
<a href="#more-exercises"> More Exercises </a><br>
&nbsp; &nbsp; &nbsp; <a href="#exer:some:formula"> Exercise 10: Make references to projects and problems </a><br>
&nbsp; &nbsp; &nbsp; <a href="#exer:you"> Project 11: References in a headings do not work well in html </a><br>
<a href="#ch:answerssolutions"> Answers and Solutions </a><br>
&nbsp; &nbsp; &nbsp; <a href="#example-1-examples-can-be-typeset-as-exercises"> Example 1: Examples can be typeset as exercises </a><br>
&nbsp; &nbsp; &nbsp; <a href="#problem-2-flip-a-coin"> Problem 2: Flip a Coin </a><br>
&nbsp; &nbsp; &nbsp; <a href="#project-5-explore-distributions-of-random-circles"> Project 5: Explore Distributions of Random Circles </a><br>
&nbsp; &nbsp; &nbsp; <a href="#exercise-6-determine-some-distance"> Exercise 6: Determine some Distance </a><br>
&nbsp; &nbsp; &nbsp; <a href="#example-9-just-an-example"> Example 9: Just an example </a><br>
<a href="#references"> References </a><br>
<a href="#app1"> Appendix: Just for testing; part I </a><br>
&nbsp; &nbsp; &nbsp; <a href="#a-subsection-within-an-appendix"> A subsection within an appendix </a><br>
<a href="#app2"> Appendix: Just for testing; part II </a><br>
&nbsp; &nbsp; &nbsp; <a href="#appendix-testing-identical-titles"> Appendix: Testing identical titles </a><br>
&nbsp; &nbsp; &nbsp; <a href="#test:title:id1"> Appendix: Testing identical titles </a><br>
&nbsp; &nbsp; &nbsp; <a href="#test:title:id2"> Appendix: Testing identical titles </a><br>
&nbsp; &nbsp; &nbsp; <a href="#appendix-testing-identical-titles"> Appendix: Testing identical titles </a><br>
&nbsp; &nbsp; &nbsp; <a href="#appendix-testing-inline-comments"> Appendix: Testing inline comments </a><br>
&nbsp; &nbsp; &nbsp; <a href="#appendix-testing-headings-ending-with-verbatim-inline"> Appendix: Testing headings ending with <code>verbatim inline</code> </a><br>
</p>
<p>
<!-- !split --><br><br><br><br><br><br><br><br><br><br>

<p>
The format of this document is
plain, homemade HTML (from DocOnce).

<p>
<b>Abstract.</b> This is a document with many test constructions for doconce syntax.
It was used heavily for the development and kept for testing
numerous constructions, also special and less common cases.

<p>
And exactly for test purposes we have an extra line here, which
is part of the abstract.

<p>
<!-- Cannot demonstrate chapter headings since abstract and chapter -->
<!-- are mutually exclusive in LaTeX -->

<h1 id="sec1">Section 1</h1>

<p>
Here is a nested list:

<ul>
  <li> item1</li>
  <li> item2</li>
  <li> item3 which continues
    on the next line to test that feature</li>
  <li> and a sublist</li>

<ul>
    <li> with indented subitem1</li>
    <li> and a subitem2</li>
</ul>

  <li> and perhaps an ordered sublist

<ol type="a"></li>
   <li> first item</li>
   <li> second item,
      continuing on a new line</li>
</ol>

</ul>

<b>Here is a list with paragraph heading.</b>

<ul>
  <li> item1</li>
  <li> item2</li>
</ul>

<h3 id="here-is-a-list-with-subsubsection-heading">Here is a list with subsubsection heading </h3>

<ul>
  <li> item1</li>
  <li> item2</li>
</ul>

<blockquote>
    Here are two lines that make up
    a block quote for testing <em>emphasized words</em> and <b>boldface words</b>,
    also with hypens:
    <em>pre</em>-fix, post-<em>fix</em>, <b>pre</b>-fix, post-<b>fix</b>.
</blockquote>


<p>
Here are two references. Equation&nbsp;\eqref{my:eq1} is fine. Eq.&nbsp;\eqref{my:eq1} too.
Even Equation \eqref{my:eq1} without the tilde.
This equation appears in another part if this document is split.

<p>
Let us add a paragraph to
test that HTML,
with WordPress
(<code>--wordpress</code> option)
can handle linebreaks
<em>correctly</em>,
even when lines begin with
<b>bold words</b> and
<code>verbatim words</code> in
<font color="red">red color</font>, and
<a href="https://google.com" target="_self">links</a> as well as math:
\( 1+1=2 \).

<p>
Test also that <em>emphasize</em>
at the end of line, and <b>bold</b>
works, as well as <font color="blue">color</font>
and <a href="https://google.com" target="_self">links2</a>
and <code>verbatim</code>
as well.

<h2 id="subsec1">Subsection 1</h2>

<p>
<!-- Refer to section/appendix etc. at the beginning of the line -->
<!-- and other special fix situations for HTML. -->

<p>
More text, with a reference back to
the section <a href="#sec1">Section 1</a> and <a href="#subsec1">Subsection 1</a>, and further to the
the sections <a href="#subsec1">Subsection 1</a> and <a href="#subsubsec:ex">URLs</a>, which
encourages you to do the tasks in <a href="#demo:ex:1">Problem 2: Flip a Coin</a> and <a href="#exer:some:formula">Exercise 10: Make references to projects and problems</a>.
 <a href="#app1">Appendix: Just for testing; part I</a> and <a href="#app2">Appendix: Just for testing; part II</a> are also nice elements.

<h3 id="test-section-reference-at-beginning-of-line-and-after-a-sentence">Test Section reference at beginning of line and after a sentence </h3>

<p>
The section <a href="#subsec1">Subsection 1</a> is fine.
The section <a href="#subsubsec:ex">URLs</a> too.

<p>
<!-- sphinx code-blocks: pycod=python cod=fortran cppcod=c++ sys=console -->

<h3 id="computer-code">Computer code </h3>

<p>
Let's do some copying from files too. First from subroutine up to the very end,

<p>

<!-- code=fortran (!bc fcod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>      <span style="color: #008000; font-weight: bold">subroutine </span>test()
      <span style="color: #B00040">integer </span>i
      <span style="color: #B00040">real</span><span style="color: #666666">*8</span> r
      r <span style="color: #666666">=</span> <span style="color: #666666">0</span>
      <span style="color: #008000; font-weight: bold">do </span>i <span style="color: #666666">=</span> <span style="color: #666666">1</span>, i
         r <span style="color: #666666">=</span> r <span style="color: #666666">+</span> i
      <span style="color: #008000; font-weight: bold">end do</span>
<span style="color: #008000; font-weight: bold">      return</span>
C     END1

      <span style="color: #008000; font-weight: bold">program </span>testme
      <span style="color: #008000; font-weight: bold">call </span>test()
      <span style="color: #008000; font-weight: bold">return</span>
</pre></div>
<p>
and then just the subroutine,
<p>

<!-- code=fortran (!bc fcod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>      <span style="color: #008000; font-weight: bold">subroutine </span>test()
      <span style="color: #B00040">integer </span>i
      <span style="color: #B00040">real</span><span style="color: #666666">*8</span> r
      r <span style="color: #666666">=</span> <span style="color: #666666">0</span>
      <span style="color: #008000; font-weight: bold">do </span>i <span style="color: #666666">=</span> <span style="color: #666666">1</span>, i
         r <span style="color: #666666">=</span> r <span style="color: #666666">+</span> i
      <span style="color: #008000; font-weight: bold">end do</span>
<span style="color: #008000; font-weight: bold">      return</span>
</pre></div>
<p>
and finally the complete file with a plain text verbatim environment
(<code>envir=ccq</code>):
<p>

<!-- code=text (!bc ccq) typeset with pygments style "default" -->
<blockquote>
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>C     a comment

      subroutine test()
      integer i
      real*8 r
      r = 0
      do i = 1, i
         r = r + i
      end do
      return
C     END1

      program testme
      call test()
      return
</pre></div>
</blockquote><p>
Testing other code environments. First Python:

<p>

<!-- code=text typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>!bc pycod
def f(x):
    return x+1
!ec
</pre></div>
<p>
which gets rendered as

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">f</span>(x):
    <span style="color: #008000; font-weight: bold">return</span> x<span style="color: #666666">+1</span>
</pre></div>
<p>
Test paragraph and subsubsection headings before
before code.

<p>
<b>Paragraph heading before code.</b>

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">import</span> <span style="color: #0000FF; font-weight: bold">sys</span>
sys<span style="color: #666666">.</span>path<span style="color: #666666">.</span>insert(<span style="color: #666666">0</span>, os<span style="color: #666666">.</span>pardir)
</pre></div>

<h3 id="subsubsection-heading-before-code">Subsubsection heading before code </h3>

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">h</span>(z):
    <span style="color: #008000; font-weight: bold">return</span> z<span style="color: #666666">+1</span>
</pre></div>
<p>
Now a complete program to be shown via Python Online Tutorial:

<p>

<iframe width="950" height="500" frameborder="0"
        src="https://pythontutor.com/iframe-embed.html#code=class+Line%3A%0A++++def+__init__%28self%2C+a%2C+b%29%3A%0A++++++++self.a%2C+self.b+%3D+a%2C+b%0A%0A++++def+__call__%28self%2C+x%29%3A%0A++++++++a%2C+b+%3D+self.a%2C+self.b%0A++++++++return+a%2Ax+%2B+b%0A%0Aline+%3D+Line%282%2C+1%29%0Ay+%3D+line%28x%3D3%29%0Aprint%28y%29&py=2&curInstr=0&cumulative=false">
</iframe>
<p>
Some more Python code (actually specified as a sage cell, but
such cells are not supported by this format).

<p>


<div class="compute"><script type="text/x-sage">
a = 2
b = 3
print('a+b:', a + b)

# In a sage cell we can also plot
from matplotlib.pyplot import *
from numpy import *
x = linspace(0, 4*pi, 101)
y = exp(-0.1*x)*cos(x)
plot(x, y)
xlabel('x'); ylabel('y')
show()

</script></div>
<p>
Then Cython (with -h option so it is hidden in html/sphinx):

<p>

<!-- code=cython (!bc cycod-h) typeset with pygments style "default" -->

<script type="text/javascript">
function show_hide_code9(){
  $("#code9").toggle();
}
</script>
<button type="button" onclick="show_hide_code9()">Show/hide code</button>
<div id="code9" style="display:none">
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">cpdef</span> <span style="color: #0000FF">f</span>(double x):
    <span style="color: #008000; font-weight: bold">return</span> x <span style="color: #666666">+</span> <span style="color: #666666">1</span>
</pre></div>

</div>
<p>
Standard Python shell sessions:

<p>

<!-- code=python (!bc pyshell) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #666666">&gt;&gt;&gt;</span> <span style="color: #008000; font-weight: bold">from</span> <span style="color: #0000FF; font-weight: bold">numpy</span> <span style="color: #008000; font-weight: bold">import</span> linspace, sin
<span style="color: #666666">&gt;&gt;&gt;</span> <span style="color: #408080; font-style: italic"># Some comment</span>
<span style="color: #666666">&gt;&gt;&gt;</span> x <span style="color: #666666">=</span> linspace(<span style="color: #666666">0</span>, <span style="color: #666666">2</span>, <span style="color: #666666">11</span>)
<span style="color: #666666">&gt;&gt;&gt;</span> y <span style="color: #666666">=</span> sin(x)
<span style="color: #666666">&gt;&gt;&gt;</span> y[<span style="color: #666666">0</span>]
<span style="color: #666666">0</span>
<span style="color: #666666">&gt;&gt;&gt;</span> <span style="color: #008000; font-weight: bold">import</span> <span style="color: #0000FF; font-weight: bold">matplotlib.pyplot</span> <span style="color: #008000; font-weight: bold">as</span> <span style="color: #0000FF; font-weight: bold">plt</span>
<span style="color: #666666">&gt;&gt;&gt;</span> plt<span style="color: #666666">.</span>plot(x, y)
</pre></div>
<p>
Similar IPython sessions:

<p>

<!-- code=ipy (!bc ipy) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #000080; font-weight: bold">In [1]: </span><span style="color: #008000; font-weight: bold">from</span> <span style="color: #0000FF; font-weight: bold">numpy</span> <span style="color: #008000; font-weight: bold">import</span> linspace, sin
<span style="color: #000080; font-weight: bold">In [2]: </span><span style="color: #408080; font-style: italic"># Some comment</span>
<span style="color: #000080; font-weight: bold">In [3]: </span>x <span style="color: #666666">=</span> linspace(<span style="color: #666666">0</span>, <span style="color: #666666">2</span>, <span style="color: #666666">11</span>)
<span style="color: #000080; font-weight: bold">In [4]: </span>y <span style="color: #666666">=</span> sin(x)
<span style="color: #000080; font-weight: bold">In [5]: </span>y[<span style="color: #666666">0</span>]
<span style="color: #000080; font-weight: bold">Out[5]: </span><span style="color: #888888">0</span>
<span style="color: #000080; font-weight: bold">In [6]: </span><span style="color: #008000; font-weight: bold">import</span> <span style="color: #0000FF; font-weight: bold">matplotlib.pyplot</span> <span style="color: #008000; font-weight: bold">as</span> <span style="color: #0000FF; font-weight: bold">plt</span>
<span style="color: #000080; font-weight: bold">In [7]: </span>plt<span style="color: #666666">.</span>plot(x, y)
<span style="color: #000080; font-weight: bold">In [8]: </span>a<span style="color: #666666">=</span><span style="color: #BA2121">&#39;multiple-</span><span style="color: #BB6622; font-weight: bold">\n</span><span style="color: #BA2121">line</span><span style="color: #BB6622; font-weight: bold">\n</span><span style="color: #BA2121">output&#39;</span>
<span style="color: #000080; font-weight: bold">In [9]: </span>a
<span style="color: #000080; font-weight: bold">Out[9]: </span><span style="color: #888888">&#39;multiple-\nline\noutput&#39;</span>
<span style="color: #000080; font-weight: bold">In [10]: </span><span style="color: #008000">print</span>(a)
<span style="color: #888888">multiple-</span>
<span style="color: #888888">line</span>
<span style="color: #888888">output</span>
</pre></div>
<p>
Here is the interactive session again, but with <code>pyshell-t</code>.

<p>

<!-- code=python (!bc pyshell) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #666666">&gt;&gt;&gt;</span> <span style="color: #008000; font-weight: bold">from</span> <span style="color: #0000FF; font-weight: bold">numpy</span> <span style="color: #008000; font-weight: bold">import</span> linspace, sin
<span style="color: #666666">&gt;&gt;&gt;</span> <span style="color: #408080; font-style: italic"># Some comment</span>
<span style="color: #666666">&gt;&gt;&gt;</span> x <span style="color: #666666">=</span> linspace(<span style="color: #666666">0</span>, <span style="color: #666666">2</span>, <span style="color: #666666">11</span>)
<span style="color: #666666">&gt;&gt;&gt;</span> y <span style="color: #666666">=</span> sin(x)
<span style="color: #666666">&gt;&gt;&gt;</span> y[<span style="color: #666666">0</span>]
<span style="color: #666666">0</span>
<span style="color: #666666">&gt;&gt;&gt;</span> <span style="color: #008000; font-weight: bold">import</span> <span style="color: #0000FF; font-weight: bold">matplotlib.pyplot</span> <span style="color: #008000; font-weight: bold">as</span> <span style="color: #0000FF; font-weight: bold">plt</span>
<span style="color: #666666">&gt;&gt;&gt;</span> plt<span style="color: #666666">.</span>plot(x, y)
</pre></div>
<p>
<!-- This one tests a + sign before a code environment -->
C++:
<p>

<!-- code=c++ (!bc cpppro) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #BC7A00">#include</span> <span style="color: #408080; font-style: italic">&lt;iostream&gt;</span><span style="color: #BC7A00"></span>

<span style="color: #B00040">int</span> <span style="color: #0000FF">main</span>()
{
   std<span style="color: #666666">::</span>cout <span style="color: #666666">&lt;&lt;</span> <span style="color: #BA2121">&quot;Sample output&quot;</span> <span style="color: #666666">&lt;&lt;</span> std<span style="color: #666666">::</span>endl;
   <span style="color: #008000; font-weight: bold">return</span> <span style="color: #666666">0</span>
}
</pre></div>
<p>
<!-- The next should get correctly typset in sphinx (cod is fcod) -->
<!-- It also tests emoji before code -->
And a little bit of Fortran: <img src="https://raw.githubusercontent.com/hplgit/doconce/master/bundled/emoji/png/dizzy_face.png" width="22px" height="22px" align="center">

<p>

<!-- code=text typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>!bc cod
      subroutine midpt(x, length, a, b)
      real*8 a, b, x
      x = (a + b)/2
      length = b - a
      return
      end
!ec
</pre></div>
<p>
which then is typeset as

<p>

<!-- code=text (!bc cod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>      subroutine midpt(x, length, a, b)
      real*8 a, b, x
      x = (a + b)/2
      length = b - a
      return
      end
</pre></div>
<p>
HTML:

<p>

<!-- code=html (!bc htmlcod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>&lt;<span style="color: #008000; font-weight: bold">table</span>&gt;
&lt;<span style="color: #008000; font-weight: bold">tr</span>&gt;&lt;<span style="color: #008000; font-weight: bold">td</span>&gt;Column 1&lt;/<span style="color: #008000; font-weight: bold">td</span>&gt;&lt;<span style="color: #008000; font-weight: bold">td</span>&gt;Column 2&lt;/<span style="color: #008000; font-weight: bold">td</span>&gt;&lt;/<span style="color: #008000; font-weight: bold">tr</span>&gt;
&lt;<span style="color: #008000; font-weight: bold">tr</span>&gt;&lt;<span style="color: #008000; font-weight: bold">td</span>&gt;0.67526 &lt;/<span style="color: #008000; font-weight: bold">td</span>&gt;&lt;<span style="color: #008000; font-weight: bold">td</span>&gt;0.92871 &lt;/<span style="color: #008000; font-weight: bold">td</span>&gt;&lt;/<span style="color: #008000; font-weight: bold">tr</span>&gt;
<span style="color: #408080; font-style: italic">&lt;!-- comment --&gt;</span>
&lt;/<span style="color: #008000; font-weight: bold">table</span>&gt;
</pre></div>
<p>
But inline HTML code is also important, like text that starts with
<code>&lt;a href=&quot;</code> (which can destroy the following text if not properly
quoted).

<p>
Matlab with comments requires special typesetting:

<p>

<!-- code=matlab (!bc mcod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #408080; font-style: italic">% Comment on the beginning of the line can be escaped by %%</span>
<span style="color: #008000; font-weight: bold">if</span> a <span style="color: #666666">&gt;</span> b
  <span style="color: #408080; font-style: italic">% Indented comment needs this trick</span>
  c = a <span style="color: #666666">+</span> b
<span style="color: #008000; font-weight: bold">end</span>
</pre></div>
<p>
And here is a system call:

<p>

<!-- code=text (!bc sys) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>Terminal&gt; mkdir test
Terminal&gt; cd test
Terminal&gt; myprog -f
output1
output2
</pre></div>
<p>
Any valid pygments lexer/language name can appear to, e.g.,

<p>

<!-- code=text typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>!bc restructuredtext
=======
Heading
=======

Some text.
!ec
</pre></div>
<p>
results in

<p>

<!-- code=restructuredtext (!bc restructuredtext) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #000080; font-weight: bold">=======</span>
<span style="color: #000080; font-weight: bold">Heading</span>
<span style="color: #000080; font-weight: bold">=======</span>

Some text.
</pre></div>
<p>
<!-- Here goes hidden code. -->
<!-- Python can be treated by some formats, Fortran is always out. -->

<p>
Finally, <code>!bc do</code> supports highlighting of DocOnce source:

<p>

<!-- code=doconce (!bc do) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #000080; font-weight: bold">======= DocOnce test file =======</span>

<span style="color: #000080; font-weight: bold">===== Computer code =====</span>

Inline verbatim code, as in `import numpy as np`, is allowed, as well as
code blocks:

!bc pycod
from math import sin

def f(x):
    &quot;&quot;&quot;Example on a function.&quot;&quot;&quot;
    return sin(x) + 1

print(f(0))
!ec


<span style="color: #000080; font-weight: bold">===== Mathematics =====</span>

Formulas can be inline, as in $\nabla\cdot\boldsymbol{u} = 0$, or typeset
as equations:

!bt
<span style="color: #008000">\begin{align*}</span>
\nabla\cdot\boldsymbol{u} &amp;= 0,\\ 
\boldsymbol{u} &amp;= \nabla\phi .
<span style="color: #008000">\end{align*}</span>
!et

<span style="color: #000080; font-weight: bold">=== Subsubsection heading ===</span>

DocOnce files can have chapters, sections, subsections, and subsubsections.

<span style="color: #800080; font-weight: bold">__Paragraph heading.__</span> Paragraphs may have headings.
</pre></div>
<p>
It is time to test <code>verbatim inline font</code> especially with <code>a newline
inside the text</code> and an exclamation mark at the end: <code>BEGIN</code>! For
spellcheck, test <code>a verbatim expression</code> in <code>another</code> in a <code>third</code>.
Also test exclamation mark as in <code>!bc</code> and <code>!ec</code> as well as <code>a != b</code>.
Also test backslashes and braces like <code>\begin</code>, <code>\begin{enumerate}</code>,
<code>\end{this}\end{that}</code>, and <code>{something \inside braces}</code>.

<p>
Here is some <font color="red">red color</font> and an attempt to write <font color="green">with
green color containing a linebreak<br />
code.</font> Some formats will only display <br />
this correctly when <code>html</code> <br />
is the output format.
But here some more running text is added which is not part of
the previous blocks with line breaks.

<h3 id="running-os-commands">Running OS commands </h3>

<p>

<!-- code=text (!bc sys) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>Terminal&gt; python -c &#39;print(&quot;Testing\noutput\nfrom\nPython.&quot;)&#39;
Testing
output
from
Python.
</pre></div>

<h3 id="footnotes">Footnotes </h3>

<p>
Here is a test of footnotes [<a id="link_footnote_1" href="#def_footnote_1">1</a>], which are handy in text.
They are used in different flavors, now in

<ul>
 <li> list items (note below that footnotes work after math, verbatim, and URLs - bin fact old and emphasize too!)</li>
 <li> even with math \( \nabla^2u \) [<a id="link_footnote_2" href="#def_footnote_2">2</a>]</li>
 <li> and code <code>h[i] += 1</code> [<a id="link_footnote_3" href="#def_footnote_3">3</a>]
   (<em>must</em> have space between inline code and footnote!)</li>
 <li> and <a href="https://google.com" target="_self">links</a> [<a id="link_footnote_4" href="#def_footnote_4">4</a>]</li>
</ul>

which gives flexibility in writing.
This is the third [<a id="link_footnote_5" href="#def_footnote_5">5</a>] example.

<p id="def_footnote_1"><a href="#link_footnote_1"><b>1:</b></a> Typesetting of the footnote depends on the format.
Plain text does nothing, LaTeX removes the
definition and inserts the footnote as part of the LaTeX text.
reStructuredText and Sphinx employ a similar type of typesetting
as Extended Markdown and DocOnce, and in HTML we keep the same
syntax, just displayed properly in HTML.</p>

<p id="def_footnote_2"><a href="#link_footnote_2"><b>2:</b></a> Math footnotes can be dangerous since it
interferes with an exponent.</p>

<p id="def_footnote_3"><a href="#link_footnote_3"><b>3:</b></a> One-line footnote.</p>

<p id="def_footnote_4"><a href="#link_footnote_4"><b>4:</b></a> <a href="google.com" target="_self"><tt>google.com</tt></a> is perhaps the most famous
web site today.</p>

<p>
Here is some more text before a new definition of a footnote that was
used above.

<p>
<div class="alert alert-block alert-notice alert-text-normal">
<b>Non-breaking space character</b>
<p>
This paragraph aims to test <a href="https://en.wikipedia.org/wiki/Non-breaking_space" target="_self">non-breaking space character</a>, and a typical
example where this is needed is in physical units: 7.4&nbsp;km is traveled
in&nbsp;\( 7.4/5.5\approx 1.345 \)&nbsp;s.  Also check that a&nbsp;<a href="https://google.com" target="_self">link</a>&nbsp;is
not broken across lines (drag the browser window to test this).
(On the other hand, the tilde is used in
computer code, e.g., as in <code>[~x for x in y]</code> or in <code>y=~x</code>, and should
of course remain a tilde in those contexts.)
</div>


<h2 id="subsec:ex">Subsection 2: Testing figures</h2>

<p>
Test of figures. In particular we refer to Figure <a href="#fig:impact">1</a> in which
there is a flow.

<p>
<center> <!-- figure label: --> <div id="fig:impact"></div> <!-- FIGURE -->
<hr class="figure">
<center><p class="caption">Figure 1:  Visualization <b>of</b> a <em>wave</em>.  <!-- caption label: fig:impact --> </p></center>
<p><img src="../doc/src/manual/fig/wave1D.png" align="bottom" width=200></p>
</center>

<p>
Figures without captions are allowed and will be inlined.

<p>
<br /><br /><center><p><img src="../doc/src/manual/fig/wave1D.png" align="bottom" width=200></p></center><br /><br />

<p>
<!-- Test multi-line caption in figure with sidecap=True -->

<p>
Here is figure <a href="#myfig">2</a> with a long (illegal) multi-line caption
containing inline verbatim text:

<p>
<center> <!-- figure label: --> <div id="myfig"></div> <!-- FIGURE -->
<hr class="figure">
<table><tr>
<td><img src="../doc/src/manual/fig/wave1D.png" align="bottom" width=500></td>
<td><p class="caption">Figure 2:  A long caption spanning several lines and containing verbatim words like <code>my_file_v1</code> and <code>my_file_v2</code> as well as math with subscript as in \( t_{i+1} \).  <!-- caption label: myfig --> </p></td>
</tr></table>
</center>

<p>
<!-- Must be a blank line after MOVIE or FIGURE to detect this problem -->

<p>
Test URL as figure name:

<p>
<br /><br /><center><p><img src="https://raw.github.com/doconce/doconce/master/doc/src/blog/f_plot.png" align="bottom" width=500></p></center><br /><br />

<p>
Test SVG figure:

<p>
<br /><br /><center><p><img src="https://openclipart.org/people/jpneok/junebug.svg" align="bottom" width=200></p></center><br /><br />

<p>
<!-- Test wikimedia type of files that otherwise reside in subdirs -->

<p>
HTML output may feature Bokeh plots:

<p>
<br /><br /><center><p>
<!-- Bokeh plot -->
<script type="text/javascript">
            Bokeh.$(function() {
                var modelid = "dc6ef912-b325-4c34-996a-cdeb5aa4d7c1";
                var modeltype = "PlotContext";
                var elementid = "ffba6087-a45a-46eb-9368-11527f1f0a34";
                Bokeh.logger.info("Realizing plot:")
                Bokeh.logger.info(" - modeltype: PlotContext");
                Bokeh.logger.info(" - modelid: dc6ef912-b325-4c34-996a-cdeb5aa4d7c1");
                Bokeh.logger.info(" - elementid: ffba6087-a45a-46eb-9368-11527f1f0a34");
                var all_models = [{"attributes": {"line_color": {"value": "#1f77b4"}, "line_alpha": {"value": 1.0}, "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "y": {"field": "y"}, "x": {"field": "x"}, "id": "f55b6039-f6a1-48ce-be42-ce4e37ec18de"}, "type": "Line", "id": "f55b6039-f6a1-48ce-be42-ce4e37ec18de"}, {"attributes": {"tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "mantissas": [2, 5, 10], "id": "d8f3c08e-df44-47cd-ab00-9391128fc8ba", "num_minor_ticks": 5}, "type": "BasicTicker", "id": "d8f3c08e-df44-47cd-ab00-9391128fc8ba"}, {"attributes": {"column_names": ["x", "y"], "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "selected": {"2d": {"indices": []}, "1d": {"indices": []}, "0d": {"indices": [], "flag": false}}, "callback": null, "data": {"y": [0.0, 1.0, 8.0, 27.0], "x": [0.0, 1.0, 2.0, 3.0]}, "id": "51fd7aaa-934d-4dab-97d6-7be6eea30d89"}, "type": "ColumnDataSource", "id": "51fd7aaa-934d-4dab-97d6-7be6eea30d89"}, {"attributes": {"plot": {"subtype": "Figure", "type": "Plot", "id": "bac26888-fe18-4833-afe3-61e241eed748"}, "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "id": "8a41a3f3-b32f-4813-bc9d-78656dd129b0"}, "type": "ResizeTool", "id": "8a41a3f3-b32f-4813-bc9d-78656dd129b0"}, {"attributes": {"plot": {"subtype": "Figure", "type": "Plot", "id": "bac26888-fe18-4833-afe3-61e241eed748"}, "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "id": "734545fc-60c1-4271-bc10-b2b490266002"}, "type": "HelpTool", "id": "734545fc-60c1-4271-bc10-b2b490266002"}, {"attributes": {"names": [], "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "id": "294cc5ee-f95b-4023-8b38-eb845e408397", "renderers": []}, "type": "DataRange1d", "id": "294cc5ee-f95b-4023-8b38-eb845e408397"}, {"attributes": {"plot": {"subtype": "Figure", "type": "Plot", "id": "bac26888-fe18-4833-afe3-61e241eed748"}, "dimensions": ["width", "height"], "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "id": "26f46aa8-dc6f-4265-84dd-4525866c89d0"}, "type": "PanTool", "id": "26f46aa8-dc6f-4265-84dd-4525866c89d0"}, {"attributes": {"plot": {"subtype": "Figure", "type": "Plot", "id": "bac26888-fe18-4833-afe3-61e241eed748"}, "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "formatter": {"type": "BasicTickFormatter", "id": "a1aa95e9-9b48-4736-8854-fd7faf6b25ed"}, "ticker": {"type": "BasicTicker", "id": "71a73f31-ff56-477b-83da-62dfb4cb7d93"}, "id": "6980f350-9b3e-40f2-9ebb-d8a349a0207e"}, "type": "LinearAxis", "id": "6980f350-9b3e-40f2-9ebb-d8a349a0207e"}, {"attributes": {"plot": {"subtype": "Figure", "type": "Plot", "id": "bac26888-fe18-4833-afe3-61e241eed748"}, "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "id": "2de49bc5-9815-4275-a6de-e81ef1840cbe"}, "type": "ResetTool", "id": "2de49bc5-9815-4275-a6de-e81ef1840cbe"}, {"attributes": {"tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "mantissas": [2, 5, 10], "id": "71a73f31-ff56-477b-83da-62dfb4cb7d93", "num_minor_ticks": 5}, "type": "BasicTicker", "id": "71a73f31-ff56-477b-83da-62dfb4cb7d93"}, {"attributes": {"plot": {"subtype": "Figure", "type": "Plot", "id": "bac26888-fe18-4833-afe3-61e241eed748"}, "dimensions": ["width", "height"], "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "id": "d242820f-6005-4e2d-aaca-d2a19392726a"}, "type": "BoxZoomTool", "id": "d242820f-6005-4e2d-aaca-d2a19392726a"}, {"attributes": {"doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "id": "a1aa95e9-9b48-4736-8854-fd7faf6b25ed", "tags": []}, "type": "BasicTickFormatter", "id": "a1aa95e9-9b48-4736-8854-fd7faf6b25ed"}, {"subtype": "Figure", "type": "Plot", "id": "bac26888-fe18-4833-afe3-61e241eed748", "attributes": {"x_range": {"type": "DataRange1d", "id": "294cc5ee-f95b-4023-8b38-eb845e408397"}, "right": [], "tags": [], "tools": [{"type": "PanTool", "id": "26f46aa8-dc6f-4265-84dd-4525866c89d0"}, {"type": "WheelZoomTool", "id": "747f14a5-9f75-417c-8168-fb0a0ae3aa11"}, {"type": "BoxZoomTool", "id": "d242820f-6005-4e2d-aaca-d2a19392726a"}, {"type": "PreviewSaveTool", "id": "0c4a0cdc-08d4-4019-b03a-c03954d8f00a"}, {"type": "ResizeTool", "id": "8a41a3f3-b32f-4813-bc9d-78656dd129b0"}, {"type": "ResetTool", "id": "2de49bc5-9815-4275-a6de-e81ef1840cbe"}, {"type": "HelpTool", "id": "734545fc-60c1-4271-bc10-b2b490266002"}], "title": "Bokeh test", "extra_y_ranges": {}, "renderers": [{"type": "LinearAxis", "id": "6980f350-9b3e-40f2-9ebb-d8a349a0207e"}, {"type": "Grid", "id": "4765692c-4f39-462b-91c6-28b2f2981e00"}, {"type": "LinearAxis", "id": "ade0b05a-7b91-42dd-98de-74fb64acf6f7"}, {"type": "Grid", "id": "b9b421c8-77f3-4e7e-826b-ac6bf659b06a"}, {"type": "GlyphRenderer", "id": "2880ba24-eb39-4b26-b4fc-475578d6fd4c"}], "extra_x_ranges": {}, "below": [{"type": "LinearAxis", "id": "6980f350-9b3e-40f2-9ebb-d8a349a0207e"}], "tool_events": {"type": "ToolEvents", "id": "1695660e-4ea6-4d6d-9921-0d71ad942082"}, "above": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "y_range": {"type": "DataRange1d", "id": "c973a007-1e1b-45a1-a7ba-d05f16dfaad0"}, "id": "bac26888-fe18-4833-afe3-61e241eed748", "left": [{"type": "LinearAxis", "id": "ade0b05a-7b91-42dd-98de-74fb64acf6f7"}]}}, {"attributes": {"names": [], "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "id": "c973a007-1e1b-45a1-a7ba-d05f16dfaad0", "renderers": []}, "type": "DataRange1d", "id": "c973a007-1e1b-45a1-a7ba-d05f16dfaad0"}, {"attributes": {"tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "id": "dc6ef912-b325-4c34-996a-cdeb5aa4d7c1", "children": [{"subtype": "Figure", "type": "Plot", "id": "bac26888-fe18-4833-afe3-61e241eed748"}]}, "type": "PlotContext", "id": "dc6ef912-b325-4c34-996a-cdeb5aa4d7c1"}, {"attributes": {"line_color": {"value": "#1f77b4"}, "line_alpha": {"value": 0.1}, "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "y": {"field": "y"}, "x": {"field": "x"}, "id": "af17e0b1-cd09-4529-b97b-aefe6bff3ee2"}, "type": "Line", "id": "af17e0b1-cd09-4529-b97b-aefe6bff3ee2"}, {"attributes": {"plot": {"subtype": "Figure", "type": "Plot", "id": "bac26888-fe18-4833-afe3-61e241eed748"}, "dimensions": ["width", "height"], "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "id": "747f14a5-9f75-417c-8168-fb0a0ae3aa11"}, "type": "WheelZoomTool", "id": "747f14a5-9f75-417c-8168-fb0a0ae3aa11"}, {"attributes": {"plot": {"subtype": "Figure", "type": "Plot", "id": "bac26888-fe18-4833-afe3-61e241eed748"}, "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "formatter": {"type": "BasicTickFormatter", "id": "e6be9566-7576-4bac-a09f-bf95a818d7f8"}, "ticker": {"type": "BasicTicker", "id": "d8f3c08e-df44-47cd-ab00-9391128fc8ba"}, "id": "ade0b05a-7b91-42dd-98de-74fb64acf6f7"}, "type": "LinearAxis", "id": "ade0b05a-7b91-42dd-98de-74fb64acf6f7"}, {"attributes": {"plot": {"subtype": "Figure", "type": "Plot", "id": "bac26888-fe18-4833-afe3-61e241eed748"}, "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "dimension": 1, "ticker": {"type": "BasicTicker", "id": "d8f3c08e-df44-47cd-ab00-9391128fc8ba"}, "id": "b9b421c8-77f3-4e7e-826b-ac6bf659b06a"}, "type": "Grid", "id": "b9b421c8-77f3-4e7e-826b-ac6bf659b06a"}, {"attributes": {"nonselection_glyph": {"type": "Line", "id": "af17e0b1-cd09-4529-b97b-aefe6bff3ee2"}, "data_source": {"type": "ColumnDataSource", "id": "51fd7aaa-934d-4dab-97d6-7be6eea30d89"}, "name": null, "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "selection_glyph": null, "id": "2880ba24-eb39-4b26-b4fc-475578d6fd4c", "glyph": {"type": "Line", "id": "f55b6039-f6a1-48ce-be42-ce4e37ec18de"}}, "type": "GlyphRenderer", "id": "2880ba24-eb39-4b26-b4fc-475578d6fd4c"}, {"attributes": {"plot": {"subtype": "Figure", "type": "Plot", "id": "bac26888-fe18-4833-afe3-61e241eed748"}, "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "dimension": 0, "ticker": {"type": "BasicTicker", "id": "71a73f31-ff56-477b-83da-62dfb4cb7d93"}, "id": "4765692c-4f39-462b-91c6-28b2f2981e00"}, "type": "Grid", "id": "4765692c-4f39-462b-91c6-28b2f2981e00"}, {"attributes": {"plot": {"subtype": "Figure", "type": "Plot", "id": "bac26888-fe18-4833-afe3-61e241eed748"}, "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "id": "0c4a0cdc-08d4-4019-b03a-c03954d8f00a"}, "type": "PreviewSaveTool", "id": "0c4a0cdc-08d4-4019-b03a-c03954d8f00a"}, {"attributes": {"geometries": [], "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "id": "1695660e-4ea6-4d6d-9921-0d71ad942082"}, "type": "ToolEvents", "id": "1695660e-4ea6-4d6d-9921-0d71ad942082"}, {"attributes": {"doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "id": "e6be9566-7576-4bac-a09f-bf95a818d7f8", "tags": []}, "type": "BasicTickFormatter", "id": "e6be9566-7576-4bac-a09f-bf95a818d7f8"}];
                Bokeh.load_models(all_models);
                var model = Bokeh.Collections(modeltype).get(modelid);
                var view = new model.default_view({model: model, el: '#ffba6087-a45a-46eb-9368-11527f1f0a34'});
                Bokeh.index[modelid] = view
            });
        </script>
<div class="plotdiv" id="ffba6087-a45a-46eb-9368-11527f1f0a34"></div></p></center><br /><br />

<p>
<b>Remark.</b>
Movies are tested in separate file <code>movies.do.txt</code>.

<p>
<!-- Somewhat challenging heading with latex math, \t, \n, ? and parenthesis -->

<h2 id="decay:sec:theta">The \( \theta \) parameter (not \( \nabla \)?)</h2>

<p>
Functions do not always need to be advanced, here is one
involving \( \theta \):
<p>

<!-- code=text typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>def f(theta):
    return theta**2
</pre></div>
<p>
<b>More on \( \theta \).</b>
Here is more text following headline with math.

<p>
Newcommands must also be tested in this test report:
\( \frac{1}{2} \), \( {1/2} \), \( \pmb{x} \), \( \frac{Du}{dt} \),
both inline and in block:

$$
\begin{align}
\frac{Du}{dt} &= 0\nonumber
\\ 
\frac{1}{2} &= {1/2}
\label{_auto1}\\ 
\frac{1}{2}\pmb{x} &= \pmb{n}
\label{_auto2}
\end{align}
$$

<p>
Or with align with label and numbers:

$$
\begin{align}
\frac{Du}{dt} &= 0
\label{aligneq1}
\\ 
\frac{1}{2} &= {1/2}
\label{_auto3}\\ 
\frac{1}{2}\pmb{x} &= \pmb{n}
\label{aligneq2}
\end{align}
$$

<p>
<!-- Must test more complicated align and matrix compositions -->
<!-- where DocOnce inserts auto-numbered labels etc. -->

<p>
First one numbered (automatically):

$$
\begin{align}
\begin{pmatrix}
G_2 + G_3 & -G_3 & -G_2 & 0 \\ 
-G_3 & G_3 + G_4 & 0 & -G_4 \\ 
-G_2 & 0 & G_1 + G_2 & 0 \\ 
0 & -G_4 & 0 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
 v_1 \\ 
 v_2 \\ 
 v_3 \\ 
 v_4
\end{pmatrix}
+ \cdots  \label{_auto4}
\\ 
\begin{pmatrix}
 C_5 + C_6 & -C_6 & 0 & 0 \\ 
 -C_6 & C_6 & 0 & 0 \\ 
 0 & 0 & 0 & 0 \\ 
 0 & 0 & 0 & 0
\end{pmatrix}
  &= \frac{d}{dt}\begin{pmatrix}
 v_1 \\ 
 v_2 \\ 
 v_3 \\ 
 v_4
\end{pmatrix} +
\begin{pmatrix}
 0 \\ 
 0 \\ 
 0 \\ 
 -i_0
\end{pmatrix}
\nonumber
\label{_auto5}
\end{align}$$

<p>
Second numbered (automatically):

$$
\begin{align}
\begin{pmatrix}
G_1 + G_2\\ 
-G_3 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
 v_1 \\ 
 v_2
\end{pmatrix}
+ \cdots\nonumber
\label{_auto6}
\\ 
\left(\begin{array}{ll}
y & 2\\ 
2 & 1
\end{array}\right)
\left(\begin{array}{ll}
0 \\ x
\end{array}\right)
&= \begin{pmatrix}
A \\ B
\end{pmatrix}
\label{_auto7}
\end{align}$$

<p>
Both numbered, with label by the user:

$$
\begin{align}
\begin{pmatrix}
G_1 + G_2\\ 
-G_3 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
 v_1 \\ 
 v_2
\end{pmatrix}
+ \cdots \label{mymatrix:eq1}
\\ 
\label{mymatrix:eq2}
\left(\begin{array}{ll}
y & 2\\ 
2 & 1
\end{array}\right)
\left(\begin{array}{ll}
0 \\ x
\end{array}\right)
&= \begin{pmatrix}
A \\ B
\end{pmatrix}
\end{align}$$

Now we refer to \eqref{mymatrix:eq1}-\eqref{mymatrix:eq2}.

<h2 id="custom-environments">Custom Environments </h2>

<p>
Here is an attempt to create a theorem environment via Mako
(for counting theorems) and comment lines to help replacing lines in
the <code>.tex</code> by proper begin-end LaTeX environments for theorems.
Should look nice in most formats!

<p>
<!-- begin theorem -->
<div id="theorem:fundamental1"></div>

<p>
<b>Theorem 5.</b>
Let \( a=1 \) and \( b=2 \). Then \( c=3 \).
<!-- end theorem -->

<p>
<!-- begin proof -->
<b>Proof.</b>
Since \( c=a+b \), the result follows from straightforward addition.
\( \Diamond \)
<!-- end proof -->

<p>
As we see, the proof of Theorem 5 is a modest
achievement.

<h2 id="subsec:table">Tables</h2>

<p>
<!-- index with comma could fool sphinx -->

<p>
Let us take this table from the manual:

<p>
<table border="1">
<thead>
<tr><th align="center">time</th> <th align="center">velocity</th> <th align="center">acceleration</th> </tr>
</thead>
<tbody>
<tr><td align="left">   0.0     </td> <td align="right">   1.4186      </td> <td align="right">   -5.01           </td> </tr>
<tr><td align="left">   2.0     </td> <td align="right">   1.376512    </td> <td align="right">   11.919          </td> </tr>
<tr><td align="left">   4.0     </td> <td align="right">   1.1E+1      </td> <td align="right">   14.717624       </td> </tr>
</tbody>
</table>
<p>
The DocOnce source code reads
<p>

<!-- code=text (!bc ccq) typeset with pygments style "default" -->
<blockquote>
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>  |--------------------------------|
  |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>
</blockquote><p>
Here is yet another table to test that we can handle more than
one table:

<p>
<table border="1">
<thead>
<tr><th align="left">time</th> <th align="left">velocity</th> <th align="left">acceleration</th> </tr>
</thead>
<tbody>
<tr><td align="left">   0.0     </td> <td align="left">   1.4186      </td> <td align="left">   -5.01           </td> </tr>
<tr><td align="left">   1.0     </td> <td align="left">   1.376512    </td> <td align="left">   11.919          </td> </tr>
<tr><td align="left">   3.0     </td> <td align="left">   1.1E+1      </td> <td align="left">   14.717624       </td> </tr>
</tbody>
</table>
<p>
And one with math headings (that are expanded and must be treated
accordingly), verbatim heading and entry, and no space around the pipe
symbol:

<p>
<table border="1">
<thead>
<tr><td align="center">\( i \)</td> <td align="center">\( h_i \)</td> <td align="center">\( \bar T_i \)</td> <td align="center"><code>L_i</code></td> </tr>
</thead>
<tbody>
<tr><td align="left">   0          </td> <td align="right">   0            </td> <td align="right">   288               </td> <td align="right">   -0.0065             </td> </tr>
<tr><td align="left">   1          </td> <td align="right">   11,000       </td> <td align="right">   216               </td> <td align="right">   0.0                 </td> </tr>
<tr><td align="left">   2          </td> <td align="right">   20,000       </td> <td align="right">   216               </td> <td align="right">   0.001               </td> </tr>
<tr><td align="left">   3          </td> <td align="right">   32,000       </td> <td align="right">   228               </td> <td align="right">   0.0028              </td> </tr>
<tr><td align="left">   4          </td> <td align="right">   47,000       </td> <td align="right">   270               </td> <td align="right">   0.0                 </td> </tr>
<tr><td align="left">   5          </td> <td align="right">   51,000       </td> <td align="right">   270               </td> <td align="right">   -0.0028             </td> </tr>
<tr><td align="left">   6          </td> <td align="right">   71,000       </td> <td align="right">   214               </td> <td align="right">   <code>NaN</code>    </td> </tr>
</tbody>
</table>
<p>
And add one with verbatim headings (with underscores),
and rows starting with <code>|-</code> because of a negative number,
and <code>|</code> right before and after verbatim word (with no space):

<p>
<table border="1">
<thead>
<tr><th align="center">exact</th> <td align="center"><code>v_1</code></td> <td align="center">\( a_i \) + <code>v_2</code></td> <td align="center"><code>verb_3_</code></td> </tr>
</thead>
<tbody>
<tr><td align="right">   9        </td> <td align="right">   9.62                </td> <td align="right">   5.57                            </td> <td align="right">   8.98                    </td> </tr>
<tr><td align="right">   -20      </td> <td align="right">   -23.39              </td> <td align="right">   -7.65                           </td> <td align="right">   -19.93                  </td> </tr>
<tr><td align="right">   10       </td> <td align="right">   17.74               </td> <td align="right">   -4.50                           </td> <td align="right">   9.96                    </td> </tr>
<tr><td align="right">   0        </td> <td align="right">   -9.19               </td> <td align="right">   4.13                            </td> <td align="right">   -0.26                   </td> </tr>
</tbody>
</table>
<p>
Pipe symbols in verbatim and math text in tables used to pose difficulties,
but not
anymore:

<p>
<table border="1">
<thead>
<tr><td align="center">   \( S \)   </td> <th align="center">        command         </th> </tr>
</thead>
<tbody>
<tr><td align="left">   $ ||a_0|| $      </td> <td align="right">   <code>norm|length</code>    </td> </tr>
<tr><td align="left">   \( x\cap y \)    </td> <td align="right">   <code>x|y</code>            </td> </tr>
</tbody>
</table>
<p>
Here is a table with X alignment:

<p>
<table border="1">
<thead>
<tr><th align="center"> Type</th> <th align="center">                                                                                                                Description                                                                                                                 </th> </tr>
</thead>
<tbody>
<tr><td align="center">   X        </td> <td align="left">   Alignment character that is used for specifying a potentially very long text in a column in a table. It makes use of the <code>tabularx</code> package in LaTeX, otherwise (for other formats) it means <code>l</code> (centered alignment).    </td> </tr>
<tr><td align="center">   l,r,c    </td> <td align="left">   standard alignment characters                                                                                                                                                                                                                   </td> </tr>
</tbody>
</table>
<p>
Finally, a table with math
(<code>bm</code> that expands to <code>boldsymbol</code>, was tricky, but
cleanly handled now)
and URLs.

<p>
<!-- Mako code to expand URLs in the table -->
<!-- (These types of tables did not work before Jan 2014) -->

<p>
<table border="1">
<tr></tr>
<tbody>
<tr><td align="center">   \( \mathcal{L}=0 \)                    </td> <td align="center">   <a href="../doc/src/manual/mov/wave_frames/frame_0080.png"><img src="../doc/src/manual/mov/wave_frames/frame_0080.png" width="300"></a>    </td> <td align="center">   <a href="../doc/src/manual/mov/wave_frames/frame_0085.png"><img src="../doc/src/manual/mov/wave_frames/frame_0085.png" width="300"></a>    </td> </tr>
<tr><td align="center">   \( a=b \)                              </td> <td align="center">   <a href="../doc/src/manual/mov/wave_frames/frame_0090.png"><img src="../doc/src/manual/mov/wave_frames/frame_0090.png" width="300"></a>    </td> <td align="center">   <a href="../doc/src/manual/mov/wave_frames/frame_0095.png"><img src="../doc/src/manual/mov/wave_frames/frame_0095.png" width="300"></a>    </td> </tr>
<tr><td align="center">   \( \nabla\cdot\boldsymbol{u} =0  \)    </td> <td align="center">   <a href="../doc/src/manual/mov/wave_frames/frame_0100.png"><img src="../doc/src/manual/mov/wave_frames/frame_0100.png" width="300"></a>    </td> <td align="center">   <a href="../doc/src/manual/mov/wave_frames/frame_0105.png"><img src="../doc/src/manual/mov/wave_frames/frame_0105.png" width="300"></a>    </td> </tr>
</tbody>
</table>

<h2 id="a-test-of-verbatim-words-in-heading-with-subscript-a_i-my_file_v1-and-my_file_v2">A test of verbatim words in heading with subscript \( a_i \): <code>my_file_v1</code> and <code>my_file_v2</code> </h2>

<p>
<b>Paragraph with verbatim and math: <code>my_file_v1.py</code> and <code>my_file_v2.py</code> define some math \( a_{i-1} \).</b>
Here is more <code>__verbatim__</code> code and
some plain text on a new line.

<p>
<!-- Test various types of headlines -->

<h2 id="_just-bold_"><b>Just bold</b> </h2>

<p>
Some text.

<h2 id="just-emphasize"><em>Just emphasize</em> </h2>

<p>
Some text.

<h2 id="just-verbatim"><code>Just verbatim</code> </h2>

<p>
Some text.

<h2 id="_bold_-beginning"><b>Bold</b> beginning </h2>

<p>
Some text.

<h2 id="emphasize-beginning"><em>Emphasize</em> beginning </h2>

<p>
Some text.

<h2 id="verbatim-beginning"><code>Verbatim</code> beginning </h2>

<p>
Some text.

<h2 id="maybe-_bold-end_">Maybe <b>bold end</b> </h2>

<p>
Some text.

<h2 id="maybe-emphasize-end">Maybe <em>emphasize end</em> </h2>

<p>
Some text.

<h2 id="maybe-verbatim-end">Maybe <code>verbatim end</code> </h2>

<p>
Some text.

<h2 id="the-middle-has-<b>bold</b>-word">The middle has <b>bold</b> word </h2>

<p>
Some text.

<h2 id="the-middle-has-emphasize-word">The middle has <em>emphasize</em> word </h2>

<p>
Some text.

<h2 id="the-middle-has-verbatim-word">The middle has <code>verbatim</code> word </h2>

<p>
Some text.

<p>
<b><em>Just emphasize</em>.</b>
Some text.

<p>
<b><code>Just verbatim</code>.</b>
Some text.

<p>
<b><em>Emphasize</em> beginning.</b>
Some text.

<p>
<b><code>Verbatim beginning</code>.</b>
Some text.

<p>
<b>Maybe <em>emphasize end</em>.</b>
Some text.

<p>
<b>Maybe <code>verbatim end</code>.</b>
Some text.

<p>
<b>The middle has <em>emphasize</em> word.</b>
Some text.

<p>
<b>The middle has <code>verbatim</code> word.</b>
Some text.

<p>
<b>Ampersand.</b>
We can test Hennes &amp; Mauritz, often abbreviated H&amp;M, but written
as <code>Hennes & Mauritz</code> and <code>H & M</code>.
A sole <code>&</code> must also work.
<!-- Note: substitutions must not occur inside verbatim, just in ordinary text. -->

<p>

<!-- code=text typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span># Just to check that ampersand works in code blocks:
c = a &amp; b
</pre></div>
<p>
<b>Quotes.</b>
Let us also add a test of quotes such as &quot;double quotes, with numbers
like 3.14 and newline/comma and hyphen (as in double-quote)&quot;; written
in the standard LaTeX-style that gives correct LaTeX formatting and
ordinary double quotes for all non-LaTeX formats.  Here is another
sentence that &quot;caused&quot; a bug in the past because double backtick
quotes could imply verbatim text up to a verbatim word starting with
period, like <code>.txt</code>.

<p>
More quotes to be tested for spellcheck:
(&quot;with parenthesis&quot;), &quot;with newline&quot;
and &quot;with comma&quot;, &quot;hyphen&quot;-wise, and &quot;period&quot;.

<h2 id="bibliography-test">Bibliography test </h2>

<p>
Here is an example: <a href="#Langtangen_Pedersen_2002">[1]</a> discussed propagation of
large destructive water waves, <a href="#Langtangen_et_al_2002">[2]</a> gave
an overview of numerical methods for solving the Navier&ndash;Stokes equations,
while the use of Backward Kolmogorov equations for analyzing
random vibrations was investigated in <a href="#Langtangen_1994a">[3]</a>.
The book chapter <a href="#Mardal_et_al_2003a">[4]</a> contains information on
C++ software tools for programming multigrid methods. A real retro
reference is <a href="#Langtangen_1988d">[5]</a> about a big FORTRAN package.
Multiple references are also possible, e.g., see
<a href="#Langtangen_Pedersen_2002">[1]</a> <a href="#Mardal_et_al_2003a">[4]</a>.

<p>
We need to cite more than 10 papers to reproduce an old formatting
problem with blanks in the keys in reST format:
<a href="#Langtangen_1992c">[6]</a> <a href="#Langtangen_1994a">[3]</a> <a href="#Mortensen_et_al_2011">[7]</a> <a href="#Langtangen_Pedersen_2002">[1]</a>
and
<a href="#Langtangen_et_al_2002">[2]</a> <a href="#Glimsdal_et_al_20006">[8]</a> <a href="#Rahman_et_al_2006b">[9]</a> <a href="#Haga_et_al_2011a">[10]</a> <a href="#Langtangen_2003a">[11]</a> <a href="#Langtangen_2008a">[12]</a> <a href="#Langtangen:95">[13]</a>
and all the work of
<a href="#Langtangen_2012">[14]</a> <a href="#Mardal_et_al_2003a">[4]</a> <a href="#Jeberg_et_al_2004">[15]</a> as well as
old work <a href="#Langtangen_1988d">[5]</a> and <a href="#Langtangen_1989e">[16]</a>, and the
talk <a href="#Langtangen_talk_2007a">[17]</a>.
Langtangen also had two thesis <a href="#Langtangen:85">[18]</a> <a href="#Langtangen_1989e">[16]</a>
back in the days.
More retro citations are
the old ME-IN323 book <a href="#Langtangen:91">[19]</a> and the
<a href="#Langtangen:94b">[20]</a> OONSKI '94 paper.

<p>
<!-- --- begin exercise --- -->

<h2 id="Example">Example 1: Examples can be typeset as exercises</h2>

<p>
Examples can start with a subsection heading starting with <code>Example:</code>
and then, with the command-line option <code>--examples_as_exercises</code> be
typeset as exercises. This is useful if one has solution
environments as part of the example.

<p>
<b>a)</b>
State some problem.

<p>
<b>Solution.</b>
The answer to this subproblem can be written here.

<p>
<b>b)</b>
State some other problem.

<p>
<b>Hint 1.</b>
A hint can be given.

<p>
<b>Hint 2.</b>
Maybe even another hint?

<p>
<b>Solution.</b>
The answer to this other subproblem goes here,
maybe over multiple doconce input lines.

<p>
<!-- --- end exercise --- -->

<h2 id="user-defined-environments">User-defined environments </h2>

<p>
The example in the section <a href="#ex:test:1p1">Example 1: A test function</a> demonstrates how to write a test function.
That is, a special test function for a function <code>add</code> appears in
the example in the section <a href="#ex:test:1p1">Example 1: A test function</a>.

<h2 id="ex:test:1p1">Example 1: A test function</h2>

<p>
Suppose we want to write a test function for checking the
implementation of a Python function for addition.

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">add</span>(a, b):
    <span style="color: #008000; font-weight: bold">return</span> a <span style="color: #666666">+</span> b

<span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">test_add</span>():
    a <span style="color: #666666">=</span> <span style="color: #666666">1</span>; b <span style="color: #666666">=</span> <span style="color: #666666">1</span>
    expected <span style="color: #666666">=</span> a <span style="color: #666666">+</span> b
    computed <span style="color: #666666">=</span> add(a, b)
    <span style="color: #008000; font-weight: bold">assert</span> expected <span style="color: #666666">==</span> computed
</pre></div>

<h2 id="ex:math:1p1">Example 2: Addition</h2>

<p>
We have

$$ 1 + 1 = 2 $$

or in tabular form:

<p>
<table border="1">
<thead>
<tr><th align="center"> Problem </th> <th align="center"> Result</th> </tr>
</thead>
<tbody>
<tr><td align="center">   \( 1+1 \)    </td> <td align="center">   \( 2 \)    </td> </tr>
</tbody>
</table>
<p>
<div style="width: 60%; padding: 10px; border: 1px solid #000;
 border-radius: 4px; box-shadow: 8px 8px 5px #888888;
 background: #cce5ff;">
 <b>Highlight box!</b><hr>
This environment is used to highlight something:

$$ E = mc^2 $$

</div>

<h2 id="subsubsec:ex">URLs</h2>

<p>
Testing of URLs: hpl's home page <a href="https://folk.uio.no/hpl" target="_self">hpl</a>, or
the entire URL if desired, <a href="https://folk.uio.no/hpl" target="_self"><tt>https://folk.uio.no/hpl</tt></a>.  Here is a
plain file link <a href="testdoc.do.txt" target="_self"><tt>testdoc.do.txt</tt></a>, or <a href="testdoc.do.txt" target="_self"><tt>testdoc.do.txt</tt></a>, or
<a href="testdoc.do.txt" target="_self"><tt>testdoc.do.txt</tt></a> or <a href="testdoc.do.txt" target="_self"><tt>testdoc.do.txt</tt></a> or <a href="testdoc.do.txt" target="_self">a link with
newline</a>. Can test spaces with the link with word
too: <a href="https://folk.uio.no/hpl" target="_self">hpl</a> or <a href="https://folk.uio.no/hpl" target="_self">hpl</a>. Also <code>file:///</code> works: <a href="file:///home/hpl/vc/doconce/doc/demos/manual/manual.html" target="_self">link to a
file</a> is
fine to have. Moreover, &quot;loose&quot; URLs work, i.e., no quotes, just
the plain URL as in <a href="https://folk.uio.no/hpl" target="_self"><tt>https://folk.uio.no/hpl</tt></a>, if followed by space, comma,
colon, semi-colon, question mark, exclamation mark, but not a period
(which gets confused with the periods inside the URL).

<p>
Mail addresses can also be used: <a href="mailto:hpl@simula.no" target="_self"><tt>hpl@simula.no</tt></a>, or just a <a href="mailto:hpl@simula.no" target="_self">mail link</a>, or a raw <a href="mailto:hpl@simula.no" target="_self"><tt>mailto:hpl@simula.no</tt></a>.

<p>
Here are some tough tests of URLs, especially for the <code>latex</code> format:
<a href="https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas" target="_self">Newton-Cotes</a> formulas
and a <a href="https://www.springer.com/mathematics/computational+science+%26+engineering/book/978-3-642-23098-1" target="_self">good book</a>. Need to test
Newton-Cotes with percentage in URL too:
<a href="https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas" target="_self"><tt>https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas</tt></a>
and <a href="https://en.wikipedia.org/wiki/Newton-Cotes#Open_Newton.E2.80.93Cotes_formulae" target="_self"><tt>https://en.wikipedia.org/wiki/Newton-Cotes#Open_Newton.E2.80.93Cotes_formulae</tt></a> which has a shebang.

<p>
For the <code>--device=paper</code> option it is important to test that URLs with
monospace font link text get a footnote
(unless the <code>--latex_no_program_footnotelink</code>
is used), as in this reference to
<a href="https://github.com/hplgit/INF5620/tree/gh-pages/src/decay/experiments/decay_mod.py" target="_self"><tt>decay_mod</tt></a>, <a href="https://tinyurl.com/pwyasaa/formulas.ball1.py" target="_self"><tt>ball1.py</tt></a>,
and <a href="https://tinyurl.com/pwyasaa/formulas.ball2.py" target="_self"><tt>ball2.py</tt></a>.

<p>
<!-- Comments should be inserted outside paragraphs (because in the rst -->
<!-- format extra blanks make a paragraph break). -->

<p>
<!-- Note that when there is no https: or file:, it can be a file link -->
<!-- if the link name is URL, url, "URL", or "url". Such files should, -->
<!-- if rst output is desired, but placed in a <code>_static*</code> folder. -->

<p>
More tough tests: repeated URLs whose footnotes when using the
<code>--device=paper</code> option must be correct. We have
<a href="https://google.com" target="_self">google</a>, <a href="https://google.com" target="_self">google</a>, and
<a href="https://google.com" target="_self">google</a>, which should result in exactly three
footnotes.

<p>
<!-- !split and check if these extra words are included properly in the comment -->

<h1 id="latex-mathematics">LaTeX Mathematics </h1>

<p>
Here is an equation without label using backslash-bracket environment:
$$ a = b + c $$

<p>
or with number and label, as in \eqref{my:eq1}, using the equation environment:

$$
\begin{equation}
{\partial u\over\partial t} = \nabla^2 u \label{my:eq1}
\end{equation}
$$

<p>
We can refer to this equation by \eqref{my:eq1}.

<p>
Here is a system without equation numbers, using the align-asterisk environment:

$$
\begin{align*}
\pmb{a} &= \pmb{q}\times\pmb{n} \\ 
b &= \nabla^2 u + \nabla^4 v
\end{align*}
$$

<p>
And here is a system of equations with labels in an align environment:

$$
\begin{align}
a &= q + 4 + 5+ 6 \label{eq1} \\ 
b &= \nabla^2 u + \nabla^4 x \label{eq2}
\end{align}

$$

We can refer to \eqref{eq1}-\eqref{eq2}. They are a bit simpler than
the Navier&ndash;Stokes equations. And test LaTeX hyphen in <code>CG-2</code>.
Also test \( a_{i-j} \) as well as \( kx-wt \).

<p>
Testing <code>alignat</code> environment:

$$
\begin{alignat}{2}
a &= q + 4 + 5+ 6\qquad & \mbox{for } q\geq 0 \label{eq1a} \\ 
b &= \nabla^2 u + \nabla^4 x & x\in\Omega \label{eq2a}
\end{alignat}
$$

<p>
More mathematical typesetting is demonstrated in the coming exercises.

<p>
Below, we have <a href="#demo:ex:1">Problem 2: Flip a Coin</a> and <a href="#demo:ex:2">Project 4: Compute a Probability</a>,
as well as <a href="#proj:circle1">Project 5: Explore Distributions of Random Circles</a> and <a href="#exer:you">Project 11: References in a headings do not work well in html</a>, and in
between there we have <a href="#exer:some:formula">Exercise 10: Make references to projects and problems</a>.

<h1 id="exercises">Exercises </h1>

<p>
<!-- --- begin exercise --- -->

<h2 id="demo:ex:1">Problem 2: Flip a Coin</h2>
<!-- keywords = random numbers; Monte Carlo simulation; ipynb -->

<p>
<!-- Torture tests -->

<p>
<b>a)</b>
Make a program that simulates flipping a coin \( N \) times.
Print out &quot;tail&quot; or &quot;head&quot; for each flip and
let the program count the number of heads.

<p>
<!-- --- begin hint in exercise --- -->

<p>
<b>Hint 1.</b>
Use <code>r = random.random()</code> and define head as <code>r &lt;= 0.5</code>.

<p>
<!-- --- end hint in exercise --- -->

<p>
<!-- --- begin hint in exercise --- -->

<p>
<b>Hint 2.</b>
Draw an integer among \( \{1,2\} \) with
<code>r = random.randint(1,2)</code> and define head when <code>r</code> is 1.

<p>
<!-- --- end hint in exercise --- -->

<p>
<!-- removed !bans ... !eans environment (because of the command-line option --without_answers)
 -->
<p>
<!-- removed !bsol ... !esol environment (because of the command-line option --without_solutions)
 -->
<p>
<b>b)</b>
Vectorize the code in a) using boolean indexing.

<p>
Vectorized code can be written in many ways.
Sometimes the code is less intuitive, sometimes not.
At least there is not much to find in the section <a href="#sec1">Section 1</a>.

<p>
<b>c)</b>
Vectorize the code in a) using <code>numpy.sum</code>.

<p>
<!-- removed !bans ... !eans environment (because of the command-line option --without_answers)
 -->
<p>
In this latter subexercise, we have an
example where the code is easy to read.

<h3 id="my-remarks">My remarks </h3>

<p>
Remarks with such a subsubsection is treated as more text
after the last subexercise. Test a list too:

<ol>
<li> Mark 1.</li>
<li> Mark 2.</li>
</ol>

Filenames: <code>flip_coin.py</code>, <code>flip_coin.pdf</code>.

<p>
<!-- Closing remarks for this Problem -->

<h3 id="remarks">Remarks </h3>

<p>
These are the exercise remarks, appearing at the very end.

<p>
<!-- solution files: mysol.txt, mysol_flip_coin.py, yet_another.file -->

<p>
<!-- --- end exercise --- -->

<h2 id="not-an-exercise">Not an exercise </h2>

<p>
Should be possible to stick a normal section in the middle of many
exercises.

<p>
<!-- --- begin exercise --- -->

<h2 id="my:exer1">Exercise 3: Test of plain text exercise</h2>

<p>
Very short exercise. What is the capital
of Norway?
Filename: <code>myexer1</code>.

<p>
<!-- --- end exercise --- -->

<p>
<!-- --- begin exercise --- -->

<h2 id="demo:ex:2">Project 4: Compute a Probability</h2>

<p>
<!-- Minimalistic exercise -->

<p>
What is the probability of getting a number between 0.5 and 0.6 when
drawing uniformly distributed random numbers from the interval \( [0,1) \)?

<p>
At the end we have a list because that caused problems in LaTeX
in previous DocOnce versions:

<ol>
<li> item1</li>
<li> item2</li>
</ol>

<!-- --- begin hint in exercise --- -->

<p>
<b>Hint.</b>
To answer this question empirically, let a program
draw \( N \) such random numbers using Python's standard <code>random</code> module,
count how many of them, \( M \), that fall in the interval \( (0.5,0.6) \), and
compute the probability as \( M/N \).

<p>
<!-- --- end hint in exercise --- -->

<p>
<!-- --- end exercise --- -->

<p>
<!-- --- begin exercise --- -->

<h2 id="proj:circle1">Project 5: Explore Distributions of Random Circles</h2>
<!-- keywords = ipynb -->

<p>
The formula for a circle is given by

$$
\begin{align}
x &= x_0 + R\cos 2\pi t,
\label{circle:x}\\ 
y &= y_0 + R\sin 2\pi t,
\label{circle:y}
\end{align}
$$

where \( R \) is the radius of the circle, \( (x_0,y_0) \) is the
center point, and \( t \) is a parameter in the unit interval \( [0,1] \).
For any \( t \), \( (x,y) \) computed from \eqref{circle:x}-\eqref{circle:y}
is a point on the circle.
The formula can be used to generate <code>n</code> points on a circle:

<p>

<!-- code=python (!bc pypro) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">import</span> <span style="color: #0000FF; font-weight: bold">numpy</span> <span style="color: #008000; font-weight: bold">as</span> <span style="color: #0000FF; font-weight: bold">np</span>

<span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">circle</span>(R, x0, y0, n<span style="color: #666666">=501</span>):
    t <span style="color: #666666">=</span> np<span style="color: #666666">.</span>linspace(<span style="color: #666666">0</span>, <span style="color: #666666">1</span>, n)
    x <span style="color: #666666">=</span> x0 <span style="color: #666666">+</span> R<span style="color: #666666">*</span>np<span style="color: #666666">.</span>cos(<span style="color: #666666">2*</span>np<span style="color: #666666">.</span>pi<span style="color: #666666">*</span>t)
    y <span style="color: #666666">=</span> y0 <span style="color: #666666">+</span> R<span style="color: #666666">*</span>np<span style="color: #666666">.</span>sin(<span style="color: #666666">2*</span>np<span style="color: #666666">.</span>pi<span style="color: #666666">*</span>t)
    <span style="color: #008000; font-weight: bold">return</span> x, y

x, y <span style="color: #666666">=</span> circle(<span style="color: #666666">2.0</span>, <span style="color: #666666">0</span>, <span style="color: #666666">0</span>)
</pre></div>
<p>
<!-- Often in an exercise we have some comments about the solution -->
<!-- which we normally want to keep where they are. -->

<p>
The goal of this project is to draw \( N \) circles with random
center and radius. Plot each circle using the <code>circle</code> function
above.

<p>
<b>a)</b>
Let \( R \) be normally distributed and \( (x_0,y_0) \) uniformly distributed.

<p>
<!-- --- begin hint in exercise --- -->

<p>
<b>Hint.</b>
Use the <code>numpy.random</code> module to draw the
\( x_0 \), \( y_0 \), and \( R \) quantities.

<p>
<!-- --- end hint in exercise --- -->

<p>
<!-- removed !bans ... !eans environment (because of the command-line option --without_answers)
 -->
<p>
<!-- removed !bsol ... !esol environment (because of the command-line option --without_solutions)
 -->
<p>
<b>b)</b>
Let \( R \) be uniformly distributed and \( (x_0,y_0) \) normally distributed.
Filename: <code>norm</code>.

<p>
<b>c)</b>
Let \( R \) and \( (x_0,y_0) \) be normally distributed.

<p>
Filename: <code>circles</code>.

<p>
<!-- Closing remarks for this Project -->

<h3 id="remarks">Remarks </h3>

<p>
At the very end of the exercise it may be appropriate to summarize
and give some perspectives.

<p>
<!-- --- end exercise --- -->

<p>
<!-- --- begin exercise --- -->

<h2 id="exer:dist">Exercise 6: Determine some Distance</h2>

<p>
Intro to this exercise. Questions are in subexercises below.

<p>
<!-- removed !bsol ... !esol environment (because of the command-line option --without_solutions)
 -->
<p>
<b>a)</b>
Subexercises are numbered a), b), etc.

<p>
<!-- --- begin hint in exercise --- -->

<p>
<b>Hint 1.</b>
First hint to subexercise a).
With math \( a=b \) in hint:

$$ a=b. $$

And with code (in plain verbatim) returning \( x+1 \) in hint:

<p>

<!-- code=text typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>def func(x):
    return x + 1  # with code in hint
</pre></div>
<p>
<!-- --- end hint in exercise --- -->

<p>
<!-- --- begin hint in exercise --- -->

<p>
<b>Hint 2.</b>
Second hint to subexercise a).

<p>
Test list in hint:

<ol>
<li> item1</li>
<li> item2</li>
</ol>

<!-- --- end hint in exercise --- -->
Filename: <code>subexer_a.pdf</code>.

<p>
<!-- removed !bans ... !eans environment (because of the command-line option --without_answers)
 -->
<p>
<b>b)</b>
Here goes the text for subexercise b).

<p>
Some math \( \cos^2 x + \sin^2 x = 1 \) written one a single line:

$$ \cos^2 x + \sin^2 x = 1 \thinspace .$$

<p>
<!-- --- begin hint in exercise --- -->

<p>
<b>Hint.</b>
A hint for this subexercise.

<p>
<!-- --- end hint in exercise --- -->
Filename: <code>subexer_b.pdf</code>.

<p>
<!-- removed !bsol ... !esol environment (because of the command-line option --without_solutions)
 -->
<p>
<!-- No meaning in this weired test example: -->
The text here belongs to the main (intro) part of the exercise. Need
closing remarks to have text after subexercises.

<p>
Test list in exercise:

<ol>
<li> item1</li>
<li> item2
<!-- Closing remarks for this Exercise --></li>
</ol>

<h3 id="remarks">Remarks </h3>

<p>
Some final closing remarks, e.g., summarizing the main findings
and their implications in other problems can be made. These
remarks will appear at the end of the typeset exercise.

<p>
<!-- --- end exercise --- -->

<p>
<!-- --- begin exercise --- -->

<h2 id="some-exercise-without-the-exercise-prefix">Some exercise without the "Exercise:" prefix </h2>

<p>
<!-- Another minimalistic exercise -->

<p>
Just some text. And some math saying that \( e^0=1 \) on a single line,
to test that math block insertion is correct:

$$ \exp{(0)} = 1 $$

<p>
And a test that the code <code>lambda x: x+2</code> is correctly placed here:

<p>

<!-- code=text typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>lambda x: x+2
</pre></div>
<p>
<!-- Have some comments at the end of the exercise to see that -->
<!-- the Filename: ... is written correctly. -->
<!-- --- end exercise --- -->

<p>
<!-- --- begin exercise --- -->

<h2 id="sec:this:exer:de">Exercise 8: Solution of differential equation</h2>

<p>
<!-- begin quiz -->
Given

$$ \frac{dy}{dx} = -y(x),\quad y(0)=1 $$

What is the solution of this equation?</p>

<p><div title="Right! "><b>Choice A:</b>
\( y=e^{-y} \)
</div></p>

<p><div title="Wrong! Almost, but the sign is wrong (note the minus!)."><b>Choice B:</b>
\( y=e^{y} \)
</div></p>

<p><div title="Wrong! "><b>Choice C:</b>
<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">from</span> <span style="color: #0000FF; font-weight: bold">math</span> <span style="color: #008000; font-weight: bold">import</span> exp
<span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">f</span>(x):
    <span style="color: #008000; font-weight: bold">return</span> exp(x)
</pre></div>
<p>
</div></p>

<p><div title="Wrong! Equations with derivatives can be solved; they are termed  differential equations ."><b>Choice D:</b>
The solution cannot be found because there is a derivative in the equation.
</div></p>

<p><div title="Wrong! Equations where the unknown is a function, as \( y(x) \) here, are called  differential equations , and are solved by special techniques."><b>Choice E:</b>
The equation is meaningless: an equation must be an equation
for \( x \) or \( y \), not a function \( y(x) \).
</div></p>
<hr>
<!-- end quiz -->


<p>
<!-- --- end exercise --- -->

<p>
<!-- --- begin exercise --- -->

<h2 id="example-9-just-an-example">Example 9: Just an example </h2>

<p>
<!-- This example needs the --examples_as_exercises option, otherwise -->
<!-- it is just typeset as it is written. -->

<p>
<b>a)</b>
What is the capital of Norway?

<p>
<b>Answer.</b>
Oslo.

<p>
<!-- --- end exercise --- -->

<h1 id="here-goes-another-section">Here goes another section </h1>

<p>
With some text, before we continue with exercises.

<h1 id="more-exercises">More Exercises </h1>

<p>
<!-- --- begin exercise --- -->

<h2 id="exer:some:formula">Exercise 10: Make references to projects and problems</h2>

<p>
<!-- Test comments not at the end only -->
Pick a statement from <a href="#proj:circle1">Project 5: Explore Distributions of Random Circles</a> or <a href="#demo:ex:1">Problem 2: Flip a Coin</a>
and verify it.

<p>
Test list at the end of an exercise without other elements (like subexercise,
hint, etc.):

<ol>
<li> item1</li>
<li> item2</li>
</ol>

Filename: <code>verify_formula.py</code>.

<p>
<!-- --- end exercise --- -->

<p>
<!-- --- begin exercise --- -->

<h2 id="exer:you">Project 11: References in a headings do not work well in html</h2>

<p>
Refer to the previous exercise as <a href="#exer:some:formula">Exercise 10: Make references to projects and problems</a>,
the two before that as <a href="#demo:ex:2">Project 4: Compute a Probability</a> and <a href="#proj:circle1">Project 5: Explore Distributions of Random Circles</a>,
and this one as <a href="#exer:you">Project 11: References in a headings do not work well in html</a>.
Filename: <code>selc_composed.pdf</code>.

<p>
<!-- --- end exercise --- -->

<h1 id="ch:answerssolutions">Answers and Solutions</h1>

<p>
<!-- --- begin exercise --- answers and solutions -->

<h2 id="example-1-examples-can-be-typeset-as-exercises">Example 1: Examples can be typeset as exercises </h2>
<!-- Solution to <a href="#Example">Example 1: Examples can be typeset as exercises</a> -->

<p>
<b>a) Solution.</b>
The answer to this subproblem can be written here.
<b>b) Solution.</b>
The answer to this other subproblem goes here,
maybe over multiple doconce input lines.

<p>
<!-- --- end exercise --- solution -->

<p>
<!-- --- begin exercise --- answers and solutions -->

<h2 id="problem-2-flip-a-coin">Problem 2: Flip a Coin </h2>
<!-- Solution to <a href="#demo:ex:1">Problem 2: Flip a Coin</a> -->

<p>
<b>a) Answer.</b>
If the <code>random.random()</code> function returns a number \( < 1/2 \), let it be
head, otherwise tail. Repeat this \( N \) number of times.

<p>
<!-- --- begin solution of exercise at end --- -->
<b>a) Solution.</b>
<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">import</span> <span style="color: #0000FF; font-weight: bold">sys</span><span style="color: #666666">,</span> <span style="color: #0000FF; font-weight: bold">random</span>
N <span style="color: #666666">=</span> <span style="color: #008000">int</span>(sys<span style="color: #666666">.</span>argv[<span style="color: #666666">1</span>])
heads <span style="color: #666666">=</span> <span style="color: #666666">0</span>
<span style="color: #008000; font-weight: bold">for</span> i <span style="color: #AA22FF; font-weight: bold">in</span> <span style="color: #008000">range</span>(N):
    r <span style="color: #666666">=</span> random<span style="color: #666666">.</span>random()
    <span style="color: #008000; font-weight: bold">if</span> r <span style="color: #666666">&lt;=</span> <span style="color: #666666">0.5</span>:
        heads <span style="color: #666666">+=</span> <span style="color: #666666">1</span>
<span style="color: #008000">print</span>(<span style="color: #BA2121">&#39;Flipping a coin </span><span style="color: #BB6688; font-weight: bold">%d</span><span style="color: #BA2121"> times gave </span><span style="color: #BB6688; font-weight: bold">%d</span><span style="color: #BA2121"> heads&#39;</span> <span style="color: #666666">%</span> (N, heads))
</pre></div>
<p>
<!-- --- end solution of exercise at end --- -->

<p>
<b>c) Answer.</b>
<code>np.sum(np.where(r &lt;= 0.5, 1, 0))</code> or <code>np.sum(r &lt;= 0.5)</code>.

<p>
<!-- --- end exercise --- solution -->

<p>
<!-- --- begin exercise --- answers and solutions -->

<h2 id="project-5-explore-distributions-of-random-circles">Project 5: Explore Distributions of Random Circles </h2>
<!-- Solution to <a href="#proj:circle1">Project 5: Explore Distributions of Random Circles</a> -->

<p>
<b>a) Answer.</b>
Here goes the short answer to part a).

<p>
<!-- --- begin solution of exercise at end --- -->
<b>a) Solution.</b>
Here goes a full solution to part a).
<!-- --- end solution of exercise at end --- -->

<p>
<!-- --- end exercise --- solution -->

<p>
<!-- --- begin exercise --- answers and solutions -->

<h2 id="exercise-6-determine-some-distance">Exercise 6: Determine some Distance </h2>
<!-- Solution to <a href="#exer:dist">Exercise 6: Determine some Distance</a> -->

<p>
<b>Solution.</b>
Here goes a full solution of the whole exercise.
With some math \( a=b \) in this solution:
$$ \hbox{math in solution: } a = b $$

And code <code>a=b</code> in this solution:
<p>

<!-- code=text typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>a = b  # code in solution
</pre></div>
<p>
End of solution is here.

<p>
<b>a) Answer.</b>
Short answer to subexercise a).
With math in answer: \( a=b \).

<p>
<!-- --- begin solution of exercise at end --- -->
<b>b) Solution.</b>
Here goes the solution of this subexercise.
<!-- --- end solution of exercise at end --- -->

<p>
<!-- --- end exercise --- solution -->

<p>
<!-- --- begin exercise --- answers and solutions -->

<h2 id="example-9-just-an-example">Example 9: Just an example </h2>

<p>
<!-- --- end exercise --- solution -->

<h1 id="references">References </h1>

<p>
<!-- begin bibliography -->

<ol>
 <li> <div id="Langtangen_Pedersen_2002"></div> <b>H. P. Langtangen and G. Pedersen</b>. 
    Propagation of Large Destructive Waves,
    <em>International Journal of Applied Mechanics and Engineering</em>,
    7(1),
    pp. 187-204,
    2002.</li>
 <li> <div id="Langtangen_et_al_2002"></div> <b>H. P. Langtangen, K.-A. Mardal and R. Winther</b>. 
    Numerical Methods for Incompressible Viscous Flow,
    <em>Advances in Water Resources</em>,
    25,
    pp. 1125-1146,
    2002.</li>
 <li> <div id="Langtangen_1994a"></div> <b>H. P. Langtangen</b>. 
    Numerical Solution of First Passage Problems in Random Vibrations,
    <em>SIAM Journal of Scientific and Statistical Computing</em>,
    15,
    pp. 997-996,
    1994.</li>
 <li> <div id="Mardal_et_al_2003a"></div> <b>K.-A. Mardal, G. W. Zumbusch and H. P. Langtangen</b>. 
    Software Tools for Multigrid Methods,
    <em>Advanced Topics in Computational Partial Differential Equations -- Numerical Methods and Diffpack Programming</em>,
    edited by <b>H. P. Langtangen and A. Tveito</b>,
    Springer,
    2003,
    Edited book,
    <a href="http://some.where.org" target="_self"><tt>http://some.where.org</tt></a>.</li>
 <li> <div id="Langtangen_1988d"></div> <b>H. P. Langtangen</b>. 
    The FEMDEQS Program System,
    <em>Department of Mathematics, University of Oslo</em>,
    1989,
    <a href="http://www.math.uio.no/old/days/hpl/femdeqs.pdf" target="_self"><tt>http://www.math.uio.no/old/days/hpl/femdeqs.pdf</tt></a>.</li>
 <li> <div id="Langtangen_1992c"></div> <b>H. P. Langtangen</b>. 
    Stochastic Breakthrough Time Analysis of an Enhanced Oil Recovery Process,
    <em>SIAM Journal on Scientific Computing</em>,
    13,
    pp. 1394-1417,
    1992.</li>
 <li> <div id="Mortensen_et_al_2011"></div> <b>M. Mortensen, H. P. Langtangen and G. N. Wells</b>. 
    A FEniCS-Based Programming Framework for Modeling Turbulent Flow by the Reynolds-Averaged Navier-Stokes Equations,
    <em>Advances in Water Resources</em>,
    34(9),
    <a href="https://dx.doi.org/10.1016/j.advwatres.2011.02.013" target="_self">doi: 10.1016/j.advwatres.2011.02.013</a>,
    2011.</li>
 <li> <div id="Glimsdal_et_al_20006"></div> <b>S. Glimsdal, G. Pedersen, K. Atakan, C. B. Harbitz, H. P. Langtangen and F. L\ovholt</b>. 
    Propagation of the Dec.&nbsp;26, 2004 Indian Ocean Tsunami: Effects of Dispersion and Source Characteristics,
    <em>International Journal of Fluid Mechanics Research</em>,
    33(1),
    pp. 15-43,
    2006.</li>
 <li> <div id="Rahman_et_al_2006b"></div> <b>S. Rahman, J. Gorman, C. H. W. Barnes, D. A. Williams and H. P. Langtangen</b>. 
    Numerical Investigation of a Piezoelectric Surface Acoustic Wave Interaction With a One-Dimensional Channel,
    <em>Physical Review B: Condensed Matter and Materials Physics</em>,
    74,
    2006,
    035308.</li>
<li> <div id="Haga_et_al_2011a"></div> <b>J. B. Haga, H. Osnes and H. P. Langtangen</b>. 
    On the Causes of Pressure Oscillations in Low-Permeable and Low-Compressible Porous Media,
    <em>International Journal of Analytical and Numerical Methods in Geomechanics</em>,
    <a href="https://dx.doi.org/10.1002/nag.1062" target="_self">doi: 10.1002/nag.1062</a>,
    2011,
    <a href="http://onlinelibrary.wiley.com/doi/10.1002/nag.1062/abstract" target="_self"><tt>http://onlinelibrary.wiley.com/doi/10.1002/nag.1062/abstract</tt></a>.</li>
<li> <div id="Langtangen_2003a"></div> <b>H. P. Langtangen</b>. 
    <em>Computational Partial Differential Equations - Numerical Methods and Diffpack Programming</em>,
    second edition,
    <em>Texts in Computational Science and Engineering</em>,
    Springer,
    2003.</li>
<li> <div id="Langtangen_2008a"></div> <b>H. P. Langtangen</b>. 
    <em>Python Scripting for Computational Science</em>,
    third edition,
    <em>Texts in Computational Science and Engineering</em>,
    Springer,
    2008.</li>
<li> <div id="Langtangen:95"></div> <b>H. P. Langtangen and G. Pedersen</b>. 
    Finite Elements for the Boussinesq Wave Equations,
    Waves and Non-linear Processes in Hydrodynamics,
    edited by <b>J. Grue, B. Gjevik and J. E. Weber</b>,
    Kluwer Academic Publishers,
    pp. pp. 117-126,
    1995,
    <a href="http://www.amazon.ca/Waves-Nonlinear-Processes-Hydrodynamics-John/dp/0792340310" target="_self"><tt>http://www.amazon.ca/Waves-Nonlinear-Processes-Hydrodynamics-John/dp/0792340310</tt></a>.</li>
<li> <div id="Langtangen_2012"></div> <b>H. P. Langtangen</b>. 
    <em>A Primer on Scientific Programming With Python</em>,
    third edition,
    <em>Texts in Computational Science and Engineering</em>,
    Springer,
    2012.</li>
<li> <div id="Jeberg_et_al_2004"></div> <b>P. V. Jeberg, H. P. Langtangen and C. B. Terp</b>. 
    Optimization With Diffpack: Practical Example From Welding,
    <em>Simula Research Laboratory</em>,
    2004,
    Internal report.</li>
<li> <div id="Langtangen_1989e"></div> <b>H. P. Langtangen</b>. 
    Computational Methods for Two-Phase Flow in Oil Reservoirs,
    Ph.D. Thesis,
    Mechanics Division, Department of Mathematics, University of Oslo,
    1989,
    Dr.&nbsp;Scient.&nbsp;thesis..</li>
<li> <div id="Langtangen_talk_2007a"></div> <b>H. P. Langtangen</b>. 
    Computational Modeling of Huge Tsunamis From Asteroid Impacts,
    2007,
    Invited keynote lecture at the \emphInternational conference on Computational Science 2007 (ICCS'07), Beijing, China.</li>
<li> <div id="Langtangen:85"></div> <b>H. P. Langtangen</b>. 
    Solution of the Navier-Stokes Equations With the Finite Element Method in Two and Three Dimensions,
    M.Sc. Thesis,
    Mechanics Division, Department of Mathematics, University of Oslo,
    1985,
    Cand.Scient. thesis.</li>
<li> <div id="Langtangen:91"></div> <b>H. P. Langtangen and A. Tveito</b>. 
    Numerical Methods in Continuum Mechanics,
    <em>Center for Industrial Research</em>,
    1991,
    Lecture notes for a course (ME-IN 324). 286 pages..</li>
<li> <div id="Langtangen:94b"></div> <b>H. P. Langtangen</b>. 
    Diffpack: Software for Partial Differential Equations,
    <em>Proceedings of the Second Annual Object-Oriented Numerics Conference (OON-SKI'94), Sunriver, Oregon, USA</em>,
    edited by <b>A. Vermeulen</b>,
    1994.</li>
</ol>

<!-- end bibliography -->

<h1 id="app1">Appendix: Just for testing; part I</h1>

<p>
This is the first appendix.

<h2 id="a-subsection-within-an-appendix">A subsection within an appendix </h2>

<p>
Some text.

<h1 id="app2">Appendix: Just for testing; part II</h1>

<p>
This is more stuff for an appendix.

<h2 id="appendix-testing-identical-titles">Appendix: Testing identical titles </h2>

<p>
Without label.

<h2 id="test:title:id1">Appendix: Testing identical titles</h2>

<p>
With label.

<h2 id="test:title:id2">Appendix: Testing identical titles</h2>

<p>
What about inserting a quiz?

<p>
<!-- !split --><br><br><br><br><br><br><br><br><br><br>
<h2>Test of quizzes</h2>

<!-- begin quiz -->
<hr>
<p>
<b>Fundamental test:</b> What is the capital of Norway?</p>

<p><div title="Wrong! Stockholm is the capital of Sweden."><b>Answer 1:</b>
Stockholm
</div></p>

<p><div title="Wrong! "><b>Answer 2:</b>
London
</div></p>

<p><div title="Right! "><b>Answer 3:</b>
Oslo
</div></p>

<p><div title="Wrong! Those from Bergen would claim so, but nobody else."><b>Choice D:</b>
Bergen
</div></p>
<hr>
<!-- end quiz -->


<h2 id="appendix-testing-identical-titles">Appendix: Testing identical titles </h2>

<p>
Without label.

<p>
<div class="alert alert-block alert-notice alert-text-normal">
<b>Tip</b>
<p>
Here is a tip or hint box, typeset as a notice box.
</div>


<p>
Need a lot of text to surround the summary box.
Version control systems allow you to record the history of files
and share files among several computers and collaborators in a
professional way. File changes on one computer are updated or
merged with changes on another computer. Especially when working
with programs or technical reports it is essential
to have changes documented and to
ensure that every computer and person involved in the project
have the latest updates of the files.
Greg Wilson' excellent <a href="https://software-carpentry.org/2010/07/script-for-introduction-to-version-control/" target="_self">Script for Introduction to Version Control</a> provides a more detailed motivation why you will benefit greatly
from using version control systems.

<p>
<div class="alert alert-block alert-summary alert-text-normal">
<b>Summary</b>
<p>
<b>Bold remark:</b> Make some text with this summary.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
</div>


<p>
Projects that you want to share among several computers or project
workers are today most conveniently stored at some web site "in the
cloud" and updated through communication with that site. I strongly
recommend you to use such sites for all serious programming and
scientific writing work - and all other important files.

<p>
The simplest services for hosting project files are <a href="https://dropbox.com" target="_self">Dropbox</a> and <a href="https://drive.google.com" target="_self">Google Drive</a>.
It is very easy to get started with these systems, and they allow you
to share files among laptops and mobile units with as many users as
you want. The systems offer a kind of version control in that the
files are stored frequently (several times per minute), and you can go
back to previous versions for the last 30 days. However, it is
challenging  to find the right version from the past when there are
so many of them.

<p>
More seriously, when several people may edit files simultaneously, it
can be difficult detect who did what when, roll back to previous
versions, and to manually merge the edits when these are
incompatible. Then one needs more sophisticated tools than Dropbox or
Google Drive: project hosting services with true version control
systems.  The following text aims at providing you with the minimum
information to started with such systems. Numerous other tutorials
contain more comprehensive material and in-depth explanations of the
concepts and tools.

<p>
The idea with project hosting services is that you have the files
associated with a project in the cloud. Many people may share these
files.  Every time you want to work on the project you explicitly
update your version of the files, edit the files as you like, and
synchronize the files with the "master version" at the site where the
project is hosted.  If you at some point need to go back to a
version of the files at some particular point in the past,
this is an easy operation. You can also use tools to see
what various people have done with the files in the various versions.

<p>
All these services are very similar. Below we describe how you get
started with Bitbucket, GitHub, and Googlecode. Launchpad works very
similarly to the latter three. All the project hosting services have
excellent introductions available at their web sites, but the recipes
below are much shorter and aim at getting you started as quickly as
possible by concentrating on the most important need-to-know steps.
The Git tutorials we refer to later in this document contain more
detailed information and constitute of course very valuable readings
when you use version control systems every day. The point now is
to get started.

<h2 id="appendix-testing-inline-comments">Appendix: Testing inline comments </h2>

<p>
<!-- Names can be [ A-Za-z0-9_'+-]+ -->

<p>
Projects that you want to share among several computers or project
workers are today most conveniently stored at some web site "in the
cloud" and updated through communication with that
site. 
<!-- begin inline comment -->
<font color="red">(<b>hpl's semi opinion 1</b>: not sure if in the cloud is understood by all.)</font>
<!-- end inline comment -->
 I strongly recommend you to use such sites for all serious
programming and scientific writing work - and all other important
files.

<p>
The simplest services for hosting project files is Dropbox. 
<!-- begin inline comment -->
<font color="red">(<b>mp 2</b>: Simply go to <a href="https://dropbox.com" target="_self"><tt>https://dropbox.com</tt></a> and watch the video. It explains how files, like <code>myfile.py</code>, perhaps containing much math, like \( \partial u/\partial t \), are easily communicated between machines.)</font>
<!-- end inline comment -->
 It
is very easy to get started with Dropbox, and it allows you to share
files among  <font color="red">(<b>hpl 3</b>:)</font> <del> laptops and mobile units </del> <font color="red">computers, tablets, and phones</font>.

<p>
<!-- Test horizontal rule -->

<p>
<hr>

<p>
<!-- Coments for editing -->

<p>
First<font color="red">, (<b>edit 4</b>: add comma)</font> consider a quantity \( Q \).  <font color="red">(<b>edit 5</b>:)</font> <del> To this end, </del> <font color="red">We note that</font>
\( Q>0 \), because  <font color="red">(<b>edit 6</b>:)</font> <del> a </del> negative  <font color="red">(<b>edit 7</b>:)</font> <del> quantity is </del> <font color="red">quantities are</font>  <font color="red">(<b>edit 8</b>:)</font> <del> just </del> negative.  <font color="red">(<b>edit 9</b>:) This comes as no surprise.</font>

<p>
<!-- Test tailored latex figure references with page number -->
Let us refer to Figure <a href="#fig:impact">1</a> again.

<p>
Test references in a list:

<ul>
 <li> <a href="#sec1">Section 1</a></li>
 <li> <a href="#subsec1">Subsection 1</a></li>
 <li> <a href="#fig:impact">1</a></li>
</ul>

<h2 id="appendix-testing-headings-ending-with-verbatim-inline">Appendix: Testing headings ending with <code>verbatim inline</code> </h2>

<p>
The point here is to test 1) <code>verbatim</code> code in headings, and 2)
ending a heading with verbatim code as this triggers a special
case in LaTeX.

<p>
We also test mdash&mdash;used as alternative to hyphen without spaces around,
or in quotes:

<p>
<blockquote>
    <em>Fun is fun</em>.&mdash;Unknown.
</blockquote>


<p>
The ndash should also be tested &ndash; as in the Hanson&ndash;Nilson equations
on page 277&ndash;278.

<p>
And finally, what about admons, quotes, and boxes? They are tested
in a separate document: <code>admon.do.txt</code>.

<p id="def_footnote_5"><a href="#link_footnote_5"><b>5:</b></a> Not much to add here, but the footnote
is at the end with only one newline.</p>

<!-- ------------------- end of main content --------------- -->

<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.js"></script>



<!-- Got these buttons from simplesharebuttons.com -->
<center>
<div id="share-buttons">

    <!-- Facebook -->
    <a href="https://www.facebook.com/sharer.php?u=https://cyber.space.com/specials" target="_blank">
        <img src="https://simplesharebuttons.com/images/somacro/facebook.png" alt="Facebook" />
    </a>

    <!-- Google+ -->
    <a href="https://plus.google.com/share?url=https://cyber.space.com/specials" target="_blank">
        <img src="https://simplesharebuttons.com/images/somacro/google.png" alt="Google" />
    </a>

    <!-- LinkedIn -->
    <a href="https://www.linkedin.com/shareArticle?mini=true&amp;url=https://cyber.space.com/specials" target="_blank">
        <img src="https://simplesharebuttons.com/images/somacro/linkedin.png" alt="LinkedIn" />
    </a>

    <!-- Twitter -->
    <a href="https://twitter.com/share?url=https://cyber.space.com/specials&amp;name=Interesting link&amp;hashtags=interesting" target="_blank">
        <img src="https://simplesharebuttons.com/images/somacro/twitter.png" alt="Twitter" />
    </a>

<!-- Print -->
    <a href="javascript:;" onclick="window.print()">
        <img src="https://simplesharebuttons.com/images/somacro/print.png" alt="Print" />
    </a>

</div>
</center>


</body>
</html>
    

************** File: testdoc_no_solutions.p.tex *****************
%%
%% Automatically generated file from DocOnce source
%% (https://github.com/hplgit/doconce/)
%%
%%
% #ifdef PTEX2TEX_EXPLANATION
%%
%% The file follows the ptex2tex extended LaTeX format, see
%% ptex2tex: https://code.google.com/p/ptex2tex/
%%
%% Run
%%      ptex2tex myfile
%% or
%%      doconce ptex2tex myfile
%%
%% to turn myfile.p.tex into an ordinary LaTeX file myfile.tex.
%% (The ptex2tex program: https://code.google.com/p/ptex2tex)
%% Many preprocess options can be added to ptex2tex or doconce ptex2tex
%%
%%      ptex2tex -DMINTED myfile
%%      doconce ptex2tex myfile envir=minted
%%
%% ptex2tex will typeset code environments according to a global or local
%% .ptex2tex.cfg configure file. doconce ptex2tex will typeset code
%% according to options on the command line (just type doconce ptex2tex to
%% see examples). If doconce ptex2tex has envir=minted, it enables the
%% minted style without needing -DMINTED.
% #endif

% #define PREAMBLE

% #ifdef PREAMBLE
%-------------------- begin preamble ----------------------

\documentclass[%
oneside,                 % oneside: electronic viewing, twoside: printing
final,                   % draft: marks overfull hboxes, figures with paths
10pt]{article}

\listfiles               %  print all files needed to compile this document

\usepackage{relsize,epsfig,makeidx,color,setspace,amsmath,amsfonts,amssymb}
\usepackage[table]{xcolor}
\usepackage{bm,ltablex,microtype}

\usepackage{graphicx}
\usepackage{sidecap}

% user-provided packages: --latex_packages=varioref
\usepackage{varioref}

% 'on page ...' reference with \vref{} and varioref package
\renewcommand\reftextfaceafter{on page~\thevpagerefnum}
\renewcommand\reftextfacebefore{on page~\thevpagerefnum}
\renewcommand\reftextafter{on page~\thevpagerefnum}
\renewcommand\reftextbefore{on page~\thevpagerefnum}

% Tools for marking corrections
\usepackage{soul}
\newcommand{\replace}[2]{{\color{red}\text{\st{#1} #2}}}
\newcommand{\remove}[1]{{\color{red}\st{#1}}}

\usepackage{ptex2tex}
% #ifdef MINTED
\usepackage{minted}
\usemintedstyle{default}
% #endif
\usepackage{fancyvrb}

\usepackage[T1]{fontenc}
%\usepackage[latin1]{inputenc}
\usepackage{ucs}
\usepackage[utf8x]{inputenc}

\usepackage{lmodern}         % Latin Modern fonts derived from Computer Modern

\newenvironment{doconcequiz}{}{}
\newcounter{doconcequizcounter}

% Hyperlinks in PDF:
\definecolor{linkcolor}{rgb}{0,0,0.4}
\usepackage{hyperref}
\hypersetup{
    breaklinks=true,
    colorlinks=true,
    linkcolor=linkcolor,
    urlcolor=linkcolor,
    citecolor=black,
    filecolor=black,
    %filecolor=blue,
    pdfmenubar=true,
    pdftoolbar=true,
    bookmarksdepth=3   % Uncomment (and tweak) for PDF bookmarks with more levels than the TOC
    }
%\hyperbaseurl{}   % hyperlinks are relative to this root

\setcounter{tocdepth}{2}  % levels in table of contents

%\VerbatimFootnotes must come after hyperref and footmisc packages
\VerbatimFootnotes

% Tricks for having figures close to where they are defined:
% 1. define less restrictive rules for where to put figures
\setcounter{topnumber}{2}
\setcounter{bottomnumber}{2}
\setcounter{totalnumber}{4}
\renewcommand{\topfraction}{0.95}
\renewcommand{\bottomfraction}{0.95}
\renewcommand{\textfraction}{0}
\renewcommand{\floatpagefraction}{0.75}
% floatpagefraction must always be less than topfraction!
% 2. ensure all figures are flushed before next section
\usepackage[section]{placeins}
% 3. enable begin{figure}[H] (often leads to ugly pagebreaks)
%\usepackage{float}\restylefloat{figure}

% newcommands for typesetting inline (doconce) comments
\newcommand{\shortinlinecomment}[3]{{\color{red}{\bf #1}: #2}}
\newcommand{\longinlinecomment}[3]{{\color{red}{\bf #1}: #2}}

% --- fancyhdr package for fancy headers ---
\usepackage{fancyhdr}
\fancyhf{} % sets both header and footer to nothing
\renewcommand{\headrulewidth}{0pt}
\fancyfoot[LE,RO]{\thepage}
% Ensure copyright on titlepage (article style) and chapter pages (book style)
\fancypagestyle{plain}{
  \fancyhf{}
  \fancyfoot[C]{{\footnotesize Made with \href{https://github.com/hplgit/doconce}{DocOnce}}}
%  \renewcommand{\footrulewidth}{0mm}
  \renewcommand{\headrulewidth}{0mm}
}
% Ensure copyright on titlepages with \thispagestyle{empty}
\fancypagestyle{empty}{
  \fancyhf{}
  \fancyfoot[C]{{\footnotesize Made with \href{https://github.com/hplgit/doconce}{DocOnce}}}
  \renewcommand{\footrulewidth}{0mm}
  \renewcommand{\headrulewidth}{0mm}
}

\pagestyle{fancy}


\usepackage[framemethod=TikZ]{mdframed}

% --- begin definitions of admonition environments ---

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "notice" admon
\colorlet{mdfbox_notice_background}{gray!5}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_notice_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=mdfbox_notice_background,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{notice_mdfboxmdframed}

\newenvironment{notice_mdfboxadmon}[1][]{
\begin{notice_mdfboxmdframed}[frametitle=#1]
}
{
\end{notice_mdfboxmdframed}
}

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "summary" admon
\colorlet{mdfbox_summary_background}{gray!5}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_summary_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=mdfbox_summary_background,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{summary_mdfboxmdframed}

\newenvironment{summary_mdfboxadmon}[1][]{
\begin{summary_mdfboxmdframed}[frametitle=#1]
}
{
\end{summary_mdfboxmdframed}
}

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "warning" admon
\colorlet{mdfbox_warning_background}{gray!5}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_warning_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=mdfbox_warning_background,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{warning_mdfboxmdframed}

\newenvironment{warning_mdfboxadmon}[1][]{
\begin{warning_mdfboxmdframed}[frametitle=#1]
}
{
\end{warning_mdfboxmdframed}
}

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "question" admon
\colorlet{mdfbox_question_background}{gray!5}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_question_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=mdfbox_question_background,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{question_mdfboxmdframed}

\newenvironment{question_mdfboxadmon}[1][]{
\begin{question_mdfboxmdframed}[frametitle=#1]
}
{
\end{question_mdfboxmdframed}
}

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "block" admon
\colorlet{mdfbox_block_background}{gray!5}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_block_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=mdfbox_block_background,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{block_mdfboxmdframed}

\newenvironment{block_mdfboxadmon}[1][]{
\begin{block_mdfboxmdframed}[frametitle=#1]
}
{
\end{block_mdfboxmdframed}
}

% --- end of definitions of admonition environments ---

% prevent orhpans and widows
\clubpenalty = 10000
\widowpenalty = 10000

\usepackage{calc}

\newenvironment{doconceexercise}{}{}
\newcounter{doconceexercisecounter}
% --- begin definition of \listofexercises command ---
\makeatletter
\newcommand\listofexercises{\section*{List of Examples, Exercises, Problems, and Projects}
\@starttoc{loe}
}
\newcommand*{\l@doconceexercise}{\@dottedtocline{0}{0pt}{6.5em}}
\makeatother
% --- end definition of \listofexercises command ---



% ------ header in subexercises ------
%\newcommand{\subex}[1]{\paragraph{#1}}
%\newcommand{\subex}[1]{\par\vspace{1.7mm}\noindent{\bf #1}\ \ }
\makeatletter
% 1.5ex is the spacing above the header, 0.5em the spacing after subex title
\newcommand\subex{\@startsection{paragraph}{4}{\z@}%
                  {1.5ex\@plus1ex \@minus.2ex}%
                  {-0.5em}%
                  {\normalfont\normalsize\bfseries}}
\makeatother


% --- end of standard preamble for documents ---


\usepackage{amsthm,tcolorbox}
\theoremstyle{definition}
\newtheorem{example}{Example}[section]



% insert custom LaTeX commands...

\raggedbottom
\makeindex
\usepackage[totoc]{idxlayout}   % for index in the toc
\usepackage[nottoc]{tocbibind}  % for references/bibliography in the toc

%-------------------- end preamble ----------------------

\begin{document}

% matching end for #ifdef PREAMBLE
% #endif

\newcommand{\exercisesection}[1]{\subsection*{#1}}

\input{newcommands_bfmath}
\input{newcommands_replace}

% ------------------- main content ----------------------



% ----------------- title -------------------------

\thispagestyle{empty}

\begin{center}
{\LARGE\bf
\begin{spacing}{1.25}
A Document for Testing DocOnce
\end{spacing}
}
\end{center}

% ----------------- author(s) -------------------------

\begin{center}
{\bf Hans Petter Langtangen${}^{1, 2}$ (\texttt{hpl@simula.no})} \\ [0mm]
\end{center}


\begin{center}
{\bf Kaare Dump${}^{3}$} \\ [0mm]
\end{center}


\begin{center}
{\bf A. Dummy Author${}^{}$} \\ [0mm]
\end{center}


\begin{center}
{\bf I. S. Overworked and Outburned${}^{4, 5, 6, 7}$} \\ [0mm]
\end{center}


\begin{center}
{\bf J. Doe${}^{}$ (\texttt{j\_doe@cyberspace.com})} \\ [0mm]
\end{center}

\begin{center}
% List of all institutions:
\centerline{{\small ${}^1$Center for Biomedical Computing, Simula Research Laboratory}}
\centerline{{\small ${}^2$Department of Informatics, University of Oslo}}
\centerline{{\small ${}^3$Segfault, Cyberspace}}
\centerline{{\small ${}^4$Inst1}}
\centerline{{\small ${}^5$Inst2, Somewhere}}
\centerline{{\small ${}^6$Third Inst, Elsewhere}}
\centerline{{\small ${}^7$Fourth Inst}}
\end{center}
    
% ----------------- end author(s) -------------------------

% --- begin date ---
\begin{center}
Jan 32, 2100
\end{center}
% --- end date ---

\vspace{1cm}


\tableofcontents


\vspace{1cm} % after toc





% !split




The format of this document is
plain, homemade {\LaTeX} (from DocOnce).

% Just a comment

\begin{abstract}
This is a document with many test constructions for doconce syntax.
It was used heavily for the development and kept for testing
numerous constructions, also special and less common cases.

And exactly for test purposes we have an extra line here, which
is part of the abstract.

% Cannot demonstrate chapter headings since abstract and chapter
% are mutually exclusive in {\LaTeX}
\end{abstract}

\subsection{Section 1}
\label{sec1}

Here is a nested list:

\begin{itemize}
  \item item1

  \item item2

  \item item3 which continues
    on the next line to test that feature

  \item and a sublist
\begin{itemize}

    \item with indented subitem1

    \item and a subitem2

\end{itemize}

\noindent
  \item and perhaps an ordered sublist
\begin{enumerate}

   \item first item

   \item second item,
      continuing on a new line
\end{enumerate}

\noindent
\end{itemize}

\noindent
\paragraph{Here is a list with paragraph heading.}

\begin{itemize}
  \item item1

  \item item2
\end{itemize}

\noindent
\paragraph{Here is a list with subsubsection heading.}
\begin{itemize}
  \item item1

  \item item2
\end{itemize}

\noindent

\begin{quote}
Here are two lines that make up
a block quote for testing \emph{emphasized words} and \textbf{boldface words},
also with hypens:
\emph{pre}-fix, post-\emph{fix}, \textbf{pre}-fix, post-\textbf{fix}.
\end{quote}


Here are two references. Equation~(\ref{my:eq1}) is fine. Eq.~(\ref{my:eq1}) too.
Even Equation (\ref{my:eq1}) without the tilde.


\paragraph{Subsection 1.}
\label{subsec1}

\index{somefunc@{\rm\texttt{somefunc}} function}

% Refer to section/appendix etc. at the beginning of the line
% and other special fix situations for HTML.

More text, with a reference back to
Section~\vref{sec1} and~\vref{subsec1}, and further to the
sections~\vref{subsec1} and~\vref{subsubsec:ex}, which
encourages you to do the tasks in the
Exercises~\vref{demo:ex:1} and~\vref{exer:some:formula}.
Appendices~\vref{app1} and~\vref{app2} are also nice elements.

\paragraph{Test Section reference at beginning of line and after a sentence.}
Section~\vref{subsec1} is fine.
Section~\vref{subsubsec:ex} too.


% sphinx code-blocks: pycod=python cod=fortran cppcod=c++ sys=console

\paragraph{Computer code.}
Let's do some copying from files too. First from subroutine up to the very end,

\bfcod
      subroutine test()
      integer i
      real*8 r
      r = 0
      do i = 1, i
         r = r + i
      end do
      return
C     END1

      program testme
      call test()
      return
\efcod
and then just the subroutine,
\bfcod

      subroutine test()
      integer i
      real*8 r
      r = 0
      do i = 1, i
         r = r + i
      end do
      return
\efcod
and finally the complete file with a plain text verbatim environment
(\texttt{envir=ccq}):
\bccq
C     a comment

      subroutine test()
      integer i
      real*8 r
      r = 0
      do i = 1, i
         r = r + i
      end do
      return
C     END1

      program testme
      call test()
      return
\eccq

Testing other code environments. First Python:

\bccq
!bc pycod
def f(x):
    return x+1
!ec
\eccq
which gets rendered as

\bpycod
def f(x):
    return x+1
\epycod

Test paragraph and subsubsection headings before
before code.

\paragraph{Paragraph heading before code.}

\bpycod
import sys
sys.path.insert(0, os.pardir)
\epycod

\paragraph{Subsubsection heading before code.}
\bpycod
def h(z):
    return z+1
\epycod

Now a complete program to be shown via Python Online Tutorial:

\bpypro
class Line:
    def __init__(self, a, b):
        self.a, self.b = a, b

    def __call__(self, x):
        a, b = self.a, self.b
        return a*x + b

line = Line(2, 1)
y = line(x=3)
print(y)
\epypro
\noindent
(\href{{https://pythontutor.com/visualize.html\#code=class+Line\%3A\%0A++++def+__init__\%28self\%2C+a\%2C+b\%29\%3A\%0A++++++++self.a\%2C+self.b+\%3D+a\%2C+b\%0A\%0A++++def+__call__\%28self\%2C+x\%29\%3A\%0A++++++++a\%2C+b+\%3D+self.a\%2C+self.b\%0A++++++++return+a\%2Ax+\%2B+b\%0A\%0Aline+\%3D+Line\%282\%2C+1\%29\%0Ay+\%3D+line\%28x\%3D3\%29\%0Aprint\%28y\%29&mode=display&cumulative=false&heapPrimitives=false&drawParentPointers=false&textReferences=false&py=2&curInstr=0}}{Visualize execution}) 


Some more Python code (actually specified as a sage cell, but
such cells are not supported by this format).

\bpypro
a = 2
b = 3
print('a+b:', a + b)

# In a sage cell we can also plot
from matplotlib.pyplot import *
from numpy import *
x = linspace(0, 4*pi, 101)
y = exp(-0.1*x)*cos(x)
plot(x, y)
xlabel('x'); ylabel('y')
show()
\epypro


Then Cython (with -h option so it is hidden in html/sphinx):

\bcycod
cpdef f(double x):
    return x + 1
\ecycod

Standard Python shell sessions:

\bpyshell
>>> from numpy import linspace, sin
>>> # Some comment
>>> x = linspace(0, 2, 11)
>>> y = sin(x)
>>> y[0]
0
>>> import matplotlib.pyplot as plt
>>> plt.plot(x, y)
\epyshell

Similar IPython sessions:

\bipy
In [1]: from numpy import linspace, sin
In [2]: # Some comment
In [3]: x = linspace(0, 2, 11)
In [4]: y = sin(x)
In [5]: y[0]
Out[5]: 0
In [6]: import matplotlib.pyplot as plt
In [7]: plt.plot(x, y)
In [8]: a='multiple-\nline\noutput'
In [9]: a
Out[9]: 'multiple-\nline\noutput'
In [10]: print(a)
multiple-
line
output
\eipy

Here is the interactive session again, but with \texttt{pyshell-t}.

\bpyshell
>>> from numpy import linspace, sin
>>> # Some comment
>>> x = linspace(0, 2, 11)
>>> y = sin(x)
>>> y[0]
0
>>> import matplotlib.pyplot as plt
>>> plt.plot(x, y)
\epyshell

% This one tests a + sign before a code environment
C++:
\bcpppro
#include <iostream>

int main()
{
   std::cout << "Sample output" << std::endl;
   return 0
}
\ecpppro
% The next should get correctly typset in sphinx (cod is fcod)
% It also tests emoji before code
And a little bit of Fortran: (\Verb!dizzy_face!)

\bccq
!bc cod
      subroutine midpt(x, length, a, b)
      real*8 a, b, x
      x = (a + b)/2
      length = b - a
      return
      end
!ec
\eccq
which then is typeset as

\bcod
      subroutine midpt(x, length, a, b)
      real*8 a, b, x
      x = (a + b)/2
      length = b - a
      return
      end
\ecod

HTML:

\bhtmlcod
<table>
<tr><td>Column 1</td><td>Column 2</td></tr>
<tr><td>0.67526 </td><td>0.92871 </td></tr>
<!-- comment -->
</table>
\ehtmlcod

But inline HTML code is also important, like text that starts with
\texttt{<a href="} (which can destroy the following text if not properly
quoted).

Matlab with comments requires special typesetting:

\bmcod
% Comment on the beginning of the line can be escaped by %%
if a > b
  % Indented comment needs this trick
  c = a + b
end
\emcod

And here is a system call:

\bsys
Terminal> mkdir test
Terminal> cd test
Terminal> myprog -f
output1
output2
\esys

Any valid pygments lexer/language name can appear to, e.g.,

\bccq
!bc restructuredtext
=======
Heading
=======

Some text.
!ec
\eccq
results in

\brestructuredtext
=======
Heading
=======

Some text.
\erestructuredtext

% Here goes hidden code.
% Python can be treated by some formats, Fortran is always out.





Finally, \Verb?!bc do? supports highlighting of DocOnce source:

\bdo
======= DocOnce test file =======

===== Computer code =====

Inline verbatim code, as in `import numpy as np`, is allowed, as well as
code blocks:

!bc pycod
from math import sin

def f(x):
    """Example on a function."""
    return sin(x) + 1

print(f(0))
!ec


===== Mathematics =====

Formulas can be inline, as in $\nabla\cdot\bm{u} = 0$, or typeset
as equations:

!bt
\begin{align*}
\nabla\cdot\bm{u} &= 0,\\ 
\bm{u} &= \nabla\phi .
\end{align*}
!et

=== Subsubsection heading ===

DocOnce files can have chapters, sections, subsections, and subsubsections.

__Paragraph heading.__ Paragraphs may have headings.
\edo

It is time to test \texttt{verbatim inline font} especially with \texttt{a newline inside the text} and an exclamation mark at the end: \texttt{BEGIN}! For
spellcheck, test \texttt{a verbatim expression} in \texttt{another} in a \texttt{third}.
Also test exclamation mark as in \Verb?!bc? and \Verb?!ec? as well as \Verb?a != b?.
Also test backslashes and braces like \Verb!\begin!, \Verb!\begin{enumerate}!,
\Verb!\end{this}\end{that}!, and \Verb!{something \inside braces}!.

Here is some \textcolor{red}{red color} and an attempt to write \textcolor{green}{with
green color containing a linebreak\\
code.} Some formats will only display \\
this correctly when \texttt{html} \\
is the output format.
But here some more running text is added which is not part of
the previous blocks with line breaks.

\paragraph{Running OS commands.}
\bsys
Terminal> python -c 'print("Testing\noutput\nfrom\nPython.")'
Testing
output
from
Python.
\esys


\paragraph{Footnotes.}
Here is a test of footnotes \footnote{Typesetting of the footnote depends on the format. Plain text does nothing, {\LaTeX} removes the definition and inserts the footnote as part of the {\LaTeX} text. reStructuredText and Sphinx employ a similar type of typesetting as Extended Markdown and DocOnce, and in HTML we keep the same syntax, just displayed properly in HTML.}, which are handy in text.
They are used in different flavors, now in

\begin{itemize}
 \item list items (note below that footnotes work after math, verbatim, and URLs - bin fact old and emphasize too!)

 \item even with math $\nabla^2u$\footnote{Math footnotes can be dangerous since it interferes with an exponent.}

 \item and code \texttt{h[i] += 1}\footnote{One-line footnote.}
   (\emph{must} have space between inline code and footnote!)

 \item and \href{{https://google.com}}{links}\footnote{\href{{google.com}}{\nolinkurl{google.com}} is perhaps the most famous web site today.}
\end{itemize}

\noindent
which gives flexibility in writing.
This is the third\footnote{Not much to add here, but the footnote is at the end with only one newline.} example.





Here is some more text before a new definition of a footnote that was
used above.


\begin{notice_mdfboxadmon}[Non-breaking space character.]
This paragraph aims to test \href{{https://en.wikipedia.org/wiki/Non-breaking_space}}{non-breaking space character}, and a typical
example where this is needed is in physical units: 7.4~km is traveled
in~$7.4/5.5\approx 1.345$~s.  Also check that a~\href{{https://google.com}}{link}~is
not broken across lines (drag the browser window to test this).
(On the other hand, the tilde is used in
computer code, e.g., as in \texttt{[~x for x in y]} or in \texttt{y=~x}, and should
of course remain a tilde in those contexts.)
\end{notice_mdfboxadmon} % title: Non-breaking space character.



\paragraph{Subsection 2: Testing figures.}
\label{subsec:ex}
\index{figures}

Test of figures. In particular we refer to Figure~\vref{fig:impact} in which
there is a flow.


\begin{figure}[!ht]  % fig:impact
  \centerline{\includegraphics[width=0.9\linewidth]{../doc/src/manual/fig/wave1D.png}}
  \caption{
  Visualization \textbf{of} a \emph{wave}. \label{fig:impact}
  }
\end{figure}
%\clearpage % flush figures fig:impact


Figures without captions are allowed and will be inlined.



\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=0.9\linewidth]{../doc/src/manual/fig/wave1D.png}}

\vspace{6mm}



\index{movies}


% Test multi-line caption in figure with sidecap=True

Here is figure~\vref{myfig} with a long (illegal) multi-line caption
containing inline verbatim text:


\begin{SCfigure}
  \centering
  \includegraphics[width=0.9\linewidth]{../doc/src/manual/fig/wave1D.png}
  \caption{
  A long caption spanning several lines and containing verbatim words like \protect \Verb!my\_file\_v1! and \protect \Verb!my\_file\_v2! as well as math with subscript as in $t_{i+1}$. \label{myfig}
  }
\end{SCfigure}
%\clearpage % flush figures myfig


% Must be a blank line after MOVIE or FIGURE to detect this problem

Test URL as figure name:



\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=0.8\linewidth]{downloaded_figures/f_plot.png}}

\vspace{6mm}




% Test wikimedia type of files that otherwise reside in subdirs


\paragraph{Remark.}
Movies are tested in separate file \texttt{movies.do.txt}.


% Somewhat challenging heading with latex math, \t, \n, ? and parenthesis

\paragraph{The $\theta$ parameter (not $\nabla$?).}
\label{decay:sec:theta}

Functions do not always need to be advanced, here is one
involving $\theta$:
\bccq
def f(theta):
    return theta**2
\eccq

\paragraph{More on $\theta$.}
Here is more text following headline with math.

Newcommands must also be tested in this \report:
$\half$, $\halfi$, $\x$, $\Ddt{u}$,
both inline and in block:

\begin{align}
\Ddt{u} &= 0\nonumber
\\ 
\half &= \halfi\\ 
\half\x &= \normalvec
\end{align}

Or with align with label and numbers:

\begin{align}
\Ddt{u} &= 0
\label{aligneq1}
\\ 
\half &= \halfi\\ 
\half\x &= \normalvec
\label{aligneq2}
\end{align}


% Must test more complicated align and matrix compositions
% where DocOnce inserts auto-numbered labels etc.

First one numbered (automatically):

\begin{align}
\begin{pmatrix}
G_2 + G_3 & -G_3 & -G_2 & 0 \\ 
-G_3 & G_3 + G_4 & 0 & -G_4 \\ 
-G_2 & 0 & G_1 + G_2 & 0 \\ 
0 & -G_4 & 0 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
 v_1 \\ 
 v_2 \\ 
 v_3 \\ 
 v_4
\end{pmatrix}
+ \cdots \\ 
\begin{pmatrix}
 C_5 + C_6 & -C_6 & 0 & 0 \\ 
 -C_6 & C_6 & 0 & 0 \\ 
 0 & 0 & 0 & 0 \\ 
 0 & 0 & 0 & 0
\end{pmatrix}
  &= \frac{d}{dt}\begin{pmatrix}
 v_1 \\ 
 v_2 \\ 
 v_3 \\ 
 v_4
\end{pmatrix} +
\begin{pmatrix}
 0 \\ 
 0 \\ 
 0 \\ 
 -i_0
\end{pmatrix}
\nonumber
\end{align}

Second numbered (automatically):

\begin{align}
\begin{pmatrix}
G_1 + G_2\\ 
-G_3 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
 v_1 \\ 
 v_2
\end{pmatrix}
+ \cdots\nonumber
\\ 
\left(\begin{array}{ll}
y & 2\\ 
2 & 1
\end{array}\right)
\left(\begin{array}{ll}
0 \\ x
\end{array}\right)
&= \begin{pmatrix}
A \\ B
\end{pmatrix}
\end{align}

Both numbered, with label by the user:

\begin{align}
\begin{pmatrix}
G_1 + G_2\\ 
-G_3 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
 v_1 \\ 
 v_2
\end{pmatrix}
+ \cdots \label{mymatrix:eq1}
\\ 
\label{mymatrix:eq2}
\left(\begin{array}{ll}
y & 2\\ 
2 & 1
\end{array}\right)
\left(\begin{array}{ll}
0 \\ x
\end{array}\right)
&= \begin{pmatrix}
A \\ B
\end{pmatrix}
\end{align}
Now we refer to (\ref{mymatrix:eq1})-(\ref{mymatrix:eq2}).

\paragraph{Custom Environments.}
Here is an attempt to create a theorem environment via Mako
(for counting theorems) and comment lines to help replacing lines in
the \texttt{.tex} by proper begin-end {\LaTeX} environments for theorems.
Should look nice in most formats!



% begin theorem
\label{theorem:fundamental1}


\paragraph{Theorem 5.}
Let $a=1$ and $b=2$. Then $c=3$.
% end theorem

% begin proof
\paragraph{Proof.}
Since $c=a+b$, the result follows from straightforward addition.
$\Diamond$
% end proof

As we see, the proof of Theorem 5 is a modest
achievement.


\paragraph{Tables.}
\label{subsec:table}

\index{test index with verbatim text@test index with {\rm\texttt{verbatim text}} which is possible}
\index{test two@test {\rm\texttt{two}} (separate) {\rm\texttt{verbatim expressions}} which is also possible}
\index{index with!subindex}
\index{\textbf{boldface word} in index}
\index{index with \textbf{boldface word}}
\index{index with!\textbf{boldface word} in subentry}
\index{double \textbf{boldface word}! \textbf{boldface word} in subentry too}

% index with comma could fool sphinx
\index{index, with comma, and one more}

Let us take this table from the manual:

\begin{table}
\caption{
Testing table environment in {\LaTeX}, enabled by testing on the "latex" format
with the preprocessor.
\label{mytab}
}



\begin{quote}
\begin{tabular}{lrr}
\hline
\multicolumn{1}{c}{ time } & \multicolumn{1}{c}{ velocity } & \multicolumn{1}{c}{ acceleration } \\
\hline
0.0  & 1.4186   & -5.01        \\
2.0  & 1.376512 & 11.919       \\
4.0  & 1.1E+1   & 14.717624    \\
\hline
\end{tabular}
\end{quote}

\noindent
\end{table}

The DocOnce source code reads
\bccq

  |--------------------------------|
  |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

Here is yet another table to test that we can handle more than
one table:


\begin{quote}
\begin{tabular}{lll}
\hline
\multicolumn{1}{l}{ time } & \multicolumn{1}{l}{ velocity } & \multicolumn{1}{l}{ acceleration } \\
\hline
0.0  & 1.4186   & -5.01        \\
1.0  & 1.376512 & 11.919       \\
3.0  & 1.1E+1   & 14.717624    \\
\hline
\end{tabular}
\end{quote}

\noindent
And one with math headings (that are expanded and must be treated
accordingly), verbatim heading and entry, and no space around the pipe
symbol:


\begin{quote}
\begin{tabular}{lrrr}
\hline
\multicolumn{1}{c}{ $i$ } & \multicolumn{1}{c}{ $h_i$ } & \multicolumn{1}{c}{ $\bar T_i$ } & \multicolumn{1}{c}{ \Verb!L\_i! } \\
\hline
0   & 0      & 288        & -0.0065    \\
1   & 11,000 & 216        & 0.0        \\
2   & 20,000 & 216        & 0.001      \\
3   & 32,000 & 228        & 0.0028     \\
4   & 47,000 & 270        & 0.0        \\
5   & 51,000 & 270        & -0.0028    \\
6   & 71,000 & 214        & \texttt{NaN} \\
\hline
\end{tabular}
\end{quote}

\noindent
And add one with verbatim headings (with underscores),
and rows starting with \texttt{|-} because of a negative number,
and \texttt{|} right before and after verbatim word (with no space):


\begin{quote}
\begin{tabular}{rrrr}
\hline
\multicolumn{1}{c}{ exact } & \multicolumn{1}{c}{ \Verb!v\_1! } & \multicolumn{1}{c}{ $a_i$ + \Verb!v\_2! } & \multicolumn{1}{c}{ \Verb!verb\_3\_! } \\
\hline
9     & 9.62       & 5.57               & 8.98           \\
-20   & -23.39     & -7.65              & -19.93         \\
10    & 17.74      & -4.50              & 9.96           \\
0     & -9.19      & 4.13               & -0.26          \\
\hline
\end{tabular}
\end{quote}

\noindent
Pipe symbols in verbatim and math text in tables used to pose difficulties,
but not
anymore:


\begin{quote}
\begin{tabular}{lr}
\hline
\multicolumn{1}{c}{ $S$ } & \multicolumn{1}{c}{ command } \\
\hline
$ ||a_0|| $ & \texttt{norm|length} \\
$x\cap y$   & \texttt{x|y}         \\
\hline
\end{tabular}
\end{quote}

\noindent

Here is a table with X alignment:


\begin{quote}
\begin{tabularx}{\linewidth}{cX}
\hline
\multicolumn{1}{c}{ Type } & \multicolumn{1}{c}{ Description } \\
\hline
X     & Alignment character that is used for specifying a potentially very long text in a column in a table. It makes use of the \texttt{tabularx} package in {\LaTeX}, otherwise (for other formats) it means \texttt{l} (centered alignment). \\
l,r,c & standard alignment characters                                                                                                                                                                                                       \\
\hline
\end{tabularx}
\end{quote}

\noindent
Finally, a table with math
and URLs.

% Mako code to expand URLs in the table
% (These types of tables did not work before Jan 2014)



\begin{quote}
\begin{tabular}{ccc}
\hline
 \\
\hline
$\mathcal{L}=0$         & \includegraphics[width=2cm]{../doc/src/manual/mov/wave_frames/frame_0080.png} & \includegraphics[width=2cm]{../doc/src/manual/mov/wave_frames/frame_0085.png} \\
$a=b$                   & \includegraphics[width=2cm]{../doc/src/manual/mov/wave_frames/frame_0090.png} & \includegraphics[width=2cm]{../doc/src/manual/mov/wave_frames/frame_0095.png} \\
$\nabla\cdot\bm{u} =0 $ & \includegraphics[width=2cm]{../doc/src/manual/mov/wave_frames/frame_0100.png} & \includegraphics[width=2cm]{../doc/src/manual/mov/wave_frames/frame_0105.png} \\
\hline
\end{tabular}
\end{quote}

\noindent

\paragraph{A test of verbatim words in heading with subscript $a_i$: \protect\Verb!my\_file\_v1! and \protect\Verb!my\_file\_v2!.}
\paragraph{Paragraph with verbatim and math: \protect\Verb!my\_file\_v1.py! and \protect\Verb!my\_file\_v2.py! define some math $a_{i-1}$.}
Here is more \Verb!__verbatim__! code and
some plain text on a new line.

% Test various types of headlines
\paragraph{\textbf{Just bold}.}
Some text.

\paragraph{\emph{Just emphasize}.}
Some text.

\paragraph{\texttt{Just verbatim}.}
Some text.

\paragraph{\textbf{Bold} beginning.}
Some text.

\paragraph{\emph{Emphasize} beginning.}
Some text.

\paragraph{\texttt{Verbatim} beginning.}
Some text.

\paragraph{Maybe \textbf{bold end}.}
Some text.

\paragraph{Maybe \emph{emphasize end}.}
Some text.

\paragraph{Maybe \texttt{verbatim end}.}
Some text.

\paragraph{The middle has \textbf{bold} word.}
Some text.

\paragraph{The middle has \emph{emphasize} word.}
Some text.

\paragraph{The middle has \texttt{verbatim} word.}
Some text.


\paragraph{\emph{Just emphasize}.}
Some text.


\paragraph{\texttt{Just verbatim}.}
Some text.


\paragraph{\emph{Emphasize} beginning.}
Some text.


\paragraph{\texttt{Verbatim beginning}.}
Some text.


\paragraph{Maybe \emph{emphasize end}.}
Some text.


\paragraph{Maybe \texttt{verbatim end}.}
Some text.


\paragraph{The middle has \emph{emphasize} word.}
Some text.


\paragraph{The middle has \texttt{verbatim} word.}
Some text.


\paragraph{Ampersand.}
We can test Hennes {\&} Mauritz, often abbreviated H{\&}M, but written
as \Verb!Hennes & Mauritz! and \Verb!H & M!.
A sole \Verb!&! must also work.
% Note: substitutions must not occur inside verbatim, just in ordinary text.

\bccq
# Just to check that ampersand works in code blocks:
c = a & b
\eccq

\paragraph{Quotes.}
Let us also add a test of quotes such as ``double quotes, with numbers
like 3.14 and newline/comma and hyphen (as in double-quote)''; written
in the standard LaTeX-style that gives correct {\LaTeX} formatting and
ordinary double quotes for all non-LaTeX formats.  Here is another
sentence that ``caused'' a bug in the past because double backtick
quotes could imply verbatim text up to a verbatim word starting with
period, like \texttt{.txt}.

More quotes to be tested for spellcheck:
(``with parenthesis''), ``with newline''
and ``with comma'', ``hyphen''-wise, and ``period''.


\paragraph{Bibliography test.}
Here is an example: \cite{Langtangen_Pedersen_2002} discussed propagation of
large destructive water waves, \cite{Langtangen_et_al_2002} gave
an overview of numerical methods for solving the Navier--Stokes equations,
while the use of Backward Kolmogorov equations for analyzing
random vibrations was investigated in \cite{Langtangen_1994a}.
The book chapter \cite{Mardal_et_al_2003a} contains information on
C++ software tools for programming multigrid methods. A real retro
reference is \cite{Langtangen_1988d} about a big FORTRAN package.
Multiple references are also possible, e.g., see
\cite{Langtangen_Pedersen_2002,Mardal_et_al_2003a}.

We need to cite more than 10 papers to reproduce an old formatting
problem with blanks in the keys in reST format:
\cite{Langtangen_1992c,Langtangen_1994a,Mortensen_et_al_2011,Langtangen_Pedersen_2002}
and
\cite{Langtangen_et_al_2002,Glimsdal_et_al_20006,Rahman_et_al_2006b,Haga_et_al_2011a,Langtangen_2003a,Langtangen_2008a,Langtangen:95}
and all the work of
\cite{Langtangen_2012,Mardal_et_al_2003a,Jeberg_et_al_2004} as well as
old work \cite{Langtangen_1988d} and \cite{Langtangen_1989e}, and the
talk \cite{Langtangen_talk_2007a}.
Langtangen also had two thesis \cite{Langtangen:85,Langtangen_1989e}
back in the days.
More retro citations are
the old ME-IN323 book \cite{Langtangen:91} and the
\cite{Langtangen:94b} OONSKI '94 paper.




% --- begin exercise ---
\begin{doconceexercise}
\refstepcounter{doconceexercisecounter}

\exercisesection{Example \thedoconceexercisecounter: Examples can be typeset as exercises}
                             
\label{Example}

Examples can start with a subsection heading starting with \texttt{Example:}
and then, with the command-line option \Verb!--examples_as_exercises! be
typeset as exercises. This is useful if one has solution
environments as part of the example.


\subex{a)}
State some problem.

\paragraph{Solution.}
The answer to this subproblem can be written here.

\subex{b)}
State some other problem.

\paragraph{Hint 1.}
A hint can be given.

\paragraph{Hint 2.}
Maybe even another hint?

\paragraph{Solution.}
The answer to this other subproblem goes here,
maybe over multiple doconce input lines.

\end{doconceexercise}
% --- end exercise ---


\paragraph{User-defined environments.}
Example~\vref{ex:test:1p1} demonstrates how to write a test function.
That is, a special test function for a function \texttt{add} appears in
Example~\vref{ex:test:1p1}.


\begin{example}
\label{ex:test:1p1}

\noindent\emph{A test function}.

Suppose we want to write a test function for checking the
implementation of a Python function for addition.

\bpycod
def add(a, b):
    return a + b

def test_add():
    a = 1; b = 1
    expected = a + b
    computed = add(a, b)
    assert expected == computed
\epycod
\end{example}



\begin{example}
\label{ex:math:1p1}

\noindent\emph{Addition}.

We have

\[ 1 + 1 = 2 \]
or in tabular form:


\begin{quote}
\begin{tabular}{cc}
\hline
\multicolumn{1}{c}{ Problem } & \multicolumn{1}{c}{ Result } \\
\hline
$1+1$   & $2$    \\
\hline
\end{tabular}
\end{quote}

\noindent
\end{example}



\begin{tcolorbox}[%skin=widget,
boxrule=1mm,
coltitle=black,
colframe=blue!45!white,
colback=blue!15!white,
width=(.9\linewidth),before=\hfill,after=\hfill,
adjusted title={Highlight box!}]
This environment is used to highlight something:

\[ E = mc^2 \]
\end{tcolorbox}



\paragraph{URLs.}
\label{subsubsec:ex}

Testing of URLs: hpl's home page \href{{https://folk.uio.no/hpl}}{hpl}, or
the entire URL if desired, \href{{https://folk.uio.no/hpl}}{\nolinkurl{https://folk.uio.no/hpl}}.  Here is a
plain file link \href{{testdoc.do.txt}}{\nolinkurl{testdoc.do.txt}}, or \href{{testdoc.do.txt}}{\nolinkurl{testdoc.do.txt}}, or
\href{{testdoc.do.txt}}{\nolinkurl{testdoc.do.txt}} or \href{{testdoc.do.txt}}{\nolinkurl{testdoc.do.txt}} or \href{{testdoc.do.txt}}{a link with
newline}. Can test spaces with the link with word
too: \href{{https://folk.uio.no/hpl}}{hpl} or \href{{https://folk.uio.no/hpl}}{hpl}. Also \texttt{file:///} works: \href{{file:///home/hpl/vc/doconce/doc/demos/manual/manual.html}}{link to a
file} is
fine to have. Moreover, ``loose'' URLs work, i.e., no quotes, just
the plain URL as in \href{{https://folk.uio.no/hpl}}{\nolinkurl{https://folk.uio.no/hpl}}, if followed by space, comma,
colon, semi-colon, question mark, exclamation mark, but not a period
(which gets confused with the periods inside the URL).

Mail addresses can also be used: \href{{mailto:hpl@simula.no}}{\nolinkurl{hpl@simula.no}}, or just a \href{{mailto:hpl@simula.no}}{mail link}, or a raw \href{{mailto:hpl@simula.no}}{\nolinkurl{mailto:hpl@simula.no}}.

Here are some tough tests of URLs, especially for the \texttt{latex} format:
\href{{https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas}}{Newton-Cotes} formulas
and a \href{{https://www.springer.com/mathematics/computational+science+%26+engineering/book/978-3-642-23098-1}}{good book}. Need to test
Newton-Cotes with percentage in URL too:
\href{{https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas}}{\nolinkurl{https://en.wikipedia.org/wiki/Newton\%E2\%80\%93Cotes_formulas}}
and \href{{https://en.wikipedia.org/wiki/Newton-Cotes#Open_Newton.E2.80.93Cotes_formulae}}{\nolinkurl{https://en.wikipedia.org/wiki/Newton-Cotes\#Open_Newton.E2.80.93Cotes_formulae}} which has a shebang.

For the \texttt{--device=paper} option it is important to test that URLs with
monospace font link text get a footnote
(unless the \Verb!--latex_no_program_footnotelink!
is used), as in this reference to
\href{{https://github.com/hplgit/INF5620/tree/gh-pages/src/decay/experiments/decay_mod.py}}{\nolinkurl{decay_mod}}, \href{{https://tinyurl.com/pwyasaa/formulas.ball1.py}}{\nolinkurl{ball1.py}},
and \href{{https://tinyurl.com/pwyasaa/formulas.ball2.py}}{\nolinkurl{ball2.py}}.


% Comments should be inserted outside paragraphs (because in the rst
% format extra blanks make a paragraph break).

% Note that when there is no https: or file:, it can be a file link
% if the link name is URL, url, "URL", or "url". Such files should,
% if rst output is desired, but placed in a \Verb!_static*! folder.

More tough tests: repeated URLs whose footnotes when using the
\texttt{--device=paper} option must be correct. We have
\href{{https://google.com}}{google}, \href{{https://google.com}}{google}, and
\href{{https://google.com}}{google}, which should result in exactly three
footnotes.



\paragraph{Test of Some {\LaTeX} Fixes.}
Let's check abbr.~of some common kind, e.g.~the well-known i.e.
expression as an example, and 1 vs.~2 which is also often used.
Dr.~Tang and Prof.~Monsen, or maybe also prof.~Ting,
will go to the Dept.~of Science to test how Mr.~Hansen is doing together
with Ms.~Larsen. A reference like Sec.~\vref{subsubsec:ex} or
Ch.~\vref{subsubsec:ex}, or even App.~\vref{subsubsec:ex}, must also be
handled. Likewise, this is test no.~$i$ of DocOnce features.
Also, look at Fig.~4 to see how the data compares with Tab.~\vref{mytab}.
Percentage must be fixed: 7\%,  87.65\% and
50\% at the beginning of the line.


% !split and check if these extra words are included properly in the comment

\subsection{{\LaTeX} Mathematics}

Here is an equation without label using backslash-bracket environment:
\[ a = b + c \]

or with number and label, as in (\ref{my:eq1}), using the equation environment:

\begin{equation}
{\partial u\over\partial t} = \nabla^2 u \label{my:eq1}
\end{equation}

We can refer to this equation by (\ref{my:eq1}).

Here is a system without equation numbers, using the align-asterisk environment:

\begin{align*}
\pmb{a} &= \pmb{q}\times\pmb{n} \\ 
b &= \nabla^2 u + \nabla^4 v
\end{align*}


And here is a system of equations with labels in an align environment:

\begin{align}
a &= q + 4 + 5+ 6 \label{eq1} \\ 
b &= \nabla^2 u + \nabla^4 x \label{eq2}
\end{align}

We can refer to (\ref{eq1})-(\ref{eq2}). They are a bit simpler than
the Navier--Stokes equations. And test {\LaTeX} hyphen in \texttt{CG-2}.
Also test $a_{i-j}$ as well as $kx-wt$.

Testing \texttt{alignat} environment:

\begin{alignat}{2}
a &= q + 4 + 5+ 6\qquad & \mbox{for } q\geq 0 \label{eq1a} \\ 
b &= \nabla^2 u + \nabla^4 x & x\in\Omega \label{eq2a}
\end{alignat}

Many of the next environments will fail in non-latex formats.
Testing multiline:

\begin{multline}
a = b = q + \\ 
  f + \nabla\cdot\nabla u
\label{multiline:eq1}
\end{multline}

Testing split:

\begin{equation}
\label{split:envir:eq}
\begin{split}
a = b = q &+ \\ 
  & f + \nabla\cdot\nabla u
\end{split}
\end{equation}
We can refer to the last equation by (\ref{split:envir:eq}).

Testing gather:
\begin{gather}
a = b \\ 
c = d + 7 + 9
\end{gather}

Let us refer to (\ref{eq1})-(\ref{eq2}) again, and to the
alignat variant (\ref{eq1a})-(\ref{eq2a}), and to (\ref{my:eq1}).

Testing eqnarray:
\begin{eqnarray}
{\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{eqnarray}

More mathematical typesetting is demonstrated in the coming exercises.

Below, we have Problem~\vref{demo:ex:1} and Project~\vref{demo:ex:2},
as well as Projects~\vref{proj:circle1} and~\vref{exer:you}, and in
between there we have Exercise~\vref{exer:some:formula}.


\subsection{Exercises}



% --- begin exercise ---
\begin{doconceexercise}
\refstepcounter{doconceexercisecounter}

\exercisesection{Problem \thedoconceexercisecounter: Flip a Coin}
                             
\label{demo:ex:1}
% keywords = random numbers; Monte Carlo simulation; ipynb

% Torture tests


\subex{a)}
Make a program that simulates flipping a coin $N$ times.
Print out ``tail'' or ``head'' for each flip and
let the program count the number of heads.

% --- begin hint in exercise ---

\paragraph{Hint 1.}
Use \texttt{r = random.random()} and define head as \texttt{r <= 0.5}.

% --- end hint in exercise ---

% --- begin hint in exercise ---

\paragraph{Hint 2.}
Draw an integer among $\{1,2\}$ with
\texttt{r = random.randint(1,2)} and define head when \texttt{r} is 1.

% --- end hint in exercise ---


% removed !bans ... !eans environment (because of the command-line option --without_answers)


% removed !bsol ... !esol environment (because of the command-line option --without_solutions)

\subex{b)}
Vectorize the code in a) using boolean indexing.

Vectorized code can be written in many ways.
Sometimes the code is less intuitive, sometimes not.
At least there is not much to find in Section~\vref{sec1}.

\subex{c)}
Vectorize the code in a) using \texttt{numpy.sum}.


% removed !bans ... !eans environment (because of the command-line option --without_answers)

In this latter subexercise, we have an
example where the code is easy to read.


\noindent Filenames: \Verb!flip_coin.py!, \Verb!flip_coin.pdf!.

% Closing remarks for this Problem

\paragraph{Remarks.}
These are the exercise remarks, appearing at the very end.

% solution files: mysol.txt, mysol_flip_coin.py, yet_another.file

\end{doconceexercise}
% --- end exercise ---


\paragraph{My remarks.}
Remarks with such a subsubsection is treated as more text
after the last subexercise. Test a list too:

\begin{enumerate}
\item Mark 1.

\item Mark 2.
\end{enumerate}

\noindent
\paragraph{Not an exercise.}
Should be possible to stick a normal section in the middle of many
exercises.



% --- begin exercise ---
\begin{doconceexercise}
\refstepcounter{doconceexercisecounter}

\exercisesection{Exercise \thedoconceexercisecounter: Test of plain text exercise}
                             
\label{my:exer1}

Very short exercise. What is the capital
of Norway?
\noindent Filename: \texttt{myexer1}.

\end{doconceexercise}
% --- end exercise ---




% --- begin exercise ---
\begin{doconceexercise}
\refstepcounter{doconceexercisecounter}

\exercisesection{Project \thedoconceexercisecounter: Compute a Probability}
                             
\label{demo:ex:2}

% Minimalistic exercise


What is the probability of getting a number between 0.5 and 0.6 when
drawing uniformly distributed random numbers from the interval $[0,1)$?


At the end we have a list because that caused problems in {\LaTeX}
in previous DocOnce versions:

\begin{enumerate}
\item item1

\item item2
\end{enumerate}

\noindent
% --- begin hint in exercise ---

\paragraph{Hint.}
To answer this question empirically, let a program
draw $N$ such random numbers using Python's standard \texttt{random} module,
count how many of them, $M$, that fall in the interval $(0.5,0.6)$, and
compute the probability as $M/N$.

% --- end hint in exercise ---

\end{doconceexercise}
% --- end exercise ---




% --- begin exercise ---
\begin{doconceexercise}
\refstepcounter{doconceexercisecounter}

\exercisesection{Project \thedoconceexercisecounter: Explore Distributions of Random Circles}
                             
\label{proj:circle1}
% keywords = ipynb

The formula for a circle is given by

\begin{align}
x &= x_0 + R\cos 2\pi t,
\label{circle:x}\\ 
y &= y_0 + R\sin 2\pi t,
\label{circle:y}
\end{align}
where $R$ is the radius of the circle, $(x_0,y_0)$ is the
center point, and $t$ is a parameter in the unit interval $[0,1]$.
For any $t$, $(x,y)$ computed from (\ref{circle:x})-(\ref{circle:y})
is a point on the circle.
The formula can be used to generate \texttt{n} points on a circle:

\bpypro
import numpy as np

def circle(R, x0, y0, n=501):
    t = np.linspace(0, 1, n)
    x = x0 + R*np.cos(2*np.pi*t)
    y = y0 + R*np.sin(2*np.pi*t)
    return x, y

x, y = circle(2.0, 0, 0)
\epypro

% Often in an exercise we have some comments about the solution
% which we normally want to keep where they are.

The goal of this project is to draw $N$ circles with random
center and radius. Plot each circle using the \texttt{circle} function
above.


\subex{a)}
Let $R$ be normally distributed and $(x_0,y_0)$ uniformly distributed.

% --- begin hint in exercise ---

\paragraph{Hint.}
Use the \texttt{numpy.random} module to draw the
$x_0$, $y_0$, and $R$ quantities.

% --- end hint in exercise ---


% removed !bans ... !eans environment (because of the command-line option --without_answers)


% removed !bsol ... !esol environment (because of the command-line option --without_solutions)

\subex{b)}
Let $R$ be uniformly distributed and $(x_0,y_0)$ normally distributed.
\noindent Filename: \texttt{norm}.

\subex{c)}
Let $R$ and $(x_0,y_0)$ be normally distributed.


\noindent Filename: \texttt{circles}.

% Closing remarks for this Project

\paragraph{Remarks.}
At the very end of the exercise it may be appropriate to summarize
and give some perspectives.


\end{doconceexercise}
% --- end exercise ---




% --- begin exercise ---
\begin{doconceexercise}
\refstepcounter{doconceexercisecounter}

\exercisesection{Exercise \thedoconceexercisecounter: Determine some Distance}
                             
\label{exer:dist}

Intro to this exercise. Questions are in subexercises below.


% removed !bsol ... !esol environment (because of the command-line option --without_solutions)


\subex{a)}
Subexercises are numbered a), b), etc.

% --- begin hint in exercise ---

\paragraph{Hint 1.}
First hint to subexercise a).
With math $a=b$ in hint:

\[ a=b. \]
And with code (in plain verbatim) returning $x+1$ in hint:

\bccq
def func(x):
    return x + 1  # with code in hint
\eccq

% --- end hint in exercise ---

% --- begin hint in exercise ---

\paragraph{Hint 2.}
Second hint to subexercise a).

Test list in hint:

\begin{enumerate}
\item item1

\item item2
\end{enumerate}

\noindent
% --- end hint in exercise ---
\noindent Filename: \Verb!subexer_a.pdf!.


% removed !bans ... !eans environment (because of the command-line option --without_answers)

\subex{b)}
Here goes the text for subexercise b).


Some math $\cos^2 x + \sin^2 x = 1$ written one a single line:

\[ \cos^2 x + \sin^2 x = 1 \thinspace .\]

% --- begin hint in exercise ---

\paragraph{Hint.}
A hint for this subexercise.

% --- end hint in exercise ---
\noindent Filename: \Verb!subexer_b.pdf!.


% removed !bsol ... !esol environment (because of the command-line option --without_solutions)



% No meaning in this weired test example:
The text here belongs to the main (intro) part of the exercise. Need
closing remarks to have text after subexercises.

Test list in exercise:

\begin{enumerate}
\item item1

\item item2
% Closing remarks for this Exercise
\end{enumerate}

\noindent
\paragraph{Remarks.}
Some final closing remarks, e.g., summarizing the main findings
and their implications in other problems can be made. These
remarks will appear at the end of the typeset exercise.


\end{doconceexercise}
% --- end exercise ---




% --- begin exercise ---
\begin{doconceexercise}

\exercisesection{Some exercise without the "Exercise:" prefix}

% Another minimalistic exercise

Just some text. And some math saying that $e^0=1$ on a single line,
to test that math block insertion is correct:

\[ \exp{(0)} = 1 \]

And a test that the code \texttt{lambda x: x+2} is correctly placed here:

\bccq
lambda x: x+2
\eccq


% Have some comments at the end of the exercise to see that
% the Filename: ... is written correctly.
\end{doconceexercise}
% --- end exercise ---




% --- begin exercise ---
\begin{doconceexercise}
\refstepcounter{doconceexercisecounter}

\exercisesection{Exercise \thedoconceexercisecounter: Solution of differential equation}
                             
\label{sec:this:exer:de}


\begin{doconcequiz}
\refstepcounter{doconcequizcounter}
\label{quiz:diff:eq1}


\noindent\textbf{\large SOlution of differential equation}

\noindent
Given

\[ \frac{dy}{dx} = -y(x),\quad y(0)=1 \]
What is the solution of this equation?

\vspace{2mm}

\textbf{A}. $\Box$ 
$y=e^{-y}$

\textbf{B}. $\Box$ 
$y=e^{y}$

\textbf{C}. $\Box$ 
\bpycod
from math import exp
def f(x):
    return exp(x)
\epycod

\textbf{D}. $\Box$ 
The solution cannot be found because there is a derivative in the equation.

\textbf{E}. $\Box$ 
The equation is meaningless: an equation must be an equation
for $x$ or $y$, not a function $y(x)$.



\vspace{3mm}

\end{doconcequiz}



\end{doconceexercise}
% --- end exercise ---




% --- begin exercise ---
\begin{doconceexercise}
\refstepcounter{doconceexercisecounter}

\exercisesection{Example \thedoconceexercisecounter: Just an example}
                             

% This example needs the --examples_as_exercises option, otherwise
% it is just typeset as it is written.


\subex{a)}
What is the capital of Norway?

\paragraph{Answer.}
Oslo.

\end{doconceexercise}
% --- end exercise ---


\subsection{Here goes another section}

With some text, before we continue with exercises.

\subsection{More Exercises}



% --- begin exercise ---
\begin{doconceexercise}
\refstepcounter{doconceexercisecounter}

\exercisesection{Exercise \thedoconceexercisecounter: Make references to projects and problems}
                             
\label{exer:some:formula}

% Test comments not at the end only
Pick a statement from Project~\vref{proj:circle1} or Problem~\vref{demo:ex:1}
and verify it.

Test list at the end of an exercise without other elements (like subexercise,
hint, etc.):

\begin{enumerate}
\item item1

\item item2
\end{enumerate}

\noindent
\noindent Filename: \Verb!verify_formula.py!.

\end{doconceexercise}
% --- end exercise ---




% --- begin exercise ---
\begin{doconceexercise}
\refstepcounter{doconceexercisecounter}

\exercisesection{Project \thedoconceexercisecounter: References to Project~\vref{demo:ex:2} in a heading works for latex}
                             
\label{exer:you}

Refer to the previous exercise as Exercise~\vref{exer:some:formula},
the two before that as Projects~\vref{demo:ex:2} and~\vref{proj:circle1},
and this one as Project~\vref{exer:you}.
\noindent Filename: \Verb!selc_composed.pdf!.

\end{doconceexercise}
% --- end exercise ---




\bibliographystyle{plain}
\bibliography{papers}



\subsection{Appendix: Just for testing; part I}
\label{app1}

This is the first appendix.

\paragraph{A subsection within an appendix.}
Some text.

\subsection{Appendix: Just for testing; part II}
\label{app2}

This is more stuff for an appendix.

\paragraph{Appendix: Testing identical titles.}
Without label.


\paragraph{Appendix: Testing identical titles.}
\label{test:title:id1}

With label.

\paragraph{Appendix: Testing identical titles.}
\label{test:title:id2}

What about inserting a quiz?


\begin{doconcequiz}
\refstepcounter{doconcequizcounter}
\label{quiz:2}


\noindent\textbf{\large Capital of Norway}
\paragraph{Fundamental test:}
What is the capital of Norway?

\vspace{2mm}

\textbf{A}. $\Box$ 
Stockholm

\textbf{B}. $\Box$ 
London

\textbf{C}. $\Box$ 
Oslo

\textbf{D}. $\Box$ 
Bergen



\vspace{3mm}

\end{doconcequiz}




\paragraph{Appendix: Testing identical titles.}
Without label.


\begin{notice_mdfboxadmon}[Tip.]
Here is a tip or hint box, typeset as a notice box.
\end{notice_mdfboxadmon} % title: Tip.




\clearpage

Need a lot of text to surround the summary box.
Version control systems allow you to record the history of files
and share files among several computers and collaborators in a
professional way. File changes on one computer are updated or
merged with changes on another computer. Especially when working
with programs or technical reports it is essential
to have changes documented and to
ensure that every computer and person involved in the project
have the latest updates of the files.
Greg Wilson' excellent \href{{https://software-carpentry.org/2010/07/script-for-introduction-to-version-control/}}{Script for Introduction to Version Control} provides a more detailed motivation why you will benefit greatly
from using version control systems.


\begin{summary_mdfboxadmon}[Summary.]
\textbf{Bold remark:} Make some text with this summary.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
\end{summary_mdfboxadmon} % title: Summary.



Projects that you want to share among several computers or project
workers are today most conveniently stored at some web site "in the
cloud" and updated through communication with that site. I strongly
recommend you to use such sites for all serious programming and
scientific writing work - and all other important files.

The simplest services for hosting project files are \href{{https://dropbox.com}}{Dropbox} and \href{{https://drive.google.com}}{Google Drive}.
It is very easy to get started with these systems, and they allow you
to share files among laptops and mobile units with as many users as
you want. The systems offer a kind of version control in that the
files are stored frequently (several times per minute), and you can go
back to previous versions for the last 30 days. However, it is
challenging  to find the right version from the past when there are
so many of them.

More seriously, when several people may edit files simultaneously, it
can be difficult detect who did what when, roll back to previous
versions, and to manually merge the edits when these are
incompatible. Then one needs more sophisticated tools than Dropbox or
Google Drive: project hosting services with true version control
systems.  The following text aims at providing you with the minimum
information to started with such systems. Numerous other tutorials
contain more comprehensive material and in-depth explanations of the
concepts and tools.

The idea with project hosting services is that you have the files
associated with a project in the cloud. Many people may share these
files.  Every time you want to work on the project you explicitly
update your version of the files, edit the files as you like, and
synchronize the files with the "master version" at the site where the
project is hosted.  If you at some point need to go back to a
version of the files at some particular point in the past,
this is an easy operation. You can also use tools to see
what various people have done with the files in the various versions.

All these services are very similar. Below we describe how you get
started with Bitbucket, GitHub, and Googlecode. Launchpad works very
similarly to the latter three. All the project hosting services have
excellent introductions available at their web sites, but the recipes
below are much shorter and aim at getting you started as quickly as
possible by concentrating on the most important need-to-know steps.
The Git tutorials we refer to later in this document contain more
detailed information and constitute of course very valuable readings
when you use version control systems every day. The point now is
to get started.


\paragraph{Appendix: Testing inline comments.}
% Names can be [ A-Za-z0-9_'+-]+

Projects that you want to share among several computers or project
workers are today most conveniently stored at some web site "in the
cloud" and updated through communication with that
site. \shortinlinecomment{hpl's semi opinion 1}{ not sure if in the cloud is understood by all. }{ not sure if in } I strongly recommend you to use such sites for all serious
programming and scientific writing work - and all other important
files.

The simplest services for hosting project files is Dropbox. \longinlinecomment{mp 2}{ Simply go to \href{{https://dropbox.com}}{\nolinkurl{https://dropbox.com}} and watch the video. It explains how files, like \texttt{myfile.py}, perhaps containing much math, like $\partial u/\partial t$, are easily communicated between machines. }{ Simply go to \href{{https://dropbox.com}}{\nolinkurl{https://dropbox.com}} } It
is very easy to get started with Dropbox, and it allows you to share
files among \textcolor{red}{(hpl 3:)} \replace{laptops and mobile units}{computers, tablets, and phones}.

% Test horizontal rule

------

% Coments for editing

First\textcolor{red}{, (\textbf{edit 4}: add comma)} consider a quantity $Q$. \textcolor{red}{(edit 5:)} \replace{To this end,}{We note that}
$Q>0$, because (\textbf{edit 6}:) \remove{a} negative \textcolor{red}{(edit 7:)} \replace{quantity is}{quantities are} (\textbf{edit 8}:) \remove{just} negative.  \textcolor{red}{ (\textbf{edit 9}:) This comes as no surprise.}

% Test tailored latex figure references with page number
Let us refer to Figure~\vref{fig:impact} again.

Test references in a list:

\begin{itemize}
 \item \vref{sec1}

 \item \vref{subsec1}

 \item \vref{fig:impact}
\end{itemize}

\noindent
\paragraph{Appendix: Testing headings ending with \texttt{verbatim inline}.}
The point here is to test 1) \texttt{verbatim} code in headings, and 2)
ending a heading with verbatim code as this triggers a special
case in {\LaTeX}.

We also test mdash---used as alternative to hyphen without spaces around,
or in quotes:


\begin{quote}
\emph{Fun is fun}.---Unknown.
\end{quote}


The ndash should also be tested -- as in the Hanson--Nilson equations
on page 277--278.

And finally, what about admons, quotes, and boxes? They are tested
in a separate document: \texttt{admon.do.txt}.


% ------------------- end of main content ---------------

% #ifdef PREAMBLE
\cleardoublepage\phantomsection  % trick to get correct link to Index
\printindex

\end{document}
% #endif

************** File: mako_test1.html *****************

<!-- tocinfo
{'highest level': 4, 'sections': []}
end of tocinfo -->


<!-- ------------------- main content ---------------------- -->

<!-- Purpose: see if doconce detects that mako must be used -->

<p>
This document is translated to the format html.

<!-- ------------------- end of main content --------------- -->


************** File: mako_test2.html *****************

<!-- tocinfo
{'highest level': 4, 'sections': []}
end of tocinfo -->


<!-- ------------------- main content ---------------------- -->

<!-- Purpose: see if doconce detects dangerous lines for mako, -->
<!-- starting with a %, but here it is not crucial since the -->
<!-- running text does not need mako :-) -->

<p>
<!-- begin verbatim block -->
<pre><code>/* Here is some SWIG code code */
%module MyMod
%{
...
%}

%init %{
import_array();
%}
</code></pre>
<!-- end verbatim block -->

<p>
And more code:
<!-- begin verbatim block -->
<pre><code>% Matlab comment only
...
</code></pre>
<!-- end verbatim block -->

<!-- ------------------- end of main content --------------- -->


************** File: mako_test3.html *****************

<!-- tocinfo
{'highest level': 4, 'sections': []}
end of tocinfo -->


<!-- ------------------- main content ---------------------- -->

<!-- Purpose: see if doconce detects dangerous lines for mako, -->
<!-- starting with a %, and here it is crucial since the -->
<!-- running text does need mako -->

<p>
<!-- begin verbatim block -->
<pre><code>/* Here is some SWIG code code */
%module MyMod
%{
...
%}

%init %{
import_array();
%}
</code></pre>
<!-- end verbatim block -->

<p>
And more code:
<!-- begin verbatim block -->
<pre><code>% Matlab comment only
...
</code></pre>
<!-- end verbatim block -->

<!-- ------------------- end of main content --------------- -->


************** File: mako_test3b.html *****************

<!-- tocinfo
{'highest level': 4, 'sections': []}
end of tocinfo -->


<!-- ------------------- main content ---------------------- -->

<!-- Purpose: see if doconce detects dangerous lines for mako, -->
<!-- starting with a %, and here it is crucial since the -->
<!-- running text does need mako -->

<p>
<!-- begin verbatim block -->
<pre><code>/* Here is some SWIG code code */
%module MyMod
%{
...
%}

%init %{
import_array();
%}
</code></pre>
<!-- end verbatim block -->

<p>
And more code:
<!-- begin verbatim block -->
<pre><code>% Matlab comment only
...
</code></pre>
<!-- end verbatim block -->

<!-- ------------------- end of main content --------------- -->


************** File: mako_test4.html *****************

<!-- tocinfo
{'highest level': 4, 'sections': []}
end of tocinfo -->


<!-- ------------------- main content ---------------------- -->

<!-- Purpose: correct mako_test3.do.txt such that we -->
<!-- can use mako and have lines starting with % -->
<!-- (i.e., the lines must manually be edited to -->
<!-- start with %%) -->

<p>
<!-- begin verbatim block -->
<pre><code>/* Here is some SWIG code code */
%module MyMod
%{
...
%}

%init %{
import_array();
%}
</code></pre>
<!-- end verbatim block -->

<p>
And more code:
<!-- begin verbatim block -->
<pre><code>% Matlab comment only
...
</code></pre>
<!-- end verbatim block -->

<!-- ------------------- end of main content --------------- -->


************** File: automake_sphinx_testdoc.py *****************
#!/usr/bin/env python
# -*- coding: utf-8 -*-
# Autogenerated file (by doconce sphinx_dir).
# Purpose: create HTML Sphinx version of document "testdoc".
#
# Note: doconce clean removes this file, so if you edit the file,
# rename it to avoid automatic removal.

# To force compilation of the doconce file to sphinx format, remove
# the sphinx (.rst) file first.
#
# Command-line arguments are transferred to the "doconce format sphinx"
# compilation command.
#

import glob, sys, os, subprocess, shutil, logging
logging.basicConfig(
    filename='automake_sphinx.log', filemode='w', level=logging.DEBUG,
    format='%(asctime)s - %(levelname)s - %(message)s',
    datefmt='%Y.%m.%d %I:%M:%S %p')


command_line_options = ' '.join(['"%s"' % arg for arg in sys.argv[1:]])

sphinx_rootdir = 'sphinx-testdoc'
source_dir = sphinx_rootdir

if not os.path.isdir(sphinx_rootdir):
    print("""*** error: %(sphinx_rootdir)s does not exist. This means unsuccessful
    doconce sphinx_dir command. Try to upgrade to latest DocOnce version.
    (The script tmp_sphinx_gen.sh runs sphinx-quickstart - it may have failed.)
""" % vars())
    sys.exit(1)

def system(cmd, capture_output=False, echo=True):
    if echo:
        print('running', cmd)
    if capture_output:
        failure, outtext = subprocess.getstatusoutput(cmd) # Unix/Linux only
    else:
        failure = os.system(cmd)
    if failure:
        print('Could not run', cmd)
        logging.critical('Could not run %s' % cmd)
        sys.exit(1)
    if capture_output:
        return outtext

# Copy generated sphinx files to sphinx root directory
filename = 'testdoc'
rst_text = ''  # holds all text in all .rst files
for part in ['._testdoc000', '._testdoc001', '._testdoc002', '._testdoc003', '._testdoc004', '._testdoc005', '._testdoc006', '._testdoc007', '._testdoc008', '._testdoc009', '._testdoc010']:
    shutil.copy('%s.rst' % part, source_dir)
    with open('%s.rst' % part, 'r') as rst_file:
        rst_text += rst_file.read()

# Copy figures and movies directories
figdirs = glob.glob('fig*') + glob.glob('mov*')
for figdir in figdirs:
    destdir = None
    if figdir.startswith('fig'):
        # Figures can be anywhere (copied by sphinx to _images)
        destdir = os.path.join(source_dir, figdir)
    elif figdir.startswith('mov'):
        # Movies must be in _static
        # Copy only the movies if they are needed through local filenames
        if '"'+ figdir in rst_text or '<' + figdir in rst_text:
            destdir = os.path.join(source_dir, '_static', figdir)
    if destdir is not None and os.path.isdir(figdir) and not os.path.isdir(destdir):
        msg = 'copy: %s to %s' % (figdir, destdir)
        print(msg)
        logging.info(msg)
        shutil.copytree(figdir, destdir)

# Copy needed figure files in current dir (not in fig* directories)
for rstfile in glob.glob(os.path.join(source_dir, '*.rst')) + glob.glob(os.path.join(source_dir, '.*.rst')):
    f = open(rstfile, 'r')
    text = text_orig = f.read()
    f.close()
    import re
    figfiles = [name.strip() for name in
                re.findall('.. figure:: (.+)', text)]
    local_figfiles = [name for name in figfiles if not os.sep in name]

    for name in figfiles:
        basename = os.path.basename(name)
        if name.startswith('http') or name.startswith('ftp'):
            pass
        else:
            if not os.path.isfile(os.path.join(source_dir, basename)):
                msg = 'copy: %s to %s' % (name, source_dir)
                print(msg)
                logging.info(msg)
                shutil.copy(name, source_dir)
            if name not in local_figfiles:
                # name lies in another directory, make local reference to it
                # since it is copied to source_dir
                text = text.replace('.. figure:: %s' % name,
                                    '.. figure:: %s' % basename)
                logging.info('edit: figure path to %s' % basename)
    if text != text_orig:
        f = open(rstfile, 'w')
        f.write(text)
        f.close()

# Copy linked local files, placed in _static*, to source_dir/_static
staticdirs = glob.glob('_static*')
for staticdir in staticdirs:
    if os.listdir(staticdir):  # copy only if non-empty dir
        cmd = 'cp -r %(staticdir)s/* %(source_dir)s/_static/' % vars()
        logging.info('running %s' % cmd)
        system(cmd)

# Create custom files in _static/_templates?
if '**Show/Hide Code**' in rst_text:
    with open(os.path.join(sphinx_rootdir, '_templates', 'page.html'), 'w') as f:
        f.write("""
{% extends "!page.html" %}

{% set css_files = css_files + ["_static/custom.css"] %}

{% block footer %}
 <script type="text/javascript">
    $(document).ready(function() {
        $(".toggle > *").hide();
        $(".toggle .header").show();
        $(".toggle .header").click(function() {
            $(this).parent().children().not(".header").toggle(400);
            $(this).parent().children(".header").toggleClass("open");
        })
    });
</script>
{% endblock %}
""")
    with open(os.path.join(sphinx_rootdir, '_static', 'custom.css'), 'w') as f:
        f.write("""
.toggle .header {
    display: block;
    clear: both;
}

.toggle .header:after {
    content: " ▼";
}

.toggle .header.open:after {
    content: " ▲";
}
""")

os.chdir(sphinx_rootdir)
if '--runestone' not in sys.argv:
    # Compile web version of the sphinx document
    print(os.getcwd())
    logging.info('running make clean and make html')
    system('make clean')
    system('make html')

    print('Fix generated files:',)
    os.chdir('_build/html')
    for filename in glob.glob('*.html') + glob.glob('.*.html'):
        print(filename)
        f = open(filename, 'r'); text = f.read(); f.close()
        text_orig = text
        # Fix double title in <title> tags
        text = re.sub(r'<title>(.+?) &mdash;.+?</title>', r'<title>\g<1></title>', text)
        # Fix untranslated math (e.g. in figure captions and raw html)
        text = re.sub(r':math:`(.+?)`', r' \( \g<1> \) ', text)
        # Fix links to movies
        text = re.sub(r'''src=['"](mov.+?)['"]''', r'src="_static/\g<1>"', text)
        # Fix movie frames in javascript player
        text = text.replace(r'.src = "mov', '.src = "_static/mov')
        # Fix admonition style
        text = text.replace('</head>', '''
       <style type="text/css">\n         div.admonition {
           background-color: whiteSmoke;
           border: 1px solid #bababa;
         }
       </style>
      </head>
    ''')

        # Check if external links should pop up in separate windows
        if '.. NOTE: Open external links in new windows.' in text:
            text = text.replace('<a class="reference external"',
                                '<a class="reference external" target="_blank"')

        # Make a link for doconce citation in copyright
        if '. Made with DocOnce' in text:
            text = text.replace('. Made with DocOnce', '')
            text = text.replace('      Created using <a href="https://sphinx-doc.org/">Sphinx', '      Created using <a href="https://github.com/hplgit/doconce">DocOnce</a> and <a href="https://sphinx-doc.org/">Sphinx')
        # Remove (1), (2), ... numberings in identical headings
        headings_wno = re.findall(r'(?<=(\d|"))>([^>]+?)          \((\d+)\)<', text)
        for dummy, heading, no in headings_wno:
            heading = heading.strip()
            text = re.sub(r'>%s +\(%d\)<' %
                          (re.escape(heading), int(no)),
                          '>%s<' % heading, text)
            text = re.sub(r'title="%s +\(%d\)"' %
                          (re.escape(heading), int(no)),
                          r'title="%s"' % heading, text)

        if os.path.isfile(filename + '.old~~'):
            os.remove(filename + '.old~~')
        f = open(filename, 'w'); f.write(text); f.close()
        if text != text_orig:
            logging.info('edit: %s' % filename)
    os.chdir('../../')
    print('\n\ngoogle-chrome sphinx-testdoc/_build/html/index.html\n')

else:
    # Add directory for RunestoneInteractive book
    use_runestonebooks_style = True  # False: use user-chosen style
    print("""

create RunestoneInteractive directory
""")
    sys.path.insert(0, os.curdir)
    import conf as source_dir_conf  # read data from conf.py

    if not os.path.isdir('RunestoneTools'):
        system('git clone https://github.com/RunestoneInteractive/RunestoneComponents.git')
    os.chdir('RunestoneComponents')
    logging.info('creating RunestoneInteractive directory')

    # Edit conf.py
    # This one does not work anymore: run runestone init instead,
    print('RunestoneInteractive has recently changed its setup - must abort')
    sys.exit(1)
    # it's the file runestone/__main__.py and function init()
    # Need to build a bash script that runs the command and feeds the answers
    # See also https://github.com/RunestoneInteractive/RunestoneComponents
    f = open('conf.py.prototype', 'r');  text = f.read();  f.close()
    text = text.replace('<ENTER YOUR PROJECT NAME HERE>', source_dir_conf.project)
    text = text.replace('<INSERT YOUR PROJECT NAME HERE>', source_dir_conf.project)
    text = text.replace('<ENTER YOUR COPYRIGHT NOTICE HERE>', source_dir_conf.copyright)
    text = text.replace('<INSERT YOUR PROJECT NAME OR OTHER TITLE HERE>', source_dir_conf.project)
    text = text.replace('<INSERT YOUR PROJECT NAME OR OTHER SHORT TITLE HERE>', source_dir_conf.project)
    text = text.replace('html_theme_path = ["_templates"]', 'html_theme_path = ["_templates", "../_themes"]')
    if not use_runestonebooks_style:
        text = text.replace("html_theme = 'sphinx_bootstrap'", "html_theme = '%s'" % source_dir_conf.html_theme)
        text = re.sub(r'html_theme_options = \{.+?\}', 'html_theme_options = ' + str(source_dir_conf.html_theme_options) if hasattr(source_dir_conf, 'html_theme_options') else 'html_theme_options = {}', text, flags=re.DOTALL)
    f = open('conf.py', 'w');  f.write(text);  f.close()

    # Copy .rst files from sphinx dir
    rst_files = [os.path.join(os.pardir, 'index.rst')] + glob.glob(os.path.join(os.pardir, '*.rst')) + glob.glob(os.path.join(os.pardir, '._*.rst'))
    for filename in rst_files:
        print('copying', filename, 'to _sources')
        logging.info('copy: %s to _sources' % filename)
        shutil.copy(filename, '_sources')
    print('*** running paver build to build the RunestoneInteractive book')
    logging.info('running paver build to create the RunestoneInteractive book')
    system('paver build')

    print('\n\ngoogle-chrome sphinx-testdoc/RunestoneTools/build/index.html')

************** File: testdoc_sphinx_index.rst *****************
.. Master file automatically created by doconce sphinx_dir


A Document for Testing DocOnce
==============================

Contents:

.. toctree::
   :maxdepth: 2

   ._testdoc000
   ._testdoc001
   ._testdoc002
   ._testdoc003
   ._testdoc004
   ._testdoc005
   ._testdoc006
   ._testdoc007
   ._testdoc008
   ._testdoc009
   ._testdoc010
Index
=====

* :ref:`genindex`

************** File: testdoc_sphinx_conf.py *****************
# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

# -- Path setup --------------------------------------------------------------

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))


# -- Project information -----------------------------------------------------

project = '_'
short_title = project
copyright = '2021, A Document for Testing DocOnce'
author = 'A Document for Testing DocOnce'

# The full version, including alpha/beta/rc tags
release = 'Hans Petter Langtangen, Kaare Dump, A. Dummy Author, I. S. Overworked and Outburned and J. Doe'


# -- General configuration ---------------------------------------------------

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
          #'sphinx.ext.pngmath',
          #'sphinx.ext.jsmath',
          'sphinx.ext.mathjax',
          #'matplotlib.sphinxext.mathmpl',
          #'matplotlib.sphinxext.only_directives',
          'matplotlib.sphinxext.plot_directive',
          'sphinx.ext.autodoc',
          'sphinx.ext.doctest',
          'sphinx.ext.viewcode',
          'sphinx.ext.intersphinx',
          'sphinx.ext.inheritance_diagram',
          'IPython.sphinxext.ipython_console_highlighting']

#pngmath_dvipng_args = ['-D 200', '-bg Transparent', '-gamma 1.5']  # large math fonts (200)

# Make sphinx aware of the DocOnce lexer
def setup(app):
    from sphinx.highlighting import lexers
    from doconce.misc import DocOnceLexer
    lexers['doconce'] = DocOnceLexer()

# Check which additional themes that are installed
additional_themes_installed = []
additional_themes_url = {}

# Add any paths that contain custom themes here, relative to this directory.
html_theme_path = ['_themes']
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']

try:
    import alabaster
    additional_themes_installed.append('alabaster')
except ImportError:
    additional_themes_url['alabaster'] = 'pip install alabaster'

try:
    import sphinxjp.themes.solarized
    additional_themes_installed.append('solarized')
except ImportError:
    additional_themes_url['solarized'] = 'https://bitbucket.org/miiton/sphinxjp.themes.solarized: pip install --exists-action i -e hg+https://bitbucket.org/miiton/sphinxjp.themes.solarized#egg=sphinxjp.themes.solarized --upgrade'

try:
    import cloud_sptheme as csp
    additional_themes_installed.append('cloud')
    additional_themes_installed.append('redcloud')
except ImportError:
    url = 'https://bitbucket.org/ecollins/cloud_sptheme: pip install --exists-action i -e hg+https://bitbucket.org/ecollins/cloud_sptheme#egg=cloud_sptheme --upgrade'
    additional_themes_url['cloud'] = url
    additional_themes_url['redcloud'] = url


'''
# FIXME: think we do not need to test on basicstrap, but some themes
# need themecore and we must test for that
try:
    import sphinxjp.themecore
    if not 'sphinxjp.themecore' in extensions:
        extensions += ['sphinxjp.themecore']
    additional_themes_installed.append('basicstrap')
except ImportError:
    # Use basicstrap as an example on a theme with sphinxjp.themecore (??)
    additional_themes_url['basicstrap'] = 'https://github.com/tell-k/sphinxjp.themes.basicstrap: pip install --exists-action i -e git+https://github.com/ryan-roemer/sphinx-bootstrap-theme#egg=sphinx-bootstrap-theme --upgrade'
'''

try:
    import sphinxjp.themes.impressjs
    additional_themes_installed.append('impressjs')
except ImportError:
    additional_themes_url['impressjs'] = 'https://github.com/shkumagai/sphinxjp.themes.impressjs: pip install --exists-action i -e git+https://github.com/shkumagai/sphinxjp.themes.impressjs#egg=sphinxjp.themes.impressjs --upgrade'

try:
    import sphinx_bootstrap_theme
    additional_themes_installed.append('bootstrap')
except ImportError:
    additional_themes_url['bootstrap'] = 'https://github.com/ryan-roemer/sphinx-bootstrap-theme: pip install --exists-action i -e git+https://github.com/ryan-roemer/sphinx-bootstrap-theme#egg=sphinx-bootstrap-theme --upgrade'

try:
    import icsecontrib.sagecellserver
    extensions += ['icsecontrib.sagecellserver']
except ImportError:
    # pip install --exists-action i -e git+https://github.com/kriskda/sphinx-sagecell#egg=sphinx-sagecell --upgrade
    pass

# Is the document built on readthedocs.org? If so, don't import
on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
if not on_rtd:  # only import and set the theme if we're building docs locally
    try:
        import sphinx_rtd_theme
        additional_themes_installed.append('sphinx_rtd_theme')
    except ImportError:
        additional_themes_url['sphinx_rtd_theme'] = 'pip install sphinx_rtd_theme'

tinker_themes = [
  'dark', 'flat', 'modern5', 'minimal5', 'responsive']
# https://tinkerer.me/index.html
# See Preview Another Theme in the sidebar of the above URL
try:
    import tinkerer
    import tinkerer.paths
    additional_themes_installed += tinker_themes
except ImportError:
    for theme in tinker_themes:
        additional_themes_url[theme] = 'pip install tinkerer --upgrade'



# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = '0.1'

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']


# -- Options for HTML output -------------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#
html_theme = 'agni'
#html_theme = 'ADCtheme'
#html_theme = 'agni'
#html_theme = 'agogo'
#html_theme = 'alabaster'
#html_theme = 'basic'
#html_theme = 'basicstrap'
#html_theme = 'bizstyle'
#html_theme = 'bloodish'
#html_theme = 'bootstrap'
#html_theme = 'cbc'
#html_theme = 'classic'
#html_theme = 'cloud'
#html_theme = 'default'
#html_theme = 'epub'
#html_theme = 'fenics'
#html_theme = 'fenics_classic'
#html_theme = 'fenics_minimal1'
#html_theme = 'fenics_minimal2'
#html_theme = 'haiku'
#html_theme = 'jal'
#html_theme = 'nature'
#html_theme = 'pylons'
#html_theme = 'pyramid'
#html_theme = 'redcloud'
#html_theme = 'scipy_lectures'
#html_theme = 'scrolls'
#html_theme = 'slim-agogo'
#html_theme = 'solarized'
#html_theme = 'sphinx_rtd_theme'
#html_theme = 'sphinxdoc'
#html_theme = 'traditional'
#html_theme = 'uio'
#html_theme = 'uio2'
#html_theme = 'vlinux-theme'
check_additional_themes= [
   'solarized', 'cloud', 'redcloud',
   'alabaster', 'bootstrap', 'impressjs']

for theme in check_additional_themes:
    if html_theme == theme:
        if not theme in additional_themes_installed:
            raise ImportError(
                'html_theme = \"%s\", but this theme is not installed. %s' % (theme, additional_themes_url[theme]))



if html_theme == 'solarized':
    pygments_style = 'solarized'



# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
************** File: automake_sphinx_math_test.py *****************
#!/usr/bin/env python
# -*- coding: utf-8 -*-
# Autogenerated file (by doconce sphinx_dir).
# Purpose: create HTML Sphinx version of document "math_test".
#
# Note: doconce clean removes this file, so if you edit the file,
# rename it to avoid automatic removal.

# To force compilation of the doconce file to sphinx format, remove
# the sphinx (.rst) file first.
#
# Command-line arguments are transferred to the "doconce format sphinx"
# compilation command.
#

import glob, sys, os, subprocess, shutil, logging
logging.basicConfig(
    filename='automake_sphinx.log', filemode='w', level=logging.DEBUG,
    format='%(asctime)s - %(levelname)s - %(message)s',
    datefmt='%Y.%m.%d %I:%M:%S %p')


command_line_options = ' '.join(['"%s"' % arg for arg in sys.argv[1:]])

sphinx_rootdir = 'sphinx-rootdir-math'
source_dir = sphinx_rootdir

if not os.path.isdir(sphinx_rootdir):
    print("""*** error: %(sphinx_rootdir)s does not exist. This means unsuccessful
    doconce sphinx_dir command. Try to upgrade to latest DocOnce version.
    (The script tmp_sphinx_gen.sh runs sphinx-quickstart - it may have failed.)
""" % vars())
    sys.exit(1)

def system(cmd, capture_output=False, echo=True):
    if echo:
        print('running', cmd)
    if capture_output:
        failure, outtext = subprocess.getstatusoutput(cmd) # Unix/Linux only
    else:
        failure = os.system(cmd)
    if failure:
        print('Could not run', cmd)
        logging.critical('Could not run %s' % cmd)
        sys.exit(1)
    if capture_output:
        return outtext

# Compile the doconce file if a sphinx version of it is not found
filename = 'math_test'
if not os.path.isfile(filename + '.rst'):
    # Transform doconce format to sphinx format and copy to sphinx directory
    cmd = 'doconce format sphinx %s %s' % (filename, command_line_options)
    print(cmd)
    logging.info('running %s' % cmd)
    system(cmd)

    # Fix: utf-8 encoding for non-English chars
    cmd = 'doconce guess_encoding %s.rst' % filename
    enc = system(cmd, capture_output=True)
    if enc == "iso-8859-1":
        # sphinx does not like non-English characters in iso-8859-1
        cmd = 'doconce change_encoding iso-8859-1 utf-8 %s.rst' % filename
        logging.info('running %s' % cmd)
        system(cmd)

# Copy generated sphinx file to sphinx directory
logging.info('copy: %s.rst to %s and reading the content' % (filename, source_dir))
shutil.copy('%s.rst' % filename, source_dir)
with open('%s.rst' % filename, 'r') as rst_file:
    rst_text = rst_file.read()

# Copy figures and movies directories
figdirs = glob.glob('fig*') + glob.glob('mov*')
for figdir in figdirs:
    destdir = None
    if figdir.startswith('fig'):
        # Figures can be anywhere (copied by sphinx to _images)
        destdir = os.path.join(source_dir, figdir)
    elif figdir.startswith('mov'):
        # Movies must be in _static
        # Copy only the movies if they are needed through local filenames
        if '"'+ figdir in rst_text or '<' + figdir in rst_text:
            destdir = os.path.join(source_dir, '_static', figdir)
    if destdir is not None and os.path.isdir(figdir) and not os.path.isdir(destdir):
        msg = 'copy: %s to %s' % (figdir, destdir)
        print(msg)
        logging.info(msg)
        shutil.copytree(figdir, destdir)

# Copy needed figure files in current dir (not in fig* directories)
for rstfile in glob.glob(os.path.join(source_dir, '*.rst')) + glob.glob(os.path.join(source_dir, '.*.rst')):
    f = open(rstfile, 'r')
    text = text_orig = f.read()
    f.close()
    import re
    figfiles = [name.strip() for name in
                re.findall('.. figure:: (.+)', text)]
    local_figfiles = [name for name in figfiles if not os.sep in name]

    for name in figfiles:
        basename = os.path.basename(name)
        if name.startswith('http') or name.startswith('ftp'):
            pass
        else:
            if not os.path.isfile(os.path.join(source_dir, basename)):
                msg = 'copy: %s to %s' % (name, source_dir)
                print(msg)
                logging.info(msg)
                shutil.copy(name, source_dir)
            if name not in local_figfiles:
                # name lies in another directory, make local reference to it
                # since it is copied to source_dir
                text = text.replace('.. figure:: %s' % name,
                                    '.. figure:: %s' % basename)
                logging.info('edit: figure path to %s' % basename)
    if text != text_orig:
        f = open(rstfile, 'w')
        f.write(text)
        f.close()

# Copy linked local files, placed in _static*, to source_dir/_static
staticdirs = glob.glob('_static*')
for staticdir in staticdirs:
    if os.listdir(staticdir):  # copy only if non-empty dir
        cmd = 'cp -r %(staticdir)s/* %(source_dir)s/_static/' % vars()
        logging.info('running %s' % cmd)
        system(cmd)

# Create custom files in _static/_templates?
if '**Show/Hide Code**' in rst_text:
    with open(os.path.join(sphinx_rootdir, '_templates', 'page.html'), 'w') as f:
        f.write("""
{% extends "!page.html" %}

{% set css_files = css_files + ["_static/custom.css"] %}

{% block footer %}
 <script type="text/javascript">
    $(document).ready(function() {
        $(".toggle > *").hide();
        $(".toggle .header").show();
        $(".toggle .header").click(function() {
            $(this).parent().children().not(".header").toggle(400);
            $(this).parent().children(".header").toggleClass("open");
        })
    });
</script>
{% endblock %}
""")
    with open(os.path.join(sphinx_rootdir, '_static', 'custom.css'), 'w') as f:
        f.write("""
.toggle .header {
    display: block;
    clear: both;
}

.toggle .header:after {
    content: " ▼";
}

.toggle .header.open:after {
    content: " ▲";
}
""")

os.chdir(sphinx_rootdir)
if '--runestone' not in sys.argv:
    # Compile web version of the sphinx document
    print(os.getcwd())
    logging.info('running make clean and make html')
    system('make clean')
    system('make html')

    print('Fix generated files:',)
    os.chdir('_build/html')
    for filename in glob.glob('*.html') + glob.glob('.*.html'):
        print(filename)
        f = open(filename, 'r'); text = f.read(); f.close()
        text_orig = text
        # Fix double title in <title> tags
        text = re.sub(r'<title>(.+?) &mdash;.+?</title>', r'<title>\g<1></title>', text)
        # Fix untranslated math (e.g. in figure captions and raw html)
        text = re.sub(r':math:`(.+?)`', r' \( \g<1> \) ', text)
        # Fix links to movies
        text = re.sub(r'''src=['"](mov.+?)['"]''', r'src="_static/\g<1>"', text)
        # Fix movie frames in javascript player
        text = text.replace(r'.src = "mov', '.src = "_static/mov')
        # Fix admonition style
        text = text.replace('</head>', '''
       <style type="text/css">\n         div.admonition {
           background-color: whiteSmoke;
           border: 1px solid #bababa;
         }
       </style>
      </head>
    ''')

        # Check if external links should pop up in separate windows
        if '.. NOTE: Open external links in new windows.' in text:
            text = text.replace('<a class="reference external"',
                                '<a class="reference external" target="_blank"')

        # Make a link for doconce citation in copyright
        if '. Made with DocOnce' in text:
            text = text.replace('. Made with DocOnce', '')
            text = text.replace('      Created using <a href="https://sphinx-doc.org/">Sphinx', '      Created using <a href="https://github.com/hplgit/doconce">DocOnce</a> and <a href="https://sphinx-doc.org/">Sphinx')
        # Remove (1), (2), ... numberings in identical headings
        headings_wno = re.findall(r'(?<=(\d|"))>([^>]+?)          \((\d+)\)<', text)
        for dummy, heading, no in headings_wno:
            heading = heading.strip()
            text = re.sub(r'>%s +\(%d\)<' %
                          (re.escape(heading), int(no)),
                          '>%s<' % heading, text)
            text = re.sub(r'title="%s +\(%d\)"' %
                          (re.escape(heading), int(no)),
                          r'title="%s"' % heading, text)

        if os.path.isfile(filename + '.old~~'):
            os.remove(filename + '.old~~')
        f = open(filename, 'w'); f.write(text); f.close()
        if text != text_orig:
            logging.info('edit: %s' % filename)
    os.chdir('../../')
    print('\n\ngoogle-chrome sphinx-rootdir-math/_build/html/index.html\n')

else:
    # Add directory for RunestoneInteractive book
    use_runestonebooks_style = True  # False: use user-chosen style
    print("""

create RunestoneInteractive directory
""")
    sys.path.insert(0, os.curdir)
    import conf as source_dir_conf  # read data from conf.py

    if not os.path.isdir('RunestoneTools'):
        system('git clone https://github.com/RunestoneInteractive/RunestoneComponents.git')
    os.chdir('RunestoneComponents')
    logging.info('creating RunestoneInteractive directory')

    # Edit conf.py
    # This one does not work anymore: run runestone init instead,
    print('RunestoneInteractive has recently changed its setup - must abort')
    sys.exit(1)
    # it's the file runestone/__main__.py and function init()
    # Need to build a bash script that runs the command and feeds the answers
    # See also https://github.com/RunestoneInteractive/RunestoneComponents
    f = open('conf.py.prototype', 'r');  text = f.read();  f.close()
    text = text.replace('<ENTER YOUR PROJECT NAME HERE>', source_dir_conf.project)
    text = text.replace('<INSERT YOUR PROJECT NAME HERE>', source_dir_conf.project)
    text = text.replace('<ENTER YOUR COPYRIGHT NOTICE HERE>', source_dir_conf.copyright)
    text = text.replace('<INSERT YOUR PROJECT NAME OR OTHER TITLE HERE>', source_dir_conf.project)
    text = text.replace('<INSERT YOUR PROJECT NAME OR OTHER SHORT TITLE HERE>', source_dir_conf.project)
    text = text.replace('html_theme_path = ["_templates"]', 'html_theme_path = ["_templates", "../_themes"]')
    if not use_runestonebooks_style:
        text = text.replace("html_theme = 'sphinx_bootstrap'", "html_theme = '%s'" % source_dir_conf.html_theme)
        text = re.sub(r'html_theme_options = \{.+?\}', 'html_theme_options = ' + str(source_dir_conf.html_theme_options) if hasattr(source_dir_conf, 'html_theme_options') else 'html_theme_options = {}', text, flags=re.DOTALL)
    f = open('conf.py', 'w');  f.write(text);  f.close()

    # Copy .rst files from sphinx dir
    rst_files = [os.path.join(os.pardir, 'index.rst')] + glob.glob(os.path.join(os.pardir, '*.rst')) + glob.glob(os.path.join(os.pardir, '._*.rst'))
    for filename in rst_files:
        print('copying', filename, 'to _sources')
        logging.info('copy: %s to _sources' % filename)
        shutil.copy(filename, '_sources')
    print('*** running paver build to build the RunestoneInteractive book')
    logging.info('running paver build to create the RunestoneInteractive book')
    system('paver build')

    print('\n\ngoogle-chrome sphinx-rootdir-math/RunestoneTools/build/index.html')

************** File: .testdoc_html_file_collection *****************
testdoc.html
../doc/src/manual/fig/wave1D.png
../doc/src/manual/mov/wave_frames/frame_0080.png
../doc/src/manual/mov/wave_frames/frame_0085.png
../doc/src/manual/mov/wave_frames/frame_0090.png
../doc/src/manual/mov/wave_frames/frame_0095.png
../doc/src/manual/mov/wave_frames/frame_0100.png
../doc/src/manual/mov/wave_frames/frame_0105.png
testdoc.do.txt
._testdoc000.html
._testdoc001.html
._testdoc002.html
._testdoc003.html

************** File: make.sh *****************
#!/bin/bash -x
set -x
#export PS4='+ l.${LINENO}: ${FUNCNAME[0]:+${FUNCNAME[0]}(): }'
function system {
  "$@"
  if [ $? -ne 0 ]; then
    echo -e "\nmake.sh: unsuccessful command $@"
    echo "abort!"
    exit 1
  fi
}

rm -rf html_images reveal.js downloaded_figures latex_styles

# Note:  --examples_as_exercises is required to avoid abortion

# Make publish database
rm -rf papers.pub  venues.list # clean

publish import refs1.bib <<EOF
1
2
EOF
if [ $? -ne 0 ]; then echo "make.sh: abort"; exit 1; fi

publish import refs2.bib <<EOF
2
2
EOF
# Simulate that we get new data, which is best put
# in a new file
publish import refs3.bib <<EOF
1
2
y
1
EOF

system doconce spellcheck -d .dict4spell.txt _testdoc.do.txt

ex="--examples_as_exercises"
rawgit="--html_raw_github_url=raw.github"

system doconce jupyterbook testdoc --show_titles --sep=section --dest=$PWD --dest_toc=$PWD $ex --allow_refs_to_external_docs

system doconce jupyterbook testdoc --show_titles --sep=section --sep_section=subsection --titles=README $ex --allow_refs_to_external_docs 

system doconce jupyterbook testdoc --show_titles --sep=section --sep_section=subsection --dest=$PWD --dest_toc=$PWD $ex --allow_refs_to_external_docs

system doconce format html testdoc --wordpress  $ex --html_exercise_icon=question_blue_on_white1.png --html_exercise_icon_width=80 --figure_prefix="https://raw.github.com/hplgit/doconce/master/test/" --movie_prefix="https://raw.github.com/hplgit/doconce/master/test/" --html_links_in_new_window --cite_doconce $rawgit

cp testdoc.html testdoc_wordpress.html

system doconce format html testdoc --without_answers --without_solutions $ex -DSOMEVAR --html_exercise_icon=default --solutions_at_end --html_share=https://cyber.space.com/specials,twitter,print,google+,facebook,linkedin $rawgit
system doconce format html testdoc --without_answers --without_solutions $ex --html_exercise_icon=default --answers_at_end --solutions_at_end --html_share=https://cyber.space.com/specials,twitter,print,google+,facebook,linkedin $rawgit

system doconce split_html testdoc.html --method=space10
cp testdoc.html testdoc_no_solutions.html

system doconce format html testdoc $ex  # just produce the mako file
doconce extract_exercises tmp_mako__testdoc.do.txt --exercise_numbering=section --filter=ipynb

system doconce format latex testdoc --without_answers --without_solutions $ex -DSOMEVAR --sections_down --number_all_equations --latex_packages=varioref --cite_doconce
cp testdoc.p.tex testdoc_no_solutions.p.tex

cp ../bundled/html_styles/style_vagrant/template_vagrant.html .
system doconce format html testdoc.do.txt $ex --html_style=bootstrap --html_template=template_vagrant.html --html_toc_indent=0 --toc_depth=2 $rawgit
cp testdoc.html testdoc_vagrant.html
# Test that a split of testdoc_vagrant.html becomes correct
doconce split_html testdoc_vagrant.html --method=split

system doconce apply_inline_edits testdoc.do.txt
system doconce format html testdoc.do.txt --pygments_html_linenos --html_style=solarized --pygments_html_style=emacs $ex --html_exercise_icon=exercise1.svg $rawgit

system doconce remove_exercise_answers testdoc.html
system doconce html_colorbullets testdoc.html
system doconce split_html testdoc.html --nav_button=gray2,bottom --font_size=slides

system doconce format html testdoc.do.txt --pygments_html_linenos --html_style=solarized --pygments_html_style=emacs $ex --html_output=demo_testdoc $rawgit

system doconce format latex testdoc.do.txt $ex SOMEVAR=True --skip_inline_comments --latex_packages=varioref

# Test lst with external and internal styles
system doconce format pdflatex testdoc.do.txt $ex "--latex_code_style=default:lst-blue1[style=myspeciallststyle,numbers=left,numberstyle=\\tiny,stepnumber=3,numbersep=15pt,xleftmargin=1mm]@fcod:vrb-gray@sys:vrb[frame=lines,label=\\fbox{{\\tiny Terminal}},framesep=2.5mm,framerule=0.7pt]" --latex_code_lststyles=mylststyles --latex_packages=varioref

# Issue #9: removed "style=redblue"
cp testdoc.tex testdoc.tex_direct

system doconce format pdflatex testdoc.do.txt --device=paper $ex --latex_double_hyphen --latex_index_in_margin --latex_no_program_footnotelink --latex_title_layout=titlepage --latex_papersize=a4 --latex_colored_table_rows=blue --latex_fancy_header --latex_section_headings=blue --latex_labels_in_margin --latex_double_spacing --latex_todonotes --latex_list_of_exercises=loe --latex_font=palatino --latex_packages=varioref '--latex_link_color=blue!90' --draft
# --latex_paper=a4 triggers summary environment to be smaller paragraph
# within the text (fine for proposals or articles).

# Drop the table exercise toc since we want to test loe above
#system doconce latex_exercise_toc testdoc

# doconce replace does not work well with system bash func above without quotes
doconce replace 'vspace{1cm} % after toc' 'clearpage % after toc' testdoc.p.tex
# can drop usepackage{theorem} since we have user-defined envir with amsthm
doconce subst '(newtheorem{example}.*)' '\g<1>\n\\newtheorem{theorem}{Theorem}[section]' testdoc.p.tex

doconce subst '\\paragraph\{Theorem \d+\.\}' '' testdoc.p.tex
doconce replace '% begin theorem' '\begin{theorem}' testdoc.p.tex
doconce replace '% end theorem' '\end{theorem}' testdoc.p.tex
# because of --latex-double-hyphen:
doconce replace Newton--Cotes Newton-Cotes testdoc.p.tex
doconce replace --examples_as__exercises $ex testdoc.p.tex

# Does not work in python 3
PYTHON_VERSION=$(python -V 2>&1 | grep -Po '(?<=Python )(.+)')
parsedVersion=$(echo "${PYTHON_VERSION//./}")
if [ "$parsedVersion" -lt "300" ]
then
	system ptex2tex -DMINTED testdoc
fi

# test that pdflatex works
rm -f *.aux
system pdflatex -shell-escape testdoc
pdflatex -shell-escape testdoc
makeindex testdoc
bibtex testdoc
pdflatex -shell-escape testdoc
pdflatex -shell-escape testdoc
pdflatex -shell-escape testdoc

cp testdoc.tex testdoc_bigex.tex
cp testdoc.pdf testdoc_bigex.pdf

system doconce ptex2tex testdoc "sys=\begin{Verbatim}[frame=lines]@\end{Verbatim}" pypro=ans:nt envir=minted > testdoc.tex_doconce_ptex2tex
echo "----------- end of doconce ptex2tex output ----------------" >> testdoc.tex_doconce_ptex2tex
cat testdoc.tex >> testdoc.tex_doconce_ptex2tex
# Test that latex can treat this file
rm -f *.aux
system pdflatex -shell-escape testdoc

# Test stand-alone exercises
system doconce format plain testdoc --exercises_in_zip $ex
rm -rf standalone_exercises
unzip testdoc_exercises.zip

# Test prefix
system doconce format html testdoc --code_prefix=https://raw.githubusercontent.com/hplgit/doconce/master/test --html_output=testdoc_code_prefix $ex

system doconce format plain testdoc.do.txt $ex -DSOMEVAR=1 --tables2csv
system doconce format st testdoc.do.txt $ex

system doconce format sphinx testdoc $ex --html_links_in_new_window
cp testdoc.rst testdoc.sphinx.rst
system doconce split_rst testdoc
# Problem reproducible after: `git clean -fd && rm -rf sphinx-testdoc`
#Hack: because doconce sphinx_dir ony works the second time (after an error), trigger that error by creating a bogus conf.py in ./
touch conf.py 
system doconce sphinx_dir dirname='sphinx-testdoc' version=0.1 theme=agni testdoc
cp automake_sphinx.py automake_sphinx_testdoc.py 
system python automake_sphinx.py
cp sphinx-testdoc/conf.py testdoc_sphinx_conf.py
cp sphinx-testdoc/index.rst testdoc_sphinx_index.rst


system doconce format rst testdoc.do.txt $ex --rst_mathjax

system doconce format epytext testdoc.do.txt $ex
system doconce format pandoc testdoc.do.txt $ex
system doconce format mwiki testdoc.do.txt $ex
system doconce format cwiki testdoc.do.txt $ex
system doconce format ipynb testdoc.do.txt $ex
system doconce format matlabnb testdoc.do.txt $ex

# Test mako variables too
system doconce format gwiki testdoc.do.txt --skip_inline_comments MYVAR1=3 MYVAR2='a string' $ex

# Test pandoc: from latex to markdown, from markdown to html
system doconce format latex testdoc.do.txt $ex --latex_title_layout=std --latex_packages=varioref
system doconce ptex2tex testdoc

#doconce subst -s 'And here is a system of equations with labels.+?\\section' '\\section' testdoc.tex
# pandoc cannot work well with \Verb, needs \verb
system doconce replace '\Verb!' '\verb!' testdoc.tex
# pandoc v 10 does not handle a couple of the URLs
doconce replace '%E2%80%93' '' testdoc.tex
doconce replace '+%26+' '' testdoc.tex

#system pandoc -f latex -t markdown -o testdoc.md testdoc.tex
#system pandoc -f markdown -t html -o testdoc_pnd_l2h.html --mathjax -s testdoc.md
#pandoc -v >> testdoc_pnd_l2h.html

system doconce format pandoc testdoc.do.txt $ex
#system pandoc -t html -o testdoc_pnd_d2h.html --mathjax -s testdoc.md
#pandoc -v >> testdoc_pnd_d2h.html

# Test slides
# slides1: rough small test
# slides2: much of scientific_writing.do.txt
# slides3: equal to slides/demo.do.txt

system doconce format html slides1 --pygments_html_style=perldoc --keep_pygments_html_bg $rawgit
cp slides1.html slides1_1st.html  # before running slides_html

system doconce slides_html slides1 reveal --html_slide_themee=simple

cp slides1.html slides1_reveal.html
/bin/ls -R reveal.js >> slides1_reveal.html

system doconce format html slides1 --pygments_html_style=emacs --keep_pygments_html_bg $rawgit
system doconce slides_html slides1 deck --html_slide_theme=web-2.0

cp slides1.html slides1_deck.html
/bin/ls -R deck.js >> slides1_deck.html

system doconce format markdown slides1 --github_md --pygments_html_style=emacs
system doconce slides_markdown slides1 remark --slide_theme=light
cp slides1.html slides1_remark.html

# The toughest test of slides1 is with minted code envir
rm -f *.aux
system doconce format pdflatex slides1 --latex_title_layout=beamer --latex_code_style=pyg --cite_doconce
system doconce slides_beamer slides1 --beamer_slide_theme=blue_shadow --handout
system pdflatex -shell-escape slides1
cp slides1.tex slides1_handout.tex
cp slides1.pdf slides1_handout.pdf

# Ordinary beamer slides (not handout)
system doconce format pdflatex slides1 --latex_title_layout=beamer "--latex_code_style=default:lst[style=yellow2_fb]"
system doconce slides_beamer slides1 --beamer_slide_theme=blue_shadow
system pdflatex -shell-escape slides1

doconce format html slides2 --pygments_html_style=emacs $rawgit --no_abort
system doconce slides_html slides2 reveal --html_slide_theme=beigesmall
cp slides2.html slides2_reveal.html

rm -f *.aux
system doconce format pdflatex slides2 --latex_title_layout=beamer -DBEAMER --no_abort
system doconce ptex2tex slides2 envir=minted
system doconce slides_beamer slides2

system doconce format html slides3 --pygments_html_style=emacs SLIDE_TYPE=reveal SLIDE_THEME=beigesmall $rawgit
system doconce slides_html slides3 reveal --html_slide_type=beigesmall
cp slides3.html slides3_reveal.html

system doconce format html slides3 --html_style=solarized3 SLIDE_TYPE=doconce SLIDE_THEME=solarized3 --html_output=slides3-solarized3 $rawgit
system doconce slides_html slides3-solarized3 doconce --nav_button=bigblue,bottom --font_size=slides

rm -f *.aux
theme=red_plain
system doconce format pdflatex slides3 SLIDE_TYPE=beamer SLIDE_THEME=$theme --latex_title_layout=beamer
system doconce ptex2tex slides3 envir=minted
system doconce slides_beamer slides3 --beamer_slide_theme=$theme

system doconce format html slides1 --pygments_html_style=emacs $rawgit
system doconce slides_html slides1 all

# Test grab
system doconce grab --from- '={5} Subsection 1' --to 'subroutine@' _testdoc.do.txt > testdoc.tmp
doconce grab --from 'Compute a Probability' --to- 'drawing uniformly' _testdoc.do.txt >> testdoc.tmp
doconce grab --from- '\*\s+\$.+normally' _testdoc.do.txt >> testdoc.tmp

# Test html templates
system doconce format html html_template --html_template=template1.html --pygments_html_style=none $rawgit
cp html_template.html html_template1.html

system doconce format html html_template --html_template=template_inf1100.html  --pygments_html_style=emacs $rawgit

# Test author special case and generalized references
system doconce format html author1 $rawgit
system doconce format latex author1
system doconce format sphinx author1
system doconce format plain author1

# Test journal styles
system doconce format pdflatex author2 --latex_style=siamltex
system doconce ptex2tex author2
cp author2.tex author2_siamltex.tex
system doconce format pdflatex author2 --latex_style=elsevier
system doconce ptex2tex author2
cp author2.tex author2_elsevier.tex

# Test notebook conversions
cp ../doc/src/ipynb/example.do.txt nbdemo.do.txt
doconce replace 'fig/oscillator_general' '../doc/src/ipynb/fig/oscillator_general' nbdemo.do.txt
doconce format ipynb nbdemo
doconce ipynb2doconce nbdemo.ipynb

# Test math
rm -f *.aux
name=math_test
doconce format pdflatex $name --no_abort
doconce ptex2tex $name
pdflatex $name
system doconce format html $name $rawgit --no_abort
cp $name.html ${name}_html.html
doconce format sphinx $name --no_abort
doconce sphinx_dir dirname=sphinx-rootdir-math $name
cp automake_sphinx.py automake_sphinx_math_test.py
python automake_sphinx.py
doconce format pandoc $name --no_abort
# Do not use pandoc directly because it does not support MathJax sufficiently well
doconce md2html $name.md --no_abort
cp $name.html ${name}_pandoc.html
doconce format pandoc $name --no_abort
doconce md2latex $name

# Test all types of copyright syntax
python test_copyright.py  # results in test_copyright.out

# Test tailored conf.py file
system doconce format sphinx copyright COPYRIGHT='{copyright,date}' BOOK=False
system doconce split_rst copyright
system doconce sphinx_dir short_title="Really short title" conf.py=myconf.py copyright
system python automake_sphinx.py
cp sphinx-rootdir/conf.py tailored_conf.py

# Test admonitions

# LaTeX admon styles
admon_tps="colors1 mdfbox paragraph-footnotesize graybox2 yellowicon grayicon colors2"
for admon_tp in $admon_tps; do
color=
opts=
if [ $admon_tp = 'mdfbox' ]; then
   color="--latex_admon_color=warning:darkgreen!40!white;notice:darkgray!20!white;summary:tucorange!20!white;question:red!50!white;block:darkgreen!40!white"
   opts=--no_abort
elif [ $admon_tp = 'grayicon' ]; then
   color="--latex_admon_color=gray!20"
elif [ $admon_tp = 'graybox2' ]; then
   opts=--no_abort
fi
system doconce format pdflatex admon --latex_admon=$admon_tp $color $opts --latex_code_style=lst --cite_doconce
cp admon.tex admon_${admon_tp}.tex
# Make a substitution to fix a problem with `pdflatex admon_colors1`
doconce subst '\\\\paragraph{Hint.}\\n' '\paragraph{Hint.}' admon_${admon_tp}.tex

system pdflatex admon_${admon_tp}
echo "admon=$admon_tp"
if [ -d latex_figs ]; then
    echo "latex_figs:"
    /bin/ls latex_figs
else
    echo "no latex_figs directory for this admon type"
fi
rm -rf latex_figs
done

# Test different code envirs inside admons
doconce format pdflatex admon --latex_admon=mdfbox --latex_admon_color=1,1,1 --latex_admon_envir_map=2 --cite_doconce --no_abort
doconce ptex2tex admon pycod2=minted pypro2=minted pycod=Verbatim pypro=Verbatim
cp admon.tex admon_double_envirs.tex
rm -rf latex_figs

# Test HTML admon styles
system doconce format html admon --html_admon=lyx --html_style=blueish2 --cite_doconce $rawgit
cp admon.html admon_lyx.html

system doconce format html admon --html_admon=paragraph --html_style=blueish2 --cite_doconce $rawgit
cp admon.html admon_paragraph.html

system doconce format html admon --html_admon=colors --cite_doconce $rawgit
cp admon.html admon_colors.html

system doconce format html admon --html_admon=gray --html_style=blueish2 --html_admon_shadow --html_box_shadow --cite_doconce $rawgit
cp admon.html admon_gray.html

system doconce format html admon --html_admon=yellow --html_admon_shadow --html_box_shadow --cite_doconce $rawgit
cp admon.html admon_yellow.html

system doconce format html admon --html_admon=apricot --html_style=solarized --cite_doconce $rawgit
cp admon.html admon_apricot.html

system doconce format html admon --html_style=bootstrap --pygments_html_style=default --html_template=template_vagrant.html --cite_doconce $rawgit
cp admon.html admon_vagrant.html

system doconce format html admon --html_style=bootstrap --pygments_html_style=default --html_admon=bootstrap_alert --cite_doconce "--html_bootstrap_navbar_links=Google|https://google.com;DocOnce formats|https://hplgit.github.io/teamods/writing_reports/index.html" $rawgit
cp admon.html admon_bootstrap_alert.html
doconce split_html admon_bootstrap_alert.html --pagination --nav_button=top+bottom

system doconce format html admon --html_style=bootswatch --pygments_html_style=default --html_admon=bootstrap_panel --cite_doconce $rawgit
cp admon.html admon_bootswatch_panel.html

system doconce sphinx_dir dirname=tmp_admon admon
system python automake_sphinx.py
rm -rf admon_sphinx
cp -r tmp_admon/_build/html admon_sphinx

system doconce format mwiki admon --cite_doconce
cp admon.mwiki admon_mwiki.mwiki

system doconce format plain admon --cite_doconce
cp admon.txt admon_paragraph.txt

cp -fr admon_*.html admon_*.pdf admon_*.*wiki admon_*.txt ._admon_*.html admon_sphinx admon_demo/
cd admon_demo
doconce replace '../doc/src/manual/fig/wave1D' '../../doc/src/manual/fig/wave1D' *.html .*.html
rm -rf *~
cd ..


#google-chrome admon_*.html
#for pdf in admon_*.pdf; do evince $pdf; done

if [ -d latex_figs ]; then
    echo "BUG: latex_figs was made by some non-latex format..."
fi

# Test Bootstrap HTML styles
system doconce format html test_boots --html_style=bootswatch_journal --pygments_html_style=default --html_admon=bootstrap_panel --html_code_style=inherit $rawgit
doconce split_html test_boots.html

# Test GitHub-extended Markdown
system doconce format pandoc github_md.do.txt --github_md

# Test Markdown input
doconce format html markdown_input.do.txt --markdown --md2do_output=mdinput2do.do.txt $rawgit

# Test movie handling
name=movies
system doconce format html $name --html_output=movies_3choices $rawgit
cp movies_3choices.html movie_demo
system doconce format html $name --no_mp4_webm_ogg_alternatives $rawgit
cp movies.html movie_demo

rm -f $name.aux
system doconce format pdflatex $name --latex_movie=media9
system doconce ptex2tex $name
system pdflatex $name
pdflatex $name
cp $name.pdf movie_demo/${name}_media9.pdf
cp $name.tex ${name}_media9.tex

system doconce format pdflatex $name --latex_movie=media9 --latex_external_movie_viewer
system doconce ptex2tex $name
system pdflatex $name
cp $name.pdf movie_demo/${name}_media9_extviewer.pdf

# multimedia (beamer \movie command) does not work well
#rm $name.aux

rm -f $name.aux
system doconce format pdflatex $name
system doconce ptex2tex $name
system pdflatex $name
cp $name.pdf movie_demo

system doconce format plain movies

# Test locale support for html and pdflatex
doconce format html locale --html_style=bootstrap_FlatUI --language=Norwegian --encoding=utf-8
doconce format pdflatex locale --latex_code_style=vrb --language=Norwegian --encoding=utf-8
# locale does not exist
#pdflatex locale
#makeindex locale
#pdflatex locale
#pdflatex locale

cd Springer_T2
bash -x make.sh
cd ..

doconce subst -m '^.*? (AM|PM) - ' '' automake_sphinx.log

# Status movies: everything works in html and sphinx, only href works
# in latex, media9 is unreliable

# Test encoding: guess and change
doconce format html encoding1   --no_header_footer $rawgit
system doconce guess_encoding encoding1.do.txt > tmp_encodings.txt
cp encoding1.do.txt tmp1.do.txt
system doconce change_encoding utf-8 latin1 tmp1.do.txt
system doconce guess_encoding tmp1.do.txt >> tmp_encodings.txt
system doconce change_encoding latin1 utf-8 tmp1.do.txt
system doconce guess_encoding tmp1.do.txt >> tmp_encodings.txt
system doconce guess_encoding encoding2.do.txt >> tmp_encodings.txt
cp encoding1.do.txt tmp2.do.txt
system doconce change_encoding utf-8 latin1 tmp2.do.txt
doconce guess_encoding tmp2.do.txt >> tmp_encodings.txt

# Handle encoding problems (and test debug output too)
# Plain ASCII with Norwegian chars printed as is (and utf8 package mode)
doconce format latex encoding3 --debug --no_header_footer
cp encoding3.p.tex encoding3.p.tex-ascii
# Plain ASCII text with Norwegian chars coded as &#...;
doconce format html encoding3 --pygments_html_style=off --debug --no_header_footer $rawgit
cp encoding3.html encoding3.html-ascii
cat _doconce_debugging.log >> encoding3.html-ascii

# Plain ASCII with verbatim blocks with Norwegian chars
doconce format latex encoding3 -DPREPROCESS --no_header_footer  # preprocess handles utf-8
cp encoding3.p.tex encoding3.p.tex-ascii-verb
doconce format html encoding3 -DPREPROCESS --no_header_footer  $rawgit # html fails with utf-8 in !bc
# Unicode with Norwegian chars in plain text and verbatim blocks
doconce format html encoding3 -DPREPROCESS  --encoding=utf-8  --pygments_html_style=none --debug --no_header_footer $rawgit # Keeps Norwegian chars since output is in utf-8
cp encoding3.html encoding3.html-ascii-verb
cat _doconce_debugging.log >> encoding3.html-ascii-verb

doconce format latex encoding3 -DMAKO --no_header_footer  # mako fails due to Norwegian chars
# Unicode with Norwegian chars in plain text and verbatim blocks
doconce format latex encoding3 -DMAKO --encoding=utf-8 --no_header_footer  # utf-8 and unicode
cp encoding3.p.tex encoding3.p.tex-utf8
doconce format html encoding3 -DMAKO --encoding=utf-8 --pygments_html_style=off --debug --no_header_footer $rawgit
cp encoding3.html encoding3.html-utf8
cat _doconce_debugging.log >> encoding3.html-utf8

# Test mako problems
system doconce format html mako_test1 --pygments_html_style=off  --no_header_footer $rawgit  # mako variable only, no % lines
system doconce format html mako_test2 --pygments_html_style=off  --no_header_footer $rawgit  # % lines inside code, but need for mako
system doconce format html mako_test3 --pygments_html_style=off  --no_header_footer $rawgit  # % lines inside code
cp mako_test3.html mako_test3b.html
system doconce format html mako_test3 --pygments_html_style=none  --no_header_footer $rawgit # no problem message
system doconce format html mako_test4 --pygments_html_style=no  --no_header_footer $rawgit   # works fine, lines start with %%

system doconce csv2table testtable.csv > testtable.do.txt

# Test doconce ref_external command
sh -x genref.sh

# Test error detection (note: the sequence of the error tests is
# crucial: an error must occur, then corrected before the next
# one will occur!)
cp failures.do.txt tmp2.do.txt
doconce format plain tmp2.do.txt
doconce replace '`myfile.py` file' '`myfile.py`' tmp2.do.txt
doconce format plain tmp2
doconce subst 'failure\}\n\n!bc' 'failure}\n\nHello\n!bc' tmp2.do.txt
doconce format sphinx tmp2.do.txt
doconce replace '!bsubex' '' tmp2.do.txt
doconce format sphinx tmp2.do.txt
doconce replace '# Comment before list' '' tmp2.do.txt
doconce format sphinx tmp2
doconce replace '\idx' 'idx' tmp2.do.txt
doconce replace '\cite' 'cite' tmp2.do.txt
doconce format rst tmp2
doconce subst -s '__Paragraph before.+!bc' '!bc' tmp2.do.txt
doconce format rst tmp2
doconce replace '\label' 'label' tmp2.do.txt
doconce replace 'wave1D width' 'wave1D,  width' tmp2.do.txt
doconce format sphinx tmp2
doconce replace 'doc/manual' 'doc/src/manual' tmp2.do.txt
doconce format sphinx tmp2
doconce replace '../lib/doconce/doconce.py' '_static/doconce.py' tmp2.do.txt
doconce replace 'two_media99' 'two_media' tmp2.do.txt
doconce format html tmp2 $rawgit
doconce replace '|--l---|---l---|' '|--l-------l---|' tmp2.do.txt
doconce format html tmp2 $rawgit
doconce replace '99x9.ogg' '.ogg' tmp2.do.txt
doconce format html tmp2 $rawgit
doconce subst -s -m '^!bsol.+?!esol' ''  tmp2.do.txt
doconce format sphinx tmp2
doconce subst -s -m '^!bhint.+?!ehint' ''  tmp2.do.txt
doconce format sphinx tmp2
doconce format pdflatex tmp2 --device=paper
# Remedy: drop paper and rewrite, just run electronic
doconce format pdflatex tmp2
#doconce replace '# Comment before math is ok' '' tmp2.do.txt
echo
echo "When we reach this point in the script,"
echo "it is clearly a successful run of all tests!"
echo "Check the generated test.v file with e.g.: "
echo "meld test.r test.v"
echo "To remove untracked files run: "
echo "cd .. & git clean -f -d"

************** File: math_test.do.txt *****************
TITLE: How various formats can deal with LaTeX math
AUTHOR: Hans Petter Langtangen at Simula Research Laboratory & University of Oslo
DATE: today

__Summary.__
The purpose of this document is to test LaTeX math in DocOnce with
various output formats.  Most LaTeX math constructions are renedered
correctly by MathJax in plain HTML, but some combinations of
constructions may fail.  Unfortunately, only a subset of what works in
html MathJax also works in sphinx MathJax. The same is true for
markdown MathJax expresions (e.g., Jupyter notebooks).  Tests and
examples are provided to illustrate what may go wrong.

The recommendation for writing math that translates to MathJax in
html, sphinx, and markdown is to stick to the environments `\[
... \]`, `equation`, `equation*`, `align`, `align*`, `alignat`, and
`alignat*` only. Test the math with sphinx output; if it works in that
format, it should work elsewhere too.

The current version of the document is translated from DocOnce source
to the format _${FORMAT}_.

======= Test of equation environments =======

===== Test 1: Inline math =====

We can get an inline equation
`$u(t)=e^{-at}$` rendered as $u(t)=e^{-at}$.

===== Test 2: A single equation with label =====

An equation with number,

!bc latexcod
|bt
\begin{equation} u(t)=e^{-at} label{eq1a}\end{equation}
|et
!ec
looks like

!bt
\begin{equation} u(t)=e^{-at} label{_eq1a}\end{equation}
!et
Maybe this multi-line version is what we actually prefer to write:

!bc latexcod
|bt
\begin{equation}
u(t)=e^{-at}
label{eq1b}
\end{equation}
|et
!ec
The result is the same:

!bt
\begin{equation}
u(t)=e^{-at} label{_eq1b}
\end{equation}
!et
We can refer to this equation through its label `eq1b`: (ref{_eq1b}).


===== Test 3: Multiple, aligned equations without label and number =====

MathJax has historically had some problems with rendering many LaTeX
math environments, but the `align*` and `align` environments have
always worked.

!bc latexcod
|bt
\begin{align*}
u(t)&=e^{-at}\\
v(t) - 1 &= \frac{du}{dt}
\end{align*}
|et
!ec
Result:

!bt
\begin{align*}
u(t)&=e^{-at}\\
v(t) - 1 &= \frac{du}{dt}
\end{align*}
!et

===== Test 4: Multiple, aligned equations with label =====

Here, we use `align` with user-prescribed labels:

!bc latexcod
|bt
\begin{align}
u(t)&=e^{-at}
label{eq2b}\\
v(t) - 1 &= \frac{du}{dt}
label{eq3b}
\end{align}
|et
!ec
Result:

!bt
\begin{align}
u(t)&=e^{-at}
label{_eq2b}\\
v(t) - 1 &= \frac{du}{dt}
label{_eq3b}
\end{align}
!et
We can refer to the last equations as the system (ref{_eq2b})-(ref{_eq3b}).

# #if FORMAT == "sphinx"
!bwarning Note: align/alignat environments with labels are anti-aligned in sphinx!
Actually, *sphinx does not support the align environment with labels*,
such as we write above,
but DocOnce splits in this case the equations into separate, single equations
with labels. Hence the user can write one code with align and labels
and have it automatically
to work in latex, html, sphinx, notebooks, and other formats.
The generated sphinx code in the present case is

!bc rst
.. math::
   :label: eq2b

        u(t)=e^{-at}


.. math::
   :label: eq3b

        v(t) - 1 = \frac{du}{dt}

!ec
!ewarning

If DocOnce had not rewritten the equation it would be rendered in
${FORMAT} as nicely aligned equations without numbers (i.e., as if
we had used the `align*` environment):

## NOTE: These math blocks, not inside !bt-!et directives will result
## in error messages from DocOnce. But if we neglect them, the code works
## as intended.

.. math::

        \begin{align}
        u(t)&=e^{-at}
        \label{__eq2b}\\
        v(t) - 1 &= \frac{du}{dt}
        \label{__eq3b}
        \end{align}
# #endif



===== Test 5: Multiple, aligned equations without label =====

In LaTeX, equations within an `align` environment is automatically
given numbers.  To ensure that an html document with MathJax gets the
same equation numbers as its latex/pdflatex companion, DocOnce
generates labels in equations where there is no label prescribed. For
example,

!bc latexcod
|bt
\begin{align}
u(t)&=e^{-at}
\\
v(t) - 1 &= \frac{du}{dt}
\end{align}
|et
!ec
is edited to something like

!bc latexcod
|bt
\begin{align}
u(t)&=e^{-at}
label{_auto5}\\
v(t) - 1 &= \frac{du}{dt}
label{_auto6}
\end{align}
|et
!ec
and the output gets the two equation numbered.
# #if FORMAT == "sphinx"
Note that in sphinx the alignment is removed and separate `equation`
environments are used to get numbered equations in equation systems, cf. the
box above.
# #endif

!bt
\begin{align}
u(t)&=e^{-at}\\
v(t) - 1 &= \frac{du}{dt}
\end{align}
!et

===== Test 6: Multiple, aligned equations with multiple alignments =====

The `align` environment can be used with two `&` alignment characters, e.g.,

!bc latexcod
|bt
\begin{align}
\frac{\partial u}{\partial t} &= \nabla^2 u, & x\in (0,L),
\ t\in (0,T]\\
u(0,t) &= u_0(x), & x\in [0,L]
\end{align}
|et
!ec
The result in ${FORMAT} becomes

!bt
\begin{align}
\frac{\partial u}{\partial t} &= \nabla^2 u, & x\in (0,L),
\ t\in (0,T]\\
u(0,t) &= u_0(x), & x\in [0,L]
\end{align}
!et
# #if FORMAT == "sphinx"
In ${FORMAT}, all alignments are removed, so this double use of `&`
results in ugly typesetting!
# #endif

A better solution is usually to use an `alignat` environment:

!bc latexcod
|bt
\begin{alignat}{2}
\frac{\partial u}{\partial t} &= \nabla^2 u, & x\in (0,L),
\ t\in (0,T]\\
u(0,t) &= u_0(x), & x\in [0,L]
\end{alignat}
|et
!ec
with the rendered result

!bt
\begin{alignat}{2}
\frac{\partial u}{\partial t} &= \nabla^2 u, & x\in (0,L),
\ t\in (0,T]\\
u(0,t) &= u_0(x), & x\in [0,L]
\end{alignat}
!et

# #if FORMAT in ("sphinx", "ipynb")
!bwarning align/alignat environments with equation numbers are anti-aligned!
In the `sphinx`, `ipynb`, and `pandoc` output formats, DocOnce rewrites
the equations in an `alignat` environment as individual equations in
`equation` environments (or more precisely, `sphinx` can work with
`alignat*` so only numbered `alignat` equations get rewritten as individual
equations). If the alignment is somewhat important, try the best with a
manual rewrite in terms of separate `equation` environments, and stick to
`align*` and `alignat*` in `sphinx`.
!ewarning
# #endif

# #if FORMAT == "sphinx"
With `alignat*` in ${FORMAT}, the equations above are typeset nicely as

!bt
\begin{alignat*}{2}
\frac{\partial u}{\partial t} &= \nabla^2 u, & x\in (0,L),
\ t\in (0,T]\\
u(0,t) &= u_0(x), & x\in [0,L]
\end{alignat*}
!et
# #endif

# #if FORMAT in ("pandoc", "ipynb")
If DocOnce had not rewritten the above equations, they would be
rendered in ${FORMAT} as

$$
\begin{alignat}{2}
\frac{\partial u}{\partial t} &= \nabla^2 u, & x\in (0,L),
\ t\in (0,T]\\
u(0,t) &= u_0(x), & x\in [0,L]
\end{alignat}
$$
# #elif FORMAT in ("sphinx")
Note that if DocOnce had not rewritten of the above equations, they would be
rendered similarly in ${FORMAT} as

.. math::

        \begin{alignat}{2}
        \frac{\partial u}{\partial t} &= \nabla^2 u, & x\in (0,L),
        \ t\in (0,T]\\
        u(0,t) &= u_0(x), & x\in [0,L]
        \end{alignat}

That is, the equation numbers are gone.
# #endif




===== Test 7: Multiple, aligned eqnarray equations without label =====

Let us try the old `eqnarray*` environment.

!bc latexcod
|bt
\begin{eqnarray*}
u(t)&=& e^{-at}\\
v(t) - 1 &=& \frac{du}{dt}
\end{eqnarray*}
|et
!ec
which results in

!bt
\begin{eqnarray*}
u(t)&=& e^{-at}\\
v(t) - 1 &=& \frac{du}{dt}
\end{eqnarray*}
!et

===== Test 8: Multiple, eqnarrayed equations with label =====

Here we use `eqnarray` with labels:

!bc latexcod
|bt
\begin{eqnarray}
u(t)&=& e^{-at}
label{eq2c}\\
v(t) - 1 &=& \frac{du}{dt}
label{eq3c}
\end{eqnarray}
|et
!ec
which results in

!bt
\begin{eqnarray}
u(t)&=& e^{-at} label{_eq2c}\\
v(t) - 1 &=& \frac{du}{dt} label{_eq3c}
\end{eqnarray}
!et
Can we refer to the last equations as the system (ref{_eq2c})-(ref{_eq3c})
in the ${FORMAT} format?
# #if FORMAT == "sphinx"
No, unfortunately not. Sphinx cannot deal with equation numbers in
`eqnarray` environments and typeset them as if they were `eqnarray*`.
But MathJax supports `eqnarray` with labels.
The rule of thumb is to use `align` and not `eqnarray`!
# #endif

===== Test 9: The `multiline` environment with label and number =====

The LaTeX code

!bc latexcod
|bt
\begin{multline}
\int_a^b f(x)dx = \sum_{j=0}^{n} \frac{1}{2} h(f(a+jh) +
f(a+(j+1)h)) \\
=\frac{h}{2}f(a) + \frac{h}{2}f(b) + \sum_{j=1}^n f(a+jh)
label{multiline:eq1}
\end{multline}
|et
!ec
gets rendered as

!bt
\begin{multline}
\int_a^b f(x)dx = \sum_{j=0}^{n} \frac{1}{2} h(f(a+jh) +
f(a+(j+1)h)) \\
=\frac{h}{2}f(a) + \frac{h}{2}f(b) + \sum_{j=1}^n f(a+jh)
label{_multiline:eq1}
\end{multline}
!et
and we can hopefully refer to the Trapezoidal rule
as the formula (ref{_multiline:eq1}).

# #if FORMAT == "sphinx"
This equation will not render in sphinx unless we remove the `multiline`
environment, which means that it was typeset here without any multiline
information.
The best cross-format solution is to use `align` instead of `multiline`
with `\nonumber` in the first equation!
# #endif

===== Test 10: Splitting equations using a split environment =====

Although `align` can be used to split too long equations, a more obvious
command is `split`:

!bc latexcod
|bt
\begin{equation}
\begin{split}
\int_a^b f(x)dx = \sum_{j=0}^{n} \frac{1}{2} h(f(a+jh) +
f(a+(j+1)h)) \\
=\frac{h}{2}f(a) + \frac{h}{2}f(b) + \sum_{j=1}^n f(a+jh)
\end{split}
\end{equation}
|et
!ec

The result becomes

!bt
\begin{equation}
\begin{split}
\int_a^b f(x)dx = \sum_{j=0}^{n} \frac{1}{2} h(f(a+jh) +
f(a+(j+1)h)) \\
=\frac{h}{2}f(a) + \frac{h}{2}f(b) + \sum_{j=1}^n f(a+jh)
\end{split}
\end{equation}
!et

===== Test 11: Newcommands and boldface bm vs pmb =====

First we use the plain old pmb package for bold math. The formula

!bc latexcod
|bt
\[ \frac{\partial\u}{\partial t} +
\u\cdot\nabla\u = \nu\nabla^2\u -
\frac{1}{\varrho}\nabla p,\]
|et
!ec
and the inline expression `$\nabla\u (\x)\cdot\normalvec$`
(with suitable newcommands using pmb)
get rendered as

!bt
\[ \frac{\partial\u}{\partial t} +
\u\cdot\nabla\u = \nu\nabla^2\u -
\frac{1}{\varrho}\nabla p,\]
!et
and $\nabla\u (\x)\cdot\normalvec$.
# #if FORMAT == "sphinx"
DocOnce replaces newcommands by the actual latex code when requesting
the sphinx output format.
# #endif

Somewhat nicer fonts may appear with the more modern `\bm` command:

!bc latexcod
|bt
\[ \frac{\partial\ubm}{\partial t} +
\ubm\cdot\nabla\ubm = \nu\nabla^2\ubm -
\frac{1}{\varrho}\nabla p,\]
|et
!ec
(backslash `ubm` is a newcommand for bold math $u$), for which we get

!bt
\[ \frac{\partial\ubm}{\partial t} +
\ubm\cdot\nabla\ubm = \nu\nabla^2\ubm -
\frac{1}{\varrho}\nabla p.\]
!et
Moreover,

!bc
$\nabla\bm{u}(\bm{x})\cdot\bm{n}$
!ec
becomes $\nabla\bm{u}(\bm{x})\cdot\bm{n}$.

# #if FORMAT in ("html", "sphinx", "pandoc", "ipynb")
!bwarning
Note: for the ${FORMAT} format, `\bm` was substituted by DocOnce
to `\boldsymbol`.
!ewarning
# #endif


======= Problematic equations =======

Finally, we collect some problematic formulas in MathJax. They all work
fine in LaTeX. Most of them look fine in html too, but some fail in
sphinx, ipynb, or markdown.

===== Colored terms in equations =====

The LaTeX code

!bc latexcod
|bt
\[ {\color{blue}\frac{\partial\u}{\partial t}} +
\nabla\cdot\nabla\u = \nu\nabla^2\u -
\frac{1}{\varrho}\nabla p,\]
|et
!ec

results in

!bt
\[ {\color{blue}\frac{\partial\u}{\partial t}} +
\nabla\cdot\nabla\u = \nu\nabla^2\u -
\frac{1}{\varrho}\nabla p,\]
!et
# #if FORMAT in ('sphinx', 'ipynb')
but correct rendering in ${FORMAT} requires omitting the `\color` command:

!bt
\[ \frac{\partial\u}{\partial t} +
\nabla\cdot\nabla\u = \nu\nabla^2\u -
\frac{1}{\varrho}\nabla p,\]
!et
# #endif

===== Bar over symbols =====

Sometimes one must be extra careful with the LaTeX syntax to get sphinx MathJax
to render a formula correctly. Consider the combination of a bar over a
bold math symbol:

!bc latexcod
|bt
\[ \bar\f = f_c^{-1}\f,\]
|et
!ec

which for ${FORMAT} output results in

!bt
\[ \bar\f = f_c^{-1}\f.\]
!et

With sphinx, this formula is not rendered. However, using curly braces for the bar,

!bc latexcod
|bt
\[ \bar{\f} = f_c^{-1}\f,\]
|et
!ec

makes the output correct also for sphinx:

!bt
\[ \bar{\f} = f_c^{-1}\f,\]
!et


===== Matrix formulas =====

Here is an `align` environment with a label and the `pmatrix`
environment for matrices and vectors in LaTeX.

!bc latexcod
|bt
\begin{align}
\begin{pmatrix}
G_2 + G_3 & -G_3 & -G_2 & 0 \\
-G_3 & G_3 + G_4 & 0 & -G_4 \\
-G_2 & 0 & G_1 + G_2 & 0 \\
0 & -G_4 & 0 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
v_1 \\
v_2 \\
v_3 \\
v_4
\end{pmatrix}
+ \cdots
label{mymatrixeq}\\
\begin{pmatrix}
C_5 + C_6 & -C_6 & 0 & 0 \\
-C_6 & C_6 & 0 & 0 \\
0 & 0 & 0 & 0 \\
0 & 0 & 0 & 0
\end{pmatrix}
\frac{d}{dt} &=
\begin{pmatrix}
v_1 \\
v_2 \\
v_3 \\
v_4
\end{pmatrix} =
\begin{pmatrix}
0 \\
0 \\
0 \\
-i_0
\end{pmatrix}
\end{align}
|et
!ec

which becomes

!bt
\begin{align}
\begin{pmatrix}
G_2 + G_3 & -G_3 & -G_2 & 0 \\
-G_3 & G_3 + G_4 & 0 & -G_4 \\
-G_2 & 0 & G_1 + G_2 & 0 \\
0 & -G_4 & 0 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
v_1 \\
v_2 \\
v_3 \\
v_4
\end{pmatrix}
+ \cdots
label{_mymatrixeq}\\
\begin{pmatrix}
C_5 + C_6 & -C_6 & 0 & 0 \\
-C_6 & C_6 & 0 & 0 \\
0 & 0 & 0 & 0 \\
0 & 0 & 0 & 0
\end{pmatrix}
\frac{d}{dt} &=
\begin{pmatrix}
v_1 \\
v_2 \\
v_3 \\
v_4
\end{pmatrix} =
\begin{pmatrix}
0 \\
0 \\
0 \\
-i_0
\end{pmatrix}
\end{align}
!et
# #if FORMAT == 'ipynb'
The first equation do not render correctly in ipynb.
# #endif

The same matrices without labels in an `align*` environment:

!bc latexcod
|bt
\begin{align*}
\begin{pmatrix}
G_2 + G_3 & -G_3 & -G_2 & 0 \\
-G_3 & G_3 + G_4 & 0 & -G_4 \\
-G_2 & 0 & G_1 + G_2 & 0 \\
0 & -G_4 & 0 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
v_1 \\
v_2 \\
v_3 \\
v_4
\end{pmatrix}
+ \cdots \\
\begin{pmatrix}
C_5 + C_6 & -C_6 & 0 & 0 \\
-C_6 & C_6 & 0 & 0 \\
0 & 0 & 0 & 0 \\
0 & 0 & 0 & 0
\end{pmatrix}
\frac{d}{dt} &=
\begin{pmatrix}
v_1 \\
v_2 \\
v_3 \\
v_4
\end{pmatrix} =
\begin{pmatrix}
0 \\
0 \\
0 \\
-i_0
\end{pmatrix}
\end{align*}
|et
!ec

The rendered result becomes

!bt
\begin{align*}
\begin{pmatrix}
G_2 + G_3 & -G_3 & -G_2 & 0 \\
-G_3 & G_3 + G_4 & 0 & -G_4 \\
-G_2 & 0 & G_1 + G_2 & 0 \\
0 & -G_4 & 0 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
v_1 \\
v_2 \\
v_3 \\
v_4
\end{pmatrix}
+ \cdots \\
\begin{pmatrix}
C_5 + C_6 & -C_6 & 0 & 0 \\
-C_6 & C_6 & 0 & 0 \\
0 & 0 & 0 & 0 \\
0 & 0 & 0 & 0
\end{pmatrix}
\frac{d}{dt} &=
\begin{pmatrix}
v_1 \\
v_2 \\
v_3 \\
v_4
\end{pmatrix} =
\begin{pmatrix}
0 \\
0 \\
0 \\
-i_0
\end{pmatrix}
\end{align*}
!et

************** File: math_test.md *****************
% How various formats can deal with LaTeX math
% **Hans Petter Langtangen** at Simula Research Laboratory and University of Oslo
% Jan 32, 2100
*Summary.* The purpose of this document is to test LaTeX math in DocOnce with
various output formats.  Most LaTeX math constructions are renedered
correctly by MathJax in plain HTML, but some combinations of
constructions may fail.  Unfortunately, only a subset of what works in
html MathJax also works in sphinx MathJax. The same is true for
markdown MathJax expresions (e.g., Jupyter notebooks).  Tests and
examples are provided to illustrate what may go wrong.

The recommendation for writing math that translates to MathJax in
html, sphinx, and markdown is to stick to the environments `\[
... \]`, `equation`, `equation*`, `align`, `align*`, `alignat`, and
`alignat*` only. Test the math with sphinx output; if it works in that
format, it should work elsewhere too.

The current version of the document is translated from DocOnce source
to the format **pandoc**.



## Test of equation environments

### Test 1: Inline math

We can get an inline equation
`$u(t)=e^{-at}$` rendered as $u(t)=e^{-at}$.

### Test 2: A single equation with label

An equation with number,


~~~
!bt
\begin{equation} u(t)=e^{-at} \label{eq1a}\end{equation}
!et
~~~

looks like

$$
\begin{equation} u(t)=e^{-at} \label{_eq1a}\end{equation}
$$
Maybe this multi-line version is what we actually prefer to write:


~~~
!bt
\begin{equation}
u(t)=e^{-at}
\label{eq1b}
\end{equation}
!et
~~~

The result is the same:

$$
\begin{equation}
u(t)=e^{-at} \label{_eq1b}
\end{equation}
$$
We can refer to this equation through its label `eq1b`: ([_eq1b](#_eq1b)).


### Test 3: Multiple, aligned equations without label and number

MathJax has historically had some problems with rendering many LaTeX
math environments, but the `align*` and `align` environments have
always worked.


~~~
!bt
\begin{align*}
u(t)&=e^{-at}\\ 
v(t) - 1 &= \frac{du}{dt}
\end{align*}
!et
~~~

Result:

$$
\begin{align*}
u(t)&=e^{-at}\\ 
v(t) - 1 &= \frac{du}{dt}
\end{align*}
$$

### Test 4: Multiple, aligned equations with label

Here, we use `align` with user-prescribed labels:


~~~
!bt
\begin{align}
u(t)&=e^{-at}
\label{eq2b}\\ 
v(t) - 1 &= \frac{du}{dt}
\label{eq3b}
\end{align}
!et
~~~

Result:

$$
\begin{align}
u(t)&=e^{-at}
\label{_eq2b}\\ 
v(t) - 1 &= \frac{du}{dt}
\label{_eq3b}
\end{align}
$$
We can refer to the last equations as the system ([_eq2b](#_eq2b))-([_eq3b](#_eq3b)).




### Test 5: Multiple, aligned equations without label

In LaTeX, equations within an `align` environment is automatically
given numbers.  To ensure that an html document with MathJax gets the
same equation numbers as its latex/pdflatex companion, DocOnce
generates labels in equations where there is no label prescribed. For
example,


~~~
!bt
\begin{align}
u(t)&=e^{-at}
\\ 
v(t) - 1 &= \frac{du}{dt}
\end{align}
!et
~~~

is edited to something like


~~~
!bt
\begin{align}
u(t)&=e^{-at}
\label{_auto5}\\ 
v(t) - 1 &= \frac{du}{dt}
\label{_auto6}
\end{align}
!et
~~~

and the output gets the two equation numbered.

$$
\begin{align}
u(t)&=e^{-at}\\ 
v(t) - 1 &= \frac{du}{dt}
\end{align}
$$

### Test 6: Multiple, aligned equations with multiple alignments

The `align` environment can be used with two `&` alignment characters, e.g.,


~~~
!bt
\begin{align}
\frac{\partial u}{\partial t} &= \nabla^2 u, & x\in (0,L),
\ t\in (0,T]\\ 
u(0,t) &= u_0(x), & x\in [0,L]
\end{align}
!et
~~~

The result in pandoc becomes

$$
\begin{align}
\frac{\partial u}{\partial t} &= \nabla^2 u, & x\in (0,L),
\ t\in (0,T]\\ 
u(0,t) &= u_0(x), & x\in [0,L]
\end{align}
$$

A better solution is usually to use an `alignat` environment:


~~~
!bt
\begin{alignat}{2}
\frac{\partial u}{\partial t} &= \nabla^2 u, & x\in (0,L),
\ t\in (0,T]\\ 
u(0,t) &= u_0(x), & x\in [0,L]
\end{alignat}
!et
~~~

with the rendered result

$$
\begin{alignat}{2}
\frac{\partial u}{\partial t} &= \nabla^2 u, & x\in (0,L),
\ t\in (0,T]\\ 
u(0,t) &= u_0(x), & x\in [0,L]
\end{alignat}
$$



If DocOnce had not rewritten the above equations, they would be
rendered in pandoc as

$$
\begin{alignat}{2}
\frac{\partial u}{\partial t} &= \nabla^2 u, & x\in (0,L),
\ t\in (0,T]\\ 
u(0,t) &= u_0(x), & x\in [0,L]
\end{alignat}
$$




### Test 7: Multiple, aligned eqnarray equations without label

Let us try the old `eqnarray*` environment.


~~~
!bt
\begin{eqnarray*}
u(t)&=& e^{-at}\\ 
v(t) - 1 &=& \frac{du}{dt}
\end{eqnarray*}
!et
~~~

which results in

$$
\begin{eqnarray*}
u(t)&=& e^{-at}\\ 
v(t) - 1 &=& \frac{du}{dt}
\end{eqnarray*}
$$

### Test 8: Multiple, eqnarrayed equations with label

Here we use `eqnarray` with labels:


~~~
!bt
\begin{eqnarray}
u(t)&=& e^{-at}
\label{eq2c}\\ 
v(t) - 1 &=& \frac{du}{dt}
\label{eq3c}
\end{eqnarray}
!et
~~~

which results in

$$
\begin{eqnarray}
u(t)&=& e^{-at} \label{_eq2c}\\ 
v(t) - 1 &=& \frac{du}{dt} \label{_eq3c}
\end{eqnarray}
$$
Can we refer to the last equations as the system ([_eq2c](#_eq2c))-([_eq3c](#_eq3c))
in the pandoc format?

### Test 9: The `multiline` environment with label and number

The LaTeX code


~~~
!bt
\begin{multline}
\int_a^b f(x)dx = \sum_{j=0}^{n} \frac{1}{2} h(f(a+jh) +
f(a+(j+1)h)) \\ 
=\frac{h}{2}f(a) + \frac{h}{2}f(b) + \sum_{j=1}^n f(a+jh)
\label{multiline:eq1}
\end{multline}
!et
~~~

gets rendered as

$$
\begin{multline}
\int_a^b f(x)dx = \sum_{j=0}^{n} \frac{1}{2} h(f(a+jh) +
f(a+(j+1)h)) \\ 
=\frac{h}{2}f(a) + \frac{h}{2}f(b) + \sum_{j=1}^n f(a+jh)
\label{_multiline:eq1}
\end{multline}
$$
and we can hopefully refer to the Trapezoidal rule
as the formula ([_multiline:eq1](#_multiline:eq1)).


### Test 10: Splitting equations using a split environment

Although `align` can be used to split too long equations, a more obvious
command is `split`:


~~~
!bt
\begin{equation}
\begin{split}
\int_a^b f(x)dx = \sum_{j=0}^{n} \frac{1}{2} h(f(a+jh) +
f(a+(j+1)h)) \\ 
=\frac{h}{2}f(a) + \frac{h}{2}f(b) + \sum_{j=1}^n f(a+jh)
\end{split}
\end{equation}
!et
~~~

The result becomes

$$
\begin{equation}
\begin{split}
\int_a^b f(x)dx = \sum_{j=0}^{n} \frac{1}{2} h(f(a+jh) +
f(a+(j+1)h)) \\ 
=\frac{h}{2}f(a) + \frac{h}{2}f(b) + \sum_{j=1}^n f(a+jh)
\end{split}
\end{equation}
$$

### Test 11: Newcommands and boldface bm vs pmb

First we use the plain old pmb package for bold math. The formula


~~~
!bt
\[ \frac{\partial\u}{\partial t} +
\u\cdot\nabla\u = \nu\nabla^2\u -
\frac{1}{\varrho}\nabla p,\]
!et
~~~

and the inline expression `$\nabla\pmb{u} (\pmb{x})\cdot\pmb{n}$`
(with suitable newcommands using pmb)
get rendered as

$$
 \frac{\partial\pmb{u}}{\partial t} +
\pmb{u}\cdot\nabla\pmb{u} = \nu\nabla^2\pmb{u} -
\frac{1}{\varrho}\nabla p,
$$
and $\nabla\pmb{u} (\pmb{x})\cdot\pmb{n}$.

Somewhat nicer fonts may appear with the more modern `\bm` command:


~~~
!bt
\[ \frac{\partial\ubm}{\partial t} +
\ubm\cdot\nabla\ubm = \nu\nabla^2\ubm -
\frac{1}{\varrho}\nabla p,\]
!et
~~~

(backslash `ubm` is a newcommand for bold math $u$), for which we get

$$
 \frac{\partial\boldsymbol{u}}{\partial t} +
\boldsymbol{u}\cdot\nabla\boldsymbol{u} = \nu\nabla^2\boldsymbol{u} -
\frac{1}{\varrho}\nabla p.
$$
Moreover,


~~~
$\nabla\boldsymbol{u}(\boldsymbol{x})\cdot\boldsymbol{n}$
~~~

becomes $\nabla\boldsymbol{u}(\boldsymbol{x})\cdot\boldsymbol{n}$.

*Warning.* 
Note: for the pandoc format, `\bm` was substituted by DocOnce
to `\boldsymbol`.




## Problematic equations

Finally, we collect some problematic formulas in MathJax. They all work
fine in LaTeX. Most of them look fine in html too, but some fail in
sphinx, ipynb, or markdown.

### Colored terms in equations

The LaTeX code


~~~
!bt
\[ {\color{blue}\frac{\partial\u}{\partial t}} +
\nabla\cdot\nabla\u = \nu\nabla^2\u -
\frac{1}{\varrho}\nabla p,\]
!et
~~~

results in

$$
 {\color{blue}\frac{\partial\pmb{u}}{\partial t}} +
\nabla\cdot\nabla\pmb{u} = \nu\nabla^2\pmb{u} -
\frac{1}{\varrho}\nabla p,
$$

### Bar over symbols

Sometimes one must be extra careful with the LaTeX syntax to get sphinx MathJax
to render a formula correctly. Consider the combination of a bar over a
bold math symbol:


~~~
!bt
\[ \bar\f = f_c^{-1}\f,\]
!et
~~~

which for pandoc output results in

$$
 \bar\boldsymbol{f} = f_c^{-1}\boldsymbol{f}.
$$

With sphinx, this formula is not rendered. However, using curly braces for the bar,


~~~
!bt
\[ \bar{\f} = f_c^{-1}\f,\]
!et
~~~

makes the output correct also for sphinx:

$$
 \bar{\boldsymbol{f}} = f_c^{-1}\boldsymbol{f},
$$


### Matrix formulas

Here is an `align` environment with a label and the `pmatrix`
environment for matrices and vectors in LaTeX.


~~~
!bt
\begin{align}
\begin{pmatrix}
G_2 + G_3 & -G_3 & -G_2 & 0 \\ 
-G_3 & G_3 + G_4 & 0 & -G_4 \\ 
-G_2 & 0 & G_1 + G_2 & 0 \\ 
0 & -G_4 & 0 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
v_1 \\ 
v_2 \\ 
v_3 \\ 
v_4
\end{pmatrix}
+ \cdots
\label{mymatrixeq}\\ 
\begin{pmatrix}
C_5 + C_6 & -C_6 & 0 & 0 \\ 
-C_6 & C_6 & 0 & 0 \\ 
0 & 0 & 0 & 0 \\ 
0 & 0 & 0 & 0
\end{pmatrix}
\frac{d}{dt} &=
\begin{pmatrix}
v_1 \\ 
v_2 \\ 
v_3 \\ 
v_4
\end{pmatrix} =
\begin{pmatrix}
0 \\ 
0 \\ 
0 \\ 
-i_0
\end{pmatrix}
\end{align}
!et
~~~

which becomes

$$
\begin{align}
\begin{pmatrix}
G_2 + G_3 & -G_3 & -G_2 & 0 \\ 
-G_3 & G_3 + G_4 & 0 & -G_4 \\ 
-G_2 & 0 & G_1 + G_2 & 0 \\ 
0 & -G_4 & 0 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
v_1 \\ 
v_2 \\ 
v_3 \\ 
v_4
\end{pmatrix}
+ \cdots
\label{_mymatrixeq}\\ 
\begin{pmatrix}
C_5 + C_6 & -C_6 & 0 & 0 \\ 
-C_6 & C_6 & 0 & 0 \\ 
0 & 0 & 0 & 0 \\ 
0 & 0 & 0 & 0
\end{pmatrix}
\frac{d}{dt} &=
\begin{pmatrix}
v_1 \\ 
v_2 \\ 
v_3 \\ 
v_4
\end{pmatrix} =
\begin{pmatrix}
0 \\ 
0 \\ 
0 \\ 
-i_0
\end{pmatrix}
\end{align}
$$

The same matrices without labels in an `align*` environment:


~~~
!bt
\begin{align*}
\begin{pmatrix}
G_2 + G_3 & -G_3 & -G_2 & 0 \\ 
-G_3 & G_3 + G_4 & 0 & -G_4 \\ 
-G_2 & 0 & G_1 + G_2 & 0 \\ 
0 & -G_4 & 0 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
v_1 \\ 
v_2 \\ 
v_3 \\ 
v_4
\end{pmatrix}
+ \cdots \\ 
\begin{pmatrix}
C_5 + C_6 & -C_6 & 0 & 0 \\ 
-C_6 & C_6 & 0 & 0 \\ 
0 & 0 & 0 & 0 \\ 
0 & 0 & 0 & 0
\end{pmatrix}
\frac{d}{dt} &=
\begin{pmatrix}
v_1 \\ 
v_2 \\ 
v_3 \\ 
v_4
\end{pmatrix} =
\begin{pmatrix}
0 \\ 
0 \\ 
0 \\ 
-i_0
\end{pmatrix}
\end{align*}
!et
~~~

The rendered result becomes

$$
\begin{align*}
\begin{pmatrix}
G_2 + G_3 & -G_3 & -G_2 & 0 \\ 
-G_3 & G_3 + G_4 & 0 & -G_4 \\ 
-G_2 & 0 & G_1 + G_2 & 0 \\ 
0 & -G_4 & 0 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
v_1 \\ 
v_2 \\ 
v_3 \\ 
v_4
\end{pmatrix}
+ \cdots \\ 
\begin{pmatrix}
C_5 + C_6 & -C_6 & 0 & 0 \\ 
-C_6 & C_6 & 0 & 0 \\ 
0 & 0 & 0 & 0 \\ 
0 & 0 & 0 & 0
\end{pmatrix}
\frac{d}{dt} &=
\begin{pmatrix}
v_1 \\ 
v_2 \\ 
v_3 \\ 
v_4
\end{pmatrix} =
\begin{pmatrix}
0 \\ 
0 \\ 
0 \\ 
-i_0
\end{pmatrix}
\end{align*}
$$


************** File: math_test_html.html *****************
<!--
Automatically generated HTML file from DocOnce source
(https://github.com/doconce/doconce/)
-->
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="DocOnce: https://github.com/doconce/doconce/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="description" content="How various formats can deal with LaTeX math">

<title>How various formats can deal with LaTeX math</title>


<style type="text/css">
/* blueish style */

/* Color definitions:  https://www.december.com/html/spec/color0.html
   CSS examples:       https://www.w3schools.com/css/css_examples.asp */

body {
  margin-top: 1.0em;
  background-color: #ffffff;
  font-family: Helvetica, Arial, FreeSans, san-serif;
  color: #000000;
}
h1 { font-size: 1.8em; color: #1e36ce; }
h2 { font-size: 1.6em; color: #1e36ce; }
h3 { font-size: 1.4em; color: #1e36ce; }
a { color: #1e36ce; text-decoration:none; }
tt { font-family: "Courier New", Courier; }
/* pre style removed because it will interfer with pygments */
p { text-indent: 0px; }
hr { border: 0; width: 80%; border-bottom: 1px solid #aaa}
p.caption { width: 80%; font-style: normal; text-align: left; }
hr.figure { border: 0; width: 80%; border-bottom: 1px solid #aaa}
.alert-text-small   { font-size: 80%;  }
.alert-text-large   { font-size: 130%; }
.alert-text-normal  { font-size: 90%;  }
.alert {
  padding:8px 35px 8px 14px; margin-bottom:18px;
  text-shadow:0 1px 0 rgba(255,255,255,0.5);
  border:1px solid #bababa;
  border-radius: 4px;
  -webkit-border-radius: 4px;
  -moz-border-radius: 4px;
  color: #555;
  background-color: #f8f8f8;
  background-position: 10px 5px;
  background-repeat: no-repeat;
  background-size: 38px;
  padding-left: 55px;
  width: 75%;
 }
.alert-block {padding-top:14px; padding-bottom:14px}
.alert-block > p, .alert-block > ul {margin-bottom:1em}
.alert li {margin-top: 1em}
.alert-block p+p {margin-top:5px}
.alert-notice { background-image: url(https://raw.github.com/doconce/doconce/master/bundled/html_images/small_gray_notice.png); }
.alert-summary  { background-image:url(https://raw.github.com/doconce/doconce/master/bundled/html_images/small_gray_summary.png); }
.alert-warning { background-image: url(https://raw.github.com/doconce/doconce/master/bundled/html_images/small_gray_warning.png); }
.alert-question {background-image:url(https://raw.github.com/doconce/doconce/master/bundled/html_images/small_gray_question.png); }

div { text-align: justify; text-justify: inter-word; }
</style>


</head>

<!-- tocinfo
{'highest level': 1,
 'sections': [('Test of equation environments',
               1,
               None,
               'test-of-equation-environments'),
              ('Test 1: Inline math', 2, None, 'test-1-inline-math'),
              ('Test 2: A single equation with label',
               2,
               None,
               'test-2-a-single-equation-with-label'),
              ('Test 3: Multiple, aligned equations without label and number',
               2,
               None,
               'test-3-multiple-aligned-equations-without-label-and-number'),
              ('Test 4: Multiple, aligned equations with label',
               2,
               None,
               'test-4-multiple-aligned-equations-with-label'),
              ('Test 5: Multiple, aligned equations without label',
               2,
               None,
               'test-5-multiple-aligned-equations-without-label'),
              ('Test 6: Multiple, aligned equations with multiple alignments',
               2,
               None,
               'test-6-multiple-aligned-equations-with-multiple-alignments'),
              ('Test 7: Multiple, aligned eqnarray equations without label',
               2,
               None,
               'test-7-multiple-aligned-eqnarray-equations-without-label'),
              ('Test 8: Multiple, eqnarrayed equations with label',
               2,
               None,
               'test-8-multiple-eqnarrayed-equations-with-label'),
              ('Test 9: The `multiline` environment with label and number',
               2,
               None,
               'test-9-the-multiline-environment-with-label-and-number'),
              ('Test 10: Splitting equations using a split environment',
               2,
               None,
               'test-10-splitting-equations-using-a-split-environment'),
              ('Test 11: Newcommands and boldface bm vs pmb',
               2,
               None,
               'test-11-newcommands-and-boldface-bm-vs-pmb'),
              ('Problematic equations', 1, None, 'problematic-equations'),
              ('Colored terms in equations',
               2,
               None,
               'colored-terms-in-equations'),
              ('Bar over symbols', 2, None, 'bar-over-symbols'),
              ('Matrix formulas', 2, None, 'matrix-formulas')]}
end of tocinfo -->

<body>



<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  TeX: {
     equationNumbers: {  autoNumber: "AMS"  },
     extensions: ["AMSmath.js", "AMSsymbols.js", "autobold.js", "color.js"]
  }
});
</script>
<script type="text/javascript" async
 src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>

<!-- newcommands_bfmath.tex -->
$$
\renewcommand{\u}{\pmb{u}}
\newcommand{\f}{\boldsymbol{f}}
\newcommand{\ubm}{\boldsymbol{u}}
$$




    
<!-- ------------------- main content ---------------------- -->



<center><h1>How various formats can deal with LaTeX math</h1></center>  <!-- document title -->

<p>
<!-- author(s): Hans Petter Langtangen -->

<center>
<b>Hans Petter Langtangen</b> [1, 2]
</center>

<p>
<!-- institution(s) -->

<center>[1] <b>Simula Research Laboratory</b></center>
<center>[2] <b>University of Oslo</b></center>
<br>
<p>
<center><h4>Jan 32, 2100</h4></center> <!-- date -->
<br>
<p>
<b>Summary.</b> The purpose of this document is to test LaTeX math in DocOnce with
various output formats.  Most LaTeX math constructions are renedered
correctly by MathJax in plain HTML, but some combinations of
constructions may fail.  Unfortunately, only a subset of what works in
html MathJax also works in sphinx MathJax. The same is true for
markdown MathJax expresions (e.g., Jupyter notebooks).  Tests and
examples are provided to illustrate what may go wrong.

<p>
The recommendation for writing math that translates to MathJax in
html, sphinx, and markdown is to stick to the environments <code>\[
... \]</code>, <code>equation</code>, <code>equation*</code>, <code>align</code>, <code>align*</code>, <code>alignat</code>, and
<code>alignat*</code> only. Test the math with sphinx output; if it works in that
format, it should work elsewhere too.

<p>
The current version of the document is translated from DocOnce source
to the format <b>html</b>.

<h1 id="test-of-equation-environments">Test of equation environments </h1>

<h2 id="test-1-inline-math">Test 1: Inline math </h2>

<p>
We can get an inline equation
<code>$u(t)=e^{-at}$</code> rendered as \( u(t)=e^{-at} \).

<h2 id="test-2-a-single-equation-with-label">Test 2: A single equation with label </h2>

<p>
An equation with number,

<p>

<!-- code=latex (!bc latexcod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>!bt
<span style="color: #008000; font-weight: bold">\begin</span><span style="color: #008000">{</span>equation<span style="color: #008000">}</span> u(t)=e<span style="color: #008000">^{</span>-at<span style="color: #008000">}</span> label<span style="color: #008000">{</span>eq1a<span style="color: #008000">}</span><span style="color: #008000; font-weight: bold">\end</span><span style="color: #008000">{</span>equation<span style="color: #008000">}</span>
!et
</pre></div>
<p>
looks like

$$
\begin{equation} u(t)=e^{-at} \label{_eq1a}\end{equation}
$$

Maybe this multi-line version is what we actually prefer to write:

<p>

<!-- code=latex (!bc latexcod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>!bt
<span style="color: #008000; font-weight: bold">\begin</span><span style="color: #008000">{</span>equation<span style="color: #008000">}</span>
u(t)=e<span style="color: #008000">^{</span>-at<span style="color: #008000">}</span>
label<span style="color: #008000">{</span>eq1b<span style="color: #008000">}</span>
<span style="color: #008000; font-weight: bold">\end</span><span style="color: #008000">{</span>equation<span style="color: #008000">}</span>
!et
</pre></div>
<p>
The result is the same:

$$
\begin{equation}
u(t)=e^{-at} \label{_eq1b}
\end{equation}
$$

We can refer to this equation through its label <code>eq1b</code>: \eqref{_eq1b}.

<h2 id="test-3-multiple-aligned-equations-without-label-and-number">Test 3: Multiple, aligned equations without label and number </h2>

<p>
MathJax has historically had some problems with rendering many LaTeX
math environments, but the <code>align*</code> and <code>align</code> environments have
always worked.

<p>

<!-- code=latex (!bc latexcod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>!bt
<span style="color: #008000; font-weight: bold">\begin</span><span style="color: #008000">{</span>align*<span style="color: #008000">}</span>
u(t)<span style="color: #008000">&amp;</span>=e<span style="color: #008000">^{</span>-at<span style="color: #008000">}</span><span style="color: #008000; font-weight: bold">\\</span> 
v(t) - 1 <span style="color: #008000">&amp;</span>= <span style="color: #008000; font-weight: bold">\frac</span><span style="color: #008000">{</span>du<span style="color: #008000">}{</span>dt<span style="color: #008000">}</span>
<span style="color: #008000; font-weight: bold">\end</span><span style="color: #008000">{</span>align*<span style="color: #008000">}</span>
!et
</pre></div>
<p>
Result:

$$
\begin{align*}
u(t)&=e^{-at}\\ 
v(t) - 1 &= \frac{du}{dt}
\end{align*}
$$

<h2 id="test-4-multiple-aligned-equations-with-label">Test 4: Multiple, aligned equations with label </h2>

<p>
Here, we use <code>align</code> with user-prescribed labels:

<p>

<!-- code=latex (!bc latexcod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>!bt
<span style="color: #008000; font-weight: bold">\begin</span><span style="color: #008000">{</span>align<span style="color: #008000">}</span>
u(t)<span style="color: #008000">&amp;</span>=e<span style="color: #008000">^{</span>-at<span style="color: #008000">}</span>
label<span style="color: #008000">{</span>eq2b<span style="color: #008000">}</span><span style="color: #008000; font-weight: bold">\\</span> 
v(t) - 1 <span style="color: #008000">&amp;</span>= <span style="color: #008000; font-weight: bold">\frac</span><span style="color: #008000">{</span>du<span style="color: #008000">}{</span>dt<span style="color: #008000">}</span>
label<span style="color: #008000">{</span>eq3b<span style="color: #008000">}</span>
<span style="color: #008000; font-weight: bold">\end</span><span style="color: #008000">{</span>align<span style="color: #008000">}</span>
!et
</pre></div>
<p>
Result:

$$
\begin{align}
u(t)&=e^{-at}
\label{_eq2b}\\ 
v(t) - 1 &= \frac{du}{dt}
\label{_eq3b}
\end{align}
$$

We can refer to the last equations as the system \eqref{_eq2b}-\eqref{_eq3b}.

<h2 id="test-5-multiple-aligned-equations-without-label">Test 5: Multiple, aligned equations without label </h2>

<p>
In LaTeX, equations within an <code>align</code> environment is automatically
given numbers.  To ensure that an html document with MathJax gets the
same equation numbers as its latex/pdflatex companion, DocOnce
generates labels in equations where there is no label prescribed. For
example,

<p>

<!-- code=latex (!bc latexcod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>!bt
<span style="color: #008000; font-weight: bold">\begin</span><span style="color: #008000">{</span>align<span style="color: #008000">}</span>
u(t)<span style="color: #008000">&amp;</span>=e<span style="color: #008000">^{</span>-at<span style="color: #008000">}</span>
<span style="color: #008000; font-weight: bold">\\</span> 
v(t) - 1 <span style="color: #008000">&amp;</span>= <span style="color: #008000; font-weight: bold">\frac</span><span style="color: #008000">{</span>du<span style="color: #008000">}{</span>dt<span style="color: #008000">}</span>
<span style="color: #008000; font-weight: bold">\end</span><span style="color: #008000">{</span>align<span style="color: #008000">}</span>
!et
</pre></div>
<p>
is edited to something like

<p>

<!-- code=latex (!bc latexcod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>!bt
<span style="color: #008000; font-weight: bold">\begin</span><span style="color: #008000">{</span>align<span style="color: #008000">}</span>
u(t)<span style="color: #008000">&amp;</span>=e<span style="color: #008000">^{</span>-at<span style="color: #008000">}</span>
label<span style="color: #008000">{_</span>auto5<span style="color: #008000">}</span><span style="color: #008000; font-weight: bold">\\</span> 
v(t) - 1 <span style="color: #008000">&amp;</span>= <span style="color: #008000; font-weight: bold">\frac</span><span style="color: #008000">{</span>du<span style="color: #008000">}{</span>dt<span style="color: #008000">}</span>
label<span style="color: #008000">{_</span>auto6<span style="color: #008000">}</span>
<span style="color: #008000; font-weight: bold">\end</span><span style="color: #008000">{</span>align<span style="color: #008000">}</span>
!et
</pre></div>
<p>
and the output gets the two equation numbered.

$$
\begin{align}
u(t)&=e^{-at}
\label{_auto1}\\ 
v(t) - 1 &= \frac{du}{dt}
\label{_auto2}
\end{align}
$$

<h2 id="test-6-multiple-aligned-equations-with-multiple-alignments">Test 6: Multiple, aligned equations with multiple alignments </h2>

<p>
The <code>align</code> environment can be used with two <code>&</code> alignment characters, e.g.,

<p>

<!-- code=latex (!bc latexcod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>!bt
<span style="color: #008000; font-weight: bold">\begin</span><span style="color: #008000">{</span>align<span style="color: #008000">}</span>
<span style="color: #008000; font-weight: bold">\frac</span><span style="color: #008000">{</span><span style="color: #008000; font-weight: bold">\partial</span> u<span style="color: #008000">}{</span><span style="color: #008000; font-weight: bold">\partial</span> t<span style="color: #008000">}</span> <span style="color: #008000">&amp;</span>= <span style="color: #008000; font-weight: bold">\nabla</span><span style="color: #008000">^</span>2 u, <span style="color: #008000">&amp;</span> x<span style="color: #008000; font-weight: bold">\in</span> (0,L),
<span style="color: #008000; font-weight: bold">\ </span>t<span style="color: #008000; font-weight: bold">\in</span> (0,T]<span style="color: #008000; font-weight: bold">\\</span> 
u(0,t) <span style="color: #008000">&amp;</span>= u<span style="color: #008000">_</span>0(x), <span style="color: #008000">&amp;</span> x<span style="color: #008000; font-weight: bold">\in</span> [0,L]
<span style="color: #008000; font-weight: bold">\end</span><span style="color: #008000">{</span>align<span style="color: #008000">}</span>
!et
</pre></div>
<p>
The result in html becomes

$$
\begin{align}
\frac{\partial u}{\partial t} &= \nabla^2 u, & x\in (0,L),
\ t\in (0,T]
\label{_auto3}\\ 
u(0,t) &= u_0(x), & x\in [0,L]
\label{_auto4}
\end{align}
$$

<p>
A better solution is usually to use an <code>alignat</code> environment:

<p>

<!-- code=latex (!bc latexcod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>!bt
<span style="color: #008000; font-weight: bold">\begin</span><span style="color: #008000">{</span>alignat<span style="color: #008000">}{</span>2<span style="color: #008000">}</span>
<span style="color: #008000; font-weight: bold">\frac</span><span style="color: #008000">{</span><span style="color: #008000; font-weight: bold">\partial</span> u<span style="color: #008000">}{</span><span style="color: #008000; font-weight: bold">\partial</span> t<span style="color: #008000">}</span> <span style="color: #008000">&amp;</span>= <span style="color: #008000; font-weight: bold">\nabla</span><span style="color: #008000">^</span>2 u, <span style="color: #008000">&amp;</span> x<span style="color: #008000; font-weight: bold">\in</span> (0,L),
<span style="color: #008000; font-weight: bold">\ </span>t<span style="color: #008000; font-weight: bold">\in</span> (0,T]<span style="color: #008000; font-weight: bold">\\</span> 
u(0,t) <span style="color: #008000">&amp;</span>= u<span style="color: #008000">_</span>0(x), <span style="color: #008000">&amp;</span> x<span style="color: #008000; font-weight: bold">\in</span> [0,L]
<span style="color: #008000; font-weight: bold">\end</span><span style="color: #008000">{</span>alignat<span style="color: #008000">}</span>
!et
</pre></div>
<p>
with the rendered result

$$
\begin{alignat}{2}
\frac{\partial u}{\partial t} &= \nabla^2 u, & x\in (0,L),
\ t\in (0,T]\\ 
u(0,t) &= u_0(x), & x\in [0,L]
\end{alignat}
$$

<h2 id="test-7-multiple-aligned-eqnarray-equations-without-label">Test 7: Multiple, aligned eqnarray equations without label </h2>

<p>
Let us try the old <code>eqnarray*</code> environment.

<p>

<!-- code=latex (!bc latexcod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>!bt
<span style="color: #008000; font-weight: bold">\begin</span><span style="color: #008000">{</span>eqnarray*<span style="color: #008000">}</span>
u(t)<span style="color: #008000">&amp;</span>=<span style="color: #008000">&amp;</span> e<span style="color: #008000">^{</span>-at<span style="color: #008000">}</span><span style="color: #008000; font-weight: bold">\\</span> 
v(t) - 1 <span style="color: #008000">&amp;</span>=<span style="color: #008000">&amp;</span> <span style="color: #008000; font-weight: bold">\frac</span><span style="color: #008000">{</span>du<span style="color: #008000">}{</span>dt<span style="color: #008000">}</span>
<span style="color: #008000; font-weight: bold">\end</span><span style="color: #008000">{</span>eqnarray*<span style="color: #008000">}</span>
!et
</pre></div>
<p>
which results in

$$
\begin{eqnarray*}
u(t)&=& e^{-at}\\ 
v(t) - 1 &=& \frac{du}{dt}
\end{eqnarray*}
$$

<h2 id="test-8-multiple-eqnarrayed-equations-with-label">Test 8: Multiple, eqnarrayed equations with label </h2>

<p>
Here we use <code>eqnarray</code> with labels:

<p>

<!-- code=latex (!bc latexcod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>!bt
<span style="color: #008000; font-weight: bold">\begin</span><span style="color: #008000">{</span>eqnarray<span style="color: #008000">}</span>
u(t)<span style="color: #008000">&amp;</span>=<span style="color: #008000">&amp;</span> e<span style="color: #008000">^{</span>-at<span style="color: #008000">}</span>
label<span style="color: #008000">{</span>eq2c<span style="color: #008000">}</span><span style="color: #008000; font-weight: bold">\\</span> 
v(t) - 1 <span style="color: #008000">&amp;</span>=<span style="color: #008000">&amp;</span> <span style="color: #008000; font-weight: bold">\frac</span><span style="color: #008000">{</span>du<span style="color: #008000">}{</span>dt<span style="color: #008000">}</span>
label<span style="color: #008000">{</span>eq3c<span style="color: #008000">}</span>
<span style="color: #008000; font-weight: bold">\end</span><span style="color: #008000">{</span>eqnarray<span style="color: #008000">}</span>
!et
</pre></div>
<p>
which results in

$$
\begin{eqnarray}
u(t)&=& e^{-at} \label{_eq2c}\\ 
v(t) - 1 &=& \frac{du}{dt} \label{_eq3c}
\end{eqnarray}
$$

Can we refer to the last equations as the system \eqref{_eq2c}-\eqref{_eq3c}
in the html format?

<h2 id="test-9-the-multiline-environment-with-label-and-number">Test 9: The <code>multiline</code> environment with label and number </h2>

<p>
The LaTeX code

<p>

<!-- code=latex (!bc latexcod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>!bt
<span style="color: #008000; font-weight: bold">\begin</span><span style="color: #008000">{</span>multline<span style="color: #008000">}</span>
<span style="color: #008000; font-weight: bold">\int</span><span style="color: #008000">_</span>a<span style="color: #008000">^</span>b f(x)dx = <span style="color: #008000; font-weight: bold">\sum</span><span style="color: #008000">_{</span>j=0<span style="color: #008000">}^{</span>n<span style="color: #008000">}</span> <span style="color: #008000; font-weight: bold">\frac</span><span style="color: #008000">{</span>1<span style="color: #008000">}{</span>2<span style="color: #008000">}</span> h(f(a+jh) +
f(a+(j+1)h)) <span style="color: #008000; font-weight: bold">\\</span> 
=<span style="color: #008000; font-weight: bold">\frac</span><span style="color: #008000">{</span>h<span style="color: #008000">}{</span>2<span style="color: #008000">}</span>f(a) + <span style="color: #008000; font-weight: bold">\frac</span><span style="color: #008000">{</span>h<span style="color: #008000">}{</span>2<span style="color: #008000">}</span>f(b) + <span style="color: #008000; font-weight: bold">\sum</span><span style="color: #008000">_{</span>j=1<span style="color: #008000">}^</span>n f(a+jh)
label<span style="color: #008000">{</span>multiline:eq1<span style="color: #008000">}</span>
<span style="color: #008000; font-weight: bold">\end</span><span style="color: #008000">{</span>multline<span style="color: #008000">}</span>
!et
</pre></div>
<p>
gets rendered as

$$
\begin{multline}
\int_a^b f(x)dx = \sum_{j=0}^{n} \frac{1}{2} h(f(a+jh) +
f(a+(j+1)h)) \\ 
=\frac{h}{2}f(a) + \frac{h}{2}f(b) + \sum_{j=1}^n f(a+jh)
\label{_multiline:eq1}
\end{multline}
$$

and we can hopefully refer to the Trapezoidal rule
as the formula \eqref{_multiline:eq1}.

<h2 id="test-10-splitting-equations-using-a-split-environment">Test 10: Splitting equations using a split environment </h2>

<p>
Although <code>align</code> can be used to split too long equations, a more obvious
command is <code>split</code>:

<p>

<!-- code=latex (!bc latexcod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>!bt
<span style="color: #008000; font-weight: bold">\begin</span><span style="color: #008000">{</span>equation<span style="color: #008000">}</span>
<span style="color: #008000; font-weight: bold">\begin</span><span style="color: #008000">{</span>split<span style="color: #008000">}</span>
<span style="color: #008000; font-weight: bold">\int</span><span style="color: #008000">_</span>a<span style="color: #008000">^</span>b f(x)dx = <span style="color: #008000; font-weight: bold">\sum</span><span style="color: #008000">_{</span>j=0<span style="color: #008000">}^{</span>n<span style="color: #008000">}</span> <span style="color: #008000; font-weight: bold">\frac</span><span style="color: #008000">{</span>1<span style="color: #008000">}{</span>2<span style="color: #008000">}</span> h(f(a+jh) +
f(a+(j+1)h)) <span style="color: #008000; font-weight: bold">\\</span> 
=<span style="color: #008000; font-weight: bold">\frac</span><span style="color: #008000">{</span>h<span style="color: #008000">}{</span>2<span style="color: #008000">}</span>f(a) + <span style="color: #008000; font-weight: bold">\frac</span><span style="color: #008000">{</span>h<span style="color: #008000">}{</span>2<span style="color: #008000">}</span>f(b) + <span style="color: #008000; font-weight: bold">\sum</span><span style="color: #008000">_{</span>j=1<span style="color: #008000">}^</span>n f(a+jh)
<span style="color: #008000; font-weight: bold">\end</span><span style="color: #008000">{</span>split<span style="color: #008000">}</span>
<span style="color: #008000; font-weight: bold">\end</span><span style="color: #008000">{</span>equation<span style="color: #008000">}</span>
!et
</pre></div>
<p>
The result becomes

$$
\begin{equation}
\begin{split}
\int_a^b f(x)dx = \sum_{j=0}^{n} \frac{1}{2} h(f(a+jh) +
f(a+(j+1)h)) \\ 
=\frac{h}{2}f(a) + \frac{h}{2}f(b) + \sum_{j=1}^n f(a+jh)
\end{split}
\label{_auto5}
\end{equation}
$$

<h2 id="test-11-newcommands-and-boldface-bm-vs-pmb">Test 11: Newcommands and boldface bm vs pmb </h2>

<p>
First we use the plain old pmb package for bold math. The formula

<p>

<!-- code=latex (!bc latexcod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>!bt
<span style="color: #BA2121">\[</span><span style="color: #008000"> </span><span style="color: #19177C">\frac</span><span style="color: #008000">{</span><span style="color: #19177C">\partial\u</span><span style="color: #008000">}{</span><span style="color: #19177C">\partial</span><span style="color: #008000"> t} </span><span style="color: #666666">+</span><span style="color: #008000"></span>
<span style="color: #19177C">\u\cdot\nabla\u</span><span style="color: #008000"> </span><span style="color: #666666">=</span><span style="color: #008000"> </span><span style="color: #19177C">\nu\nabla</span><span style="color: #008000">^</span><span style="color: #666666">2</span><span style="color: #19177C">\u</span><span style="color: #008000"> </span><span style="color: #666666">-</span><span style="color: #008000"></span>
<span style="color: #19177C">\frac</span><span style="color: #008000">{</span><span style="color: #666666">1</span><span style="color: #008000">}{</span><span style="color: #19177C">\varrho</span><span style="color: #008000">}</span><span style="color: #19177C">\nabla</span><span style="color: #008000"> p,</span><span style="color: #BA2121">\]</span>
!et
</pre></div>
<p>
and the inline expression <code>$\nabla\u (\pmb{x})\cdot\pmb{n}$</code>
(with suitable newcommands using pmb)
get rendered as

$$ \frac{\partial\u}{\partial t} +
\u\cdot\nabla\u = \nu\nabla^2\u -
\frac{1}{\varrho}\nabla p,$$

and \( \nabla\u (\pmb{x})\cdot\pmb{n} \).

<p>
Somewhat nicer fonts may appear with the more modern <code>\bm</code> command:

<p>

<!-- code=latex (!bc latexcod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>!bt
<span style="color: #BA2121">\[</span><span style="color: #008000"> </span><span style="color: #19177C">\frac</span><span style="color: #008000">{</span><span style="color: #19177C">\partial\ubm</span><span style="color: #008000">}{</span><span style="color: #19177C">\partial</span><span style="color: #008000"> t} </span><span style="color: #666666">+</span><span style="color: #008000"></span>
<span style="color: #19177C">\ubm\cdot\nabla\ubm</span><span style="color: #008000"> </span><span style="color: #666666">=</span><span style="color: #008000"> </span><span style="color: #19177C">\nu\nabla</span><span style="color: #008000">^</span><span style="color: #666666">2</span><span style="color: #19177C">\ubm</span><span style="color: #008000"> </span><span style="color: #666666">-</span><span style="color: #008000"></span>
<span style="color: #19177C">\frac</span><span style="color: #008000">{</span><span style="color: #666666">1</span><span style="color: #008000">}{</span><span style="color: #19177C">\varrho</span><span style="color: #008000">}</span><span style="color: #19177C">\nabla</span><span style="color: #008000"> p,</span><span style="color: #BA2121">\]</span>
!et
</pre></div>
<p>
(backslash <code>ubm</code> is a newcommand for bold math \( u \)), for which we get

$$ \frac{\partial\ubm}{\partial t} +
\ubm\cdot\nabla\ubm = \nu\nabla^2\ubm -
\frac{1}{\varrho}\nabla p.$$

Moreover,

<p>

<!-- code=text typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>$\nabla\boldsymbol{u}(\boldsymbol{x})\cdot\boldsymbol{n}$
</pre></div>
<p>
becomes \( \nabla\boldsymbol{u}(\boldsymbol{x})\cdot\boldsymbol{n} \).

<p>
<div class="alert alert-block alert-warning alert-text-normal">
<b>Warning</b>
<p>
Note: for the html format, <code>\bm</code> was substituted by DocOnce
to <code>\boldsymbol</code>.
</div>


<h1 id="problematic-equations">Problematic equations </h1>

<p>
Finally, we collect some problematic formulas in MathJax. They all work
fine in LaTeX. Most of them look fine in html too, but some fail in
sphinx, ipynb, or markdown.

<h2 id="colored-terms-in-equations">Colored terms in equations </h2>

<p>
The LaTeX code

<p>

<!-- code=latex (!bc latexcod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>!bt
<span style="color: #BA2121">\[</span><span style="color: #008000"> {</span><span style="color: #19177C">\color</span><span style="color: #008000">{blue}</span><span style="color: #19177C">\frac</span><span style="color: #008000">{</span><span style="color: #19177C">\partial\u</span><span style="color: #008000">}{</span><span style="color: #19177C">\partial</span><span style="color: #008000"> t}} </span><span style="color: #666666">+</span><span style="color: #008000"></span>
<span style="color: #19177C">\nabla\cdot\nabla\u</span><span style="color: #008000"> </span><span style="color: #666666">=</span><span style="color: #008000"> </span><span style="color: #19177C">\nu\nabla</span><span style="color: #008000">^</span><span style="color: #666666">2</span><span style="color: #19177C">\u</span><span style="color: #008000"> </span><span style="color: #666666">-</span><span style="color: #008000"></span>
<span style="color: #19177C">\frac</span><span style="color: #008000">{</span><span style="color: #666666">1</span><span style="color: #008000">}{</span><span style="color: #19177C">\varrho</span><span style="color: #008000">}</span><span style="color: #19177C">\nabla</span><span style="color: #008000"> p,</span><span style="color: #BA2121">\]</span>
!et
</pre></div>
<p>
results in

$$ {\color{blue}\frac{\partial\u}{\partial t}} +
\nabla\cdot\nabla\u = \nu\nabla^2\u -
\frac{1}{\varrho}\nabla p,$$

<h2 id="bar-over-symbols">Bar over symbols </h2>

<p>
Sometimes one must be extra careful with the LaTeX syntax to get sphinx MathJax
to render a formula correctly. Consider the combination of a bar over a
bold math symbol:

<p>

<!-- code=latex (!bc latexcod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>!bt
<span style="color: #BA2121">\[</span><span style="color: #008000"> </span><span style="color: #19177C">\bar\f</span><span style="color: #008000"> </span><span style="color: #666666">=</span><span style="color: #008000"> f_c^{</span><span style="color: #666666">-1</span><span style="color: #008000">}</span><span style="color: #19177C">\f</span><span style="color: #008000">,</span><span style="color: #BA2121">\]</span>
!et
</pre></div>
<p>
which for html output results in

$$ \bar\f = f_c^{-1}\f.$$

<p>
With sphinx, this formula is not rendered. However, using curly braces for the bar,

<p>

<!-- code=latex (!bc latexcod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>!bt
<span style="color: #BA2121">\[</span><span style="color: #008000"> </span><span style="color: #19177C">\bar</span><span style="color: #008000">{</span><span style="color: #19177C">\f</span><span style="color: #008000">} </span><span style="color: #666666">=</span><span style="color: #008000"> f_c^{</span><span style="color: #666666">-1</span><span style="color: #008000">}</span><span style="color: #19177C">\f</span><span style="color: #008000">,</span><span style="color: #BA2121">\]</span>
!et
</pre></div>
<p>
makes the output correct also for sphinx:

$$ \bar{\f} = f_c^{-1}\f,$$

<h2 id="matrix-formulas">Matrix formulas </h2>

<p>
Here is an <code>align</code> environment with a label and the <code>pmatrix</code>
environment for matrices and vectors in LaTeX.

<p>

<!-- code=latex (!bc latexcod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>!bt
<span style="color: #008000; font-weight: bold">\begin</span><span style="color: #008000">{</span>align<span style="color: #008000">}</span>
<span style="color: #008000; font-weight: bold">\begin</span><span style="color: #008000">{</span>pmatrix<span style="color: #008000">}</span>
G<span style="color: #008000">_</span>2 + G<span style="color: #008000">_</span>3 <span style="color: #008000">&amp;</span> -G<span style="color: #008000">_</span>3 <span style="color: #008000">&amp;</span> -G<span style="color: #008000">_</span>2 <span style="color: #008000">&amp;</span> 0 <span style="color: #008000; font-weight: bold">\\</span> 
-G<span style="color: #008000">_</span>3 <span style="color: #008000">&amp;</span> G<span style="color: #008000">_</span>3 + G<span style="color: #008000">_</span>4 <span style="color: #008000">&amp;</span> 0 <span style="color: #008000">&amp;</span> -G<span style="color: #008000">_</span>4 <span style="color: #008000; font-weight: bold">\\</span> 
-G<span style="color: #008000">_</span>2 <span style="color: #008000">&amp;</span> 0 <span style="color: #008000">&amp;</span> G<span style="color: #008000">_</span>1 + G<span style="color: #008000">_</span>2 <span style="color: #008000">&amp;</span> 0 <span style="color: #008000; font-weight: bold">\\</span> 
0 <span style="color: #008000">&amp;</span> -G<span style="color: #008000">_</span>4 <span style="color: #008000">&amp;</span> 0 <span style="color: #008000">&amp;</span> G<span style="color: #008000">_</span>4
<span style="color: #008000; font-weight: bold">\end</span><span style="color: #008000">{</span>pmatrix<span style="color: #008000">}</span>
<span style="color: #008000">&amp;</span>=
<span style="color: #008000; font-weight: bold">\begin</span><span style="color: #008000">{</span>pmatrix<span style="color: #008000">}</span>
v<span style="color: #008000">_</span>1 <span style="color: #008000; font-weight: bold">\\</span> 
v<span style="color: #008000">_</span>2 <span style="color: #008000; font-weight: bold">\\</span> 
v<span style="color: #008000">_</span>3 <span style="color: #008000; font-weight: bold">\\</span> 
v<span style="color: #008000">_</span>4
<span style="color: #008000; font-weight: bold">\end</span><span style="color: #008000">{</span>pmatrix<span style="color: #008000">}</span>
+ <span style="color: #008000; font-weight: bold">\cdots</span>
label<span style="color: #008000">{</span>mymatrixeq<span style="color: #008000">}</span><span style="color: #008000; font-weight: bold">\\</span> 
<span style="color: #008000; font-weight: bold">\begin</span><span style="color: #008000">{</span>pmatrix<span style="color: #008000">}</span>
C<span style="color: #008000">_</span>5 + C<span style="color: #008000">_</span>6 <span style="color: #008000">&amp;</span> -C<span style="color: #008000">_</span>6 <span style="color: #008000">&amp;</span> 0 <span style="color: #008000">&amp;</span> 0 <span style="color: #008000; font-weight: bold">\\</span> 
-C<span style="color: #008000">_</span>6 <span style="color: #008000">&amp;</span> C<span style="color: #008000">_</span>6 <span style="color: #008000">&amp;</span> 0 <span style="color: #008000">&amp;</span> 0 <span style="color: #008000; font-weight: bold">\\</span> 
0 <span style="color: #008000">&amp;</span> 0 <span style="color: #008000">&amp;</span> 0 <span style="color: #008000">&amp;</span> 0 <span style="color: #008000; font-weight: bold">\\</span> 
0 <span style="color: #008000">&amp;</span> 0 <span style="color: #008000">&amp;</span> 0 <span style="color: #008000">&amp;</span> 0
<span style="color: #008000; font-weight: bold">\end</span><span style="color: #008000">{</span>pmatrix<span style="color: #008000">}</span>
<span style="color: #008000; font-weight: bold">\frac</span><span style="color: #008000">{</span>d<span style="color: #008000">}{</span>dt<span style="color: #008000">}</span> <span style="color: #008000">&amp;</span>=
<span style="color: #008000; font-weight: bold">\begin</span><span style="color: #008000">{</span>pmatrix<span style="color: #008000">}</span>
v<span style="color: #008000">_</span>1 <span style="color: #008000; font-weight: bold">\\</span> 
v<span style="color: #008000">_</span>2 <span style="color: #008000; font-weight: bold">\\</span> 
v<span style="color: #008000">_</span>3 <span style="color: #008000; font-weight: bold">\\</span> 
v<span style="color: #008000">_</span>4
<span style="color: #008000; font-weight: bold">\end</span><span style="color: #008000">{</span>pmatrix<span style="color: #008000">}</span> =
<span style="color: #008000; font-weight: bold">\begin</span><span style="color: #008000">{</span>pmatrix<span style="color: #008000">}</span>
0 <span style="color: #008000; font-weight: bold">\\</span> 
0 <span style="color: #008000; font-weight: bold">\\</span> 
0 <span style="color: #008000; font-weight: bold">\\</span> 
-i<span style="color: #008000">_</span>0
<span style="color: #008000; font-weight: bold">\end</span><span style="color: #008000">{</span>pmatrix<span style="color: #008000">}</span>
<span style="color: #008000; font-weight: bold">\end</span><span style="color: #008000">{</span>align<span style="color: #008000">}</span>
!et
</pre></div>
<p>
which becomes

$$
\begin{align}
\begin{pmatrix}
G_2 + G_3 & -G_3 & -G_2 & 0 \\ 
-G_3 & G_3 + G_4 & 0 & -G_4 \\ 
-G_2 & 0 & G_1 + G_2 & 0 \\ 
0 & -G_4 & 0 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
v_1 \\ 
v_2 \\ 
v_3 \\ 
v_4
\end{pmatrix}
+ \cdots
\label{_mymatrixeq}\\ 
\begin{pmatrix}
C_5 + C_6 & -C_6 & 0 & 0 \\ 
-C_6 & C_6 & 0 & 0 \\ 
0 & 0 & 0 & 0 \\ 
0 & 0 & 0 & 0
\end{pmatrix}
\frac{d}{dt} &=
\begin{pmatrix}
v_1 \\ 
v_2 \\ 
v_3 \\ 
v_4
\end{pmatrix} =
\begin{pmatrix}
0 \\ 
0 \\ 
0 \\ 
-i_0
\end{pmatrix}
\end{align}$$

<p>
The same matrices without labels in an <code>align*</code> environment:

<p>

<!-- code=latex (!bc latexcod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>!bt
<span style="color: #008000; font-weight: bold">\begin</span><span style="color: #008000">{</span>align*<span style="color: #008000">}</span>
<span style="color: #008000; font-weight: bold">\begin</span><span style="color: #008000">{</span>pmatrix<span style="color: #008000">}</span>
G<span style="color: #008000">_</span>2 + G<span style="color: #008000">_</span>3 <span style="color: #008000">&amp;</span> -G<span style="color: #008000">_</span>3 <span style="color: #008000">&amp;</span> -G<span style="color: #008000">_</span>2 <span style="color: #008000">&amp;</span> 0 <span style="color: #008000; font-weight: bold">\\</span> 
-G<span style="color: #008000">_</span>3 <span style="color: #008000">&amp;</span> G<span style="color: #008000">_</span>3 + G<span style="color: #008000">_</span>4 <span style="color: #008000">&amp;</span> 0 <span style="color: #008000">&amp;</span> -G<span style="color: #008000">_</span>4 <span style="color: #008000; font-weight: bold">\\</span> 
-G<span style="color: #008000">_</span>2 <span style="color: #008000">&amp;</span> 0 <span style="color: #008000">&amp;</span> G<span style="color: #008000">_</span>1 + G<span style="color: #008000">_</span>2 <span style="color: #008000">&amp;</span> 0 <span style="color: #008000; font-weight: bold">\\</span> 
0 <span style="color: #008000">&amp;</span> -G<span style="color: #008000">_</span>4 <span style="color: #008000">&amp;</span> 0 <span style="color: #008000">&amp;</span> G<span style="color: #008000">_</span>4
<span style="color: #008000; font-weight: bold">\end</span><span style="color: #008000">{</span>pmatrix<span style="color: #008000">}</span>
<span style="color: #008000">&amp;</span>=
<span style="color: #008000; font-weight: bold">\begin</span><span style="color: #008000">{</span>pmatrix<span style="color: #008000">}</span>
v<span style="color: #008000">_</span>1 <span style="color: #008000; font-weight: bold">\\</span> 
v<span style="color: #008000">_</span>2 <span style="color: #008000; font-weight: bold">\\</span> 
v<span style="color: #008000">_</span>3 <span style="color: #008000; font-weight: bold">\\</span> 
v<span style="color: #008000">_</span>4
<span style="color: #008000; font-weight: bold">\end</span><span style="color: #008000">{</span>pmatrix<span style="color: #008000">}</span>
+ <span style="color: #008000; font-weight: bold">\cdots</span> <span style="color: #008000; font-weight: bold">\\</span> 
<span style="color: #008000; font-weight: bold">\begin</span><span style="color: #008000">{</span>pmatrix<span style="color: #008000">}</span>
C<span style="color: #008000">_</span>5 + C<span style="color: #008000">_</span>6 <span style="color: #008000">&amp;</span> -C<span style="color: #008000">_</span>6 <span style="color: #008000">&amp;</span> 0 <span style="color: #008000">&amp;</span> 0 <span style="color: #008000; font-weight: bold">\\</span> 
-C<span style="color: #008000">_</span>6 <span style="color: #008000">&amp;</span> C<span style="color: #008000">_</span>6 <span style="color: #008000">&amp;</span> 0 <span style="color: #008000">&amp;</span> 0 <span style="color: #008000; font-weight: bold">\\</span> 
0 <span style="color: #008000">&amp;</span> 0 <span style="color: #008000">&amp;</span> 0 <span style="color: #008000">&amp;</span> 0 <span style="color: #008000; font-weight: bold">\\</span> 
0 <span style="color: #008000">&amp;</span> 0 <span style="color: #008000">&amp;</span> 0 <span style="color: #008000">&amp;</span> 0
<span style="color: #008000; font-weight: bold">\end</span><span style="color: #008000">{</span>pmatrix<span style="color: #008000">}</span>
<span style="color: #008000; font-weight: bold">\frac</span><span style="color: #008000">{</span>d<span style="color: #008000">}{</span>dt<span style="color: #008000">}</span> <span style="color: #008000">&amp;</span>=
<span style="color: #008000; font-weight: bold">\begin</span><span style="color: #008000">{</span>pmatrix<span style="color: #008000">}</span>
v<span style="color: #008000">_</span>1 <span style="color: #008000; font-weight: bold">\\</span> 
v<span style="color: #008000">_</span>2 <span style="color: #008000; font-weight: bold">\\</span> 
v<span style="color: #008000">_</span>3 <span style="color: #008000; font-weight: bold">\\</span> 
v<span style="color: #008000">_</span>4
<span style="color: #008000; font-weight: bold">\end</span><span style="color: #008000">{</span>pmatrix<span style="color: #008000">}</span> =
<span style="color: #008000; font-weight: bold">\begin</span><span style="color: #008000">{</span>pmatrix<span style="color: #008000">}</span>
0 <span style="color: #008000; font-weight: bold">\\</span> 
0 <span style="color: #008000; font-weight: bold">\\</span> 
0 <span style="color: #008000; font-weight: bold">\\</span> 
-i<span style="color: #008000">_</span>0
<span style="color: #008000; font-weight: bold">\end</span><span style="color: #008000">{</span>pmatrix<span style="color: #008000">}</span>
<span style="color: #008000; font-weight: bold">\end</span><span style="color: #008000">{</span>align*<span style="color: #008000">}</span>
!et
</pre></div>
<p>
The rendered result becomes

$$
\begin{align*}
\begin{pmatrix}
G_2 + G_3 & -G_3 & -G_2 & 0 \\ 
-G_3 & G_3 + G_4 & 0 & -G_4 \\ 
-G_2 & 0 & G_1 + G_2 & 0 \\ 
0 & -G_4 & 0 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
v_1 \\ 
v_2 \\ 
v_3 \\ 
v_4
\end{pmatrix}
+ \cdots \\ 
\begin{pmatrix}
C_5 + C_6 & -C_6 & 0 & 0 \\ 
-C_6 & C_6 & 0 & 0 \\ 
0 & 0 & 0 & 0 \\ 
0 & 0 & 0 & 0
\end{pmatrix}
\frac{d}{dt} &=
\begin{pmatrix}
v_1 \\ 
v_2 \\ 
v_3 \\ 
v_4
\end{pmatrix} =
\begin{pmatrix}
0 \\ 
0 \\ 
0 \\ 
-i_0
\end{pmatrix}
\end{align*}
$$


<!-- ------------------- end of main content --------------- -->


</body>
</html>
    


************** File: math_test_pandoc.html *****************
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  <meta http-equiv="Content-Style-Type" content="text/css" />
  <meta name="generator" content="pandoc" />
  <meta name="author" content="Hans Petter Langtangen at Simula Research Laboratory and University of Oslo" />
  <title>How various formats can deal with LaTeX math</title>
  <style type="text/css">code{white-space: pre;}</style>
  
<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  TeX: {
     equationNumbers: {  autoNumber: "AMS"  },
     extensions: ["AMSmath.js", "AMSsymbols.js", "autobold.js", "color.js"]
  }
});
</script>
<script src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS_CHTML-full" type="text/javascript"></script>
</head>
<body>
<div id="header">
<h1 class="title">How various formats can deal with LaTeX math</h1>
<h2 class="author"><strong>Hans Petter Langtangen</strong> at Simula Research Laboratory and University of Oslo</h2>
<h3 class="date">Jan 32, 2100</h3>
</div>
<p><em>Summary.</em> The purpose of this document is to test LaTeX math in DocOnce with various output formats. Most LaTeX math constructions are renedered correctly by MathJax in plain HTML, but some combinations of constructions may fail. Unfortunately, only a subset of what works in html MathJax also works in sphinx MathJax. The same is true for markdown MathJax expresions (e.g., Jupyter notebooks). Tests and examples are provided to illustrate what may go wrong.</p>
<p>The recommendation for writing math that translates to MathJax in html, sphinx, and markdown is to stick to the environments <code>\[ ... \]</code>, <code>equation</code>, <code>equation*</code>, <code>align</code>, <code>align*</code>, <code>alignat</code>, and <code>alignat*</code> only. Test the math with sphinx output; if it works in that format, it should work elsewhere too.</p>
<p>The current version of the document is translated from DocOnce source to the format <strong>pandoc</strong>.</p>
<h2 id="test-of-equation-environments">Test of equation environments</h2>
<h3 id="test-1-inline-math">Test 1: Inline math</h3>
<p>We can get an inline equation <code>$u(t)=e^{-at}$</code> rendered as <span class="math inline">\(u(t)=e^{-at}\)</span>.</p>
<h3 id="test-2-a-single-equation-with-label">Test 2: A single equation with label</h3>
<p>An equation with number,</p>
<pre><code>!bt
\begin{equation} u(t)=e^{-at} \label{eq1a}\end{equation}
!et</code></pre>
<p>looks like</p>
<p><span class="math display">\[
\begin{equation} u(t)=e^{-at} \label{_eq1a}\end{equation}
\]</span> Maybe this multi-line version is what we actually prefer to write:</p>
<pre><code>!bt
\begin{equation}
u(t)=e^{-at}
\label{eq1b}
\end{equation}
!et</code></pre>
<p>The result is the same:</p>
<p><span class="math display">\[
\begin{equation}
u(t)=e^{-at} \label{_eq1b}
\end{equation}
\]</span> We can refer to this equation through its label <code>eq1b</code>: (<a href="#_eq1b">_eq1b</a>).</p>
<h3 id="test-3-multiple-aligned-equations-without-label-and-number">Test 3: Multiple, aligned equations without label and number</h3>
<p>MathJax has historically had some problems with rendering many LaTeX math environments, but the <code>align*</code> and <code>align</code> environments have always worked.</p>
<pre><code>!bt
\begin{align*}
u(t)&amp;=e^{-at}\\ 
v(t) - 1 &amp;= \frac{du}{dt}
\end{align*}
!et</code></pre>
<p>Result:</p>
<p><span class="math display">\[
\begin{align*}
u(t)&amp;=e^{-at}\\ 
v(t) - 1 &amp;= \frac{du}{dt}
\end{align*}
\]</span></p>
<h3 id="test-4-multiple-aligned-equations-with-label">Test 4: Multiple, aligned equations with label</h3>
<p>Here, we use <code>align</code> with user-prescribed labels:</p>
<pre><code>!bt
\begin{align}
u(t)&amp;=e^{-at}
\label{eq2b}\\ 
v(t) - 1 &amp;= \frac{du}{dt}
\label{eq3b}
\end{align}
!et</code></pre>
<p>Result:</p>
<p><span class="math display">\[
\begin{align}
u(t)&amp;=e^{-at}
\label{_eq2b}\\ 
v(t) - 1 &amp;= \frac{du}{dt}
\label{_eq3b}
\end{align}
\]</span> We can refer to the last equations as the system (<a href="#_eq2b">_eq2b</a>)-(<a href="#_eq3b">_eq3b</a>).</p>
<h3 id="test-5-multiple-aligned-equations-without-label">Test 5: Multiple, aligned equations without label</h3>
<p>In LaTeX, equations within an <code>align</code> environment is automatically given numbers. To ensure that an html document with MathJax gets the same equation numbers as its latex/pdflatex companion, DocOnce generates labels in equations where there is no label prescribed. For example,</p>
<pre><code>!bt
\begin{align}
u(t)&amp;=e^{-at}
\\ 
v(t) - 1 &amp;= \frac{du}{dt}
\end{align}
!et</code></pre>
<p>is edited to something like</p>
<pre><code>!bt
\begin{align}
u(t)&amp;=e^{-at}
\label{_auto5}\\ 
v(t) - 1 &amp;= \frac{du}{dt}
\label{_auto6}
\end{align}
!et</code></pre>
<p>and the output gets the two equation numbered.</p>
<p><span class="math display">\[
\begin{align}
u(t)&amp;=e^{-at}\\ 
v(t) - 1 &amp;= \frac{du}{dt}
\end{align}
\]</span></p>
<h3 id="test-6-multiple-aligned-equations-with-multiple-alignments">Test 6: Multiple, aligned equations with multiple alignments</h3>
<p>The <code>align</code> environment can be used with two <code>&amp;</code> alignment characters, e.g.,</p>
<pre><code>!bt
\begin{align}
\frac{\partial u}{\partial t} &amp;= \nabla^2 u, &amp; x\in (0,L),
\ t\in (0,T]\\ 
u(0,t) &amp;= u_0(x), &amp; x\in [0,L]
\end{align}
!et</code></pre>
<p>The result in pandoc becomes</p>
<p><span class="math display">\[
\begin{align}
\frac{\partial u}{\partial t} &amp;= \nabla^2 u, &amp; x\in (0,L),
\ t\in (0,T]\\ 
u(0,t) &amp;= u_0(x), &amp; x\in [0,L]
\end{align}
\]</span></p>
<p>A better solution is usually to use an <code>alignat</code> environment:</p>
<pre><code>!bt
\begin{alignat}{2}
\frac{\partial u}{\partial t} &amp;= \nabla^2 u, &amp; x\in (0,L),
\ t\in (0,T]\\ 
u(0,t) &amp;= u_0(x), &amp; x\in [0,L]
\end{alignat}
!et</code></pre>
<p>with the rendered result</p>
<p><span class="math display">\[
\begin{alignat}{2}
\frac{\partial u}{\partial t} &amp;= \nabla^2 u, &amp; x\in (0,L),
\ t\in (0,T]\\ 
u(0,t) &amp;= u_0(x), &amp; x\in [0,L]
\end{alignat}
\]</span></p>
<p>If DocOnce had not rewritten the above equations, they would be rendered in pandoc as</p>
<p><span class="math display">\[
\begin{alignat}{2}
\frac{\partial u}{\partial t} &amp;= \nabla^2 u, &amp; x\in (0,L),
\ t\in (0,T]\\ 
u(0,t) &amp;= u_0(x), &amp; x\in [0,L]
\end{alignat}
\]</span></p>
<h3 id="test-7-multiple-aligned-eqnarray-equations-without-label">Test 7: Multiple, aligned eqnarray equations without label</h3>
<p>Let us try the old <code>eqnarray*</code> environment.</p>
<pre><code>!bt
\begin{eqnarray*}
u(t)&amp;=&amp; e^{-at}\\ 
v(t) - 1 &amp;=&amp; \frac{du}{dt}
\end{eqnarray*}
!et</code></pre>
<p>which results in</p>
<p><span class="math display">\[
\begin{eqnarray*}
u(t)&amp;=&amp; e^{-at}\\ 
v(t) - 1 &amp;=&amp; \frac{du}{dt}
\end{eqnarray*}
\]</span></p>
<h3 id="test-8-multiple-eqnarrayed-equations-with-label">Test 8: Multiple, eqnarrayed equations with label</h3>
<p>Here we use <code>eqnarray</code> with labels:</p>
<pre><code>!bt
\begin{eqnarray}
u(t)&amp;=&amp; e^{-at}
\label{eq2c}\\ 
v(t) - 1 &amp;=&amp; \frac{du}{dt}
\label{eq3c}
\end{eqnarray}
!et</code></pre>
<p>which results in</p>
<p><span class="math display">\[
\begin{eqnarray}
u(t)&amp;=&amp; e^{-at} \label{_eq2c}\\ 
v(t) - 1 &amp;=&amp; \frac{du}{dt} \label{_eq3c}
\end{eqnarray}
\]</span> Can we refer to the last equations as the system (<a href="#_eq2c">_eq2c</a>)-(<a href="#_eq3c">_eq3c</a>) in the pandoc format?</p>
<h3 id="test-9-the-multiline-environment-with-label-and-number">Test 9: The <code>multiline</code> environment with label and number</h3>
<p>The LaTeX code</p>
<pre><code>!bt
\begin{multline}
\int_a^b f(x)dx = \sum_{j=0}^{n} \frac{1}{2} h(f(a+jh) +
f(a+(j+1)h)) \\ 
=\frac{h}{2}f(a) + \frac{h}{2}f(b) + \sum_{j=1}^n f(a+jh)
\label{multiline:eq1}
\end{multline}
!et</code></pre>
<p>gets rendered as</p>
<p><span class="math display">\[
\begin{multline}
\int_a^b f(x)dx = \sum_{j=0}^{n} \frac{1}{2} h(f(a+jh) +
f(a+(j+1)h)) \\ 
=\frac{h}{2}f(a) + \frac{h}{2}f(b) + \sum_{j=1}^n f(a+jh)
\label{_multiline:eq1}
\end{multline}
\]</span> and we can hopefully refer to the Trapezoidal rule as the formula (<a href="#_multiline:eq1">_multiline:eq1</a>).</p>
<h3 id="test-10-splitting-equations-using-a-split-environment">Test 10: Splitting equations using a split environment</h3>
<p>Although <code>align</code> can be used to split too long equations, a more obvious command is <code>split</code>:</p>
<pre><code>!bt
\begin{equation}
\begin{split}
\int_a^b f(x)dx = \sum_{j=0}^{n} \frac{1}{2} h(f(a+jh) +
f(a+(j+1)h)) \\ 
=\frac{h}{2}f(a) + \frac{h}{2}f(b) + \sum_{j=1}^n f(a+jh)
\end{split}
\end{equation}
!et</code></pre>
<p>The result becomes</p>
<p><span class="math display">\[
\begin{equation}
\begin{split}
\int_a^b f(x)dx = \sum_{j=0}^{n} \frac{1}{2} h(f(a+jh) +
f(a+(j+1)h)) \\ 
=\frac{h}{2}f(a) + \frac{h}{2}f(b) + \sum_{j=1}^n f(a+jh)
\end{split}
\end{equation}
\]</span></p>
<h3 id="test-11-newcommands-and-boldface-bm-vs-pmb">Test 11: Newcommands and boldface bm vs pmb</h3>
<p>First we use the plain old pmb package for bold math. The formula</p>
<pre><code>!bt
\[ \frac{\partial\u}{\partial t} +
\u\cdot\nabla\u = \nu\nabla^2\u -
\frac{1}{\varrho}\nabla p,\]
!et</code></pre>
<p>and the inline expression <code>$\nabla\pmb{u} (\pmb{x})\cdot\pmb{n}$</code> (with suitable newcommands using pmb) get rendered as</p>
<p><span class="math display">\[
 \frac{\partial\pmb{u}}{\partial t} +
\pmb{u}\cdot\nabla\pmb{u} = \nu\nabla^2\pmb{u} -
\frac{1}{\varrho}\nabla p,
\]</span> and <span class="math inline">\(\nabla\pmb{u} (\pmb{x})\cdot\pmb{n}\)</span>.</p>
<p>Somewhat nicer fonts may appear with the more modern <code>\bm</code> command:</p>
<pre><code>!bt
\[ \frac{\partial\ubm}{\partial t} +
\ubm\cdot\nabla\ubm = \nu\nabla^2\ubm -
\frac{1}{\varrho}\nabla p,\]
!et</code></pre>
<p>(backslash <code>ubm</code> is a newcommand for bold math <span class="math inline">\(u\)</span>), for which we get</p>
<p><span class="math display">\[
 \frac{\partial\boldsymbol{u}}{\partial t} +
\boldsymbol{u}\cdot\nabla\boldsymbol{u} = \nu\nabla^2\boldsymbol{u} -
\frac{1}{\varrho}\nabla p.
\]</span> Moreover,</p>
<pre><code>$\nabla\boldsymbol{u}(\boldsymbol{x})\cdot\boldsymbol{n}$</code></pre>
<p>becomes <span class="math inline">\(\nabla\boldsymbol{u}(\boldsymbol{x})\cdot\boldsymbol{n}\)</span>.</p>
<p><em>Warning.</em> Note: for the pandoc format, <code>\bm</code> was substituted by DocOnce to <code>\boldsymbol</code>.</p>
<h2 id="problematic-equations">Problematic equations</h2>
<p>Finally, we collect some problematic formulas in MathJax. They all work fine in LaTeX. Most of them look fine in html too, but some fail in sphinx, ipynb, or markdown.</p>
<h3 id="colored-terms-in-equations">Colored terms in equations</h3>
<p>The LaTeX code</p>
<pre><code>!bt
\[ {\color{blue}\frac{\partial\u}{\partial t}} +
\nabla\cdot\nabla\u = \nu\nabla^2\u -
\frac{1}{\varrho}\nabla p,\]
!et</code></pre>
<p>results in</p>
<p><span class="math display">\[
 {\color{blue}\frac{\partial\pmb{u}}{\partial t}} +
\nabla\cdot\nabla\pmb{u} = \nu\nabla^2\pmb{u} -
\frac{1}{\varrho}\nabla p,
\]</span></p>
<h3 id="bar-over-symbols">Bar over symbols</h3>
<p>Sometimes one must be extra careful with the LaTeX syntax to get sphinx MathJax to render a formula correctly. Consider the combination of a bar over a bold math symbol:</p>
<pre><code>!bt
\[ \bar\f = f_c^{-1}\f,\]
!et</code></pre>
<p>which for pandoc output results in</p>
<p><span class="math display">\[
 \bar\boldsymbol{f} = f_c^{-1}\boldsymbol{f}.
\]</span></p>
<p>With sphinx, this formula is not rendered. However, using curly braces for the bar,</p>
<pre><code>!bt
\[ \bar{\f} = f_c^{-1}\f,\]
!et</code></pre>
<p>makes the output correct also for sphinx:</p>
<p><span class="math display">\[
 \bar{\boldsymbol{f}} = f_c^{-1}\boldsymbol{f},
\]</span></p>
<h3 id="matrix-formulas">Matrix formulas</h3>
<p>Here is an <code>align</code> environment with a label and the <code>pmatrix</code> environment for matrices and vectors in LaTeX.</p>
<pre><code>!bt
\begin{align}
\begin{pmatrix}
G_2 + G_3 &amp; -G_3 &amp; -G_2 &amp; 0 \\ 
-G_3 &amp; G_3 + G_4 &amp; 0 &amp; -G_4 \\ 
-G_2 &amp; 0 &amp; G_1 + G_2 &amp; 0 \\ 
0 &amp; -G_4 &amp; 0 &amp; G_4
\end{pmatrix}
&amp;=
\begin{pmatrix}
v_1 \\ 
v_2 \\ 
v_3 \\ 
v_4
\end{pmatrix}
+ \cdots
\label{mymatrixeq}\\ 
\begin{pmatrix}
C_5 + C_6 &amp; -C_6 &amp; 0 &amp; 0 \\ 
-C_6 &amp; C_6 &amp; 0 &amp; 0 \\ 
0 &amp; 0 &amp; 0 &amp; 0 \\ 
0 &amp; 0 &amp; 0 &amp; 0
\end{pmatrix}
\frac{d}{dt} &amp;=
\begin{pmatrix}
v_1 \\ 
v_2 \\ 
v_3 \\ 
v_4
\end{pmatrix} =
\begin{pmatrix}
0 \\ 
0 \\ 
0 \\ 
-i_0
\end{pmatrix}
\end{align}
!et</code></pre>
<p>which becomes</p>
<p><span class="math display">\[
\begin{align}
\begin{pmatrix}
G_2 + G_3 &amp; -G_3 &amp; -G_2 &amp; 0 \\ 
-G_3 &amp; G_3 + G_4 &amp; 0 &amp; -G_4 \\ 
-G_2 &amp; 0 &amp; G_1 + G_2 &amp; 0 \\ 
0 &amp; -G_4 &amp; 0 &amp; G_4
\end{pmatrix}
&amp;=
\begin{pmatrix}
v_1 \\ 
v_2 \\ 
v_3 \\ 
v_4
\end{pmatrix}
+ \cdots
\label{_mymatrixeq}\\ 
\begin{pmatrix}
C_5 + C_6 &amp; -C_6 &amp; 0 &amp; 0 \\ 
-C_6 &amp; C_6 &amp; 0 &amp; 0 \\ 
0 &amp; 0 &amp; 0 &amp; 0 \\ 
0 &amp; 0 &amp; 0 &amp; 0
\end{pmatrix}
\frac{d}{dt} &amp;=
\begin{pmatrix}
v_1 \\ 
v_2 \\ 
v_3 \\ 
v_4
\end{pmatrix} =
\begin{pmatrix}
0 \\ 
0 \\ 
0 \\ 
-i_0
\end{pmatrix}
\end{align}
\]</span></p>
<p>The same matrices without labels in an <code>align*</code> environment:</p>
<pre><code>!bt
\begin{align*}
\begin{pmatrix}
G_2 + G_3 &amp; -G_3 &amp; -G_2 &amp; 0 \\ 
-G_3 &amp; G_3 + G_4 &amp; 0 &amp; -G_4 \\ 
-G_2 &amp; 0 &amp; G_1 + G_2 &amp; 0 \\ 
0 &amp; -G_4 &amp; 0 &amp; G_4
\end{pmatrix}
&amp;=
\begin{pmatrix}
v_1 \\ 
v_2 \\ 
v_3 \\ 
v_4
\end{pmatrix}
+ \cdots \\ 
\begin{pmatrix}
C_5 + C_6 &amp; -C_6 &amp; 0 &amp; 0 \\ 
-C_6 &amp; C_6 &amp; 0 &amp; 0 \\ 
0 &amp; 0 &amp; 0 &amp; 0 \\ 
0 &amp; 0 &amp; 0 &amp; 0
\end{pmatrix}
\frac{d}{dt} &amp;=
\begin{pmatrix}
v_1 \\ 
v_2 \\ 
v_3 \\ 
v_4
\end{pmatrix} =
\begin{pmatrix}
0 \\ 
0 \\ 
0 \\ 
-i_0
\end{pmatrix}
\end{align*}
!et</code></pre>
<p>The rendered result becomes</p>
<p><span class="math display">\[
\begin{align*}
\begin{pmatrix}
G_2 + G_3 &amp; -G_3 &amp; -G_2 &amp; 0 \\ 
-G_3 &amp; G_3 + G_4 &amp; 0 &amp; -G_4 \\ 
-G_2 &amp; 0 &amp; G_1 + G_2 &amp; 0 \\ 
0 &amp; -G_4 &amp; 0 &amp; G_4
\end{pmatrix}
&amp;=
\begin{pmatrix}
v_1 \\ 
v_2 \\ 
v_3 \\ 
v_4
\end{pmatrix}
+ \cdots \\ 
\begin{pmatrix}
C_5 + C_6 &amp; -C_6 &amp; 0 &amp; 0 \\ 
-C_6 &amp; C_6 &amp; 0 &amp; 0 \\ 
0 &amp; 0 &amp; 0 &amp; 0 \\ 
0 &amp; 0 &amp; 0 &amp; 0
\end{pmatrix}
\frac{d}{dt} &amp;=
\begin{pmatrix}
v_1 \\ 
v_2 \\ 
v_3 \\ 
v_4
\end{pmatrix} =
\begin{pmatrix}
0 \\ 
0 \\ 
0 \\ 
-i_0
\end{pmatrix}
\end{align*}
\]</span></p>
</body>
</html>

************** File: math_test.p.tex *****************
%%
%% Automatically generated file from DocOnce source
%% (https://github.com/hplgit/doconce/)
%%
%%
% #ifdef PTEX2TEX_EXPLANATION
%%
%% The file follows the ptex2tex extended LaTeX format, see
%% ptex2tex: https://code.google.com/p/ptex2tex/
%%
%% Run
%%      ptex2tex myfile
%% or
%%      doconce ptex2tex myfile
%%
%% to turn myfile.p.tex into an ordinary LaTeX file myfile.tex.
%% (The ptex2tex program: https://code.google.com/p/ptex2tex)
%% Many preprocess options can be added to ptex2tex or doconce ptex2tex
%%
%%      ptex2tex -DMINTED myfile
%%      doconce ptex2tex myfile envir=minted
%%
%% ptex2tex will typeset code environments according to a global or local
%% .ptex2tex.cfg configure file. doconce ptex2tex will typeset code
%% according to options on the command line (just type doconce ptex2tex to
%% see examples). If doconce ptex2tex has envir=minted, it enables the
%% minted style without needing -DMINTED.
% #endif

% #define PREAMBLE

% #ifdef PREAMBLE
%-------------------- begin preamble ----------------------

\documentclass[%
oneside,                 % oneside: electronic viewing, twoside: printing
final,                   % draft: marks overfull hboxes, figures with paths
10pt]{article}

\listfiles               %  print all files needed to compile this document

\usepackage{relsize,makeidx,color,setspace,amsmath,amsfonts,amssymb}
\usepackage[table]{xcolor}
\usepackage{bm,ltablex,microtype}

\usepackage[pdftex]{graphicx}

\usepackage{ptex2tex}
% #ifdef MINTED
\usepackage{minted}
\usemintedstyle{default}
% #endif
\usepackage{fancyvrb}

\usepackage[T1]{fontenc}
%\usepackage[latin1]{inputenc}
\usepackage{ucs}
\usepackage[utf8x]{inputenc}

\usepackage{lmodern}         % Latin Modern fonts derived from Computer Modern

% Hyperlinks in PDF:
\definecolor{linkcolor}{rgb}{0,0,0.4}
\usepackage{hyperref}
\hypersetup{
    breaklinks=true,
    colorlinks=true,
    linkcolor=linkcolor,
    urlcolor=linkcolor,
    citecolor=black,
    filecolor=black,
    %filecolor=blue,
    pdfmenubar=true,
    pdftoolbar=true,
    bookmarksdepth=3   % Uncomment (and tweak) for PDF bookmarks with more levels than the TOC
    }
%\hyperbaseurl{}   % hyperlinks are relative to this root

\setcounter{tocdepth}{2}  % levels in table of contents

% prevent orhpans and widows
\clubpenalty = 10000
\widowpenalty = 10000

% --- end of standard preamble for documents ---


% insert custom LaTeX commands...

\raggedbottom
\makeindex
\usepackage[totoc]{idxlayout}   % for index in the toc
\usepackage[nottoc]{tocbibind}  % for references/bibliography in the toc

%-------------------- end preamble ----------------------

\begin{document}

% matching end for #ifdef PREAMBLE
% #endif

\newcommand{\exercisesection}[1]{\subsection*{#1}}

\input{newcommands_bfmath}
\input{newcommands_replace}

% ------------------- main content ----------------------



% ----------------- title -------------------------

\thispagestyle{empty}

\begin{center}
{\LARGE\bf
\begin{spacing}{1.25}
How various formats can deal with {\LaTeX} math
\end{spacing}
}
\end{center}

% ----------------- author(s) -------------------------

\begin{center}
{\bf Hans Petter Langtangen${}^{1, 2}$} \\ [0mm]
\end{center}

\begin{center}
% List of all institutions:
\centerline{{\small ${}^1$Simula Research Laboratory}}
\centerline{{\small ${}^2$University of Oslo}}
\end{center}
    
% ----------------- end author(s) -------------------------

% --- begin date ---
\begin{center}
Jan 32, 2100
\end{center}
% --- end date ---

\vspace{1cm}

\begin{abstract}
The purpose of this document is to test {\LaTeX} math in DocOnce with
various output formats.  Most {\LaTeX} math constructions are renedered
correctly by MathJax in plain HTML, but some combinations of
constructions may fail.  Unfortunately, only a subset of what works in
html MathJax also works in sphinx MathJax. The same is true for
markdown MathJax expresions (e.g., Jupyter notebooks).  Tests and
examples are provided to illustrate what may go wrong.

The recommendation for writing math that translates to MathJax in
html, sphinx, and markdown is to stick to the environments \Verb!\[ ... \]!, \texttt{equation}, \texttt{equation*}, \texttt{align}, \texttt{align*}, \texttt{alignat}, and
\texttt{alignat*} only. Test the math with sphinx output; if it works in that
format, it should work elsewhere too.

The current version of the document is translated from DocOnce source
to the format \textbf{pdflatex}.
\end{abstract}

\section{Test of equation environments}

\subsection{Test 1: Inline math}

We can get an inline equation
\Verb!$u(t)=e^{-at}$! rendered as $u(t)=e^{-at}$.

\subsection{Test 2: A single equation with label}

An equation with number,

\blatexcod
!bt
\begin{equation} u(t)=e^{-at} label{eq1a}\end{equation}
!et
\elatexcod
looks like

\begin{equation} u(t)=e^{-at} \label{_eq1a}\end{equation}
Maybe this multi-line version is what we actually prefer to write:

\blatexcod
!bt
\begin{equation}
u(t)=e^{-at}
label{eq1b}
\end{equation}
!et
\elatexcod
The result is the same:

\begin{equation}
u(t)=e^{-at} \label{_eq1b}
\end{equation}
We can refer to this equation through its label \texttt{eq1b}: (\ref{_eq1b}).


\subsection{Test 3: Multiple, aligned equations without label and number}

MathJax has historically had some problems with rendering many {\LaTeX}
math environments, but the \texttt{align*} and \texttt{align} environments have
always worked.

\blatexcod
!bt
\begin{align*}
u(t)&=e^{-at}\\ 
v(t) - 1 &= \frac{du}{dt}
\end{align*}
!et
\elatexcod
Result:

\begin{align*}
u(t)&=e^{-at}\\ 
v(t) - 1 &= \frac{du}{dt}
\end{align*}

\subsection{Test 4: Multiple, aligned equations with label}

Here, we use \texttt{align} with user-prescribed labels:

\blatexcod
!bt
\begin{align}
u(t)&=e^{-at}
label{eq2b}\\ 
v(t) - 1 &= \frac{du}{dt}
label{eq3b}
\end{align}
!et
\elatexcod
Result:

\begin{align}
u(t)&=e^{-at}
\label{_eq2b}\\ 
v(t) - 1 &= \frac{du}{dt}
\label{_eq3b}
\end{align}
We can refer to the last equations as the system (\ref{_eq2b})-(\ref{_eq3b}).




\subsection{Test 5: Multiple, aligned equations without label}

In {\LaTeX}, equations within an \texttt{align} environment is automatically
given numbers.  To ensure that an html document with MathJax gets the
same equation numbers as its latex/pdflatex companion, DocOnce
generates labels in equations where there is no label prescribed. For
example,

\blatexcod
!bt
\begin{align}
u(t)&=e^{-at}
\\ 
v(t) - 1 &= \frac{du}{dt}
\end{align}
!et
\elatexcod
is edited to something like

\blatexcod
!bt
\begin{align}
u(t)&=e^{-at}
label{_auto5}\\ 
v(t) - 1 &= \frac{du}{dt}
label{_auto6}
\end{align}
!et
\elatexcod
and the output gets the two equation numbered.

\begin{align}
u(t)&=e^{-at}\\ 
v(t) - 1 &= \frac{du}{dt}
\end{align}

\subsection{Test 6: Multiple, aligned equations with multiple alignments}

The \texttt{align} environment can be used with two \Verb!&! alignment characters, e.g.,

\blatexcod
!bt
\begin{align}
\frac{\partial u}{\partial t} &= \nabla^2 u, & x\in (0,L),
\ t\in (0,T]\\ 
u(0,t) &= u_0(x), & x\in [0,L]
\end{align}
!et
\elatexcod
The result in pdflatex becomes

\begin{align}
\frac{\partial u}{\partial t} &= \nabla^2 u, & x\in (0,L),
\ t\in (0,T]\\ 
u(0,t) &= u_0(x), & x\in [0,L]
\end{align}

A better solution is usually to use an \texttt{alignat} environment:

\blatexcod
!bt
\begin{alignat}{2}
\frac{\partial u}{\partial t} &= \nabla^2 u, & x\in (0,L),
\ t\in (0,T]\\ 
u(0,t) &= u_0(x), & x\in [0,L]
\end{alignat}
!et
\elatexcod
with the rendered result

\begin{alignat}{2}
\frac{\partial u}{\partial t} &= \nabla^2 u, & x\in (0,L),
\ t\in (0,T]\\ 
u(0,t) &= u_0(x), & x\in [0,L]
\end{alignat}







\subsection{Test 7: Multiple, aligned eqnarray equations without label}

Let us try the old \texttt{eqnarray*} environment.

\blatexcod
!bt
\begin{eqnarray*}
u(t)&=& e^{-at}\\ 
v(t) - 1 &=& \frac{du}{dt}
\end{eqnarray*}
!et
\elatexcod
which results in

\begin{eqnarray*}
u(t)&=& e^{-at}\\ 
v(t) - 1 &=& \frac{du}{dt}
\end{eqnarray*}

\subsection{Test 8: Multiple, eqnarrayed equations with label}

Here we use \texttt{eqnarray} with labels:

\blatexcod
!bt
\begin{eqnarray}
u(t)&=& e^{-at}
label{eq2c}\\ 
v(t) - 1 &=& \frac{du}{dt}
label{eq3c}
\end{eqnarray}
!et
\elatexcod
which results in

\begin{eqnarray}
u(t)&=& e^{-at} \label{_eq2c}\\ 
v(t) - 1 &=& \frac{du}{dt} \label{_eq3c}
\end{eqnarray}
Can we refer to the last equations as the system (\ref{_eq2c})-(\ref{_eq3c})
in the pdflatex format?

\subsection{Test 9: The \texttt{multiline} environment with label and number}

The {\LaTeX} code

\blatexcod
!bt
\begin{multline}
\int_a^b f(x)dx = \sum_{j=0}^{n} \frac{1}{2} h(f(a+jh) +
f(a+(j+1)h)) \\ 
=\frac{h}{2}f(a) + \frac{h}{2}f(b) + \sum_{j=1}^n f(a+jh)
label{multiline:eq1}
\end{multline}
!et
\elatexcod
gets rendered as

\begin{multline}
\int_a^b f(x)dx = \sum_{j=0}^{n} \frac{1}{2} h(f(a+jh) +
f(a+(j+1)h)) \\ 
=\frac{h}{2}f(a) + \frac{h}{2}f(b) + \sum_{j=1}^n f(a+jh)
\label{_multiline:eq1}
\end{multline}
and we can hopefully refer to the Trapezoidal rule
as the formula (\ref{_multiline:eq1}).


\subsection{Test 10: Splitting equations using a split environment}

Although \texttt{align} can be used to split too long equations, a more obvious
command is \texttt{split}:

\blatexcod
!bt
\begin{equation}
\begin{split}
\int_a^b f(x)dx = \sum_{j=0}^{n} \frac{1}{2} h(f(a+jh) +
f(a+(j+1)h)) \\ 
=\frac{h}{2}f(a) + \frac{h}{2}f(b) + \sum_{j=1}^n f(a+jh)
\end{split}
\end{equation}
!et
\elatexcod

The result becomes

\begin{equation}
\begin{split}
\int_a^b f(x)dx = \sum_{j=0}^{n} \frac{1}{2} h(f(a+jh) +
f(a+(j+1)h)) \\ 
=\frac{h}{2}f(a) + \frac{h}{2}f(b) + \sum_{j=1}^n f(a+jh)
\end{split}
\end{equation}

\subsection{Test 11: Newcommands and boldface bm vs pmb}

First we use the plain old pmb package for bold math. The formula

\blatexcod
!bt
\[ \frac{\partial\u}{\partial t} +
\u\cdot\nabla\u = \nu\nabla^2\u -
\frac{1}{\varrho}\nabla p,\]
!et
\elatexcod
and the inline expression \Verb!$\nabla\u (\x)\cdot\normalvec$!
(with suitable newcommands using pmb)
get rendered as

\[ \frac{\partial\u}{\partial t} +
\u\cdot\nabla\u = \nu\nabla^2\u -
\frac{1}{\varrho}\nabla p,\]
and $\nabla\u (\x)\cdot\normalvec$.

Somewhat nicer fonts may appear with the more modern \Verb!\bm! command:

\blatexcod
!bt
\[ \frac{\partial\ubm}{\partial t} +
\ubm\cdot\nabla\ubm = \nu\nabla^2\ubm -
\frac{1}{\varrho}\nabla p,\]
!et
\elatexcod
(backslash \texttt{ubm} is a newcommand for bold math $u$), for which we get

\[ \frac{\partial\ubm}{\partial t} +
\ubm\cdot\nabla\ubm = \nu\nabla^2\ubm -
\frac{1}{\varrho}\nabla p.\]
Moreover,

\bccq
$\nabla\bm{u}(\bm{x})\cdot\bm{n}$
\eccq
becomes $\nabla\bm{u}(\bm{x})\cdot\bm{n}$.



\section{Problematic equations}

Finally, we collect some problematic formulas in MathJax. They all work
fine in {\LaTeX}. Most of them look fine in html too, but some fail in
sphinx, ipynb, or markdown.

\subsection{Colored terms in equations}

The {\LaTeX} code

\blatexcod
!bt
\[ {\color{blue}\frac{\partial\u}{\partial t}} +
\nabla\cdot\nabla\u = \nu\nabla^2\u -
\frac{1}{\varrho}\nabla p,\]
!et
\elatexcod

results in

\[ {\color{blue}\frac{\partial\u}{\partial t}} +
\nabla\cdot\nabla\u = \nu\nabla^2\u -
\frac{1}{\varrho}\nabla p,\]

\subsection{Bar over symbols}

Sometimes one must be extra careful with the {\LaTeX} syntax to get sphinx MathJax
to render a formula correctly. Consider the combination of a bar over a
bold math symbol:

\blatexcod
!bt
\[ \bar\f = f_c^{-1}\f,\]
!et
\elatexcod

which for pdflatex output results in

\[ \bar\f = f_c^{-1}\f.\]

With sphinx, this formula is not rendered. However, using curly braces for the bar,

\blatexcod
!bt
\[ \bar{\f} = f_c^{-1}\f,\]
!et
\elatexcod

makes the output correct also for sphinx:

\[ \bar{\f} = f_c^{-1}\f,\]


\subsection{Matrix formulas}

Here is an \texttt{align} environment with a label and the \texttt{pmatrix}
environment for matrices and vectors in {\LaTeX}.

\blatexcod
!bt
\begin{align}
\begin{pmatrix}
G_2 + G_3 & -G_3 & -G_2 & 0 \\ 
-G_3 & G_3 + G_4 & 0 & -G_4 \\ 
-G_2 & 0 & G_1 + G_2 & 0 \\ 
0 & -G_4 & 0 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
v_1 \\ 
v_2 \\ 
v_3 \\ 
v_4
\end{pmatrix}
+ \cdots
label{mymatrixeq}\\ 
\begin{pmatrix}
C_5 + C_6 & -C_6 & 0 & 0 \\ 
-C_6 & C_6 & 0 & 0 \\ 
0 & 0 & 0 & 0 \\ 
0 & 0 & 0 & 0
\end{pmatrix}
\frac{d}{dt} &=
\begin{pmatrix}
v_1 \\ 
v_2 \\ 
v_3 \\ 
v_4
\end{pmatrix} =
\begin{pmatrix}
0 \\ 
0 \\ 
0 \\ 
-i_0
\end{pmatrix}
\end{align}
!et
\elatexcod

which becomes

\begin{align}
\begin{pmatrix}
G_2 + G_3 & -G_3 & -G_2 & 0 \\ 
-G_3 & G_3 + G_4 & 0 & -G_4 \\ 
-G_2 & 0 & G_1 + G_2 & 0 \\ 
0 & -G_4 & 0 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
v_1 \\ 
v_2 \\ 
v_3 \\ 
v_4
\end{pmatrix}
+ \cdots
\label{_mymatrixeq}\\ 
\begin{pmatrix}
C_5 + C_6 & -C_6 & 0 & 0 \\ 
-C_6 & C_6 & 0 & 0 \\ 
0 & 0 & 0 & 0 \\ 
0 & 0 & 0 & 0
\end{pmatrix}
\frac{d}{dt} &=
\begin{pmatrix}
v_1 \\ 
v_2 \\ 
v_3 \\ 
v_4
\end{pmatrix} =
\begin{pmatrix}
0 \\ 
0 \\ 
0 \\ 
-i_0
\end{pmatrix}
\end{align}

The same matrices without labels in an \texttt{align*} environment:

\blatexcod
!bt
\begin{align*}
\begin{pmatrix}
G_2 + G_3 & -G_3 & -G_2 & 0 \\ 
-G_3 & G_3 + G_4 & 0 & -G_4 \\ 
-G_2 & 0 & G_1 + G_2 & 0 \\ 
0 & -G_4 & 0 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
v_1 \\ 
v_2 \\ 
v_3 \\ 
v_4
\end{pmatrix}
+ \cdots \\ 
\begin{pmatrix}
C_5 + C_6 & -C_6 & 0 & 0 \\ 
-C_6 & C_6 & 0 & 0 \\ 
0 & 0 & 0 & 0 \\ 
0 & 0 & 0 & 0
\end{pmatrix}
\frac{d}{dt} &=
\begin{pmatrix}
v_1 \\ 
v_2 \\ 
v_3 \\ 
v_4
\end{pmatrix} =
\begin{pmatrix}
0 \\ 
0 \\ 
0 \\ 
-i_0
\end{pmatrix}
\end{align*}
!et
\elatexcod

The rendered result becomes

\begin{align*}
\begin{pmatrix}
G_2 + G_3 & -G_3 & -G_2 & 0 \\ 
-G_3 & G_3 + G_4 & 0 & -G_4 \\ 
-G_2 & 0 & G_1 + G_2 & 0 \\ 
0 & -G_4 & 0 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
v_1 \\ 
v_2 \\ 
v_3 \\ 
v_4
\end{pmatrix}
+ \cdots \\ 
\begin{pmatrix}
C_5 + C_6 & -C_6 & 0 & 0 \\ 
-C_6 & C_6 & 0 & 0 \\ 
0 & 0 & 0 & 0 \\ 
0 & 0 & 0 & 0
\end{pmatrix}
\frac{d}{dt} &=
\begin{pmatrix}
v_1 \\ 
v_2 \\ 
v_3 \\ 
v_4
\end{pmatrix} =
\begin{pmatrix}
0 \\ 
0 \\ 
0 \\ 
-i_0
\end{pmatrix}
\end{align*}

% ------------------- end of main content ---------------

% #ifdef PREAMBLE
\end{document}
% #endif


************** File: math_test.rst *****************
.. Automatically generated Sphinx-extended reStructuredText file from DocOnce source
   (https://github.com/hplgit/doconce/)

.. Document title:

How various formats can deal with LaTeX math
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

:Authors: Hans Petter Langtangen
:Date: Jan 32, 2100

*Summary.* The purpose of this document is to test LaTeX math in DocOnce with
various output formats.  Most LaTeX math constructions are renedered
correctly by MathJax in plain HTML, but some combinations of
constructions may fail.  Unfortunately, only a subset of what works in
html MathJax also works in sphinx MathJax. The same is true for
markdown MathJax expresions (e.g., Jupyter notebooks).  Tests and
examples are provided to illustrate what may go wrong.

The recommendation for writing math that translates to MathJax in
html, sphinx, and markdown is to stick to the environments ``\[
... \]``, ``equation``, ``equation*``, ``align``, ``align*``, ``alignat``, and
``alignat*`` only. Test the math with sphinx output; if it works in that
format, it should work elsewhere too.

The current version of the document is translated from DocOnce source
to the format **sphinx**.

Test of equation environments
=============================

Test 1: Inline math
-------------------

We can get an inline equation
``$u(t)=e^{-at}$`` rendered as :math:`u(t)=e^{-at}`.

Test 2: A single equation with label
------------------------------------

An equation with number,

.. code-block:: latex

    !bt
    \begin{equation} u(t)=e^{-at} label{eq1a}\end{equation}
    !et

looks like

.. math::
   :label: _eq1a

         u(t)=e^{-at} 

Maybe this multi-line version is what we actually prefer to write:

.. code-block:: latex

    !bt
    \begin{equation}
    u(t)=e^{-at}
    label{eq1b}
    \end{equation}
    !et

The result is the same:

.. math::
   :label: _eq1b

        
        u(t)=e^{-at} 
        

We can refer to this equation through its label ``eq1b``: :eq:`_eq1b`.

Test 3: Multiple, aligned equations without label and number
------------------------------------------------------------

MathJax has historically had some problems with rendering many LaTeX
math environments, but the ``align*`` and ``align`` environments have
always worked.

.. code-block:: latex

    !bt
    \begin{align*}
    u(t)&=e^{-at}\\ 
    v(t) - 1 &= \frac{du}{dt}
    \end{align*}
    !et

Result:

.. math::
        \begin{align*}
        u(t)&=e^{-at}\\ 
        v(t) - 1 &= \frac{du}{dt}
        \end{align*}

Test 4: Multiple, aligned equations with label
----------------------------------------------

Here, we use ``align`` with user-prescribed labels:

.. code-block:: latex

    !bt
    \begin{align}
    u(t)&=e^{-at}
    label{eq2b}\\ 
    v(t) - 1 &= \frac{du}{dt}
    label{eq3b}
    \end{align}
    !et

Result:

.. math::
   :label: _eq2b

        
        u(t)=e^{-at}
        
        

.. math::
   :label: _eq3b

          
        v(t) - 1 = \frac{du}{dt}
        
        

We can refer to the last equations as the system :eq:`_eq2b`-:eq:`_eq3b`.


.. admonition:: Note: align/alignat environments with labels are anti-aligned in sphinx

   Actually, *sphinx does not support the align environment with labels*,
   such as we write above,
   but DocOnce splits in this case the equations into separate, single equations
   with labels. Hence the user can write one code with align and labels
   and have it automatically
   to work in latex, html, sphinx, notebooks, and other formats.
   The generated sphinx code in the present case is
   
   .. code-block:: rst
   
       .. math::
          :label: eq2b
       
               u(t)=e^{-at}
       
       
       .. math::
          :label: eq3b
       
               v(t) - 1 = \frac{du}{dt}




If DocOnce had not rewritten the equation it would be rendered in
sphinx as nicely aligned equations without numbers (i.e., as if
we had used the ``align*`` environment):

.. math::

        \begin{align}
        u(t)&=e^{-at}
        \\\ 
        v(t) - 1 &= \frac{du}{dt}
        \
        \end{align}

Test 5: Multiple, aligned equations without label
-------------------------------------------------

In LaTeX, equations within an ``align`` environment is automatically
given numbers.  To ensure that an html document with MathJax gets the
same equation numbers as its latex/pdflatex companion, DocOnce
generates labels in equations where there is no label prescribed. For
example,

.. code-block:: latex

    !bt
    \begin{align}
    u(t)&=e^{-at}
    \\ 
    v(t) - 1 &= \frac{du}{dt}
    \end{align}
    !et

is edited to something like

.. code-block:: latex

    !bt
    \begin{align}
    u(t)&=e^{-at}
    label{_auto5}\\ 
    v(t) - 1 &= \frac{du}{dt}
    label{_auto6}
    \end{align}
    !et

and the output gets the two equation numbered.
Note that in sphinx the alignment is removed and separate ``equation``
environments are used to get numbered equations in equation systems, cf. the
box above.

.. math::
   :label: _auto1

        
        u(t)=e^{-at}
        
        

.. math::
   :label: _auto2

          
        v(t) - 1 = \frac{du}{dt}
        
        

Test 6: Multiple, aligned equations with multiple alignments
------------------------------------------------------------

The ``align`` environment can be used with two ``&`` alignment characters, e.g.,

.. code-block:: latex

    !bt
    \begin{align}
    \frac{\partial u}{\partial t} &= \nabla^2 u, & x\in (0,L),
    \ t\in (0,T]\\ 
    u(0,t) &= u_0(x), & x\in [0,L]
    \end{align}
    !et

The result in sphinx becomes

.. math::
   :label: _auto3

        
        \frac{\partial u}{\partial t} = \nabla^2 u,  x\in (0,L),
        \ t\in (0,T]
        
        

.. math::
   :label: _auto4

          
        u(0,t) = u_0(x),  x\in [0,L]
        
        

In sphinx, all alignments are removed, so this double use of ``&``
results in ugly typesetting!

A better solution is usually to use an ``alignat`` environment:

.. code-block:: latex

    !bt
    \begin{alignat}{2}
    \frac{\partial u}{\partial t} &= \nabla^2 u, & x\in (0,L),
    \ t\in (0,T]\\ 
    u(0,t) &= u_0(x), & x\in [0,L]
    \end{alignat}
    !et

with the rendered result

.. math::
   :label: _auto5

        
        \frac{\partial u}{\partial t} = \nabla^2 u,  x\in (0,L),
        \ t\in (0,T]
        
        

.. math::
   :label: _auto6

          
        u(0,t) = u_0(x),  x\in [0,L]
        
        


.. admonition:: align/alignat environments with equation numbers are anti-aligned

   In the ``sphinx``, ``ipynb``, and ``pandoc`` output formats, DocOnce rewrites
   the equations in an ``alignat`` environment as individual equations in
   ``equation`` environments (or more precisely, ``sphinx`` can work with
   ``alignat*`` so only numbered ``alignat`` equations get rewritten as individual
   equations). If the alignment is somewhat important, try the best with a
   manual rewrite in terms of separate ``equation`` environments, and stick to
   ``align*`` and ``alignat*`` in ``sphinx``.




With ``alignat*`` in sphinx, the equations above are typeset nicely as

.. math::
        \begin{alignat*}{2}
        \frac{\partial u}{\partial t} &= \nabla^2 u, & x\in (0,L),
        \ t\in (0,T]\\ 
        u(0,t) &= u_0(x), & x\in [0,L]
        \end{alignat*}

Note that if DocOnce had not rewritten of the above equations, they would be
rendered similarly in sphinx as

.. math::

        \begin{alignat}{2}
        \frac{\partial u}{\partial t} &= \nabla^2 u, & x\in (0,L),
        \ t\in (0,T]\\ 
        u(0,t) &= u_0(x), & x\in [0,L]
        \end{alignat}

That is, the equation numbers are gone.

Test 7: Multiple, aligned eqnarray equations without label
----------------------------------------------------------

Let us try the old ``eqnarray*`` environment.

.. code-block:: latex

    !bt
    \begin{eqnarray*}
    u(t)&=& e^{-at}\\ 
    v(t) - 1 &=& \frac{du}{dt}
    \end{eqnarray*}
    !et

which results in

.. math::
        \begin{eqnarray*}
        u(t) &=  e^{-at}\\ 
        v(t) - 1  &=  \frac{du}{dt}
        \end{eqnarray*}

Test 8: Multiple, eqnarrayed equations with label
-------------------------------------------------

Here we use ``eqnarray`` with labels:

.. code-block:: latex

    !bt
    \begin{eqnarray}
    u(t)&=& e^{-at}
    label{eq2c}\\ 
    v(t) - 1 &=& \frac{du}{dt}
    label{eq3c}
    \end{eqnarray}
    !et

which results in

.. math::
        \begin{eqnarray}
        u(t) &=  e^{-at} \\ 
        v(t) - 1  &=  \frac{du}{dt} 
        \end{eqnarray}

Can we refer to the last equations as the system :eq:`_eq2c`-:eq:`_eq3c`
in the sphinx format?
No, unfortunately not. Sphinx cannot deal with equation numbers in
``eqnarray`` environments and typeset them as if they were ``eqnarray*``.
But MathJax supports ``eqnarray`` with labels.
The rule of thumb is to use ``align`` and not ``eqnarray``!

Test 9: The ``multiline`` environment with label and number
-----------------------------------------------------------

The LaTeX code

.. code-block:: latex

    !bt
    \begin{multline}
    \int_a^b f(x)dx = \sum_{j=0}^{n} \frac{1}{2} h(f(a+jh) +
    f(a+(j+1)h)) \\ 
    =\frac{h}{2}f(a) + \frac{h}{2}f(b) + \sum_{j=1}^n f(a+jh)
    label{multiline:eq1}
    \end{multline}
    !et

gets rendered as

.. math::
   :label: _multiline:eq1

        
        \int_a^b f(x)dx = \sum_{j=0}^{n} \frac{1}{2} h(f(a+jh) +
        f(a+(j+1)h)) \\ 
        =\frac{h}{2}f(a) + \frac{h}{2}f(b) + \sum_{j=1}^n f(a+jh)
        
        

and we can hopefully refer to the Trapezoidal rule
as the formula :eq:`_multiline:eq1`.

This equation will not render in sphinx unless we remove the ``multiline``
environment, which means that it was typeset here without any multiline
information.
The best cross-format solution is to use ``align`` instead of ``multiline``
with ``\nonumber`` in the first equation!

Test 10: Splitting equations using a split environment
------------------------------------------------------

Although ``align`` can be used to split too long equations, a more obvious
command is ``split``:

.. code-block:: latex

    !bt
    \begin{equation}
    \begin{split}
    \int_a^b f(x)dx = \sum_{j=0}^{n} \frac{1}{2} h(f(a+jh) +
    f(a+(j+1)h)) \\ 
    =\frac{h}{2}f(a) + \frac{h}{2}f(b) + \sum_{j=1}^n f(a+jh)
    \end{split}
    \end{equation}
    !et

The result becomes

.. math::
   :label: _auto7

        
        \begin{split}
        \int_a^b f(x)dx = \sum_{j=0}^{n} \frac{1}{2} h(f(a+jh) +
        f(a+(j+1)h)) \\ 
        =\frac{h}{2}f(a) + \frac{h}{2}f(b) + \sum_{j=1}^n f(a+jh)
        \end{split}
        
        

Test 11: Newcommands and boldface bm vs pmb
-------------------------------------------

First we use the plain old pmb package for bold math. The formula

.. code-block:: latex

    !bt
    \[ \frac{\partial\u}{\partial t} +
    \u\cdot\nabla\u = \nu\nabla^2\u -
    \frac{1}{\varrho}\nabla p,\]
    !et

and the inline expression ``$\nabla\pmb{u} (\pmb{x})\cdot\pmb{n}$``
(with suitable newcommands using pmb)
get rendered as

.. math::
         \frac{\partial\pmb{u}}{\partial t} +
        \pmb{u}\cdot\nabla\pmb{u} = \nu\nabla^2\pmb{u} -
        \frac{1}{\varrho}\nabla p,

and :math:`\nabla\pmb{u} (\pmb{x})\cdot\pmb{n}`.
DocOnce replaces newcommands by the actual latex code when requesting
the sphinx output format.

Somewhat nicer fonts may appear with the more modern ``\bm`` command:

.. code-block:: latex

    !bt
    \[ \frac{\partial\ubm}{\partial t} +
    \ubm\cdot\nabla\ubm = \nu\nabla^2\ubm -
    \frac{1}{\varrho}\nabla p,\]
    !et

(backslash ``ubm`` is a newcommand for bold math :math:`u`), for which we get

.. math::
         \frac{\partial\boldsymbol{u}}{\partial t} +
        \boldsymbol{u}\cdot\nabla\boldsymbol{u} = \nu\nabla^2\boldsymbol{u} -
        \frac{1}{\varrho}\nabla p.

Moreover,

.. code-block:: text

    $\nabla\boldsymbol{u}(\boldsymbol{x})\cdot\boldsymbol{n}$

becomes :math:`\nabla\boldsymbol{u}(\boldsymbol{x})\cdot\boldsymbol{n}`.


.. warning::
    Note: for the sphinx format, ``\bm`` was substituted by DocOnce
    to ``\boldsymbol``.




Problematic equations
=====================

Finally, we collect some problematic formulas in MathJax. They all work
fine in LaTeX. Most of them look fine in html too, but some fail in
sphinx, ipynb, or markdown.

Colored terms in equations
--------------------------

The LaTeX code

.. code-block:: latex

    !bt
    \[ {\color{blue}\frac{\partial\u}{\partial t}} +
    \nabla\cdot\nabla\u = \nu\nabla^2\u -
    \frac{1}{\varrho}\nabla p,\]
    !et

results in

.. math::
         {\color{blue}\frac{\partial\pmb{u}}{\partial t}} +
        \nabla\cdot\nabla\pmb{u} = \nu\nabla^2\pmb{u} -
        \frac{1}{\varrho}\nabla p,

but correct rendering in sphinx requires omitting the ``\color`` command:

.. math::
         \frac{\partial\pmb{u}}{\partial t} +
        \nabla\cdot\nabla\pmb{u} = \nu\nabla^2\pmb{u} -
        \frac{1}{\varrho}\nabla p,

Bar over symbols
----------------

Sometimes one must be extra careful with the LaTeX syntax to get sphinx MathJax
to render a formula correctly. Consider the combination of a bar over a
bold math symbol:

.. code-block:: latex

    !bt
    \[ \bar\f = f_c^{-1}\f,\]
    !et

which for sphinx output results in

.. math::
         \bar\boldsymbol{f} = f_c^{-1}\boldsymbol{f}.

With sphinx, this formula is not rendered. However, using curly braces for the bar,

.. code-block:: latex

    !bt
    \[ \bar{\f} = f_c^{-1}\f,\]
    !et

makes the output correct also for sphinx:

.. math::
         \bar{\boldsymbol{f}} = f_c^{-1}\boldsymbol{f},

Matrix formulas
---------------

Here is an ``align`` environment with a label and the ``pmatrix``
environment for matrices and vectors in LaTeX.

.. code-block:: latex

    !bt
    \begin{align}
    \begin{pmatrix}
    G_2 + G_3 & -G_3 & -G_2 & 0 \\ 
    -G_3 & G_3 + G_4 & 0 & -G_4 \\ 
    -G_2 & 0 & G_1 + G_2 & 0 \\ 
    0 & -G_4 & 0 & G_4
    \end{pmatrix}
    &=
    \begin{pmatrix}
    v_1 \\ 
    v_2 \\ 
    v_3 \\ 
    v_4
    \end{pmatrix}
    + \cdots
    label{mymatrixeq}\\ 
    \begin{pmatrix}
    C_5 + C_6 & -C_6 & 0 & 0 \\ 
    -C_6 & C_6 & 0 & 0 \\ 
    0 & 0 & 0 & 0 \\ 
    0 & 0 & 0 & 0
    \end{pmatrix}
    \frac{d}{dt} &=
    \begin{pmatrix}
    v_1 \\ 
    v_2 \\ 
    v_3 \\ 
    v_4
    \end{pmatrix} =
    \begin{pmatrix}
    0 \\ 
    0 \\ 
    0 \\ 
    -i_0
    \end{pmatrix}
    \end{align}
    !et

which becomes

.. math::
   :label: _mymatrixeq

        
        \begin{pmatrix}
        G_2 + G_3 & -G_3 & -G_2 & 0 \\ 
        -G_3 & G_3 + G_4 & 0 & -G_4 \\ 
        -G_2 & 0 & G_1 + G_2 & 0 \\ 
        0 & -G_4 & 0 & G_4
        \end{pmatrix}
        =
        \begin{pmatrix}
        v_1 \\ 
        v_2 \\ 
        v_3 \\ 
        v_4
        \end{pmatrix}
        + \cdots
        
        

.. math::
   :label: _auto8

          
        \begin{pmatrix}
        C_5 + C_6 & -C_6 & 0 & 0 \\ 
        -C_6 & C_6 & 0 & 0 \\ 
        0 & 0 & 0 & 0 \\ 
        0 & 0 & 0 & 0
        \end{pmatrix}
        \frac{d}{dt} =
        \begin{pmatrix}
        v_1 \\ 
        v_2 \\ 
        v_3 \\ 
        v_4
        \end{pmatrix} =
        \begin{pmatrix}
        0 \\ 
        0 \\ 
        0 \\ 
        -i_0
        \end{pmatrix}
        
        

The same matrices without labels in an ``align*`` environment:

.. code-block:: latex

    !bt
    \begin{align*}
    \begin{pmatrix}
    G_2 + G_3 & -G_3 & -G_2 & 0 \\ 
    -G_3 & G_3 + G_4 & 0 & -G_4 \\ 
    -G_2 & 0 & G_1 + G_2 & 0 \\ 
    0 & -G_4 & 0 & G_4
    \end{pmatrix}
    &=
    \begin{pmatrix}
    v_1 \\ 
    v_2 \\ 
    v_3 \\ 
    v_4
    \end{pmatrix}
    + \cdots \\ 
    \begin{pmatrix}
    C_5 + C_6 & -C_6 & 0 & 0 \\ 
    -C_6 & C_6 & 0 & 0 \\ 
    0 & 0 & 0 & 0 \\ 
    0 & 0 & 0 & 0
    \end{pmatrix}
    \frac{d}{dt} &=
    \begin{pmatrix}
    v_1 \\ 
    v_2 \\ 
    v_3 \\ 
    v_4
    \end{pmatrix} =
    \begin{pmatrix}
    0 \\ 
    0 \\ 
    0 \\ 
    -i_0
    \end{pmatrix}
    \end{align*}
    !et

The rendered result becomes

.. math::
        \begin{align*}
        \begin{pmatrix}
        G_2 + G_3 & -G_3 & -G_2 & 0 \\ 
        -G_3 & G_3 + G_4 & 0 & -G_4 \\ 
        -G_2 & 0 & G_1 + G_2 & 0 \\ 
        0 & -G_4 & 0 & G_4
        \end{pmatrix}
        &=
        \begin{pmatrix}
        v_1 \\ 
        v_2 \\ 
        v_3 \\ 
        v_4
        \end{pmatrix}
        + \cdots \\ 
        \begin{pmatrix}
        C_5 + C_6 & -C_6 & 0 & 0 \\ 
        -C_6 & C_6 & 0 & 0 \\ 
        0 & 0 & 0 & 0 \\ 
        0 & 0 & 0 & 0
        \end{pmatrix}
        \frac{d}{dt} &=
        \begin{pmatrix}
        v_1 \\ 
        v_2 \\ 
        v_3 \\ 
        v_4
        \end{pmatrix} =
        \begin{pmatrix}
        0 \\ 
        0 \\ 
        0 \\ 
        -i_0
        \end{pmatrix}
        \end{align*}



************** File: testdoc_vagrant.html *****************
<html>
<head>
<!-- Bootstrap style: vagrant 1.0 web pages -->

<!--
This style is adopted from the (now old) vagrant 1.0 web pages.

This style file should be copied and the following elements edited:

Logo heading:

 LogoWord
 withSubWord

Navigation links at the top:

 GO TO 1
 GO TO 2

Footer at the end
-->

<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Doconce: http://code.google.com/p/doconce/" />

<title>A Document for Testing DocOnce</title>

<!-- If you copy the css subdirectory (and, e.g., make optional edits):
<link rel="stylesheet" href="css/twitter_bootstrap.css">
<link rel="stylesheet" href="css/vagrant.css">
Otherwise, rely on the URLs below (vagrant.css adapted to Doconce layout)
-->

<link rel="stylesheet" href="https://raw.githubusercontent.com/hplgit/doconce/master/bundled/html_styles/style_vagrant/css/twitter_bootstrap.css">
<link rel="stylesheet" href="https://raw.githubusercontent.com/hplgit/doconce/master/bundled/html_styles/style_vagrant/css/vagrant.css">

<!-- Define color of headings here (last definition counts) -->
<style type="text/css">
h1, h2, h3, h4, h5, h6 {
  color: #000;     /* black */
  color: #999;     /* gray */
  color: #005580;  /* dark blue */
  color: #08c;     /* characteristic blue */
</style>

<!-- Tools for embedded Bokeh plots -->
<link rel="stylesheet"
      href="https://cdn.pydata.org/bokeh/release/bokeh-0.9.0.min.css"
      type="text/css" />
<script type="text/javascript"
	src="https://cdn.pydata.org/bokeh/release/bokeh-0.9.0.min.js">
</script>
<script type="text/javascript">
  Bokeh.set_log_level("info");
</script>


</head>
<body>

<div class="container">
 <div class="row Header with-border">
  <div class="span3 Module logo">
   <h1><a href="/">LogoWord<span class="subtitle">withSubWord</span></a></h1>
  </div>
  <div class="span9">
   <div class="Module navigation">
   <!-- Navigation at the top of the page -->
    <ul>
     <li> <a href="">GO TO 1</a></li>
     <li> <a href="">GO TO 2</a></li>
    </ul>
   </div>
  </div>
 </div>
</div>


<!-- Here goes the table of contents in the sidebar
     <li class="active"> means dark blue background for current section
-->
<div class="row">
 <div class="span3 Module sidebar">
  <div class="well" style="padding: 8px 0px;">
   <ul class="nav nav-list">
     <!-- navigation toc: --> <li><a href="#table_of_contents" style="font-size: 80%;"><b>Table of contents</b></a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#sec1" style="font-size: 80%;"><b>Section 1</b></a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#subsec1" style="font-size: 80%;">Subsection 1</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#subsec:ex" style="font-size: 80%;">Subsection 2: Testing figures</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#decay:sec:theta" style="font-size: 80%;">The \( \theta \) parameter (not \( \nabla \)?)</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#custom-environments" style="font-size: 80%;">Custom Environments</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#subsec:table" style="font-size: 80%;">Tables</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#a-test-of-verbatim-words-in-heading-with-subscript-a_i-my_file_v1-and-my_file_v2" style="font-size: 80%;">A test of verbatim words in heading with subscript \( a_i \): <code>my_file_v1</code> and <code>my_file_v2</code></a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#_just-bold_" style="font-size: 80%;"><b>Just bold</b></a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#just-emphasize" style="font-size: 80%;"><em>Just emphasize</em></a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#just-verbatim" style="font-size: 80%;"><code>Just verbatim</code></a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#_bold_-beginning" style="font-size: 80%;"><b>Bold</b> beginning</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#emphasize-beginning" style="font-size: 80%;"><em>Emphasize</em> beginning</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#verbatim-beginning" style="font-size: 80%;"><code>Verbatim</code> beginning</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#maybe-_bold-end_" style="font-size: 80%;">Maybe <b>bold end</b></a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#maybe-emphasize-end" style="font-size: 80%;">Maybe <em>emphasize end</em></a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#maybe-verbatim-end" style="font-size: 80%;">Maybe <code>verbatim end</code></a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#the-middle-has-<b>bold</b>-word" style="font-size: 80%;">The middle has <b>bold</b> word</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#the-middle-has-emphasize-word" style="font-size: 80%;">The middle has <em>emphasize</em> word</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#the-middle-has-verbatim-word" style="font-size: 80%;">The middle has <code>verbatim</code> word</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#bibliography-test" style="font-size: 80%;">Bibliography test</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#Example" style="font-size: 80%;">Example 1: Examples can be typeset as exercises</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#user-defined-environments" style="font-size: 80%;">User-defined environments</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#ex:test:1p1" style="font-size: 80%;">Example 1: A test function</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#ex:math:1p1" style="font-size: 80%;">Example 2: Addition</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#subsubsec:ex" style="font-size: 80%;">URLs</a></li>
     </ul>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#latex-mathematics" style="font-size: 80%;"><b>LaTeX Mathematics</b></a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#exercises" style="font-size: 80%;"><b>Exercises</b></a></li>
     <ul class="nav">
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#demo:ex:1" style="font-size: 80%;">Problem 2: Flip a Coin</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#not-an-exercise" style="font-size: 80%;">Not an exercise</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#my:exer1" style="font-size: 80%;">Exercise 3: Test of plain text exercise</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#demo:ex:2" style="font-size: 80%;">Project 4: Compute a Probability</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#proj:circle1" style="font-size: 80%;">Project 5: Explore Distributions of Random Circles</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#exer:dist" style="font-size: 80%;">Exercise 6: Determine some Distance</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#some-exercise-without-the-exercise-prefix" style="font-size: 80%;">Some exercise without the "Exercise:" prefix</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#sec:this:exer:de" style="font-size: 80%;">Exercise 8: Solution of differential equation</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#example-9-just-an-example" style="font-size: 80%;">Example 9: Just an example</a></li>
     </ul>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#here-goes-another-section" style="font-size: 80%;"><b>Here goes another section</b></a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#more-exercises" style="font-size: 80%;"><b>More Exercises</b></a></li>
     <ul class="nav">
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#exer:some:formula" style="font-size: 80%;">Exercise 10: Make references to projects and problems</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#exer:you" style="font-size: 80%;">Project 11: References in a headings do not work well in html</a></li>
     </ul>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#references" style="font-size: 80%;"><b>References</b></a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#app1" style="font-size: 80%;"><b>Appendix: Just for testing; part I</b></a></li>
     <ul class="nav">
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#a-subsection-within-an-appendix" style="font-size: 80%;">A subsection within an appendix</a></li>
     </ul>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#app2" style="font-size: 80%;"><b>Appendix: Just for testing; part II</b></a></li>
     <ul class="nav">
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant003.html#appendix-testing-identical-titles" style="font-size: 80%;">Appendix: Testing identical titles</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#test:title:id1" style="font-size: 80%;">Appendix: Testing identical titles</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#test:title:id2" style="font-size: 80%;">Appendix: Testing identical titles</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant003.html#appendix-testing-identical-titles" style="font-size: 80%;">Appendix: Testing identical titles</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant003.html#appendix-testing-inline-comments" style="font-size: 80%;">Appendix: Testing inline comments</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant003.html#appendix-testing-headings-ending-with-verbatim-inline" style="font-size: 80%;">Appendix: Testing headings ending with <code>verbatim inline</code></a></li>

   </ul>
  </div>
 </div>

 <div class="span9">

<!-- tocinfo
{'highest level': 1,
 'sections': [('Table of contents',
               1,
               'table_of_contents',
               'table_of_contents'),
              ('Section 1', 1, 'sec1', 'sec1'),
              ('Here is a list with subsubsection heading',
               3,
               None,
               'here-is-a-list-with-subsubsection-heading'),
              ('Subsection 1', 2, 'subsec1', 'subsec1'),
              ('Test Section reference at beginning of line and after a '
               'sentence',
               3,
               None,
               'test-section-reference-at-beginning-of-line-and-after-a-sentence'),
              ('Computer code', 3, None, 'computer-code'),
              ('Subsubsection heading before code',
               3,
               None,
               'subsubsection-heading-before-code'),
              ('Running OS commands', 3, None, 'running-os-commands'),
              ('Footnotes', 3, None, 'footnotes'),
              ('Subsection 2: Testing figures', 2, 'subsec:ex', 'subsec:ex'),
              ('The $\\theta$ parameter (not $\\nabla$?)',
               2,
               'decay:sec:theta',
               'decay:sec:theta'),
              ('Custom Environments', 2, None, 'custom-environments'),
              ('Tables', 2, 'subsec:table', 'subsec:table'),
              ('A test of verbatim words in heading with subscript $a_i$: '
               '`my_file_v1` and `my_file_v2`',
               2,
               None,
               'a-test-of-verbatim-words-in-heading-with-subscript-a_i-my_file_v1-and-my_file_v2'),
              ('_Just bold_', 2, None, '_just-bold_'),
              ('*Just emphasize*', 2, None, 'just-emphasize'),
              ('`Just verbatim`', 2, None, 'just-verbatim'),
              ('_Bold_ beginning', 2, None, '_bold_-beginning'),
              ('*Emphasize* beginning', 2, None, 'emphasize-beginning'),
              ('`Verbatim` beginning', 2, None, 'verbatim-beginning'),
              ('Maybe _bold end_', 2, None, 'maybe-_bold-end_'),
              ('Maybe *emphasize end*', 2, None, 'maybe-emphasize-end'),
              ('Maybe `verbatim end`', 2, None, 'maybe-verbatim-end'),
              ('The middle has _bold_ word',
               2,
               None,
               'the-middle-has-_bold_-word'),
              ('The middle has *emphasize* word',
               2,
               None,
               'the-middle-has-emphasize-word'),
              ('The middle has `verbatim` word',
               2,
               None,
               'the-middle-has-verbatim-word'),
              ('Bibliography test', 2, None, 'bibliography-test'),
              ('Example 1: Examples can be typeset as exercises',
               2,
               'Example',
               'Example'),
              ('User-defined environments',
               2,
               None,
               'user-defined-environments'),
              ('Example 1: A test function', 2, 'ex:test:1p1', 'ex:test:1p1'),
              ('Example 2: Addition', 2, 'ex:math:1p1', 'ex:math:1p1'),
              ('URLs', 2, 'subsubsec:ex', 'subsubsec:ex'),
              ('LaTeX Mathematics', 1, None, 'latex-mathematics'),
              ('Exercises', 1, None, 'exercises'),
              ('Problem 2: Flip a Coin', 2, 'demo:ex:1', 'demo:ex:1'),
              ('My remarks', 3, None, 'my-remarks'),
              ('Remarks', 3, None, 'remarks'),
              ('Not an exercise', 2, None, 'not-an-exercise'),
              ('Exercise 3: Test of plain text exercise',
               2,
               'my:exer1',
               'my:exer1'),
              ('Project 4: Compute a Probability', 2, 'demo:ex:2', 'demo:ex:2'),
              ('Project 5: Explore Distributions of Random Circles',
               2,
               'proj:circle1',
               'proj:circle1'),
              ('Remarks', 3, None, 'remarks'),
              ('Exercise 6: Determine some Distance',
               2,
               'exer:dist',
               'exer:dist'),
              ('Remarks', 3, None, 'remarks'),
              ('Some exercise without the "Exercise:" prefix',
               2,
               None,
               'some-exercise-without-the-exercise-prefix'),
              ('Exercise 8: Solution of differential equation',
               2,
               'sec:this:exer:de',
               'sec:this:exer:de'),
              ('Example 9: Just an example',
               2,
               None,
               'example-9-just-an-example'),
              ('Here goes another section',
               1,
               None,
               'here-goes-another-section'),
              ('More Exercises', 1, None, 'more-exercises'),
              ('Exercise 10: Make references to projects and problems',
               2,
               'exer:some:formula',
               'exer:some:formula'),
              ('Project 11: References in a headings do not work well in html',
               2,
               'exer:you',
               'exer:you'),
              ('References', 1, None, 'references'),
              ('Appendix: Just for testing; part I', 1, 'app1', 'app1'),
              ('A subsection within an appendix',
               2,
               None,
               'a-subsection-within-an-appendix'),
              ('Appendix: Just for testing; part II', 1, 'app2', 'app2'),
              ('Appendix: Testing identical titles',
               2,
               None,
               'appendix-testing-identical-titles'),
              ('Appendix: Testing identical titles',
               2,
               'test:title:id1',
               'test:title:id1'),
              ('Appendix: Testing identical titles',
               2,
               'test:title:id2',
               'test:title:id2'),
              ('Appendix: Testing identical titles',
               2,
               None,
               'appendix-testing-identical-titles'),
              ('Appendix: Testing inline comments',
               2,
               None,
               'appendix-testing-inline-comments'),
              ('Appendix: Testing headings ending with `verbatim inline`',
               2,
               None,
               'appendix-testing-headings-ending-with-verbatim-inline')]}
end of tocinfo -->





<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  TeX: {
     equationNumbers: {  autoNumber: "none"  },
     extensions: ["AMSmath.js", "AMSsymbols.js", "autobold.js", "color.js"]
  }
});
</script>
<script type="text/javascript" async
 src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>



<a name="part0000"></a>
<!-- ------------------- main content ---------------------- -->



<div class="jumbotron">
<center><h1>A Document for Testing DocOnce</h1></center>  <!-- document title -->

<p>
<!-- author(s): Hans Petter Langtangen, Kaare Dump, A. Dummy Author, I. S. Overworked and Outburned, and J. Doe -->

<center>
<b>Hans Petter Langtangen</b> [1, 2] (<tt>hpl at simula.no</tt>)
</center>

<center>
<b>Kaare Dump</b> [3]
</center>

<center>
<b>A. Dummy Author</b> 
</center>

<center>
<b>I. S. Overworked and Outburned</b> [4, 5, 6, 7]
</center>

<center>
<b>J. Doe</b>  (<tt>j_doe at cyberspace.com</tt>)
</center>

<p>
<!-- institution(s) -->

<center>[1] <b>Center for Biomedical Computing, Simula Research Laboratory</b></center>
<center>[2] <b>Department of Informatics, University of Oslo</b></center>
<center>[3] <b>Segfault, Cyberspace</b></center>
<center>[4] <b>Inst1</b></center>
<center>[5] <b>Inst2, Somewhere</b></center>
<center>[6] <b>Third Inst, Elsewhere</b></center>
<center>[7] <b>Fourth Inst</b></center>
<br>
<p>

<br>
<p>
</div> <!-- end jumbotron -->

<h1 id="table_of_contents">Table of contents</h2>

<p>
<a href="._testdoc_vagrant001.html#sec1"> Section 1 </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant001.html#subsec1"> Subsection 1 </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant001.html#subsec:ex"> Subsection 2: Testing figures </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant001.html#decay:sec:theta"> The \( \theta \) parameter (not \( \nabla \)?) </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant001.html#custom-environments"> Custom Environments </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant001.html#subsec:table"> Tables </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant001.html#a-test-of-verbatim-words-in-heading-with-subscript-a_i-my_file_v1-and-my_file_v2"> A test of verbatim words in heading with subscript \( a_i \): <code>my_file_v1</code> and <code>my_file_v2</code> </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant001.html#_just-bold_"> <b>Just bold</b> </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant001.html#just-emphasize"> <em>Just emphasize</em> </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant001.html#just-verbatim"> <code>Just verbatim</code> </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant001.html#_bold_-beginning"> <b>Bold</b> beginning </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant001.html#emphasize-beginning"> <em>Emphasize</em> beginning </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant001.html#verbatim-beginning"> <code>Verbatim</code> beginning </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant001.html#maybe-_bold-end_"> Maybe <b>bold end</b> </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant001.html#maybe-emphasize-end"> Maybe <em>emphasize end</em> </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant001.html#maybe-verbatim-end"> Maybe <code>verbatim end</code> </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant001.html#the-middle-has-<b>bold</b>-word"> The middle has <b>bold</b> word </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant001.html#the-middle-has-emphasize-word"> The middle has <em>emphasize</em> word </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant001.html#the-middle-has-verbatim-word"> The middle has <code>verbatim</code> word </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant001.html#bibliography-test"> Bibliography test </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant001.html#Example"> Example 1: Examples can be typeset as exercises </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant001.html#user-defined-environments"> User-defined environments </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant001.html#ex:test:1p1"> Example 1: A test function </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant001.html#ex:math:1p1"> Example 2: Addition </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant001.html#subsubsec:ex"> URLs </a><br>
<a href="._testdoc_vagrant002.html#latex-mathematics"> LaTeX Mathematics </a><br>
<a href="._testdoc_vagrant002.html#exercises"> Exercises </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant002.html#demo:ex:1"> Problem 2: Flip a Coin </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant002.html#not-an-exercise"> Not an exercise </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant002.html#my:exer1"> Exercise 3: Test of plain text exercise </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant002.html#demo:ex:2"> Project 4: Compute a Probability </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant002.html#proj:circle1"> Project 5: Explore Distributions of Random Circles </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant002.html#exer:dist"> Exercise 6: Determine some Distance </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant002.html#some-exercise-without-the-exercise-prefix"> Some exercise without the "Exercise:" prefix </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant002.html#sec:this:exer:de"> Exercise 8: Solution of differential equation </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant002.html#example-9-just-an-example"> Example 9: Just an example </a><br>
<a href="._testdoc_vagrant002.html#here-goes-another-section"> Here goes another section </a><br>
<a href="._testdoc_vagrant002.html#more-exercises"> More Exercises </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant002.html#exer:some:formula"> Exercise 10: Make references to projects and problems </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant002.html#exer:you"> Project 11: References in a headings do not work well in html </a><br>
<a href="._testdoc_vagrant002.html#references"> References </a><br>
<a href="._testdoc_vagrant002.html#app1"> Appendix: Just for testing; part I </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant002.html#a-subsection-within-an-appendix"> A subsection within an appendix </a><br>
<a href="._testdoc_vagrant002.html#app2"> Appendix: Just for testing; part II </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant003.html#appendix-testing-identical-titles"> Appendix: Testing identical titles </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant002.html#test:title:id1"> Appendix: Testing identical titles </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant002.html#test:title:id2"> Appendix: Testing identical titles </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant003.html#appendix-testing-identical-titles"> Appendix: Testing identical titles </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant003.html#appendix-testing-inline-comments"> Appendix: Testing inline comments </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant003.html#appendix-testing-headings-ending-with-verbatim-inline"> Appendix: Testing headings ending with <code>verbatim inline</code> </a><br>
</p>
<p>
<p>
<!-- navigation buttons at the bottom of the page -->
<ul class="pager">

  <li class="next">
    <a href="._testdoc_vagrant001.html">Next &rarr;</a>
  </li>
</ul>
<!-- ------------------- end of main content --------------- -->

 </div>

 <div class="row Footer">
  <div class="span12">
  <!-- footer --> Here goes a footer, if desired, maybe with author(s) and a copyright &copy;
  </div>
 </div>
</div>
</body>
</html>

************** File: ._testdoc_vagrant000.html *****************
<html>
<head>
<!-- Bootstrap style: vagrant 1.0 web pages -->

<!--
This style is adopted from the (now old) vagrant 1.0 web pages.

This style file should be copied and the following elements edited:

Logo heading:

 LogoWord
 withSubWord

Navigation links at the top:

 GO TO 1
 GO TO 2

Footer at the end
-->

<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Doconce: http://code.google.com/p/doconce/" />

<title>A Document for Testing DocOnce</title>

<!-- If you copy the css subdirectory (and, e.g., make optional edits):
<link rel="stylesheet" href="css/twitter_bootstrap.css">
<link rel="stylesheet" href="css/vagrant.css">
Otherwise, rely on the URLs below (vagrant.css adapted to Doconce layout)
-->

<link rel="stylesheet" href="https://raw.githubusercontent.com/hplgit/doconce/master/bundled/html_styles/style_vagrant/css/twitter_bootstrap.css">
<link rel="stylesheet" href="https://raw.githubusercontent.com/hplgit/doconce/master/bundled/html_styles/style_vagrant/css/vagrant.css">

<!-- Define color of headings here (last definition counts) -->
<style type="text/css">
h1, h2, h3, h4, h5, h6 {
  color: #000;     /* black */
  color: #999;     /* gray */
  color: #005580;  /* dark blue */
  color: #08c;     /* characteristic blue */
</style>

<!-- Tools for embedded Bokeh plots -->
<link rel="stylesheet"
      href="https://cdn.pydata.org/bokeh/release/bokeh-0.9.0.min.css"
      type="text/css" />
<script type="text/javascript"
	src="https://cdn.pydata.org/bokeh/release/bokeh-0.9.0.min.js">
</script>
<script type="text/javascript">
  Bokeh.set_log_level("info");
</script>


</head>
<body>

<div class="container">
 <div class="row Header with-border">
  <div class="span3 Module logo">
   <h1><a href="/">LogoWord<span class="subtitle">withSubWord</span></a></h1>
  </div>
  <div class="span9">
   <div class="Module navigation">
   <!-- Navigation at the top of the page -->
    <ul>
     <li> <a href="">GO TO 1</a></li>
     <li> <a href="">GO TO 2</a></li>
    </ul>
   </div>
  </div>
 </div>
</div>


<!-- Here goes the table of contents in the sidebar
     <li class="active"> means dark blue background for current section
-->
<div class="row">
 <div class="span3 Module sidebar">
  <div class="well" style="padding: 8px 0px;">
   <ul class="nav nav-list">
     <!-- navigation toc: --> <li><a href="#table_of_contents" style="font-size: 80%;"><b>Table of contents</b></a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#sec1" style="font-size: 80%;"><b>Section 1</b></a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#subsec1" style="font-size: 80%;">Subsection 1</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#subsec:ex" style="font-size: 80%;">Subsection 2: Testing figures</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#decay:sec:theta" style="font-size: 80%;">The \( \theta \) parameter (not \( \nabla \)?)</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#custom-environments" style="font-size: 80%;">Custom Environments</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#subsec:table" style="font-size: 80%;">Tables</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#a-test-of-verbatim-words-in-heading-with-subscript-a_i-my_file_v1-and-my_file_v2" style="font-size: 80%;">A test of verbatim words in heading with subscript \( a_i \): <code>my_file_v1</code> and <code>my_file_v2</code></a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#_just-bold_" style="font-size: 80%;"><b>Just bold</b></a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#just-emphasize" style="font-size: 80%;"><em>Just emphasize</em></a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#just-verbatim" style="font-size: 80%;"><code>Just verbatim</code></a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#_bold_-beginning" style="font-size: 80%;"><b>Bold</b> beginning</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#emphasize-beginning" style="font-size: 80%;"><em>Emphasize</em> beginning</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#verbatim-beginning" style="font-size: 80%;"><code>Verbatim</code> beginning</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#maybe-_bold-end_" style="font-size: 80%;">Maybe <b>bold end</b></a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#maybe-emphasize-end" style="font-size: 80%;">Maybe <em>emphasize end</em></a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#maybe-verbatim-end" style="font-size: 80%;">Maybe <code>verbatim end</code></a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#the-middle-has-<b>bold</b>-word" style="font-size: 80%;">The middle has <b>bold</b> word</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#the-middle-has-emphasize-word" style="font-size: 80%;">The middle has <em>emphasize</em> word</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#the-middle-has-verbatim-word" style="font-size: 80%;">The middle has <code>verbatim</code> word</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#bibliography-test" style="font-size: 80%;">Bibliography test</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#Example" style="font-size: 80%;">Example 1: Examples can be typeset as exercises</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#user-defined-environments" style="font-size: 80%;">User-defined environments</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#ex:test:1p1" style="font-size: 80%;">Example 1: A test function</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#ex:math:1p1" style="font-size: 80%;">Example 2: Addition</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#subsubsec:ex" style="font-size: 80%;">URLs</a></li>
     </ul>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#latex-mathematics" style="font-size: 80%;"><b>LaTeX Mathematics</b></a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#exercises" style="font-size: 80%;"><b>Exercises</b></a></li>
     <ul class="nav">
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#demo:ex:1" style="font-size: 80%;">Problem 2: Flip a Coin</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#not-an-exercise" style="font-size: 80%;">Not an exercise</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#my:exer1" style="font-size: 80%;">Exercise 3: Test of plain text exercise</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#demo:ex:2" style="font-size: 80%;">Project 4: Compute a Probability</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#proj:circle1" style="font-size: 80%;">Project 5: Explore Distributions of Random Circles</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#exer:dist" style="font-size: 80%;">Exercise 6: Determine some Distance</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#some-exercise-without-the-exercise-prefix" style="font-size: 80%;">Some exercise without the "Exercise:" prefix</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#sec:this:exer:de" style="font-size: 80%;">Exercise 8: Solution of differential equation</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#example-9-just-an-example" style="font-size: 80%;">Example 9: Just an example</a></li>
     </ul>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#here-goes-another-section" style="font-size: 80%;"><b>Here goes another section</b></a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#more-exercises" style="font-size: 80%;"><b>More Exercises</b></a></li>
     <ul class="nav">
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#exer:some:formula" style="font-size: 80%;">Exercise 10: Make references to projects and problems</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#exer:you" style="font-size: 80%;">Project 11: References in a headings do not work well in html</a></li>
     </ul>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#references" style="font-size: 80%;"><b>References</b></a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#app1" style="font-size: 80%;"><b>Appendix: Just for testing; part I</b></a></li>
     <ul class="nav">
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#a-subsection-within-an-appendix" style="font-size: 80%;">A subsection within an appendix</a></li>
     </ul>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#app2" style="font-size: 80%;"><b>Appendix: Just for testing; part II</b></a></li>
     <ul class="nav">
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant003.html#appendix-testing-identical-titles" style="font-size: 80%;">Appendix: Testing identical titles</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#test:title:id1" style="font-size: 80%;">Appendix: Testing identical titles</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#test:title:id2" style="font-size: 80%;">Appendix: Testing identical titles</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant003.html#appendix-testing-identical-titles" style="font-size: 80%;">Appendix: Testing identical titles</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant003.html#appendix-testing-inline-comments" style="font-size: 80%;">Appendix: Testing inline comments</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant003.html#appendix-testing-headings-ending-with-verbatim-inline" style="font-size: 80%;">Appendix: Testing headings ending with <code>verbatim inline</code></a></li>

   </ul>
  </div>
 </div>

 <div class="span9">

<!-- tocinfo
{'highest level': 1,
 'sections': [('Table of contents',
               1,
               'table_of_contents',
               'table_of_contents'),
              ('Section 1', 1, 'sec1', 'sec1'),
              ('Here is a list with subsubsection heading',
               3,
               None,
               'here-is-a-list-with-subsubsection-heading'),
              ('Subsection 1', 2, 'subsec1', 'subsec1'),
              ('Test Section reference at beginning of line and after a '
               'sentence',
               3,
               None,
               'test-section-reference-at-beginning-of-line-and-after-a-sentence'),
              ('Computer code', 3, None, 'computer-code'),
              ('Subsubsection heading before code',
               3,
               None,
               'subsubsection-heading-before-code'),
              ('Running OS commands', 3, None, 'running-os-commands'),
              ('Footnotes', 3, None, 'footnotes'),
              ('Subsection 2: Testing figures', 2, 'subsec:ex', 'subsec:ex'),
              ('The $\\theta$ parameter (not $\\nabla$?)',
               2,
               'decay:sec:theta',
               'decay:sec:theta'),
              ('Custom Environments', 2, None, 'custom-environments'),
              ('Tables', 2, 'subsec:table', 'subsec:table'),
              ('A test of verbatim words in heading with subscript $a_i$: '
               '`my_file_v1` and `my_file_v2`',
               2,
               None,
               'a-test-of-verbatim-words-in-heading-with-subscript-a_i-my_file_v1-and-my_file_v2'),
              ('_Just bold_', 2, None, '_just-bold_'),
              ('*Just emphasize*', 2, None, 'just-emphasize'),
              ('`Just verbatim`', 2, None, 'just-verbatim'),
              ('_Bold_ beginning', 2, None, '_bold_-beginning'),
              ('*Emphasize* beginning', 2, None, 'emphasize-beginning'),
              ('`Verbatim` beginning', 2, None, 'verbatim-beginning'),
              ('Maybe _bold end_', 2, None, 'maybe-_bold-end_'),
              ('Maybe *emphasize end*', 2, None, 'maybe-emphasize-end'),
              ('Maybe `verbatim end`', 2, None, 'maybe-verbatim-end'),
              ('The middle has _bold_ word',
               2,
               None,
               'the-middle-has-_bold_-word'),
              ('The middle has *emphasize* word',
               2,
               None,
               'the-middle-has-emphasize-word'),
              ('The middle has `verbatim` word',
               2,
               None,
               'the-middle-has-verbatim-word'),
              ('Bibliography test', 2, None, 'bibliography-test'),
              ('Example 1: Examples can be typeset as exercises',
               2,
               'Example',
               'Example'),
              ('User-defined environments',
               2,
               None,
               'user-defined-environments'),
              ('Example 1: A test function', 2, 'ex:test:1p1', 'ex:test:1p1'),
              ('Example 2: Addition', 2, 'ex:math:1p1', 'ex:math:1p1'),
              ('URLs', 2, 'subsubsec:ex', 'subsubsec:ex'),
              ('LaTeX Mathematics', 1, None, 'latex-mathematics'),
              ('Exercises', 1, None, 'exercises'),
              ('Problem 2: Flip a Coin', 2, 'demo:ex:1', 'demo:ex:1'),
              ('My remarks', 3, None, 'my-remarks'),
              ('Remarks', 3, None, 'remarks'),
              ('Not an exercise', 2, None, 'not-an-exercise'),
              ('Exercise 3: Test of plain text exercise',
               2,
               'my:exer1',
               'my:exer1'),
              ('Project 4: Compute a Probability', 2, 'demo:ex:2', 'demo:ex:2'),
              ('Project 5: Explore Distributions of Random Circles',
               2,
               'proj:circle1',
               'proj:circle1'),
              ('Remarks', 3, None, 'remarks'),
              ('Exercise 6: Determine some Distance',
               2,
               'exer:dist',
               'exer:dist'),
              ('Remarks', 3, None, 'remarks'),
              ('Some exercise without the "Exercise:" prefix',
               2,
               None,
               'some-exercise-without-the-exercise-prefix'),
              ('Exercise 8: Solution of differential equation',
               2,
               'sec:this:exer:de',
               'sec:this:exer:de'),
              ('Example 9: Just an example',
               2,
               None,
               'example-9-just-an-example'),
              ('Here goes another section',
               1,
               None,
               'here-goes-another-section'),
              ('More Exercises', 1, None, 'more-exercises'),
              ('Exercise 10: Make references to projects and problems',
               2,
               'exer:some:formula',
               'exer:some:formula'),
              ('Project 11: References in a headings do not work well in html',
               2,
               'exer:you',
               'exer:you'),
              ('References', 1, None, 'references'),
              ('Appendix: Just for testing; part I', 1, 'app1', 'app1'),
              ('A subsection within an appendix',
               2,
               None,
               'a-subsection-within-an-appendix'),
              ('Appendix: Just for testing; part II', 1, 'app2', 'app2'),
              ('Appendix: Testing identical titles',
               2,
               None,
               'appendix-testing-identical-titles'),
              ('Appendix: Testing identical titles',
               2,
               'test:title:id1',
               'test:title:id1'),
              ('Appendix: Testing identical titles',
               2,
               'test:title:id2',
               'test:title:id2'),
              ('Appendix: Testing identical titles',
               2,
               None,
               'appendix-testing-identical-titles'),
              ('Appendix: Testing inline comments',
               2,
               None,
               'appendix-testing-inline-comments'),
              ('Appendix: Testing headings ending with `verbatim inline`',
               2,
               None,
               'appendix-testing-headings-ending-with-verbatim-inline')]}
end of tocinfo -->





<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  TeX: {
     equationNumbers: {  autoNumber: "none"  },
     extensions: ["AMSmath.js", "AMSsymbols.js", "autobold.js", "color.js"]
  }
});
</script>
<script type="text/javascript" async
 src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>



<a name="part0000"></a>
<!-- ------------------- main content ---------------------- -->



<div class="jumbotron">
<center><h1>A Document for Testing DocOnce</h1></center>  <!-- document title -->

<p>
<!-- author(s): Hans Petter Langtangen, Kaare Dump, A. Dummy Author, I. S. Overworked and Outburned, and J. Doe -->

<center>
<b>Hans Petter Langtangen</b> [1, 2] (<tt>hpl at simula.no</tt>)
</center>

<center>
<b>Kaare Dump</b> [3]
</center>

<center>
<b>A. Dummy Author</b> 
</center>

<center>
<b>I. S. Overworked and Outburned</b> [4, 5, 6, 7]
</center>

<center>
<b>J. Doe</b>  (<tt>j_doe at cyberspace.com</tt>)
</center>

<p>
<!-- institution(s) -->

<center>[1] <b>Center for Biomedical Computing, Simula Research Laboratory</b></center>
<center>[2] <b>Department of Informatics, University of Oslo</b></center>
<center>[3] <b>Segfault, Cyberspace</b></center>
<center>[4] <b>Inst1</b></center>
<center>[5] <b>Inst2, Somewhere</b></center>
<center>[6] <b>Third Inst, Elsewhere</b></center>
<center>[7] <b>Fourth Inst</b></center>
<br>
<p>

<br>
<p>
</div> <!-- end jumbotron -->

<h1 id="table_of_contents">Table of contents</h2>

<p>
<a href="._testdoc_vagrant001.html#sec1"> Section 1 </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant001.html#subsec1"> Subsection 1 </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant001.html#subsec:ex"> Subsection 2: Testing figures </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant001.html#decay:sec:theta"> The \( \theta \) parameter (not \( \nabla \)?) </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant001.html#custom-environments"> Custom Environments </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant001.html#subsec:table"> Tables </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant001.html#a-test-of-verbatim-words-in-heading-with-subscript-a_i-my_file_v1-and-my_file_v2"> A test of verbatim words in heading with subscript \( a_i \): <code>my_file_v1</code> and <code>my_file_v2</code> </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant001.html#_just-bold_"> <b>Just bold</b> </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant001.html#just-emphasize"> <em>Just emphasize</em> </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant001.html#just-verbatim"> <code>Just verbatim</code> </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant001.html#_bold_-beginning"> <b>Bold</b> beginning </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant001.html#emphasize-beginning"> <em>Emphasize</em> beginning </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant001.html#verbatim-beginning"> <code>Verbatim</code> beginning </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant001.html#maybe-_bold-end_"> Maybe <b>bold end</b> </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant001.html#maybe-emphasize-end"> Maybe <em>emphasize end</em> </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant001.html#maybe-verbatim-end"> Maybe <code>verbatim end</code> </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant001.html#the-middle-has-<b>bold</b>-word"> The middle has <b>bold</b> word </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant001.html#the-middle-has-emphasize-word"> The middle has <em>emphasize</em> word </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant001.html#the-middle-has-verbatim-word"> The middle has <code>verbatim</code> word </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant001.html#bibliography-test"> Bibliography test </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant001.html#Example"> Example 1: Examples can be typeset as exercises </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant001.html#user-defined-environments"> User-defined environments </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant001.html#ex:test:1p1"> Example 1: A test function </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant001.html#ex:math:1p1"> Example 2: Addition </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant001.html#subsubsec:ex"> URLs </a><br>
<a href="._testdoc_vagrant002.html#latex-mathematics"> LaTeX Mathematics </a><br>
<a href="._testdoc_vagrant002.html#exercises"> Exercises </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant002.html#demo:ex:1"> Problem 2: Flip a Coin </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant002.html#not-an-exercise"> Not an exercise </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant002.html#my:exer1"> Exercise 3: Test of plain text exercise </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant002.html#demo:ex:2"> Project 4: Compute a Probability </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant002.html#proj:circle1"> Project 5: Explore Distributions of Random Circles </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant002.html#exer:dist"> Exercise 6: Determine some Distance </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant002.html#some-exercise-without-the-exercise-prefix"> Some exercise without the "Exercise:" prefix </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant002.html#sec:this:exer:de"> Exercise 8: Solution of differential equation </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant002.html#example-9-just-an-example"> Example 9: Just an example </a><br>
<a href="._testdoc_vagrant002.html#here-goes-another-section"> Here goes another section </a><br>
<a href="._testdoc_vagrant002.html#more-exercises"> More Exercises </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant002.html#exer:some:formula"> Exercise 10: Make references to projects and problems </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant002.html#exer:you"> Project 11: References in a headings do not work well in html </a><br>
<a href="._testdoc_vagrant002.html#references"> References </a><br>
<a href="._testdoc_vagrant002.html#app1"> Appendix: Just for testing; part I </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant002.html#a-subsection-within-an-appendix"> A subsection within an appendix </a><br>
<a href="._testdoc_vagrant002.html#app2"> Appendix: Just for testing; part II </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant003.html#appendix-testing-identical-titles"> Appendix: Testing identical titles </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant002.html#test:title:id1"> Appendix: Testing identical titles </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant002.html#test:title:id2"> Appendix: Testing identical titles </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant003.html#appendix-testing-identical-titles"> Appendix: Testing identical titles </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant003.html#appendix-testing-inline-comments"> Appendix: Testing inline comments </a><br>
&nbsp; &nbsp; &nbsp; <a href="._testdoc_vagrant003.html#appendix-testing-headings-ending-with-verbatim-inline"> Appendix: Testing headings ending with <code>verbatim inline</code> </a><br>
</p>
<p>
<p>
<!-- navigation buttons at the bottom of the page -->
<ul class="pager">

  <li class="next">
    <a href="._testdoc_vagrant001.html">Next &rarr;</a>
  </li>
</ul>
<!-- ------------------- end of main content --------------- -->

 </div>

 <div class="row Footer">
  <div class="span12">
  <!-- footer --> Here goes a footer, if desired, maybe with author(s) and a copyright &copy;
  </div>
 </div>
</div>
</body>
</html>

************** File: ._testdoc_vagrant001.html *****************
<html>
<head>
<!-- Bootstrap style: vagrant 1.0 web pages -->

<!--
This style is adopted from the (now old) vagrant 1.0 web pages.

This style file should be copied and the following elements edited:

Logo heading:

 LogoWord
 withSubWord

Navigation links at the top:

 GO TO 1
 GO TO 2

Footer at the end
-->

<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Doconce: http://code.google.com/p/doconce/" />

<title>A Document for Testing DocOnce</title>

<!-- If you copy the css subdirectory (and, e.g., make optional edits):
<link rel="stylesheet" href="css/twitter_bootstrap.css">
<link rel="stylesheet" href="css/vagrant.css">
Otherwise, rely on the URLs below (vagrant.css adapted to Doconce layout)
-->

<link rel="stylesheet" href="https://raw.githubusercontent.com/hplgit/doconce/master/bundled/html_styles/style_vagrant/css/twitter_bootstrap.css">
<link rel="stylesheet" href="https://raw.githubusercontent.com/hplgit/doconce/master/bundled/html_styles/style_vagrant/css/vagrant.css">

<!-- Define color of headings here (last definition counts) -->
<style type="text/css">
h1, h2, h3, h4, h5, h6 {
  color: #000;     /* black */
  color: #999;     /* gray */
  color: #005580;  /* dark blue */
  color: #08c;     /* characteristic blue */
</style>

<!-- Tools for embedded Bokeh plots -->
<link rel="stylesheet"
      href="https://cdn.pydata.org/bokeh/release/bokeh-0.9.0.min.css"
      type="text/css" />
<script type="text/javascript"
	src="https://cdn.pydata.org/bokeh/release/bokeh-0.9.0.min.js">
</script>
<script type="text/javascript">
  Bokeh.set_log_level("info");
</script>


</head>
<body>

<div class="container">
 <div class="row Header with-border">
  <div class="span3 Module logo">
   <h1><a href="/">LogoWord<span class="subtitle">withSubWord</span></a></h1>
  </div>
  <div class="span9">
   <div class="Module navigation">
   <!-- Navigation at the top of the page -->
    <ul>
     <li> <a href="">GO TO 1</a></li>
     <li> <a href="">GO TO 2</a></li>
    </ul>
   </div>
  </div>
 </div>
</div>


<!-- Here goes the table of contents in the sidebar
     <li class="active"> means dark blue background for current section
-->
<div class="row">
 <div class="span3 Module sidebar">
  <div class="well" style="padding: 8px 0px;">
   <ul class="nav nav-list">
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant000.html#table_of_contents" style="font-size: 80%;"><b>Table of contents</b></a></li>
     <!-- navigation toc: --> <li><a href="#sec1" style="font-size: 80%;"><b>Section 1</b></a></li>
     <!-- navigation toc: --> <li><a href="#subsec1" style="font-size: 80%;">Subsection 1</a></li>
     <!-- navigation toc: --> <li><a href="#subsec:ex" style="font-size: 80%;">Subsection 2: Testing figures</a></li>
     <!-- navigation toc: --> <li><a href="#decay:sec:theta" style="font-size: 80%;">The \( \theta \) parameter (not \( \nabla \)?)</a></li>
     <!-- navigation toc: --> <li><a href="#custom-environments" style="font-size: 80%;">Custom Environments</a></li>
     <!-- navigation toc: --> <li><a href="#subsec:table" style="font-size: 80%;">Tables</a></li>
     <!-- navigation toc: --> <li><a href="#a-test-of-verbatim-words-in-heading-with-subscript-a_i-my_file_v1-and-my_file_v2" style="font-size: 80%;">A test of verbatim words in heading with subscript \( a_i \): <code>my_file_v1</code> and <code>my_file_v2</code></a></li>
     <!-- navigation toc: --> <li><a href="#_just-bold_" style="font-size: 80%;"><b>Just bold</b></a></li>
     <!-- navigation toc: --> <li><a href="#just-emphasize" style="font-size: 80%;"><em>Just emphasize</em></a></li>
     <!-- navigation toc: --> <li><a href="#just-verbatim" style="font-size: 80%;"><code>Just verbatim</code></a></li>
     <!-- navigation toc: --> <li><a href="#_bold_-beginning" style="font-size: 80%;"><b>Bold</b> beginning</a></li>
     <!-- navigation toc: --> <li><a href="#emphasize-beginning" style="font-size: 80%;"><em>Emphasize</em> beginning</a></li>
     <!-- navigation toc: --> <li><a href="#verbatim-beginning" style="font-size: 80%;"><code>Verbatim</code> beginning</a></li>
     <!-- navigation toc: --> <li><a href="#maybe-_bold-end_" style="font-size: 80%;">Maybe <b>bold end</b></a></li>
     <!-- navigation toc: --> <li><a href="#maybe-emphasize-end" style="font-size: 80%;">Maybe <em>emphasize end</em></a></li>
     <!-- navigation toc: --> <li><a href="#maybe-verbatim-end" style="font-size: 80%;">Maybe <code>verbatim end</code></a></li>
     <!-- navigation toc: --> <li><a href="#the-middle-has-<b>bold</b>-word" style="font-size: 80%;">The middle has <b>bold</b> word</a></li>
     <!-- navigation toc: --> <li><a href="#the-middle-has-emphasize-word" style="font-size: 80%;">The middle has <em>emphasize</em> word</a></li>
     <!-- navigation toc: --> <li><a href="#the-middle-has-verbatim-word" style="font-size: 80%;">The middle has <code>verbatim</code> word</a></li>
     <!-- navigation toc: --> <li><a href="#bibliography-test" style="font-size: 80%;">Bibliography test</a></li>
     <!-- navigation toc: --> <li><a href="#Example" style="font-size: 80%;">Example 1: Examples can be typeset as exercises</a></li>
     <!-- navigation toc: --> <li><a href="#user-defined-environments" style="font-size: 80%;">User-defined environments</a></li>
     <!-- navigation toc: --> <li><a href="#ex:test:1p1" style="font-size: 80%;">Example 1: A test function</a></li>
     <!-- navigation toc: --> <li><a href="#ex:math:1p1" style="font-size: 80%;">Example 2: Addition</a></li>
     <!-- navigation toc: --> <li><a href="#subsubsec:ex" style="font-size: 80%;">URLs</a></li>
     </ul>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#latex-mathematics" style="font-size: 80%;"><b>LaTeX Mathematics</b></a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#exercises" style="font-size: 80%;"><b>Exercises</b></a></li>
     <ul class="nav">
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#demo:ex:1" style="font-size: 80%;">Problem 2: Flip a Coin</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#not-an-exercise" style="font-size: 80%;">Not an exercise</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#my:exer1" style="font-size: 80%;">Exercise 3: Test of plain text exercise</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#demo:ex:2" style="font-size: 80%;">Project 4: Compute a Probability</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#proj:circle1" style="font-size: 80%;">Project 5: Explore Distributions of Random Circles</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#exer:dist" style="font-size: 80%;">Exercise 6: Determine some Distance</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#some-exercise-without-the-exercise-prefix" style="font-size: 80%;">Some exercise without the "Exercise:" prefix</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#sec:this:exer:de" style="font-size: 80%;">Exercise 8: Solution of differential equation</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#example-9-just-an-example" style="font-size: 80%;">Example 9: Just an example</a></li>
     </ul>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#here-goes-another-section" style="font-size: 80%;"><b>Here goes another section</b></a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#more-exercises" style="font-size: 80%;"><b>More Exercises</b></a></li>
     <ul class="nav">
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#exer:some:formula" style="font-size: 80%;">Exercise 10: Make references to projects and problems</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#exer:you" style="font-size: 80%;">Project 11: References in a headings do not work well in html</a></li>
     </ul>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#references" style="font-size: 80%;"><b>References</b></a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#app1" style="font-size: 80%;"><b>Appendix: Just for testing; part I</b></a></li>
     <ul class="nav">
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#a-subsection-within-an-appendix" style="font-size: 80%;">A subsection within an appendix</a></li>
     </ul>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#app2" style="font-size: 80%;"><b>Appendix: Just for testing; part II</b></a></li>
     <ul class="nav">
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant003.html#appendix-testing-identical-titles" style="font-size: 80%;">Appendix: Testing identical titles</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#test:title:id1" style="font-size: 80%;">Appendix: Testing identical titles</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant002.html#test:title:id2" style="font-size: 80%;">Appendix: Testing identical titles</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant003.html#appendix-testing-identical-titles" style="font-size: 80%;">Appendix: Testing identical titles</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant003.html#appendix-testing-inline-comments" style="font-size: 80%;">Appendix: Testing inline comments</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant003.html#appendix-testing-headings-ending-with-verbatim-inline" style="font-size: 80%;">Appendix: Testing headings ending with <code>verbatim inline</code></a></li>

   </ul>
  </div>
 </div>

 <div class="span9">

<!-- tocinfo
{'highest level': 1,
 'sections': [('Table of contents',
               1,
               'table_of_contents',
               'table_of_contents'),
              ('Section 1', 1, 'sec1', 'sec1'),
              ('Here is a list with subsubsection heading',
               3,
               None,
               'here-is-a-list-with-subsubsection-heading'),
              ('Subsection 1', 2, 'subsec1', 'subsec1'),
              ('Test Section reference at beginning of line and after a '
               'sentence',
               3,
               None,
               'test-section-reference-at-beginning-of-line-and-after-a-sentence'),
              ('Computer code', 3, None, 'computer-code'),
              ('Subsubsection heading before code',
               3,
               None,
               'subsubsection-heading-before-code'),
              ('Running OS commands', 3, None, 'running-os-commands'),
              ('Footnotes', 3, None, 'footnotes'),
              ('Subsection 2: Testing figures', 2, 'subsec:ex', 'subsec:ex'),
              ('The $\\theta$ parameter (not $\\nabla$?)',
               2,
               'decay:sec:theta',
               'decay:sec:theta'),
              ('Custom Environments', 2, None, 'custom-environments'),
              ('Tables', 2, 'subsec:table', 'subsec:table'),
              ('A test of verbatim words in heading with subscript $a_i$: '
               '`my_file_v1` and `my_file_v2`',
               2,
               None,
               'a-test-of-verbatim-words-in-heading-with-subscript-a_i-my_file_v1-and-my_file_v2'),
              ('_Just bold_', 2, None, '_just-bold_'),
              ('*Just emphasize*', 2, None, 'just-emphasize'),
              ('`Just verbatim`', 2, None, 'just-verbatim'),
              ('_Bold_ beginning', 2, None, '_bold_-beginning'),
              ('*Emphasize* beginning', 2, None, 'emphasize-beginning'),
              ('`Verbatim` beginning', 2, None, 'verbatim-beginning'),
              ('Maybe _bold end_', 2, None, 'maybe-_bold-end_'),
              ('Maybe *emphasize end*', 2, None, 'maybe-emphasize-end'),
              ('Maybe `verbatim end`', 2, None, 'maybe-verbatim-end'),
              ('The middle has _bold_ word',
               2,
               None,
               'the-middle-has-_bold_-word'),
              ('The middle has *emphasize* word',
               2,
               None,
               'the-middle-has-emphasize-word'),
              ('The middle has `verbatim` word',
               2,
               None,
               'the-middle-has-verbatim-word'),
              ('Bibliography test', 2, None, 'bibliography-test'),
              ('Example 1: Examples can be typeset as exercises',
               2,
               'Example',
               'Example'),
              ('User-defined environments',
               2,
               None,
               'user-defined-environments'),
              ('Example 1: A test function', 2, 'ex:test:1p1', 'ex:test:1p1'),
              ('Example 2: Addition', 2, 'ex:math:1p1', 'ex:math:1p1'),
              ('URLs', 2, 'subsubsec:ex', 'subsubsec:ex'),
              ('LaTeX Mathematics', 1, None, 'latex-mathematics'),
              ('Exercises', 1, None, 'exercises'),
              ('Problem 2: Flip a Coin', 2, 'demo:ex:1', 'demo:ex:1'),
              ('My remarks', 3, None, 'my-remarks'),
              ('Remarks', 3, None, 'remarks'),
              ('Not an exercise', 2, None, 'not-an-exercise'),
              ('Exercise 3: Test of plain text exercise',
               2,
               'my:exer1',
               'my:exer1'),
              ('Project 4: Compute a Probability', 2, 'demo:ex:2', 'demo:ex:2'),
              ('Project 5: Explore Distributions of Random Circles',
               2,
               'proj:circle1',
               'proj:circle1'),
              ('Remarks', 3, None, 'remarks'),
              ('Exercise 6: Determine some Distance',
               2,
               'exer:dist',
               'exer:dist'),
              ('Remarks', 3, None, 'remarks'),
              ('Some exercise without the "Exercise:" prefix',
               2,
               None,
               'some-exercise-without-the-exercise-prefix'),
              ('Exercise 8: Solution of differential equation',
               2,
               'sec:this:exer:de',
               'sec:this:exer:de'),
              ('Example 9: Just an example',
               2,
               None,
               'example-9-just-an-example'),
              ('Here goes another section',
               1,
               None,
               'here-goes-another-section'),
              ('More Exercises', 1, None, 'more-exercises'),
              ('Exercise 10: Make references to projects and problems',
               2,
               'exer:some:formula',
               'exer:some:formula'),
              ('Project 11: References in a headings do not work well in html',
               2,
               'exer:you',
               'exer:you'),
              ('References', 1, None, 'references'),
              ('Appendix: Just for testing; part I', 1, 'app1', 'app1'),
              ('A subsection within an appendix',
               2,
               None,
               'a-subsection-within-an-appendix'),
              ('Appendix: Just for testing; part II', 1, 'app2', 'app2'),
              ('Appendix: Testing identical titles',
               2,
               None,
               'appendix-testing-identical-titles'),
              ('Appendix: Testing identical titles',
               2,
               'test:title:id1',
               'test:title:id1'),
              ('Appendix: Testing identical titles',
               2,
               'test:title:id2',
               'test:title:id2'),
              ('Appendix: Testing identical titles',
               2,
               None,
               'appendix-testing-identical-titles'),
              ('Appendix: Testing inline comments',
               2,
               None,
               'appendix-testing-inline-comments'),
              ('Appendix: Testing headings ending with `verbatim inline`',
               2,
               None,
               'appendix-testing-headings-ending-with-verbatim-inline')]}
end of tocinfo -->





<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  TeX: {
     equationNumbers: {  autoNumber: "none"  },
     extensions: ["AMSmath.js", "AMSsymbols.js", "autobold.js", "color.js"]
  }
});
</script>
<script type="text/javascript" async
 src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>



<a name="part0001"></a>
<!-- !split -->

<p>
The format of this document is
plain, homemade HTML (from DocOnce).

<p>
<b>Abstract.</b> This is a document with many test constructions for doconce syntax.
It was used heavily for the development and kept for testing
numerous constructions, also special and less common cases.

<p>
And exactly for test purposes we have an extra line here, which
is part of the abstract.

<p>
<!-- Cannot demonstrate chapter headings since abstract and chapter -->
<!-- are mutually exclusive in LaTeX -->

<h1 id="sec1" class="anchor">Section 1</h1>

<p>
Here is a nested list:

<ul>
  <li> item1</li>
  <li> item2</li>
  <li> item3 which continues
    on the next line to test that feature</li>
  <li> and a sublist</li>

<ul>
    <li> with indented subitem1</li>
    <li> and a subitem2</li>
</ul>

  <li> and perhaps an ordered sublist

<ol type="a"></li>
   <li> first item</li>
   <li> second item,
      continuing on a new line</li>
</ol>

</ul>

<b>Here is a list with paragraph heading.</b>

<ul>
  <li> item1</li>
  <li> item2</li>
</ul>

<h3 id="here-is-a-list-with-subsubsection-heading" class="anchor">Here is a list with subsubsection heading </h3>

<ul>
  <li> item1</li>
  <li> item2</li>
</ul>

<blockquote>
    Here are two lines that make up
    a block quote for testing <em>emphasized words</em> and <b>boldface words</b>,
    also with hypens:
    <em>pre</em>-fix, post-<em>fix</em>, <b>pre</b>-fix, post-<b>fix</b>.
</blockquote>


<p>
Here are two references. Equation&nbsp;<a href="._testdoc_vagrant002.html#mjx-eqn-12">(12)</a> is fine. Eq.&nbsp;<a href="._testdoc_vagrant002.html#mjx-eqn-12">(12)</a> too.
Even Equation <a href="._testdoc_vagrant002.html#mjx-eqn-12">(12)</a> without the tilde.
This equation appears in another part if this document is split.

<p>
Let us add a paragraph to
test that HTML,
with WordPress
(<code>--wordpress</code> option)
can handle linebreaks
<em>correctly</em>,
even when lines begin with
<b>bold words</b> and
<code>verbatim words</code> in
<font color="red">red color</font>, and
<a href="https://google.com" target="_self">links</a> as well as math:
\( 1+1=2 \).

<p>
Test also that <em>emphasize</em>
at the end of line, and <b>bold</b>
works, as well as <font color="blue">color</font>
and <a href="https://google.com" target="_self">links2</a>
and <code>verbatim</code>
as well.

<h2 id="subsec1" class="anchor">Subsection 1</h2>

<p>
<!-- Refer to section/appendix etc. at the beginning of the line -->
<!-- and other special fix situations for HTML. -->

<p>
More text, with a reference back to
the section <a href="#sec1">Section 1</a> and <a href="#subsec1">Subsection 1</a>, and further to the
the sections <a href="#subsec1">Subsection 1</a> and <a href="#subsubsec:ex">URLs</a>, which
encourages you to do the tasks in <a href="._testdoc_vagrant002.html#demo:ex:1">Problem 2: Flip a Coin</a> and <a href="._testdoc_vagrant002.html#exer:some:formula">Exercise 10: Make references to projects and problems</a>.
 <a href="._testdoc_vagrant002.html#app1">Appendix: Just for testing; part I</a> and <a href="._testdoc_vagrant002.html#app2">Appendix: Just for testing; part II</a> are also nice elements.

<h3 id="test-section-reference-at-beginning-of-line-and-after-a-sentence" class="anchor">Test Section reference at beginning of line and after a sentence </h3>

<p>
The section <a href="#subsec1">Subsection 1</a> is fine.
The section <a href="#subsubsec:ex">URLs</a> too.

<p>
<!-- sphinx code-blocks: pycod=python cod=fortran cppcod=c++ sys=console -->

<h3 id="computer-code" class="anchor">Computer code </h3>

<p>
Let's do some copying from files too. First from subroutine up to the very end,

<p>

<!-- code=fortran (!bc fcod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>      <span style="color: #008000; font-weight: bold">subroutine </span>test()
      <span style="color: #B00040">integer </span>i
      <span style="color: #B00040">real</span><span style="color: #666666">*8</span> r
      r <span style="color: #666666">=</span> <span style="color: #666666">0</span>
      <span style="color: #008000; font-weight: bold">do </span>i <span style="color: #666666">=</span> <span style="color: #666666">1</span>, i
         r <span style="color: #666666">=</span> r <span style="color: #666666">+</span> i
      <span style="color: #008000; font-weight: bold">end do</span>
<span style="color: #008000; font-weight: bold">      return</span>
C     END1

      <span style="color: #008000; font-weight: bold">program </span>testme
      <span style="color: #008000; font-weight: bold">call </span>test()
      <span style="color: #008000; font-weight: bold">return</span>
</pre></div>
<p>
and then just the subroutine,
<p>

<!-- code=fortran (!bc fcod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>      <span style="color: #008000; font-weight: bold">subroutine </span>test()
      <span style="color: #B00040">integer </span>i
      <span style="color: #B00040">real</span><span style="color: #666666">*8</span> r
      r <span style="color: #666666">=</span> <span style="color: #666666">0</span>
      <span style="color: #008000; font-weight: bold">do </span>i <span style="color: #666666">=</span> <span style="color: #666666">1</span>, i
         r <span style="color: #666666">=</span> r <span style="color: #666666">+</span> i
      <span style="color: #008000; font-weight: bold">end do</span>
<span style="color: #008000; font-weight: bold">      return</span>
</pre></div>
<p>
and finally the complete file with a plain text verbatim environment
(<code>envir=ccq</code>):
<p>

<!-- code=text (!bc ccq) typeset with pygments style "default" -->
<blockquote>
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>C     a comment

      subroutine test()
      integer i
      real*8 r
      r = 0
      do i = 1, i
         r = r + i
      end do
      return
C     END1

      program testme
      call test()
      return
</pre></div>
</blockquote><p>
Testing other code environments. First Python:

<p>

<!-- code=text typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>!bc pycod
def f(x):
    return x+1
!ec
</pre></div>
<p>
which gets rendered as

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">f</span>(x):
    <span style="color: #008000; font-weight: bold">return</span> x<span style="color: #666666">+1</span>
</pre></div>
<p>
Test paragraph and subsubsection headings before
before code.

<p>
<b>Paragraph heading before code.</b>

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">import</span> <span style="color: #0000FF; font-weight: bold">sys</span>
sys<span style="color: #666666">.</span>path<span style="color: #666666">.</span>insert(<span style="color: #666666">0</span>, os<span style="color: #666666">.</span>pardir)
</pre></div>

<h3 id="subsubsection-heading-before-code" class="anchor">Subsubsection heading before code </h3>

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">h</span>(z):
    <span style="color: #008000; font-weight: bold">return</span> z<span style="color: #666666">+1</span>
</pre></div>
<p>
Now a complete program to be shown via Python Online Tutorial:

<p>

<iframe width="950" height="500" frameborder="0"
        src="https://pythontutor.com/iframe-embed.html#code=class+Line%3A%0A++++def+__init__%28self%2C+a%2C+b%29%3A%0A++++++++self.a%2C+self.b+%3D+a%2C+b%0A%0A++++def+__call__%28self%2C+x%29%3A%0A++++++++a%2C+b+%3D+self.a%2C+self.b%0A++++++++return+a%2Ax+%2B+b%0A%0Aline+%3D+Line%282%2C+1%29%0Ay+%3D+line%28x%3D3%29%0Aprint%28y%29&py=2&curInstr=0&cumulative=false">
</iframe>
<p>
Some more Python code (actually specified as a sage cell, but
such cells are not supported by this format).

<p>


<div class="compute"><script type="text/x-sage">
a = 2
b = 3
print('a+b:', a + b)

# In a sage cell we can also plot
from matplotlib.pyplot import *
from numpy import *
x = linspace(0, 4*pi, 101)
y = exp(-0.1*x)*cos(x)
plot(x, y)
xlabel('x'); ylabel('y')
show()

</script></div>
<p>
Then Cython (with -h option so it is hidden in html/sphinx):

<p>

<!-- code=cython (!bc cycod-h) typeset with pygments style "default" -->

<script type="text/javascript">
function show_hide_code9(){
  $("#code9").toggle();
}
</script>
<button type="button" onclick="show_hide_code9()">Show/hide code</button>
<div id="code9" style="display:none">
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">cpdef</span> <span style="color: #0000FF">f</span>(double x):
    <span style="color: #008000; font-weight: bold">return</span> x <span style="color: #666666">+</span> <span style="color: #666666">1</span>
</pre></div>

</div>
<p>
Standard Python shell sessions:

<p>

<!-- code=python (!bc pyshell) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #666666">&gt;&gt;&gt;</span> <span style="color: #008000; font-weight: bold">from</span> <span style="color: #0000FF; font-weight: bold">numpy</span> <span style="color: #008000; font-weight: bold">import</span> linspace, sin
<span style="color: #666666">&gt;&gt;&gt;</span> <span style="color: #408080; font-style: italic"># Some comment</span>
<span style="color: #666666">&gt;&gt;&gt;</span> x <span style="color: #666666">=</span> linspace(<span style="color: #666666">0</span>, <span style="color: #666666">2</span>, <span style="color: #666666">11</span>)
<span style="color: #666666">&gt;&gt;&gt;</span> y <span style="color: #666666">=</span> sin(x)
<span style="color: #666666">&gt;&gt;&gt;</span> y[<span style="color: #666666">0</span>]
<span style="color: #666666">0</span>
<span style="color: #666666">&gt;&gt;&gt;</span> <span style="color: #008000; font-weight: bold">import</span> <span style="color: #0000FF; font-weight: bold">matplotlib.pyplot</span> <span style="color: #008000; font-weight: bold">as</span> <span style="color: #0000FF; font-weight: bold">plt</span>
<span style="color: #666666">&gt;&gt;&gt;</span> plt<span style="color: #666666">.</span>plot(x, y)
</pre></div>
<p>
Similar IPython sessions:

<p>

<!-- code=ipy (!bc ipy) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #000080; font-weight: bold">In [1]: </span><span style="color: #008000; font-weight: bold">from</span> <span style="color: #0000FF; font-weight: bold">numpy</span> <span style="color: #008000; font-weight: bold">import</span> linspace, sin
<span style="color: #000080; font-weight: bold">In [2]: </span><span style="color: #408080; font-style: italic"># Some comment</span>
<span style="color: #000080; font-weight: bold">In [3]: </span>x <span style="color: #666666">=</span> linspace(<span style="color: #666666">0</span>, <span style="color: #666666">2</span>, <span style="color: #666666">11</span>)
<span style="color: #000080; font-weight: bold">In [4]: </span>y <span style="color: #666666">=</span> sin(x)
<span style="color: #000080; font-weight: bold">In [5]: </span>y[<span style="color: #666666">0</span>]
<span style="color: #000080; font-weight: bold">Out[5]: </span><span style="color: #888888">0</span>
<span style="color: #000080; font-weight: bold">In [6]: </span><span style="color: #008000; font-weight: bold">import</span> <span style="color: #0000FF; font-weight: bold">matplotlib.pyplot</span> <span style="color: #008000; font-weight: bold">as</span> <span style="color: #0000FF; font-weight: bold">plt</span>
<span style="color: #000080; font-weight: bold">In [7]: </span>plt<span style="color: #666666">.</span>plot(x, y)
<span style="color: #000080; font-weight: bold">In [8]: </span>a<span style="color: #666666">=</span><span style="color: #BA2121">&#39;multiple-</span><span style="color: #BB6622; font-weight: bold">\n</span><span style="color: #BA2121">line</span><span style="color: #BB6622; font-weight: bold">\n</span><span style="color: #BA2121">output&#39;</span>
<span style="color: #000080; font-weight: bold">In [9]: </span>a
<span style="color: #000080; font-weight: bold">Out[9]: </span><span style="color: #888888">&#39;multiple-\nline\noutput&#39;</span>
<span style="color: #000080; font-weight: bold">In [10]: </span><span style="color: #008000">print</span>(a)
<span style="color: #888888">multiple-</span>
<span style="color: #888888">line</span>
<span style="color: #888888">output</span>
</pre></div>
<p>
Here is the interactive session again, but with <code>pyshell-t</code>.

<p>

<!-- code=python (!bc pyshell) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #666666">&gt;&gt;&gt;</span> <span style="color: #008000; font-weight: bold">from</span> <span style="color: #0000FF; font-weight: bold">numpy</span> <span style="color: #008000; font-weight: bold">import</span> linspace, sin
<span style="color: #666666">&gt;&gt;&gt;</span> <span style="color: #408080; font-style: italic"># Some comment</span>
<span style="color: #666666">&gt;&gt;&gt;</span> x <span style="color: #666666">=</span> linspace(<span style="color: #666666">0</span>, <span style="color: #666666">2</span>, <span style="color: #666666">11</span>)
<span style="color: #666666">&gt;&gt;&gt;</span> y <span style="color: #666666">=</span> sin(x)
<span style="color: #666666">&gt;&gt;&gt;</span> y[<span style="color: #666666">0</span>]
<span style="color: #666666">0</span>
<span style="color: #666666">&gt;&gt;&gt;</span> <span style="color: #008000; font-weight: bold">import</span> <span style="color: #0000FF; font-weight: bold">matplotlib.pyplot</span> <span style="color: #008000; font-weight: bold">as</span> <span style="color: #0000FF; font-weight: bold">plt</span>
<span style="color: #666666">&gt;&gt;&gt;</span> plt<span style="color: #666666">.</span>plot(x, y)
</pre></div>
<p>
<!-- This one tests a + sign before a code environment -->
C++:
<p>

<!-- code=c++ (!bc cpppro) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #BC7A00">#include</span> <span style="color: #408080; font-style: italic">&lt;iostream&gt;</span><span style="color: #BC7A00"></span>

<span style="color: #B00040">int</span> <span style="color: #0000FF">main</span>()
{
   std<span style="color: #666666">::</span>cout <span style="color: #666666">&lt;&lt;</span> <span style="color: #BA2121">&quot;Sample output&quot;</span> <span style="color: #666666">&lt;&lt;</span> std<span style="color: #666666">::</span>endl;
   <span style="color: #008000; font-weight: bold">return</span> <span style="color: #666666">0</span>
}
</pre></div>
<p>
<!-- The next should get correctly typset in sphinx (cod is fcod) -->
<!-- It also tests emoji before code -->
And a little bit of Fortran: <img src="https://raw.githubusercontent.com/hplgit/doconce/master/bundled/emoji/png/dizzy_face.png" width="22px" height="22px" align="center">

<p>

<!-- code=text typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>!bc cod
      subroutine midpt(x, length, a, b)
      real*8 a, b, x
      x = (a + b)/2
      length = b - a
      return
      end
!ec
</pre></div>
<p>
which then is typeset as

<p>

<!-- code=text (!bc cod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>      subroutine midpt(x, length, a, b)
      real*8 a, b, x
      x = (a + b)/2
      length = b - a
      return
      end
</pre></div>
<p>
HTML:

<p>

<!-- code=html (!bc htmlcod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>&lt;<span style="color: #008000; font-weight: bold">table</span>&gt;
&lt;<span style="color: #008000; font-weight: bold">tr</span>&gt;&lt;<span style="color: #008000; font-weight: bold">td</span>&gt;Column 1&lt;/<span style="color: #008000; font-weight: bold">td</span>&gt;&lt;<span style="color: #008000; font-weight: bold">td</span>&gt;Column 2&lt;/<span style="color: #008000; font-weight: bold">td</span>&gt;&lt;/<span style="color: #008000; font-weight: bold">tr</span>&gt;
&lt;<span style="color: #008000; font-weight: bold">tr</span>&gt;&lt;<span style="color: #008000; font-weight: bold">td</span>&gt;0.67526 &lt;/<span style="color: #008000; font-weight: bold">td</span>&gt;&lt;<span style="color: #008000; font-weight: bold">td</span>&gt;0.92871 &lt;/<span style="color: #008000; font-weight: bold">td</span>&gt;&lt;/<span style="color: #008000; font-weight: bold">tr</span>&gt;
<span style="color: #408080; font-style: italic">&lt;!-- comment --&gt;</span>
&lt;/<span style="color: #008000; font-weight: bold">table</span>&gt;
</pre></div>
<p>
But inline HTML code is also important, like text that starts with
<code>&lt;a href=&quot;</code> (which can destroy the following text if not properly
quoted).

<p>
Matlab with comments requires special typesetting:

<p>

<!-- code=matlab (!bc mcod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #408080; font-style: italic">% Comment on the beginning of the line can be escaped by %%</span>
<span style="color: #008000; font-weight: bold">if</span> a <span style="color: #666666">&gt;</span> b
  <span style="color: #408080; font-style: italic">% Indented comment needs this trick</span>
  c = a <span style="color: #666666">+</span> b
<span style="color: #008000; font-weight: bold">end</span>
</pre></div>
<p>
And here is a system call:

<p>

<!-- code=text (!bc sys) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>Terminal&gt; mkdir test
Terminal&gt; cd test
Terminal&gt; myprog -f
output1
output2
</pre></div>
<p>
Any valid pygments lexer/language name can appear to, e.g.,

<p>

<!-- code=text typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>!bc restructuredtext
=======
Heading
=======

Some text.
!ec
</pre></div>
<p>
results in

<p>

<!-- code=restructuredtext (!bc restructuredtext) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #000080; font-weight: bold">=======</span>
<span style="color: #000080; font-weight: bold">Heading</span>
<span style="color: #000080; font-weight: bold">=======</span>

Some text.
</pre></div>
<p>
<!-- Here goes hidden code. -->
<!-- Python can be treated by some formats, Fortran is always out. -->

<p>
Finally, <code>!bc do</code> supports highlighting of DocOnce source:

<p>

<!-- code=doconce (!bc do) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #000080; font-weight: bold">======= DocOnce test file =======</span>

<span style="color: #000080; font-weight: bold">===== Computer code =====</span>

Inline verbatim code, as in `import numpy as np`, is allowed, as well as
code blocks:

!bc pycod
from math import sin

def f(x):
    &quot;&quot;&quot;Example on a function.&quot;&quot;&quot;
    return sin(x) + 1

print(f(0))
!ec


<span style="color: #000080; font-weight: bold">===== Mathematics =====</span>

Formulas can be inline, as in $\nabla\cdot\boldsymbol{u} = 0$, or typeset
as equations:

!bt
<span style="color: #008000">\begin{align*}</span>
\nabla\cdot\boldsymbol{u} &amp;= 0,\\ 
\boldsymbol{u} &amp;= \nabla\phi .
<span style="color: #008000">\end{align*}</span>
!et

<span style="color: #000080; font-weight: bold">=== Subsubsection heading ===</span>

DocOnce files can have chapters, sections, subsections, and subsubsections.

<span style="color: #800080; font-weight: bold">__Paragraph heading.__</span> Paragraphs may have headings.
</pre></div>
<p>
It is time to test <code>verbatim inline font</code> especially with <code>a newline
inside the text</code> and an exclamation mark at the end: <code>BEGIN</code>! For
spellcheck, test <code>a verbatim expression</code> in <code>another</code> in a <code>third</code>.
Also test exclamation mark as in <code>!bc</code> and <code>!ec</code> as well as <code>a != b</code>.
Also test backslashes and braces like <code>\begin</code>, <code>\begin{enumerate}</code>,
<code>\end{this}\end{that}</code>, and <code>{something \inside braces}</code>.

<p>
Here is some <font color="red">red color</font> and an attempt to write <font color="green">with
green color containing a linebreak<br />
code.</font> Some formats will only display <br />
this correctly when <code>html</code> <br />
is the output format.
But here some more running text is added which is not part of
the previous blocks with line breaks.

<h3 id="running-os-commands" class="anchor">Running OS commands </h3>

<p>

<!-- code=text (!bc sys) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>Terminal&gt; python -c &#39;print(&quot;Testing\noutput\nfrom\nPython.&quot;)&#39;
Testing
output
from
Python.
</pre></div>

<h3 id="footnotes" class="anchor">Footnotes </h3>

<p>
Here is a test of footnotes <button type="button" class="btn btn-primary btn-xs" rel="tooltip" data-placement="top" title="Typesetting of the footnote depends on the format. Plain text does nothing, LaTeX removes the definition and inserts the footnote as part of the LaTeX text. reStructuredText and Sphinx employ a similar type of typesetting as Extended Markdown and DocOnce, and in HTML we keep the same syntax, just displayed properly in HTML."><a href="#def_footnote_1" id="link_footnote_1" style="color: white">1</a></button>, which are handy in text.
They are used in different flavors, now in

<ul>
 <li> list items (note below that footnotes work after math, verbatim, and URLs - bin fact old and emphasize too!)</li>
 <li> even with math \( \nabla^2u \) <button type="button" class="btn btn-primary btn-xs" rel="tooltip" data-placement="top" title="Math footnotes can be dangerous since it interferes with an exponent."><a href="#def_footnote_2" id="link_footnote_2" style="color: white">2</a></button></li>
 <li> and code <code>h[i] += 1</code> <button type="button" class="btn btn-primary btn-xs" rel="tooltip" data-placement="top" title="One-line footnote."><a href="#def_footnote_3" id="link_footnote_3" style="color: white">3</a></button>
   (<em>must</em> have space between inline code and footnote!)</li>
 <li> and <a href="https://google.com" target="_self">links</a> <button type="button" class="btn btn-primary btn-xs" rel="tooltip" data-placement="top" title="google.com is perhaps the most famous web site today."><a href="#def_footnote_4" id="link_footnote_4" style="color: white">4</a></button></li>
</ul>

which gives flexibility in writing.
This is the third <button type="button" class="btn btn-primary btn-xs" rel="tooltip" data-placement="top" title="Not much to add here, but the footnote is at the end with only one newline."><a href="._testdoc_vagrant003.html#def_footnote_5" id="link_footnote_5" style="color: white">5</a></button> example.

<p id="def_footnote_1"><a href="#link_footnote_1"><b>1:</b></a> Typesetting of the footnote depends on the format.
Plain text does nothing, LaTeX removes the
definition and inserts the footnote as part of the LaTeX text.
reStructuredText and Sphinx employ a similar type of typesetting
as Extended Markdown and DocOnce, and in HTML we keep the same
syntax, just displayed properly in HTML.</p>

<p id="def_footnote_2"><a href="#link_footnote_2"><b>2:</b></a> Math footnotes can be dangerous since it
interferes with an exponent.</p>

<p id="def_footnote_3"><a href="#link_footnote_3"><b>3:</b></a> One-line footnote.</p>

<p id="def_footnote_4"><a href="#link_footnote_4"><b>4:</b></a> <a href="google.com" target="_self"><tt>google.com</tt></a> is perhaps the most famous
web site today.</p>

<p>
Here is some more text before a new definition of a footnote that was
used above.

<p>
<div class="alert alert-block alert-success alert-text-normal"><b>Non-breaking space character</b>
This paragraph aims to test <a href="https://en.wikipedia.org/wiki/Non-breaking_space" target="_self">non-breaking space character</a>, and a typical
example where this is needed is in physical units: 7.4&nbsp;km is traveled
in&nbsp;\( 7.4/5.5\approx 1.345 \)&nbsp;s.  Also check that a&nbsp;<a href="https://google.com" target="_self">link</a>&nbsp;is
not broken across lines (drag the browser window to test this).
(On the other hand, the tilde is used in
computer code, e.g., as in <code>[~x for x in y]</code> or in <code>y=~x</code>, and should
of course remain a tilde in those contexts.)
</div>


<h2 id="subsec:ex" class="anchor">Subsection 2: Testing figures</h2>

<p>
Test of figures. In particular we refer to Figure <a href="#fig:impact">1</a> in which
there is a flow.

<p>
<center> <!-- figure label: --> <div id="fig:impact"></div> <!-- FIGURE -->
<hr class="figure">
<center><p class="caption">Figure 1:  Visualization <b>of</b> a <em>wave</em>.  <!-- caption label: fig:impact --> </p></center>
<p><img src="../doc/src/manual/fig/wave1D.png" align="bottom" width=200></p>
</center>

<p>
Figures without captions are allowed and will be inlined.

<p>
<br /><br /><center><p><img src="../doc/src/manual/fig/wave1D.png" align="bottom" width=200></p></center><br /><br />

<p>
<!-- Test multi-line caption in figure with sidecap=True -->

<p>
Here is figure <a href="#myfig">2</a> with a long (illegal) multi-line caption
containing inline verbatim text:

<p>
<center> <!-- figure label: --> <div id="myfig"></div> <!-- FIGURE -->
<hr class="figure">
<table><tr>
<td><img src="../doc/src/manual/fig/wave1D.png" align="bottom" width=500></td>
<td><p class="caption">Figure 2:  A long caption spanning several lines and containing verbatim words like <code>my_file_v1</code> and <code>my_file_v2</code> as well as math with subscript as in \( t_{i+1} \).  <!-- caption label: myfig --> </p></td>
</tr></table>
</center>

<p>
<!-- Must be a blank line after MOVIE or FIGURE to detect this problem -->

<p>
Test URL as figure name:

<p>
<br /><br /><center><p><img src="https://raw.github.com/doconce/doconce/master/doc/src/blog/f_plot.png" align="bottom" width=500></p></center><br /><br />

<p>
Test SVG figure:

<p>
<br /><br /><center><p><img src="https://openclipart.org/people/jpneok/junebug.svg" align="bottom" width=200></p></center><br /><br />

<p>
<!-- Test wikimedia type of files that otherwise reside in subdirs -->

<p>
HTML output may feature Bokeh plots:

<p>
<br /><br /><center><p>
<!-- Bokeh plot -->
<script type="text/javascript">
            Bokeh.$(function() {
                var modelid = "dc6ef912-b325-4c34-996a-cdeb5aa4d7c1";
                var modeltype = "PlotContext";
                var elementid = "ffba6087-a45a-46eb-9368-11527f1f0a34";
                Bokeh.logger.info("Realizing plot:")
                Bokeh.logger.info(" - modeltype: PlotContext");
                Bokeh.logger.info(" - modelid: dc6ef912-b325-4c34-996a-cdeb5aa4d7c1");
                Bokeh.logger.info(" - elementid: ffba6087-a45a-46eb-9368-11527f1f0a34");
                var all_models = [{"attributes": {"line_color": {"value": "#1f77b4"}, "line_alpha": {"value": 1.0}, "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "y": {"field": "y"}, "x": {"field": "x"}, "id": "f55b6039-f6a1-48ce-be42-ce4e37ec18de"}, "type": "Line", "id": "f55b6039-f6a1-48ce-be42-ce4e37ec18de"}, {"attributes": {"tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "mantissas": [2, 5, 10], "id": "d8f3c08e-df44-47cd-ab00-9391128fc8ba", "num_minor_ticks": 5}, "type": "BasicTicker", "id": "d8f3c08e-df44-47cd-ab00-9391128fc8ba"}, {"attributes": {"column_names": ["x", "y"], "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "selected": {"2d": {"indices": []}, "1d": {"indices": []}, "0d": {"indices": [], "flag": false}}, "callback": null, "data": {"y": [0.0, 1.0, 8.0, 27.0], "x": [0.0, 1.0, 2.0, 3.0]}, "id": "51fd7aaa-934d-4dab-97d6-7be6eea30d89"}, "type": "ColumnDataSource", "id": "51fd7aaa-934d-4dab-97d6-7be6eea30d89"}, {"attributes": {"plot": {"subtype": "Figure", "type": "Plot", "id": "bac26888-fe18-4833-afe3-61e241eed748"}, "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "id": "8a41a3f3-b32f-4813-bc9d-78656dd129b0"}, "type": "ResizeTool", "id": "8a41a3f3-b32f-4813-bc9d-78656dd129b0"}, {"attributes": {"plot": {"subtype": "Figure", "type": "Plot", "id": "bac26888-fe18-4833-afe3-61e241eed748"}, "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "id": "734545fc-60c1-4271-bc10-b2b490266002"}, "type": "HelpTool", "id": "734545fc-60c1-4271-bc10-b2b490266002"}, {"attributes": {"names": [], "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "id": "294cc5ee-f95b-4023-8b38-eb845e408397", "renderers": []}, "type": "DataRange1d", "id": "294cc5ee-f95b-4023-8b38-eb845e408397"}, {"attributes": {"plot": {"subtype": "Figure", "type": "Plot", "id": "bac26888-fe18-4833-afe3-61e241eed748"}, "dimensions": ["width", "height"], "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "id": "26f46aa8-dc6f-4265-84dd-4525866c89d0"}, "type": "PanTool", "id": "26f46aa8-dc6f-4265-84dd-4525866c89d0"}, {"attributes": {"plot": {"subtype": "Figure", "type": "Plot", "id": "bac26888-fe18-4833-afe3-61e241eed748"}, "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "formatter": {"type": "BasicTickFormatter", "id": "a1aa95e9-9b48-4736-8854-fd7faf6b25ed"}, "ticker": {"type": "BasicTicker", "id": "71a73f31-ff56-477b-83da-62dfb4cb7d93"}, "id": "6980f350-9b3e-40f2-9ebb-d8a349a0207e"}, "type": "LinearAxis", "id": "6980f350-9b3e-40f2-9ebb-d8a349a0207e"}, {"attributes": {"plot": {"subtype": "Figure", "type": "Plot", "id": "bac26888-fe18-4833-afe3-61e241eed748"}, "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "id": "2de49bc5-9815-4275-a6de-e81ef1840cbe"}, "type": "ResetTool", "id": "2de49bc5-9815-4275-a6de-e81ef1840cbe"}, {"attributes": {"tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "mantissas": [2, 5, 10], "id": "71a73f31-ff56-477b-83da-62dfb4cb7d93", "num_minor_ticks": 5}, "type": "BasicTicker", "id": "71a73f31-ff56-477b-83da-62dfb4cb7d93"}, {"attributes": {"plot": {"subtype": "Figure", "type": "Plot", "id": "bac26888-fe18-4833-afe3-61e241eed748"}, "dimensions": ["width", "height"], "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "id": "d242820f-6005-4e2d-aaca-d2a19392726a"}, "type": "BoxZoomTool", "id": "d242820f-6005-4e2d-aaca-d2a19392726a"}, {"attributes": {"doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "id": "a1aa95e9-9b48-4736-8854-fd7faf6b25ed", "tags": []}, "type": "BasicTickFormatter", "id": "a1aa95e9-9b48-4736-8854-fd7faf6b25ed"}, {"subtype": "Figure", "type": "Plot", "id": "bac26888-fe18-4833-afe3-61e241eed748", "attributes": {"x_range": {"type": "DataRange1d", "id": "294cc5ee-f95b-4023-8b38-eb845e408397"}, "right": [], "tags": [], "tools": [{"type": "PanTool", "id": "26f46aa8-dc6f-4265-84dd-4525866c89d0"}, {"type": "WheelZoomTool", "id": "747f14a5-9f75-417c-8168-fb0a0ae3aa11"}, {"type": "BoxZoomTool", "id": "d242820f-6005-4e2d-aaca-d2a19392726a"}, {"type": "PreviewSaveTool", "id": "0c4a0cdc-08d4-4019-b03a-c03954d8f00a"}, {"type": "ResizeTool", "id": "8a41a3f3-b32f-4813-bc9d-78656dd129b0"}, {"type": "ResetTool", "id": "2de49bc5-9815-4275-a6de-e81ef1840cbe"}, {"type": "HelpTool", "id": "734545fc-60c1-4271-bc10-b2b490266002"}], "title": "Bokeh test", "extra_y_ranges": {}, "renderers": [{"type": "LinearAxis", "id": "6980f350-9b3e-40f2-9ebb-d8a349a0207e"}, {"type": "Grid", "id": "4765692c-4f39-462b-91c6-28b2f2981e00"}, {"type": "LinearAxis", "id": "ade0b05a-7b91-42dd-98de-74fb64acf6f7"}, {"type": "Grid", "id": "b9b421c8-77f3-4e7e-826b-ac6bf659b06a"}, {"type": "GlyphRenderer", "id": "2880ba24-eb39-4b26-b4fc-475578d6fd4c"}], "extra_x_ranges": {}, "below": [{"type": "LinearAxis", "id": "6980f350-9b3e-40f2-9ebb-d8a349a0207e"}], "tool_events": {"type": "ToolEvents", "id": "1695660e-4ea6-4d6d-9921-0d71ad942082"}, "above": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "y_range": {"type": "DataRange1d", "id": "c973a007-1e1b-45a1-a7ba-d05f16dfaad0"}, "id": "bac26888-fe18-4833-afe3-61e241eed748", "left": [{"type": "LinearAxis", "id": "ade0b05a-7b91-42dd-98de-74fb64acf6f7"}]}}, {"attributes": {"names": [], "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "id": "c973a007-1e1b-45a1-a7ba-d05f16dfaad0", "renderers": []}, "type": "DataRange1d", "id": "c973a007-1e1b-45a1-a7ba-d05f16dfaad0"}, {"attributes": {"tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "id": "dc6ef912-b325-4c34-996a-cdeb5aa4d7c1", "children": [{"subtype": "Figure", "type": "Plot", "id": "bac26888-fe18-4833-afe3-61e241eed748"}]}, "type": "PlotContext", "id": "dc6ef912-b325-4c34-996a-cdeb5aa4d7c1"}, {"attributes": {"line_color": {"value": "#1f77b4"}, "line_alpha": {"value": 0.1}, "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "y": {"field": "y"}, "x": {"field": "x"}, "id": "af17e0b1-cd09-4529-b97b-aefe6bff3ee2"}, "type": "Line", "id": "af17e0b1-cd09-4529-b97b-aefe6bff3ee2"}, {"attributes": {"plot": {"subtype": "Figure", "type": "Plot", "id": "bac26888-fe18-4833-afe3-61e241eed748"}, "dimensions": ["width", "height"], "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "id": "747f14a5-9f75-417c-8168-fb0a0ae3aa11"}, "type": "WheelZoomTool", "id": "747f14a5-9f75-417c-8168-fb0a0ae3aa11"}, {"attributes": {"plot": {"subtype": "Figure", "type": "Plot", "id": "bac26888-fe18-4833-afe3-61e241eed748"}, "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "formatter": {"type": "BasicTickFormatter", "id": "e6be9566-7576-4bac-a09f-bf95a818d7f8"}, "ticker": {"type": "BasicTicker", "id": "d8f3c08e-df44-47cd-ab00-9391128fc8ba"}, "id": "ade0b05a-7b91-42dd-98de-74fb64acf6f7"}, "type": "LinearAxis", "id": "ade0b05a-7b91-42dd-98de-74fb64acf6f7"}, {"attributes": {"plot": {"subtype": "Figure", "type": "Plot", "id": "bac26888-fe18-4833-afe3-61e241eed748"}, "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "dimension": 1, "ticker": {"type": "BasicTicker", "id": "d8f3c08e-df44-47cd-ab00-9391128fc8ba"}, "id": "b9b421c8-77f3-4e7e-826b-ac6bf659b06a"}, "type": "Grid", "id": "b9b421c8-77f3-4e7e-826b-ac6bf659b06a"}, {"attributes": {"nonselection_glyph": {"type": "Line", "id": "af17e0b1-cd09-4529-b97b-aefe6bff3ee2"}, "data_source": {"type": "ColumnDataSource", "id": "51fd7aaa-934d-4dab-97d6-7be6eea30d89"}, "name": null, "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "selection_glyph": null, "id": "2880ba24-eb39-4b26-b4fc-475578d6fd4c", "glyph": {"type": "Line", "id": "f55b6039-f6a1-48ce-be42-ce4e37ec18de"}}, "type": "GlyphRenderer", "id": "2880ba24-eb39-4b26-b4fc-475578d6fd4c"}, {"attributes": {"plot": {"subtype": "Figure", "type": "Plot", "id": "bac26888-fe18-4833-afe3-61e241eed748"}, "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "dimension": 0, "ticker": {"type": "BasicTicker", "id": "71a73f31-ff56-477b-83da-62dfb4cb7d93"}, "id": "4765692c-4f39-462b-91c6-28b2f2981e00"}, "type": "Grid", "id": "4765692c-4f39-462b-91c6-28b2f2981e00"}, {"attributes": {"plot": {"subtype": "Figure", "type": "Plot", "id": "bac26888-fe18-4833-afe3-61e241eed748"}, "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "id": "0c4a0cdc-08d4-4019-b03a-c03954d8f00a"}, "type": "PreviewSaveTool", "id": "0c4a0cdc-08d4-4019-b03a-c03954d8f00a"}, {"attributes": {"geometries": [], "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "id": "1695660e-4ea6-4d6d-9921-0d71ad942082"}, "type": "ToolEvents", "id": "1695660e-4ea6-4d6d-9921-0d71ad942082"}, {"attributes": {"doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "id": "e6be9566-7576-4bac-a09f-bf95a818d7f8", "tags": []}, "type": "BasicTickFormatter", "id": "e6be9566-7576-4bac-a09f-bf95a818d7f8"}];
                Bokeh.load_models(all_models);
                var model = Bokeh.Collections(modeltype).get(modelid);
                var view = new model.default_view({model: model, el: '#ffba6087-a45a-46eb-9368-11527f1f0a34'});
                Bokeh.index[modelid] = view
            });
        </script>
<div class="plotdiv" id="ffba6087-a45a-46eb-9368-11527f1f0a34"></div></p></center><br /><br />

<p>
<b>Remark.</b>
Movies are tested in separate file <code>movies.do.txt</code>.

<p>
<!-- Somewhat challenging heading with latex math, \t, \n, ? and parenthesis -->

<h2 id="decay:sec:theta" class="anchor">The \( \theta \) parameter (not \( \nabla \)?)</h2>

<p>
Functions do not always need to be advanced, here is one
involving \( \theta \):
<p>

<!-- code=text typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>def f(theta):
    return theta**2
</pre></div>
<p>
<b>More on \( \theta \).</b>
Here is more text following headline with math.

<p>
Newcommands must also be tested in this test report:
\( \frac{1}{2} \), \( {1/2} \), \( \pmb{x} \), \( \frac{Du}{dt} \),
both inline and in block:

$$
\begin{align}
\frac{Du}{dt} &= 0\nonumber
\\ 
\frac{1}{2} &= {1/2}
\tag{1}\\ 
\frac{1}{2}\pmb{x} &= \pmb{n}
\tag{2}
\end{align}
$$

<p>
Or with align with label and numbers:

$$
\begin{align}
\frac{Du}{dt} &= 0
\tag{3}
\\ 
\frac{1}{2} &= {1/2}
\tag{4}\\ 
\frac{1}{2}\pmb{x} &= \pmb{n}
\tag{5}
\end{align}
$$

<p>
<!-- Must test more complicated align and matrix compositions -->
<!-- where DocOnce inserts auto-numbered labels etc. -->

<p>
First one numbered (automatically):

$$
\begin{align}
\begin{pmatrix}
G_2 + G_3 & -G_3 & -G_2 & 0 \\ 
-G_3 & G_3 + G_4 & 0 & -G_4 \\ 
-G_2 & 0 & G_1 + G_2 & 0 \\ 
0 & -G_4 & 0 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
 v_1 \\ 
 v_2 \\ 
 v_3 \\ 
 v_4
\end{pmatrix}
+ \cdots  \tag{6}
\\ 
\begin{pmatrix}
 C_5 + C_6 & -C_6 & 0 & 0 \\ 
 -C_6 & C_6 & 0 & 0 \\ 
 0 & 0 & 0 & 0 \\ 
 0 & 0 & 0 & 0
\end{pmatrix}
  &= \frac{d}{dt}\begin{pmatrix}
 v_1 \\ 
 v_2 \\ 
 v_3 \\ 
 v_4
\end{pmatrix} +
\begin{pmatrix}
 0 \\ 
 0 \\ 
 0 \\ 
 -i_0
\end{pmatrix}
\nonumber
\tag{7}
\end{align}$$

<p>
Second numbered (automatically):

$$
\begin{align}
\begin{pmatrix}
G_1 + G_2\\ 
-G_3 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
 v_1 \\ 
 v_2
\end{pmatrix}
+ \cdots\nonumber
\tag{8}
\\ 
\left(\begin{array}{ll}
y & 2\\ 
2 & 1
\end{array}\right)
\left(\begin{array}{ll}
0 \\ x
\end{array}\right)
&= \begin{pmatrix}
A \\ B
\end{pmatrix}
\tag{9}
\end{align}$$

<p>
Both numbered, with label by the user:

$$
\begin{align}
\begin{pmatrix}
G_1 + G_2\\ 
-G_3 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
 v_1 \\ 
 v_2
\end{pmatrix}
+ \cdots \tag{10}
\\ 
\tag{11}
\left(\begin{array}{ll}
y & 2\\ 
2 & 1
\end{array}\right)
\left(\begin{array}{ll}
0 \\ x
\end{array}\right)
&= \begin{pmatrix}
A \\ B
\end{pmatrix}
\end{align}$$

Now we refer to <a href="#mjx-eqn-10">(10)</a>-<a href="#mjx-eqn-11">(11)</a>.

<h2 id="custom-environments" class="anchor">Custom Environments </h2>

<p>
Here is an attempt to create a theorem environment via Mako
(for counting theorems) and comment lines to help replacing lines in
the <code>.tex</code> by proper begin-end LaTeX environments for theorems.
Should look nice in most formats!

<p>
<!-- begin theorem -->
<div id="theorem:fundamental1"></div>

<p>
<b>Theorem 5.</b>
Let \( a=1 \) and \( b=2 \). Then \( c=3 \).
<!-- end theorem -->

<p>
<!-- begin proof -->
<b>Proof.</b>
Since \( c=a+b \), the result follows from straightforward addition.
\( \Diamond \)
<!-- end proof -->

<p>
As we see, the proof of Theorem 5 is a modest
achievement.

<h2 id="subsec:table" class="anchor">Tables</h2>

<p>
<!-- index with comma could fool sphinx -->

<p>
Let us take this table from the manual:

<p>

<div class="row">
  <div class="col-xs-2">
    <table class="table table-striped table-hover table-condensed">
<thead>
<tr><td align="center"><b>time</b></td> <td align="center"><b>velocity</b></td> <td align="center"><b>acceleration</b></td> </tr>
</thead>
<tbody>
<tr><td align="left">   0.0     </td> <td align="right">   1.4186      </td> <td align="right">   -5.01           </td> </tr>
<tr><td align="left">   2.0     </td> <td align="right">   1.376512    </td> <td align="right">   11.919          </td> </tr>
<tr><td align="left">   4.0     </td> <td align="right">   1.1E+1      </td> <td align="right">   14.717624       </td> </tr>
</tbody>
    </table>
  </div> <!-- col-xs-2 -->
</div> <!-- cell row -->
<p>
The DocOnce source code reads
<p>

<!-- code=text (!bc ccq) typeset with pygments style "default" -->
<blockquote>
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>  |--------------------------------|
  |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>
</blockquote><p>
Here is yet another table to test that we can handle more than
one table:

<p>

<div class="row">
  <div class="col-xs-2">
    <table class="table table-striped table-hover table-condensed">
<thead>
<tr><td align="left"><b>time</b></td> <td align="left"><b>velocity</b></td> <td align="left"><b>acceleration</b></td> </tr>
</thead>
<tbody>
<tr><td align="left">   0.0     </td> <td align="left">   1.4186      </td> <td align="left">   -5.01           </td> </tr>
<tr><td align="left">   1.0     </td> <td align="left">   1.376512    </td> <td align="left">   11.919          </td> </tr>
<tr><td align="left">   3.0     </td> <td align="left">   1.1E+1      </td> <td align="left">   14.717624       </td> </tr>
</tbody>
    </table>
  </div> <!-- col-xs-2 -->
</div> <!-- cell row -->
<p>
And one with math headings (that are expanded and must be treated
accordingly), verbatim heading and entry, and no space around the pipe
symbol:

<p>

<div class="row">
  <div class="col-xs-5">
    <table class="table table-striped table-hover table-condensed">
<thead>
<tr><td align="center">\( i \)</td> <td align="center">\( h_i \)</td> <td align="center">\( \bar T_i \)</td> <td align="center"><code>L_i</code></td> </tr>
</thead>
<tbody>
<tr><td align="left">   0          </td> <td align="right">   0            </td> <td align="right">   288               </td> <td align="right">   -0.0065             </td> </tr>
<tr><td align="left">   1          </td> <td align="right">   11,000       </td> <td align="right">   216               </td> <td align="right">   0.0                 </td> </tr>
<tr><td align="left">   2          </td> <td align="right">   20,000       </td> <td align="right">   216               </td> <td align="right">   0.001               </td> </tr>
<tr><td align="left">   3          </td> <td align="right">   32,000       </td> <td align="right">   228               </td> <td align="right">   0.0028              </td> </tr>
<tr><td align="left">   4          </td> <td align="right">   47,000       </td> <td align="right">   270               </td> <td align="right">   0.0                 </td> </tr>
<tr><td align="left">   5          </td> <td align="right">   51,000       </td> <td align="right">   270               </td> <td align="right">   -0.0028             </td> </tr>
<tr><td align="left">   6          </td> <td align="right">   71,000       </td> <td align="right">   214               </td> <td align="right">   <code>NaN</code>    </td> </tr>
</tbody>
    </table>
  </div> <!-- col-xs-5 -->
</div> <!-- cell row -->
<p>
And add one with verbatim headings (with underscores),
and rows starting with <code>|-</code> because of a negative number,
and <code>|</code> right before and after verbatim word (with no space):

<p>

<div class="row">
  <div class="col-xs-8">
    <table class="table table-striped table-hover table-condensed">
<thead>
<tr><td align="center"><b>exact</b></td> <td align="center"><code>v_1</code></td> <td align="center">\( a_i \) + <code>v_2</code></td> <td align="center"><code>verb_3_</code></td> </tr>
</thead>
<tbody>
<tr><td align="right">   9        </td> <td align="right">   9.62                </td> <td align="right">   5.57                            </td> <td align="right">   8.98                    </td> </tr>
<tr><td align="right">   -20      </td> <td align="right">   -23.39              </td> <td align="right">   -7.65                           </td> <td align="right">   -19.93                  </td> </tr>
<tr><td align="right">   10       </td> <td align="right">   17.74               </td> <td align="right">   -4.50                           </td> <td align="right">   9.96                    </td> </tr>
<tr><td align="right">   0        </td> <td align="right">   -9.19               </td> <td align="right">   4.13                            </td> <td align="right">   -0.26                   </td> </tr>
</tbody>
    </table>
  </div> <!-- col-xs-8 -->
</div> <!-- cell row -->
<p>
Pipe symbols in verbatim and math text in tables used to pose difficulties,
but not
anymore:

<p>

<div class="row">
  <div class="col-xs-4">
    <table class="table table-striped table-hover table-condensed">
<thead>
<tr><td align="center">   \( S \)   </td> <td align="center"><b>        command         </b></td> </tr>
</thead>
<tbody>
<tr><td align="left">   $ ||a_0|| $      </td> <td align="right">   <code>norm|length</code>    </td> </tr>
<tr><td align="left">   \( x\cap y \)    </td> <td align="right">   <code>x|y</code>            </td> </tr>
</tbody>
    </table>
  </div> <!-- col-xs-4 -->
</div> <!-- cell row -->
<p>
Here is a table with X alignment:

<p>

<div class="row">
  <div class="col-xs-12">
    <table class="table table-striped table-hover table-condensed">
<thead>
<tr><td align="center"><b> Type</b></td> <td align="center"><b>                                                                                                                Description                                                                                                                 </b></td> </tr>
</thead>
<tbody>
<tr><td align="center">   X        </td> <td align="left">   Alignment character that is used for specifying a potentially very long text in a column in a table. It makes use of the <code>tabularx</code> package in LaTeX, otherwise (for other formats) it means <code>l</code> (centered alignment).    </td> </tr>
<tr><td align="center">   l,r,c    </td> <td align="left">   standard alignment characters                                                                                                                                                                                                                   </td> </tr>
</tbody>
    </table>
  </div> <!-- col-xs-12 -->
</div> <!-- cell row -->
<p>
Finally, a table with math
(<code>bm</code> that expands to <code>boldsymbol</code>, was tricky, but
cleanly handled now)
and URLs.

<p>
<!-- Mako code to expand URLs in the table -->
<!-- (These types of tables did not work before Jan 2014) -->

<p>

<div class="row">
  <div class="col-xs-12">
    <table class="table table-striped table-hover table-condensed">
<tr></tr>
<tbody>
<tr><td align="center">   \( \mathcal{L}=0 \)                    </td> <td align="center">   <a href="../doc/src/manual/mov/wave_frames/frame_0080.png"><img src="../doc/src/manual/mov/wave_frames/frame_0080.png" width="300"></a>    </td> <td align="center">   <a href="../doc/src/manual/mov/wave_frames/frame_0085.png"><img src="../doc/src/manual/mov/wave_frames/frame_0085.png" width="300"></a>    </td> </tr>
<tr><td align="center">   \( a=b \)                              </td> <td align="center">   <a href="../doc/src/manual/mov/wave_frames/frame_0090.png"><img src="../doc/src/manual/mov/wave_frames/frame_0090.png" width="300"></a>    </td> <td align="center">   <a href="../doc/src/manual/mov/wave_frames/frame_0095.png"><img src="../doc/src/manual/mov/wave_frames/frame_0095.png" width="300"></a>    </td> </tr>
<tr><td align="center">   \( \nabla\cdot\boldsymbol{u} =0  \)    </td> <td align="center">   <a href="../doc/src/manual/mov/wave_frames/frame_0100.png"><img src="../doc/src/manual/mov/wave_frames/frame_0100.png" width="300"></a>    </td> <td align="center">   <a href="../doc/src/manual/mov/wave_frames/frame_0105.png"><img src="../doc/src/manual/mov/wave_frames/frame_0105.png" width="300"></a>    </td> </tr>
</tbody>
    </table>
  </div> <!-- col-xs-12 -->
</div> <!-- cell row -->

<h2 id="a-test-of-verbatim-words-in-heading-with-subscript-a_i-my_file_v1-and-my_file_v2" class="anchor">A test of verbatim words in heading with subscript \( a_i \): <code>my_file_v1</code> and <code>my_file_v2</code> </h2>

<p>
<b>Paragraph with verbatim and math: <code>my_file_v1.py</code> and <code>my_file_v2.py</code> define some math \( a_{i-1} \).</b>
Here is more <code>__verbatim__</code> code and
some plain text on a new line.

<p>
<!-- Test various types of headlines -->

<h2 id="_just-bold_" class="anchor"><b>Just bold</b> </h2>

<p>
Some text.

<h2 id="just-emphasize" class="anchor"><em>Just emphasize</em> </h2>

<p>
Some text.

<h2 id="just-verbatim" class="anchor"><code>Just verbatim</code> </h2>

<p>
Some text.

<h2 id="_bold_-beginning" class="anchor"><b>Bold</b> beginning </h2>

<p>
Some text.

<h2 id="emphasize-beginning" class="anchor"><em>Emphasize</em> beginning </h2>

<p>
Some text.

<h2 id="verbatim-beginning" class="anchor"><code>Verbatim</code> beginning </h2>

<p>
Some text.

<h2 id="maybe-_bold-end_" class="anchor">Maybe <b>bold end</b> </h2>

<p>
Some text.

<h2 id="maybe-emphasize-end" class="anchor">Maybe <em>emphasize end</em> </h2>

<p>
Some text.

<h2 id="maybe-verbatim-end" class="anchor">Maybe <code>verbatim end</code> </h2>

<p>
Some text.

<h2 id="the-middle-has-<b>bold</b>-word" class="anchor">The middle has <b>bold</b> word </h2>

<p>
Some text.

<h2 id="the-middle-has-emphasize-word" class="anchor">The middle has <em>emphasize</em> word </h2>

<p>
Some text.

<h2 id="the-middle-has-verbatim-word" class="anchor">The middle has <code>verbatim</code> word </h2>

<p>
Some text.

<p>
<b><em>Just emphasize</em>.</b>
Some text.

<p>
<b><code>Just verbatim</code>.</b>
Some text.

<p>
<b><em>Emphasize</em> beginning.</b>
Some text.

<p>
<b><code>Verbatim beginning</code>.</b>
Some text.

<p>
<b>Maybe <em>emphasize end</em>.</b>
Some text.

<p>
<b>Maybe <code>verbatim end</code>.</b>
Some text.

<p>
<b>The middle has <em>emphasize</em> word.</b>
Some text.

<p>
<b>The middle has <code>verbatim</code> word.</b>
Some text.

<p>
<b>Ampersand.</b>
We can test Hennes &amp; Mauritz, often abbreviated H&amp;M, but written
as <code>Hennes & Mauritz</code> and <code>H & M</code>.
A sole <code>&</code> must also work.
<!-- Note: substitutions must not occur inside verbatim, just in ordinary text. -->

<p>

<!-- code=text typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span># Just to check that ampersand works in code blocks:
c = a &amp; b
</pre></div>
<p>
<b>Quotes.</b>
Let us also add a test of quotes such as &quot;double quotes, with numbers
like 3.14 and newline/comma and hyphen (as in double-quote)&quot;; written
in the standard LaTeX-style that gives correct LaTeX formatting and
ordinary double quotes for all non-LaTeX formats.  Here is another
sentence that &quot;caused&quot; a bug in the past because double backtick
quotes could imply verbatim text up to a verbatim word starting with
period, like <code>.txt</code>.

<p>
More quotes to be tested for spellcheck:
(&quot;with parenthesis&quot;), &quot;with newline&quot;
and &quot;with comma&quot;, &quot;hyphen&quot;-wise, and &quot;period&quot;.

<h2 id="bibliography-test" class="anchor">Bibliography test </h2>

<p>
Here is an example: <a href="._testdoc_vagrant002.html#Langtangen_Pedersen_2002">[1]</a> discussed propagation of
large destructive water waves, <a href="._testdoc_vagrant002.html#Langtangen_et_al_2002">[2]</a> gave
an overview of numerical methods for solving the Navier&ndash;Stokes equations,
while the use of Backward Kolmogorov equations for analyzing
random vibrations was investigated in <a href="._testdoc_vagrant002.html#Langtangen_1994a">[3]</a>.
The book chapter <a href="._testdoc_vagrant002.html#Mardal_et_al_2003a">[4]</a> contains information on
C++ software tools for programming multigrid methods. A real retro
reference is <a href="._testdoc_vagrant002.html#Langtangen_1988d">[5]</a> about a big FORTRAN package.
Multiple references are also possible, e.g., see
<a href="._testdoc_vagrant002.html#Langtangen_Pedersen_2002">[1]</a> <a href="._testdoc_vagrant002.html#Mardal_et_al_2003a">[4]</a>.

<p>
We need to cite more than 10 papers to reproduce an old formatting
problem with blanks in the keys in reST format:
<a href="._testdoc_vagrant002.html#Langtangen_1992c">[6]</a> <a href="._testdoc_vagrant002.html#Langtangen_1994a">[3]</a> <a href="._testdoc_vagrant002.html#Mortensen_et_al_2011">[7]</a> <a href="._testdoc_vagrant002.html#Langtangen_Pedersen_2002">[1]</a>
and
<a href="._testdoc_vagrant002.html#Langtangen_et_al_2002">[2]</a> <a href="._testdoc_vagrant002.html#Glimsdal_et_al_20006">[8]</a> <a href="._testdoc_vagrant002.html#Rahman_et_al_2006b">[9]</a> <a href="._testdoc_vagrant002.html#Haga_et_al_2011a">[10]</a> <a href="._testdoc_vagrant002.html#Langtangen_2003a">[11]</a> <a href="._testdoc_vagrant002.html#Langtangen_2008a">[12]</a> <a href="._testdoc_vagrant002.html#Langtangen:95">[13]</a>
and all the work of
<a href="._testdoc_vagrant002.html#Langtangen_2012">[14]</a> <a href="._testdoc_vagrant002.html#Mardal_et_al_2003a">[4]</a> <a href="._testdoc_vagrant002.html#Jeberg_et_al_2004">[15]</a> as well as
old work <a href="._testdoc_vagrant002.html#Langtangen_1988d">[5]</a> and <a href="._testdoc_vagrant002.html#Langtangen_1989e">[16]</a>, and the
talk <a href="._testdoc_vagrant002.html#Langtangen_talk_2007a">[17]</a>.
Langtangen also had two thesis <a href="._testdoc_vagrant002.html#Langtangen:85">[18]</a> <a href="._testdoc_vagrant002.html#Langtangen_1989e">[16]</a>
back in the days.
More retro citations are
the old ME-IN323 book <a href="._testdoc_vagrant002.html#Langtangen:91">[19]</a> and the
<a href="._testdoc_vagrant002.html#Langtangen:94b">[20]</a> OONSKI '94 paper.

<p>
<!-- --- begin exercise --- -->

<h2 id="Example" class="anchor">Example 1: Examples can be typeset as exercises</h2>

<p>
Examples can start with a subsection heading starting with <code>Example:</code>
and then, with the command-line option <code>--examples_as_exercises</code> be
typeset as exercises. This is useful if one has solution
environments as part of the example.

<p>
<b>a)</b>
State some problem.

<p>
<b>Solution.</b>
The answer to this subproblem can be written here.

<p>
<b>b)</b>
State some other problem.

<p>
<b>Hint 1.</b>
A hint can be given.

<p>
<b>Hint 2.</b>
Maybe even another hint?

<p>
<b>Solution.</b>
The answer to this other subproblem goes here,
maybe over multiple doconce input lines.

<p>
<!-- --- end exercise --- -->

<h2 id="user-defined-environments" class="anchor">User-defined environments </h2>

<p>
The example in the section <a href="#ex:test:1p1">Example 1: A test function</a> demonstrates how to write a test function.
That is, a special test function for a function <code>add</code> appears in
the example in the section <a href="#ex:test:1p1">Example 1: A test function</a>.

<h2 id="ex:test:1p1" class="anchor">Example 1: A test function</h2>

<p>
Suppose we want to write a test function for checking the
implementation of a Python function for addition.

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">add</span>(a, b):
    <span style="color: #008000; font-weight: bold">return</span> a <span style="color: #666666">+</span> b

<span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">test_add</span>():
    a <span style="color: #666666">=</span> <span style="color: #666666">1</span>; b <span style="color: #666666">=</span> <span style="color: #666666">1</span>
    expected <span style="color: #666666">=</span> a <span style="color: #666666">+</span> b
    computed <span style="color: #666666">=</span> add(a, b)
    <span style="color: #008000; font-weight: bold">assert</span> expected <span style="color: #666666">==</span> computed
</pre></div>

<h2 id="ex:math:1p1" class="anchor">Example 2: Addition</h2>

<p>
We have

$$ 1 + 1 = 2 $$

or in tabular form:

<p>

<div class="row">
  <div class="col-xs-1">
    <table class="table table-striped table-hover table-condensed">
<thead>
<tr><td align="center"><b> Problem </b></td> <td align="center"><b> Result</b></td> </tr>
</thead>
<tbody>
<tr><td align="center">   \( 1+1 \)    </td> <td align="center">   \( 2 \)    </td> </tr>
</tbody>
    </table>
  </div> <!-- col-xs-1 -->
</div> <!-- cell row -->
<p>
<div style="width: 60%; padding: 10px; border: 1px solid #000;
 border-radius: 4px; box-shadow: 8px 8px 5px #888888;
 background: #cce5ff;">
 <b>Highlight box!</b><hr>
This environment is used to highlight something:

$$ E = mc^2 $$

</div>

<h2 id="subsubsec:ex" class="anchor">URLs</h2>

<p>
Testing of URLs: hpl's home page <a href="https://folk.uio.no/hpl" target="_self">hpl</a>, or
the entire URL if desired, <a href="https://folk.uio.no/hpl" target="_self"><tt>https://folk.uio.no/hpl</tt></a>.  Here is a
plain file link <a href="testdoc.do.txt" target="_self"><tt>testdoc.do.txt</tt></a>, or <a href="testdoc.do.txt" target="_self"><tt>testdoc.do.txt</tt></a>, or
<a href="testdoc.do.txt" target="_self"><tt>testdoc.do.txt</tt></a> or <a href="testdoc.do.txt" target="_self"><tt>testdoc.do.txt</tt></a> or <a href="testdoc.do.txt" target="_self">a link with
newline</a>. Can test spaces with the link with word
too: <a href="https://folk.uio.no/hpl" target="_self">hpl</a> or <a href="https://folk.uio.no/hpl" target="_self">hpl</a>. Also <code>file:///</code> works: <a href="file:///home/hpl/vc/doconce/doc/demos/manual/manual.html" target="_self">link to a
file</a> is
fine to have. Moreover, &quot;loose&quot; URLs work, i.e., no quotes, just
the plain URL as in <a href="https://folk.uio.no/hpl" target="_self"><tt>https://folk.uio.no/hpl</tt></a>, if followed by space, comma,
colon, semi-colon, question mark, exclamation mark, but not a period
(which gets confused with the periods inside the URL).

<p>
Mail addresses can also be used: <a href="mailto:hpl@simula.no" target="_self"><tt>hpl@simula.no</tt></a>, or just a <a href="mailto:hpl@simula.no" target="_self">mail link</a>, or a raw <a href="mailto:hpl@simula.no" target="_self"><tt>mailto:hpl@simula.no</tt></a>.

<p>
Here are some tough tests of URLs, especially for the <code>latex</code> format:
<a href="https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas" target="_self">Newton-Cotes</a> formulas
and a <a href="https://www.springer.com/mathematics/computational+science+%26+engineering/book/978-3-642-23098-1" target="_self">good book</a>. Need to test
Newton-Cotes with percentage in URL too:
<a href="https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas" target="_self"><tt>https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas</tt></a>
and <a href="https://en.wikipedia.org/wiki/Newton-Cotes#Open_Newton.E2.80.93Cotes_formulae" target="_self"><tt>https://en.wikipedia.org/wiki/Newton-Cotes#Open_Newton.E2.80.93Cotes_formulae</tt></a> which has a shebang.

<p>
For the <code>--device=paper</code> option it is important to test that URLs with
monospace font link text get a footnote
(unless the <code>--latex_no_program_footnotelink</code>
is used), as in this reference to
<a href="https://github.com/hplgit/INF5620/tree/gh-pages/src/decay/experiments/decay_mod.py" target="_self"><tt>decay_mod</tt></a>, <a href="https://tinyurl.com/pwyasaa/formulas.ball1.py" target="_self"><tt>ball1.py</tt></a>,
and <a href="https://tinyurl.com/pwyasaa/formulas.ball2.py" target="_self"><tt>ball2.py</tt></a>.

<p>
<!-- Comments should be inserted outside paragraphs (because in the rst -->
<!-- format extra blanks make a paragraph break). -->

<p>
<!-- Note that when there is no https: or file:, it can be a file link -->
<!-- if the link name is URL, url, "URL", or "url". Such files should, -->
<!-- if rst output is desired, but placed in a <code>_static*</code> folder. -->

<p>
More tough tests: repeated URLs whose footnotes when using the
<code>--device=paper</code> option must be correct. We have
<a href="https://google.com" target="_self">google</a>, <a href="https://google.com" target="_self">google</a>, and
<a href="https://google.com" target="_self">google</a>, which should result in exactly three
footnotes.

<p>
<p>
<!-- navigation buttons at the bottom of the page -->
<ul class="pager">

  <li class="previous">
    <a href="._testdoc_vagrant000.html">&larr; Prev</a>
  </li>

  <li class="next">
    <a href="._testdoc_vagrant002.html">Next &rarr;</a>
  </li>
</ul>
<!-- ------------------- end of main content --------------- -->

 </div>

 <div class="row Footer">
  <div class="span12">
  <!-- footer --> Here goes a footer, if desired, maybe with author(s) and a copyright &copy;
  </div>
 </div>
</div>
</body>
</html>

************** File: ._testdoc_vagrant002.html *****************
<html>
<head>
<!-- Bootstrap style: vagrant 1.0 web pages -->

<!--
This style is adopted from the (now old) vagrant 1.0 web pages.

This style file should be copied and the following elements edited:

Logo heading:

 LogoWord
 withSubWord

Navigation links at the top:

 GO TO 1
 GO TO 2

Footer at the end
-->

<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Doconce: http://code.google.com/p/doconce/" />

<title>A Document for Testing DocOnce</title>

<!-- If you copy the css subdirectory (and, e.g., make optional edits):
<link rel="stylesheet" href="css/twitter_bootstrap.css">
<link rel="stylesheet" href="css/vagrant.css">
Otherwise, rely on the URLs below (vagrant.css adapted to Doconce layout)
-->

<link rel="stylesheet" href="https://raw.githubusercontent.com/hplgit/doconce/master/bundled/html_styles/style_vagrant/css/twitter_bootstrap.css">
<link rel="stylesheet" href="https://raw.githubusercontent.com/hplgit/doconce/master/bundled/html_styles/style_vagrant/css/vagrant.css">

<!-- Define color of headings here (last definition counts) -->
<style type="text/css">
h1, h2, h3, h4, h5, h6 {
  color: #000;     /* black */
  color: #999;     /* gray */
  color: #005580;  /* dark blue */
  color: #08c;     /* characteristic blue */
</style>

<!-- Tools for embedded Bokeh plots -->
<link rel="stylesheet"
      href="https://cdn.pydata.org/bokeh/release/bokeh-0.9.0.min.css"
      type="text/css" />
<script type="text/javascript"
	src="https://cdn.pydata.org/bokeh/release/bokeh-0.9.0.min.js">
</script>
<script type="text/javascript">
  Bokeh.set_log_level("info");
</script>


</head>
<body>

<div class="container">
 <div class="row Header with-border">
  <div class="span3 Module logo">
   <h1><a href="/">LogoWord<span class="subtitle">withSubWord</span></a></h1>
  </div>
  <div class="span9">
   <div class="Module navigation">
   <!-- Navigation at the top of the page -->
    <ul>
     <li> <a href="">GO TO 1</a></li>
     <li> <a href="">GO TO 2</a></li>
    </ul>
   </div>
  </div>
 </div>
</div>


<!-- Here goes the table of contents in the sidebar
     <li class="active"> means dark blue background for current section
-->
<div class="row">
 <div class="span3 Module sidebar">
  <div class="well" style="padding: 8px 0px;">
   <ul class="nav nav-list">
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant000.html#table_of_contents" style="font-size: 80%;"><b>Table of contents</b></a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#sec1" style="font-size: 80%;"><b>Section 1</b></a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#subsec1" style="font-size: 80%;">Subsection 1</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#subsec:ex" style="font-size: 80%;">Subsection 2: Testing figures</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#decay:sec:theta" style="font-size: 80%;">The \( \theta \) parameter (not \( \nabla \)?)</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#custom-environments" style="font-size: 80%;">Custom Environments</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#subsec:table" style="font-size: 80%;">Tables</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#a-test-of-verbatim-words-in-heading-with-subscript-a_i-my_file_v1-and-my_file_v2" style="font-size: 80%;">A test of verbatim words in heading with subscript \( a_i \): <code>my_file_v1</code> and <code>my_file_v2</code></a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#_just-bold_" style="font-size: 80%;"><b>Just bold</b></a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#just-emphasize" style="font-size: 80%;"><em>Just emphasize</em></a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#just-verbatim" style="font-size: 80%;"><code>Just verbatim</code></a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#_bold_-beginning" style="font-size: 80%;"><b>Bold</b> beginning</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#emphasize-beginning" style="font-size: 80%;"><em>Emphasize</em> beginning</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#verbatim-beginning" style="font-size: 80%;"><code>Verbatim</code> beginning</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#maybe-_bold-end_" style="font-size: 80%;">Maybe <b>bold end</b></a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#maybe-emphasize-end" style="font-size: 80%;">Maybe <em>emphasize end</em></a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#maybe-verbatim-end" style="font-size: 80%;">Maybe <code>verbatim end</code></a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#the-middle-has-<b>bold</b>-word" style="font-size: 80%;">The middle has <b>bold</b> word</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#the-middle-has-emphasize-word" style="font-size: 80%;">The middle has <em>emphasize</em> word</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#the-middle-has-verbatim-word" style="font-size: 80%;">The middle has <code>verbatim</code> word</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#bibliography-test" style="font-size: 80%;">Bibliography test</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#Example" style="font-size: 80%;">Example 1: Examples can be typeset as exercises</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#user-defined-environments" style="font-size: 80%;">User-defined environments</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#ex:test:1p1" style="font-size: 80%;">Example 1: A test function</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#ex:math:1p1" style="font-size: 80%;">Example 2: Addition</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant001.html#subsubsec:ex" style="font-size: 80%;">URLs</a></li>
     </ul>
     <!-- navigation toc: --> <li><a href="#latex-mathematics" style="font-size: 80%;"><b>LaTeX Mathematics</b></a></li>
     <!-- navigation toc: --> <li><a href="#exercises" style="font-size: 80%;"><b>Exercises</b></a></li>
     <ul class="nav">
     <!-- navigation toc: --> <li><a href="#demo:ex:1" style="font-size: 80%;">Problem 2: Flip a Coin</a></li>
     <!-- navigation toc: --> <li><a href="#not-an-exercise" style="font-size: 80%;">Not an exercise</a></li>
     <!-- navigation toc: --> <li><a href="#my:exer1" style="font-size: 80%;">Exercise 3: Test of plain text exercise</a></li>
     <!-- navigation toc: --> <li><a href="#demo:ex:2" style="font-size: 80%;">Project 4: Compute a Probability</a></li>
     <!-- navigation toc: --> <li><a href="#proj:circle1" style="font-size: 80%;">Project 5: Explore Distributions of Random Circles</a></li>
     <!-- navigation toc: --> <li><a href="#exer:dist" style="font-size: 80%;">Exercise 6: Determine some Distance</a></li>
     <!-- navigation toc: --> <li><a href="#some-exercise-without-the-exercise-prefix" style="font-size: 80%;">Some exercise without the "Exercise:" prefix</a></li>
     <!-- navigation toc: --> <li><a href="#sec:this:exer:de" style="font-size: 80%;">Exercise 8: Solution of differential equation</a></li>
     <!-- navigation toc: --> <li><a href="#example-9-just-an-example" style="font-size: 80%;">Example 9: Just an example</a></li>
     </ul>
     <!-- navigation toc: --> <li><a href="#here-goes-another-section" style="font-size: 80%;"><b>Here goes another section</b></a></li>
     <!-- navigation toc: --> <li><a href="#more-exercises" style="font-size: 80%;"><b>More Exercises</b></a></li>
     <ul class="nav">
     <!-- navigation toc: --> <li><a href="#exer:some:formula" style="font-size: 80%;">Exercise 10: Make references to projects and problems</a></li>
     <!-- navigation toc: --> <li><a href="#exer:you" style="font-size: 80%;">Project 11: References in a headings do not work well in html</a></li>
     </ul>
     <!-- navigation toc: --> <li><a href="#references" style="font-size: 80%;"><b>References</b></a></li>
     <!-- navigation toc: --> <li><a href="#app1" style="font-size: 80%;"><b>Appendix: Just for testing; part I</b></a></li>
     <ul class="nav">
     <!-- navigation toc: --> <li><a href="#a-subsection-within-an-appendix" style="font-size: 80%;">A subsection within an appendix</a></li>
     </ul>
     <!-- navigation toc: --> <li><a href="#app2" style="font-size: 80%;"><b>Appendix: Just for testing; part II</b></a></li>
     <ul class="nav">
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant003.html#appendix-testing-identical-titles" style="font-size: 80%;">Appendix: Testing identical titles</a></li>
     <!-- navigation toc: --> <li><a href="#test:title:id1" style="font-size: 80%;">Appendix: Testing identical titles</a></li>
     <!-- navigation toc: --> <li><a href="#test:title:id2" style="font-size: 80%;">Appendix: Testing identical titles</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant003.html#appendix-testing-identical-titles" style="font-size: 80%;">Appendix: Testing identical titles</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant003.html#appendix-testing-inline-comments" style="font-size: 80%;">Appendix: Testing inline comments</a></li>
     <!-- navigation toc: --> <li><a href="._testdoc_vagrant003.html#appendix-testing-headings-ending-with-verbatim-inline" style="font-size: 80%;">Appendix: Testing headings ending with <code>verbatim inline</code></a></li>

   </ul>
  </div>
 </div>

 <div class="span9">

<!-- tocinfo
{'highest level': 1,
 'sections': [('Table of contents',
               1,
               'table_of_contents',
               'table_of_contents'),
              ('Section 1', 1, 'sec1', 'sec1'),
              ('Here is a list with subsubsection heading',
               3,
               None,
               'here-is-a-list-with-subsubsection-heading'),
              ('Subsection 1', 2, 'subsec1', 'subsec1'),
              ('Test Section reference at beginning of line and after a '
               'sentence',
               3,
               None,
               'test-section-reference-at-beginning-of-line-and-after-a-sentence'),
              ('Computer code', 3, None, 'computer-code'),
              ('Subsubsection heading before code',
               3,
               None,
               'subsubsection-heading-before-code'),
              ('Running OS commands', 3, None, 'running-os-commands'),
              ('Footnotes', 3, None, 'footnotes'),
              ('Subsection 2: Testing figures', 2, 'subsec:ex', 'subsec:ex'),
              ('The $\\theta$ parameter (not $\\nabla$?)',
               2,
               'decay:sec:theta',
               'decay:sec:theta'),
              ('Custom Environments', 2, None, 'custom-environments'),
              ('Tables', 2, 'subsec:table', 'subsec:table'),
              ('A test of verbatim words in heading with subscript $a_i$: '
               '`my_file_v1` and `my_file_v2`',
               2,
               None,
               'a-test-of-verbatim-words-in-heading-with-subscript-a_i-my_file_v1-and-my_file_v2'),
              ('_Just bold_', 2, None, '_just-bold_'),
              ('*Just emphasize*', 2, None, 'just-emphasize'),
              ('`Just verbatim`', 2, None, 'just-verbatim'),
              ('_Bold_ beginning', 2, None, '_bold_-beginning'),
              ('*Emphasize* beginning', 2, None, 'emphasize-beginning'),
              ('`Verbatim` beginning', 2, None, 'verbatim-beginning'),
              ('Maybe _bold end_', 2, None, 'maybe-_bold-end_'),
              ('Maybe *emphasize end*', 2, None, 'maybe-emphasize-end'),
              ('Maybe `verbatim end`', 2, None, 'maybe-verbatim-end'),
              ('The middle has _bold_ word',
               2,
               None,
               'the-middle-has-_bold_-word'),
              ('The middle has *emphasize* word',
               2,
               None,
               'the-middle-has-emphasize-word'),
              ('The middle has `verbatim` word',
               2,
               None,
               'the-middle-has-verbatim-word'),
              ('Bibliography test', 2, None, 'bibliography-test'),
              ('Example 1: Examples can be typeset as exercises',
               2,
               'Example',
               'Example'),
              ('User-defined environments',
               2,
               None,
               'user-defined-environments'),
              ('Example 1: A test function', 2, 'ex:test:1p1', 'ex:test:1p1'),
              ('Example 2: Addition', 2, 'ex:math:1p1', 'ex:math:1p1'),
              ('URLs', 2, 'subsubsec:ex', 'subsubsec:ex'),
              ('LaTeX Mathematics', 1, None, 'latex-mathematics'),
              ('Exercises', 1, None, 'exercises'),
              ('Problem 2: Flip a Coin', 2, 'demo:ex:1', 'demo:ex:1'),
              ('My remarks', 3, None, 'my-remarks'),
              ('Remarks', 3, None, 'remarks'),
              ('Not an exercise', 2, None, 'not-an-exercise'),
              ('Exercise 3: Test of plain text exercise',
               2,
               'my:exer1',
               'my:exer1'),
              ('Project 4: Compute a Probability', 2, 'demo:ex:2', 'demo:ex:2'),
              ('Project 5: Explore Distributions of Random Circles',
               2,
               'proj:circle1',
               'proj:circle1'),
              ('Remarks', 3, None, 'remarks'),
              ('Exercise 6: Determine some Distance',
               2,
               'exer:dist',
               'exer:dist'),
              ('Remarks', 3, None, 'remarks'),
              ('Some exercise without the "Exercise:" prefix',
               2,
               None,
               'some-exercise-without-the-exercise-prefix'),
              ('Exercise 8: Solution of differential equation',
               2,
               'sec:this:exer:de',
               'sec:this:exer:de'),
              ('Example 9: Just an example',
               2,
               None,
               'example-9-just-an-example'),
              ('Here goes another section',
               1,
               None,
               'here-goes-another-section'),
              ('More Exercises', 1, None, 'more-exercises'),
              ('Exercise 10: Make references to projects and problems',
               2,
               'exer:some:formula',
               'exer:some:formula'),
              ('Project 11: References in a headings do not work well in html',
               2,
               'exer:you',
               'exer:you'),
              ('References', 1, None, 'references'),
              ('Appendix: Just for testing; part I', 1, 'app1', 'app1'),
              ('A subsection within an appendix',
               2,
               None,
               'a-subsection-within-an-appendix'),
              ('Appendix: Just for testing; part II', 1, 'app2', 'app2'),
              ('Appendix: Testing identical titles',
               2,
               None,
               'appendix-testing-identical-titles'),
              ('Appendix: Testing identical titles',
               2,
               'test:title:id1',
               'test:title:id1'),
              ('Appendix: Testing identical titles',
               2,
               'test:title:id2',
               'test:title:id2'),
              ('Appendix: Testing identical titles',
               2,
               None,
               'appendix-testing-identical-titles'),
              ('Appendix: Testing inline comments',
               2,
               None,
               'appendix-testing-inline-comments'),
              ('Appendix: Testing headings ending with `verbatim inline`',
               2,
               None,
               'appendix-testing-headings-ending-with-verbatim-inline')]}
end of tocinfo -->





<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  TeX: {
     equationNumbers: {  autoNumber: "none"  },
     extensions: ["AMSmath.js", "AMSsymbols.js", "autobold.js", "color.js"]
  }
});
</script>
<script type="text/javascript" async
 src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>



<a name="part0002"></a>
<!-- !split and check if these extra words are included properly in the comment -->

<h1 id="latex-mathematics" class="anchor">LaTeX Mathematics </h1>

<p>
Here is an equation without label using backslash-bracket environment:
$$ a = b + c $$

<p>
or with number and label, as in <a href="#mjx-eqn-12">(12)</a>, using the equation environment:

$$
\begin{equation}
{\partial u\over\partial t} = \nabla^2 u \tag{12}
\end{equation}
$$

<p>
We can refer to this equation by <a href="#mjx-eqn-12">(12)</a>.

<p>
Here is a system without equation numbers, using the align-asterisk environment:

$$
\begin{align*}
\pmb{a} &= \pmb{q}\times\pmb{n} \\ 
b &= \nabla^2 u + \nabla^4 v
\end{align*}
$$

<p>
And here is a system of equations with labels in an align environment:

$$
\begin{align}
a &= q + 4 + 5+ 6 \tag{13} \\ 
b &= \nabla^2 u + \nabla^4 x \tag{14}
\end{align}

$$

We can refer to <a href="#mjx-eqn-13">(13)</a>-<a href="#mjx-eqn-14">(14)</a>. They are a bit simpler than
the Navier&ndash;Stokes equations. And test LaTeX hyphen in <code>CG-2</code>.
Also test \( a_{i-j} \) as well as \( kx-wt \).

<p>
Testing <code>alignat</code> environment:

$$
\begin{alignat}{2}
a &= q + 4 + 5+ 6\qquad & \mbox{for } q\geq 0 \tag{15} \\ 
b &= \nabla^2 u + \nabla^4 x & x\in\Omega \tag{16}
\end{alignat}
$$

<p>
More mathematical typesetting is demonstrated in the coming exercises.

<p>
Below, we have <a href="#demo:ex:1">Problem 2: Flip a Coin</a> and <a href="#demo:ex:2">Project 4: Compute a Probability</a>,
as well as <a href="#proj:circle1">Project 5: Explore Distributions of Random Circles</a> and <a href="#exer:you">Project 11: References in a headings do not work well in html</a>, and in
between there we have <a href="#exer:some:formula">Exercise 10: Make references to projects and problems</a>.

<h1 id="exercises" class="anchor">Exercises </h1>

<p>
<!-- --- begin exercise --- -->

<h2 id="demo:ex:1" class="anchor">Problem 2: Flip a Coin</h2>
<!-- keywords = random numbers; Monte Carlo simulation; ipynb -->

<p>
<!-- Torture tests -->

<p>
<b>a)</b>
Make a program that simulates flipping a coin \( N \) times.
Print out &quot;tail&quot; or &quot;head&quot; for each flip and
let the program count the number of heads.

<p>
<!-- --- begin hint in exercise --- -->

<p>
<a class="glyphicon glyphicon-hand-right showdetails" data-toggle="collapse"
 data-target="#exer_2_1" style="font-size: 80%;"></a>
<a href="#exer_2_1" data-toggle="collapse">
<b>Hint 1.</b>
</a>
<div class="collapse-group">
<p><div class="collapse" id="exer_2_1">

<p>
Use <code>r = random.random()</code> and define head as <code>r &lt;= 0.5</code>.

<p>
</div></p>
</div>
</p>

<p>
<!-- --- end hint in exercise --- -->

<p>
<!-- --- begin hint in exercise --- -->

<p>
<a class="glyphicon glyphicon-hand-right showdetails" data-toggle="collapse"
 data-target="#exer_2_2" style="font-size: 80%;"></a>
<a href="#exer_2_2" data-toggle="collapse">
<b>Hint 2.</b>
</a>
<div class="collapse-group">
<p><div class="collapse" id="exer_2_2">

<p>
Draw an integer among \( \{1,2\} \) with
<code>r = random.randint(1,2)</code> and define head when <code>r</code> is 1.

<p>
</div></p>
</div>
</p>

<p>
<!-- --- end hint in exercise --- -->

<p>
<!-- --- begin answer of exercise --- -->

<p>
<a class="glyphicon glyphicon-hand-right showdetails" data-toggle="collapse"
 data-target="#exer_2_3" style="font-size: 80%;"></a>
<a href="#exer_2_3" data-toggle="collapse">
<b>Answer.</b>
</a>
<div class="collapse-group">
<p><div class="collapse" id="exer_2_3">

<p>
If the <code>random.random()</code> function returns a number \( < 1/2 \), let it be
head, otherwise tail. Repeat this \( N \) number of times.
</div></p>
</div>
</p>

<p>
<!-- --- end answer of exercise --- -->

<p>
<!-- --- begin solution of exercise --- -->

<p>
<a class="glyphicon glyphicon-hand-right showdetails" data-toggle="collapse"
 data-target="#exer_2_5" style="font-size: 80%;"></a>
<a href="#exer_2_5" data-toggle="collapse">
<b>Solution.</b>
</a>
<div class="collapse-group">
<p><div class="collapse" id="exer_2_5">

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">import</span> <span style="color: #0000FF; font-weight: bold">sys</span><span style="color: #666666">,</span> <span style="color: #0000FF; font-weight: bold">random</span>
N <span style="color: #666666">=</span> <span style="color: #008000">int</span>(sys<span style="color: #666666">.</span>argv[<span style="color: #666666">1</span>])
heads <span style="color: #666666">=</span> <span style="color: #666666">0</span>
<span style="color: #008000; font-weight: bold">for</span> i <span style="color: #AA22FF; font-weight: bold">in</span> <span style="color: #008000">range</span>(N):
    r <span style="color: #666666">=</span> random<span style="color: #666666">.</span>random()
    <span style="color: #008000; font-weight: bold">if</span> r <span style="color: #666666">&lt;=</span> <span style="color: #666666">0.5</span>:
        heads <span style="color: #666666">+=</span> <span style="color: #666666">1</span>
<span style="color: #008000">print</span>(<span style="color: #BA2121">&#39;Flipping a coin </span><span style="color: #BB6688; font-weight: bold">%d</span><span style="color: #BA2121"> times gave </span><span style="color: #BB6688; font-weight: bold">%d</span><span style="color: #BA2121"> heads&#39;</span> <span style="color: #666666">%</span> (N, heads))
</pre></div>
<p>
</div></p>
</div>
</p>

<p>
<!-- --- end solution of exercise --- -->

<p>
<b>b)</b>
Vectorize the code in a) using boolean indexing.

<p>
Vectorized code can be written in many ways.
Sometimes the code is less intuitive, sometimes not.
At least there is not much to find in the section <a href="._testdoc_vagrant001.html#sec1">Section 1</a>.

<p>
<b>c)</b>
Vectorize the code in a) using <code>numpy.sum</code>.

<p>
<!-- --- begin answer of exercise --- -->

<p>
<a class="glyphicon glyphicon-hand-right showdetails" data-toggle="collapse"
 data-target="#exer_2_4" style="font-size: 80%;"></a>
<a href="#exer_2_4" data-toggle="collapse">
<b>Answer.</b>
</a>
<div class="collapse-group">
<p><div class="collapse" id="exer_2_4">

<p>
<code>np.sum(np.where(r &lt;= 0.5, 1, 0))</code> or <code>np.sum(r &lt;= 0.5)</code>.
</div></p>
</div>
</p>

<p>
<!-- --- end answer of exercise --- -->

<p>
In this latter subexercise, we have an
example where the code is easy to read.

<h3 id="my-remarks" class="anchor">My remarks </h3>

<p>
Remarks with such a subsubsection is treated as more text
after the last subexercise. Test a list too:

<ol>
<li> Mark 1.</li>
<li> Mark 2.</li>
</ol>

Filenames: <code>flip_coin.py</code>, <code>flip_coin.pdf</code>.

<p>
<!-- Closing remarks for this Problem -->

<h3 id="remarks" class="anchor">Remarks </h3>

<p>
These are the exercise remarks, appearing at the very end.

<p>
<!-- solution files: mysol.txt, mysol_flip_coin.py, yet_another.file -->

<p>
<!-- --- end exercise --- -->

<h2 id="not-an-exercise" class="anchor">Not an exercise </h2>

<p>
Should be possible to stick a normal section in the middle of many
exercises.

<p>
<!-- --- begin exercise --- -->

<h2 id="my:exer1" class="anchor">Exercise 3: Test of plain text exercise</h2>

<p>
Very short exercise. What is the capital
of Norway?
Filename: <code>myexer1</code>.

<p>
<!-- --- end exercise --- -->

<p>
<!-- --- begin exercise --- -->

<h2 id="demo:ex:2" class="anchor">Project 4: Compute a Probability</h2>

<p>
<!-- Minimalistic exercise -->

<p>
What is the probability of getting a number between 0.5 and 0.6 when
drawing uniformly distributed random numbers from the interval \( [0,1) \)?

<p>
At the end we have a list because that caused problems in LaTeX
in previous DocOnce versions:

<ol>
<li> item1</li>
<li> item2</li>
</ol>

<!-- --- begin hint in exercise --- -->

<p>
<a class="glyphicon glyphicon-hand-right showdetails" data-toggle="collapse"
 data-target="#exer_4_1" style="font-size: 80%;"></a>
<a href="#exer_4_1" data-toggle="collapse">
<b>Hint.</b>
</a>
<div class="collapse-group">
<p><div class="collapse" id="exer_4_1">

<p>
To answer this question empirically, let a program
draw \( N \) such random numbers using Python's standard <code>random</code> module,
count how many of them, \( M \), that fall in the interval \( (0.5,0.6) \), and
compute the probability as \( M/N \).

<p>
</div></p>
</div>
</p>

<p>
<!-- --- end hint in exercise --- -->

<p>
<!-- --- end exercise --- -->

<p>
<!-- --- begin exercise --- -->

<h2 id="proj:circle1" class="anchor">Project 5: Explore Distributions of Random Circles</h2>
<!-- keywords = ipynb -->

<p>
The formula for a circle is given by

$$
\begin{align}
x &= x_0 + R\cos 2\pi t,
\tag{17}\\ 
y &= y_0 + R\sin 2\pi t,
\tag{18}
\end{align}
$$

where \( R \) is the radius of the circle, \( (x_0,y_0) \) is the
center point, and \( t \) is a parameter in the unit interval \( [0,1] \).
For any \( t \), \( (x,y) \) computed from <a href="#mjx-eqn-17">(17)</a>-<a href="#mjx-eqn-18">(18)</a>
is a point on the circle.
The formula can be used to generate <code>n</code> points on a circle:

<p>

<!-- code=python (!bc pypro) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">import</span> <span style="color: #0000FF; font-weight: bold">numpy</span> <span style="color: #008000; font-weight: bold">as</span> <span style="color: #0000FF; font-weight: bold">np</span>

<span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">circle</span>(R, x0, y0, n<span style="color: #666666">=501</span>):
    t <span style="color: #666666">=</span> np<span style="color: #666666">.</span>linspace(<span style="color: #666666">0</span>, <span style="color: #666666">1</span>, n)
    x <span style="color: #666666">=</span> x0 <span style="color: #666666">+</span> R<span style="color: #666666">*</span>np<span style="color: #666666">.</span>cos(<span style="color: #666666">2*</span>np<span style="color: #666666">.</span>pi<span style="color: #666666">*</span>t)
    y <span style="color: #666666">=</span> y0 <span style="color: #666666">+</span> R<span style="color: #666666">*</span>np<span style="color: #666666">.</span>sin(<span style="color: #666666">2*</span>np<span style="color: #666666">.</span>pi<span style="color: #666666">*</span>t)
    <span style="color: #008000; font-weight: bold">return</span> x, y

x, y <span style="color: #666666">=</span> circle(<span style="color: #666666">2.0</span>, <span style="color: #666666">0</span>, <span style="color: #666666">0</span>)
</pre></div>
<p>
<!-- Often in an exercise we have some comments about the solution -->
<!-- which we normally want to keep where they are. -->

<p>
The goal of this project is to draw \( N \) circles with random
center and radius. Plot each circle using the <code>circle</code> function
above.

<p>
<b>a)</b>
Let \( R \) be normally distributed and \( (x_0,y_0) \) uniformly distributed.

<p>
<!-- --- begin hint in exercise --- -->

<p>
<a class="glyphicon glyphicon-hand-right showdetails" data-toggle="collapse"
 data-target="#exer_5_1" style="font-size: 80%;"></a>
<a href="#exer_5_1" data-toggle="collapse">
<b>Hint.</b>
</a>
<div class="collapse-group">
<p><div class="collapse" id="exer_5_1">

<p>
Use the <code>numpy.random</code> module to draw the
\( x_0 \), \( y_0 \), and \( R \) quantities.

<p>
</div></p>
</div>
</p>

<p>
<!-- --- end hint in exercise --- -->

<p>
<!-- --- begin answer of exercise --- -->

<p>
<a class="glyphicon glyphicon-hand-right showdetails" data-toggle="collapse"
 data-target="#exer_5_2" style="font-size: 80%;"></a>
<a href="#exer_5_2" data-toggle="collapse">
<b>Answer.</b>
</a>
<div class="collapse-group">
<p><div class="collapse" id="exer_5_2">

<p>
Here goes the short answer to part a).
</div></p>
</div>
</p>

<p>
<!-- --- end answer of exercise --- -->

<p>
<!-- --- begin solution of exercise --- -->

<p>
<a class="glyphicon glyphicon-hand-right showdetails" data-toggle="collapse"
 data-target="#exer_5_3" style="font-size: 80%;"></a>
<a href="#exer_5_3" data-toggle="collapse">
<b>Solution.</b>
</a>
<div class="collapse-group">
<p><div class="collapse" id="exer_5_3">

<p>
Here goes a full solution to part a).
</div></p>
</div>
</p>

<p>
<!-- --- end solution of exercise --- -->

<p>
<b>b)</b>
Let \( R \) be uniformly distributed and \( (x_0,y_0) \) normally distributed.
Filename: <code>norm</code>.

<p>
<b>c)</b>
Let \( R \) and \( (x_0,y_0) \) be normally distributed.

<p>
Filename: <code>circles</code>.

<p>
<!-- Closing remarks for this Project -->

<h3 id="remarks" class="anchor">Remarks </h3>

<p>
At the very end of the exercise it may be appropriate to summarize
and give some perspectives.

<p>
<!-- --- end exercise --- -->

<p>
<!-- --- begin exercise --- -->

<h2 id="exer:dist" class="anchor">Exercise 6: Determine some Distance</h2>

<p>
Intro to this exercise. Questions are in subexercises below.

<p>
<!-- --- begin solution of exercise --- -->

<p>
<a class="glyphicon glyphicon-hand-right showdetails" data-toggle="collapse"
 data-target="#exer_6_5" style="font-size: 80%;"></a>
<a href="#exer_6_5" data-toggle="collapse">
<b>Solution.</b>
</a>
<div class="collapse-group">
<p><div class="collapse" id="exer_6_5">

<p>
Here goes a full solution of the whole exercise.
With some math \( a=b \) in this solution:
$$ \hbox{math in solution: } a = b $$

And code <code>a=b</code> in this solution:
<p>

<!-- code=text typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>a = b  # code in solution
</pre></div>
<p>
End of solution is here.

<p>
</div></p>
</div>
</p>

<p>
<!-- --- end solution of exercise --- -->

<p>
<b>a)</b>
Subexercises are numbered a), b), etc.

<p>
<!-- --- begin hint in exercise --- -->

<p>
<a class="glyphicon glyphicon-hand-right showdetails" data-toggle="collapse"
 data-target="#exer_6_1" style="font-size: 80%;"></a>
<a href="#exer_6_1" data-toggle="collapse">
<b>Hint 1.</b>
</a>
<div class="collapse-group">
<p><div class="collapse" id="exer_6_1">

<p>
First hint to subexercise a).
With math \( a=b \) in hint:

$$ a=b. $$

And with code (in plain verbatim) returning \( x+1 \) in hint:

<p>

<!-- code=text typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>def func(x):
    return x + 1  # with code in hint
</pre></div>
<p>
</div></p>
</div>
</p>

<p>
<!-- --- end hint in exercise --- -->

<p>
<!-- --- begin hint in exercise --- -->

<p>
<a class="glyphicon glyphicon-hand-right showdetails" data-toggle="collapse"
 data-target="#exer_6_2" style="font-size: 80%;"></a>
<a href="#exer_6_2" data-toggle="collapse">
<b>Hint 2.</b>
</a>
<div class="collapse-group">
<p><div class="collapse" id="exer_6_2">

<p>
Second hint to subexercise a).

<p>
Test list in hint:

<ol>
<li> item1</li>
<li> item2</li>
</ol>

</div></p>
</div>
</p>

<p>
<!-- --- end hint in exercise --- -->
Filename: <code>subexer_a.pdf</code>.

<p>
<!-- --- begin answer of exercise --- -->

<p>
<a class="glyphicon glyphicon-hand-right showdetails" data-toggle="collapse"
 data-target="#exer_6_4" style="font-size: 80%;"></a>
<a href="#exer_6_4" data-toggle="collapse">
<b>Answer.</b>
</a>
<div class="collapse-group">
<p><div class="collapse" id="exer_6_4">

<p>
Short answer to subexercise a).
With math in answer: \( a=b \).
</div></p>
</div>
</p>

<p>
<!-- --- end answer of exercise --- -->

<p>
<b>b)</b>
Here goes the text for subexercise b).

<p>
Some math \( \cos^2 x + \sin^2 x = 1 \) written one a single line:

$$ \cos^2 x + \sin^2 x = 1 \thinspace .$$

<p>
<!-- --- begin hint in exercise --- -->

<p>
<a class="glyphicon glyphicon-hand-right showdetails" data-toggle="collapse"
 data-target="#exer_6_3" style="font-size: 80%;"></a>
<a href="#exer_6_3" data-toggle="collapse">
<b>Hint.</b>
</a>
<div class="collapse-group">
<p><div class="collapse" id="exer_6_3">

<p>
A hint for this subexercise.

<p>
</div></p>
</div>
</p>

<p>
<!-- --- end hint in exercise --- -->
Filename: <code>subexer_b.pdf</code>.

<p>
<!-- --- begin solution of exercise --- -->

<p>
<a class="glyphicon glyphicon-hand-right showdetails" data-toggle="collapse"
 data-target="#exer_6_6" style="font-size: 80%;"></a>
<a href="#exer_6_6" data-toggle="collapse">
<b>Solution.</b>
</a>
<div class="collapse-group">
<p><div class="collapse" id="exer_6_6">

<p>
Here goes the solution of this subexercise.
</div></p>
</div>
</p>

<p>
<!-- --- end solution of exercise --- -->

<p>
<!-- No meaning in this weired test example: -->
The text here belongs to the main (intro) part of the exercise. Need
closing remarks to have text after subexercises.

<p>
Test list in exercise:

<ol>
<li> item1</li>
<li> item2
<!-- Closing remarks for this Exercise --></li>
</ol>

<h3 id="remarks" class="anchor">Remarks </h3>

<p>
Some final closing remarks, e.g., summarizing the main findings
and their implications in other problems can be made. These
remarks will appear at the end of the typeset exercise.

<p>
<!-- --- end exercise --- -->

<p>
<!-- --- begin exercise --- -->

<h2 id="some-exercise-without-the-exercise-prefix" class="anchor">Some exercise without the "Exercise:" prefix </h2>

<p>
<!-- Another minimalistic exercise -->

<p>
Just some text. And some math saying that \( e^0=1 \) on a single line,
to test that math block insertion is correct:

$$ \exp{(0)} = 1 $$

<p>
And a test that the code <code>lambda x: x+2</code> is correctly placed here:

<p>

<!-- code=text typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>lambda x: x+2
</pre></div>
<p>
<!-- Have some comments at the end of the exercise to see that -->
<!-- the Filename: ... is written correctly. -->
<!-- --- end exercise --- -->

<p>
<!-- --- begin exercise --- -->

<h2 id="sec:this:exer:de" class="anchor">Exercise 8: Solution of differential equation</h2>

<p>
<!-- begin quiz -->
Given

$$ \frac{dy}{dx} = -y(x),\quad y(0)=1 $$

What is the solution of this equation?</p>

<p>
<a class="glyphicon glyphicon-pencil showdetails" data-toggle="collapse"
 data-target="#quiz_id_1_A" style="font-size: 80%;"></a>
<a href="#quiz_id_1_A" data-toggle="collapse">
&nbsp;<b>Choice A:</b>
\( y=e^{-y} \)
</a>
<div class="collapse-group">
<p><div class="collapse" id="quiz_id_1_A">
<img src="https://raw.github.com/doconce/doconce/master/bundled/html_images/correct.gif">
Correct!
</div></p>
</div>
</p>

<p>
<a class="glyphicon glyphicon-pencil showdetails" data-toggle="collapse"
 data-target="#quiz_id_1_B" style="font-size: 80%;"></a>
<a href="#quiz_id_1_B" data-toggle="collapse">
&nbsp;<b>Choice B:</b>
\( y=e^{y} \)
</a>
<div class="collapse-group">
<p><div class="collapse" id="quiz_id_1_B">
<img src="https://raw.github.com/doconce/doconce/master/bundled/html_images/incorrect.gif">
Almost, but the sign is wrong (note the minus!).
</div></p>
</div>
</p>

<p>
<a class="glyphicon glyphicon-pencil showdetails" data-toggle="collapse"
 data-target="#quiz_id_1_C" style="font-size: 80%;"></a>
<a href="#quiz_id_1_C" data-toggle="collapse">
&nbsp;<b>Choice C:</b>
<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">from</span> <span style="color: #0000FF; font-weight: bold">math</span> <span style="color: #008000; font-weight: bold">import</span> exp
<span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">f</span>(x):
    <span style="color: #008000; font-weight: bold">return</span> exp(x)
</pre></div>
<p>
</a>
<div class="collapse-group">
<p><div class="collapse" id="quiz_id_1_C">
<img src="https://raw.github.com/doconce/doconce/master/bundled/html_images/incorrect.gif">
Ooops, forgot a minus: <code>exp(-x)</code>, otherwise this Python code
must be considered as a good answer. It is more natural,
though, to write the solution to the problem
in mathematical notation:

$$ y(x) = e^{-y}.$$
</div></p>
</div>
</p>

<p>
<a class="glyphicon glyphicon-pencil showdetails" data-toggle="collapse"
 data-target="#quiz_id_1_D" style="font-size: 80%;"></a>
<a href="#quiz_id_1_D" data-toggle="collapse">
&nbsp;<b>Choice D:</b>
The solution cannot be found because there is a derivative in the equation.
</a>
<div class="collapse-group">
<p><div class="collapse" id="quiz_id_1_D">
<img src="https://raw.github.com/doconce/doconce/master/bundled/html_images/incorrect.gif">
Equations with derivatives can be solved;
they are termed <em>differential
equations</em>.
</div></p>
</div>
</p>

<p>
<a class="glyphicon glyphicon-pencil showdetails" data-toggle="collapse"
 data-target="#quiz_id_1_E" style="font-size: 80%;"></a>
<a href="#quiz_id_1_E" data-toggle="collapse">
&nbsp;<b>Choice E:</b>
The equation is meaningless: an equation must be an equation
for \( x \) or \( y \), not a function \( y(x) \).
</a>
<div class="collapse-group">
<p><div class="collapse" id="quiz_id_1_E">
<img src="https://raw.github.com/doconce/doconce/master/bundled/html_images/incorrect.gif">
Equations where the unknown is a function, as \( y(x) \)
here, are called <em>differential equations</em>, and are solved by
special techniques.
</div></p>
</div>
</p>
<!-- end quiz -->


<p>
<!-- --- end exercise --- -->

<p>
<!-- --- begin exercise --- -->

<h2 id="example-9-just-an-example" class="anchor">Example 9: Just an example </h2>

<p>
<!-- This example needs the --examples_as_exercises option, otherwise -->
<!-- it is just typeset as it is written. -->

<p>
<b>a)</b>
What is the capital of Norway?

<p>
<b>Answer.</b>
Oslo.

<p>
<!-- --- end exercise --- -->

<h1 id="here-goes-another-section" class="anchor">Here goes another section </h1>

<p>
With some text, before we continue with exercises.

<h1 id="more-exercises" class="anchor">More Exercises </h1>

<p>
<!-- --- begin exercise --- -->

<h2 id="exer:some:formula" class="anchor">Exercise 10: Make references to projects and problems</h2>

<p>
<!-- Test comments not at the end only -->
Pick a statement from <a href="#proj:circle1">Project 5: Explore Distributions of Random Circles</a> or <a href="#demo:ex:1">Problem 2: Flip a Coin</a>
and verify it.

<p>
Test list at the end of an exercise without other elements (like subexercise,
hint, etc.):

<ol>
<li> item1</li>
<li> item2</li>
</ol>

Filename: <code>verify_formula.py</code>.

<p>
<!-- --- end exercise --- -->

<p>
<!-- --- begin exercise --- -->

<h2 id="exer:you" class="anchor">Project 11: References in a headings do not work well in html</h2>

<p>
Refer to the previous exercise as <a href="#exer:some:formula">Exercise 10: Make references to projects and problems</a>,
the two before that as <a href="#demo:ex:2">Project 4: Compute a Probability</a> and <a href="#proj:circle1">Project 5: Explore Distributions of Random Circles</a>,
and this one as <a href="#exer:you">Project 11: References in a headings do not work well in html</a>.
Filename: <code>selc_composed.pdf</code>.

<p>
<!-- --- end exercise --- -->

<h1 id="references" class="anchor">References </h1>

<p>
<!-- begin bibliography -->

<ol>
 <li> <div id="Langtangen_Pedersen_2002"></div> <b>H. P. Langtangen and G. Pedersen</b>. 
    Propagation of Large Destructive Waves,
    <em>International Journal of Applied Mechanics and Engineering</em>,
    7(1),
    pp. 187-204,
    2002.</li>
 <li> <div id="Langtangen_et_al_2002"></div> <b>H. P. Langtangen, K.-A. Mardal and R. Winther</b>. 
    Numerical Methods for Incompressible Viscous Flow,
    <em>Advances in Water Resources</em>,
    25,
    pp. 1125-1146,
    2002.</li>
 <li> <div id="Langtangen_1994a"></div> <b>H. P. Langtangen</b>. 
    Numerical Solution of First Passage Problems in Random Vibrations,
    <em>SIAM Journal of Scientific and Statistical Computing</em>,
    15,
    pp. 997-996,
    1994.</li>
 <li> <div id="Mardal_et_al_2003a"></div> <b>K.-A. Mardal, G. W. Zumbusch and H. P. Langtangen</b>. 
    Software Tools for Multigrid Methods,
    <em>Advanced Topics in Computational Partial Differential Equations -- Numerical Methods and Diffpack Programming</em>,
    edited by <b>H. P. Langtangen and A. Tveito</b>,
    Springer,
    2003,
    Edited book,
    <a href="http://some.where.org" target="_self"><tt>http://some.where.org</tt></a>.</li>
 <li> <div id="Langtangen_1988d"></div> <b>H. P. Langtangen</b>. 
    The FEMDEQS Program System,
    <em>Department of Mathematics, University of Oslo</em>,
    1989,
    <a href="http://www.math.uio.no/old/days/hpl/femdeqs.pdf" target="_self"><tt>http://www.math.uio.no/old/days/hpl/femdeqs.pdf</tt></a>.</li>
 <li> <div id="Langtangen_1992c"></div> <b>H. P. Langtangen</b>. 
    Stochastic Breakthrough Time Analysis of an Enhanced Oil Recovery Process,
    <em>SIAM Journal on Scientific Computing</em>,
    13,
    pp. 1394-1417,
    1992.</li>
 <li> <div id="Mortensen_et_al_2011"></div> <b>M. Mortensen, H. P. Langtangen and G. N. Wells</b>. 
    A FEniCS-Based Programming Framework for Modeling Turbulent Flow by the Reynolds-Averaged Navier-Stokes Equations,
    <em>Advances in Water Resources</em>,
    34(9),
    <a href="https://dx.doi.org/10.1016/j.advwatres.2011.02.013" target="_self">doi: 10.1016/j.advwatres.2011.02.013</a>,
    2011.</li>
 <li> <div id="Glimsdal_et_al_20006"></div> <b>S. Glimsdal, G. Pedersen, K. Atakan, C. B. Harbitz, H. P. Langtangen and F. L\ovholt</b>. 
    Propagation of the Dec.&nbsp;26, 2004 Indian Ocean Tsunami: Effects of Dispersion and Source Characteristics,
    <em>International Journal of Fluid Mechanics Research</em>,
    33(1),
    pp. 15-43,
    2006.</li>
 <li> <div id="Rahman_et_al_2006b"></div> <b>S. Rahman, J. Gorman, C. H. W. Barnes, D. A. Williams and H. P. Langtangen</b>. 
    Numerical Investigation of a Piezoelectric Surface Acoustic Wave Interaction With a One-Dimensional Channel,
    <em>Physical Review B: Condensed Matter and Materials Physics</em>,
    74,
    2006,
    035308.</li>
<li> <div id="Haga_et_al_2011a"></div> <b>J. B. Haga, H. Osnes and H. P. Langtangen</b>. 
    On the Causes of Pressure Oscillations in Low-Permeable and Low-Compressible Porous Media,
    <em>International Journal of Analytical and Numerical Methods in Geomechanics</em>,
    <a href="https://dx.doi.org/10.1002/nag.1062" target="_self">doi: 10.1002/nag.1062</a>,
    2011,
    <a href="http://onlinelibrary.wiley.com/doi/10.1002/nag.1062/abstract" target="_self"><tt>http://onlinelibrary.wiley.com/doi/10.1002/nag.1062/abstract</tt></a>.</li>
<li> <div id="Langtangen_2003a"></div> <b>H. P. Langtangen</b>. 
    <em>Computational Partial Differential Equations - Numerical Methods and Diffpack Programming</em>,
    second edition,
    <em>Texts in Computational Science and Engineering</em>,
    Springer,
    2003.</li>
<li> <div id="Langtangen_2008a"></div> <b>H. P. Langtangen</b>. 
    <em>Python Scripting for Computational Science</em>,
    third edition,
    <em>Texts in Computational Science and Engineering</em>,
    Springer,
    2008.</li>
<li> <div id="Langtangen:95"></div> <b>H. P. Langtangen and G. Pedersen</b>. 
    Finite Elements for the Boussinesq Wave Equations,
    Waves and Non-linear Processes in Hydrodynamics,
    edited by <b>J. Grue, B. Gjevik and J. E. Weber</b>,
    Kluwer Academic Publishers,
    pp. pp. 117-126,
    1995,
    <a href="http://www.amazon.ca/Waves-Nonlinear-Processes-Hydrodynamics-John/dp/0792340310" target="_self"><tt>http://www.amazon.ca/Waves-Nonlinear-Processes-Hydrodynamics-John/dp/0792340310</tt></a>.</li>
<li> <div id="Langtangen_2012"></div> <b>H. P. Langtangen</b>. 
    <em>A Primer on Scientific Programming With Python</em>,
    third edition,
    <em>Texts in Computational Science and Engineering</em>,
    Springer,
    2012.</li>
<li> <div id="Jeberg_et_al_2004"></div> <b>P. V. Jeberg, H. P. Langtangen and C. B. Terp</b>. 
    Optimization With Diffpack: Practical Example From Welding,
    <em>Simula Research Laboratory</em>,
    2004,
    Internal report.</li>
<li> <div id="Langtangen_1989e"></div> <b>H. P. Langtangen</b>. 
    Computational Methods for Two-Phase Flow in Oil Reservoirs,
    Ph.D. Thesis,
    Mechanics Division, Department of Mathematics, University of Oslo,
    1989,
    Dr.&nbsp;Scient.&nbsp;thesis..</li>
<li> <div id="Langtangen_talk_2007a"></div> <b>H. P. Langtangen</b>. 
    Computational Modeling of Huge Tsunamis From Asteroid Impacts,
    2007,
    Invited keynote lecture at the \emphInternational conference on Computational Science 2007 (ICCS'07), Beijing, China.</li>
<li> <div id="Langtangen:85"></div> <b>H. P. Langtangen</b>. 
    Solution of the Navier-Stokes Equations With the Finite Element Method in Two and Three Dimensions,
    M.Sc. Thesis,
    Mechanics Division, Department of Mathematics, University of Oslo,
    1985,
    Cand.Scient. thesis.</li>
<li> <div id="Langtangen:91"></div> <b>H. P. Langtangen and A. Tveito</b>. 
    Numerical Methods in Continuum Mechanics,
    <em>Center for Industrial Research</em>,
    1991,
    Lecture notes for a course (ME-IN 324). 286 pages..</li>
<li> <div id="Langtangen:94b"></div> <b>H. P. Langtangen</b>. 
    Diffpack: Software for Partial Differential Equations,
    <em>Proceedings of the Second Annual Object-Oriented Numerics Conference (OON-SKI'94), Sunriver, Oregon, USA</em>,
    edited by <b>A. Vermeulen</b>,
    1994.</li>
</ol>

<!-- end bibliography -->

<h1 id="app1" class="anchor">Appendix: Just for testing; part I</h1>

<p>
This is the first appendix.

<h2 id="a-subsection-within-an-appendix" class="anchor">A subsection within an appendix </h2>

<p>
Some text.

<h1 id="app2" class="anchor">Appendix: Just for testing; part II</h1>

<p>
This is more stuff for an appendix.

<h2 id="appendix-testing-identical-titles" class="anchor">Appendix: Testing identical titles </h2>

<p>
Without label.

<h2 id="test:title:id1" class="anchor">Appendix: Testing identical titles</h2>

<p>
With label.

<h2 id="test:title:id2" class="anchor">Appendix: Testing identical titles</h2>

<p>
What about inserting a quiz?

<p>
<p>
<!-- navigation buttons at the bottom of the page -->
<ul class="pager">

  <li class="previous">
    <a href="._testdoc_vagrant001.html">&larr; Prev</a>
  </li>

  <li class="next">
    <a href="._testdoc_vagrant003.html">Next &rarr;</a>
  </li>
</ul>
<!-- ------------------- end of main content --------------- -->

 </div>

 <div class="row Footer">
  <div class="span12">
  <!-- footer --> Here goes a footer, if desired, maybe with author(s) and a copyright &copy;
  </div>
 </div>
</div>
</body>
</html>

************** File: ._testdoc000.rst *****************
.. raw:: html

        <script type="text/javascript">
        $(document).ready(function() {
            $("a[href^='http']").attr('target','_blank');
        });
        </script>

.. Automatically generated Sphinx-extended reStructuredText file from DocOnce source
   (https://github.com/hplgit/doconce/)

.. |nbsp| unicode:: 0xA0
   :trim:

.. Document title:

A Document for Testing DocOnce
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

:Authors: Hans Petter Langtangen (hpl at simula.no), Kaare Dump, A. Dummy Author, I. S. Overworked and Outburned, J. Doe (j_doe at cyberspace.com)
:Date: Jan 32, 2100

The format of this document is
sphinx

*Abstract.* This is a document with many test constructions for doconce syntax.
It was used heavily for the development and kept for testing
numerous constructions, also special and less common cases.

And exactly for test purposes we have an extra line here, which
is part of the abstract.

.. Cannot demonstrate chapter headings since abstract and chapter

.. are mutually exclusive in LaTeX


************** File: ._testdoc001.rst *****************


.. |nbsp| unicode:: 0xA0
   :trim:

.. !split

.. _sec1:

Section 1
=========

Here is a nested list:

  * item1

  * item2

  * item3 which continues
    on the next line to test that feature

  * and a sublist

    * with indented subitem1

    * and a subitem2

  * and perhaps an ordered sublist

   a. first item

   b. second item,
      continuing on a new line

**Here is a list with paragraph heading.**

  * item1

  * item2

Here is a list with subsubsection heading
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  * item1

  * item2


..

    Here are two lines that make up
    a block quote for testing *emphasized words* and **boldface words**,
    also with hypens:
    *pre*-fix, post-*fix*, **pre**-fix, post-**fix**.



Here are two references. Equation |nbsp| :ref:`(6) <Eq:my:eq1>` is fine. Eq. |nbsp| :ref:`(6) <Eq:my:eq1>` too.
Even Equation :ref:`(6) <Eq:my:eq1>` without the tilde.
This equation appears in another part if this document is split.

.. _subsec1:

Subsection 1
------------

.. index:: somefunc function

.. Refer to section/appendix etc. at the beginning of the line

.. and other special fix situations for HTML.

More text, with a reference back to
the section :ref:`sec1` and :ref:`subsec1`, and further to the
the sections :ref:`subsec1` and :ref:`subsubsec:ex`, which
encourages you to do the tasks in :ref:`demo:ex:1` and :ref:`exer:some:formula`.
 :ref:`app1` and :ref:`app2` are also nice elements.

Test Section reference at beginning of line and after a sentence
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The section :ref:`subsec1` is fine.
The section :ref:`subsubsec:ex` too.

.. sphinx code-blocks: pycod=python cod=fortran cppcod=c++ sys=console

Computer code
~~~~~~~~~~~~~

Let's do some copying from files too. First from subroutine up to the very end,

.. code-block:: fortran

          subroutine test()
          integer i
          real*8 r
          r = 0
          do i = 1, i
             r = r + i
          end do
          return
    C     END1
    
          program testme
          call test()
          return

and then just the subroutine,

.. code-block:: fortran

          subroutine test()
          integer i
          real*8 r
          r = 0
          do i = 1, i
             r = r + i
          end do
          return

and finally the complete file with a plain text verbatim environment
(``envir=ccq``):

.. code-block:: text

    C     a comment
    
          subroutine test()
          integer i
          real*8 r
          r = 0
          do i = 1, i
             r = r + i
          end do
          return
    C     END1
    
          program testme
          call test()
          return

Testing other code environments. First Python:

.. code-block:: text

    !bc pycod
    def f(x):
        return x+1
    !ec

which gets rendered as

.. code-block:: python

    def f(x):
        return x+1

Test paragraph and subsubsection headings before
before code.

**Paragraph heading before code.**

.. code-block:: python

    import sys
    sys.path.insert(0, os.pardir)

Subsubsection heading before code
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

    def h(z):
        return z+1

Now a complete program to be shown via Python Online Tutorial:

.. raw:: html

    <iframe width="950" height="500" frameborder="0"
            src="https://pythontutor.com/iframe-embed.html#code=class+Line%3A%0A++++def+__init__%28self%2C+a%2C+b%29%3A%0A++++++++self.a%2C+self.b+%3D+a%2C+b%0A%0A++++def+__call__%28self%2C+x%29%3A%0A++++++++a%2C+b+%3D+self.a%2C+self.b%0A++++++++return+a%2Ax+%2B+b%0A%0Aline+%3D+Line%282%2C+1%29%0Ay+%3D+line%28x%3D3%29%0Aprint%28y%29&py=2&curInstr=0&cumulative=false">
    </iframe>

Another complete program to be typeset as a sage cell:

.. code-block:: text

    a = 2
    b = 3
    print('a+b:', a + b)
    
    # In a sage cell we can also plot
    from matplotlib.pyplot import *
    from numpy import *
    x = linspace(0, 4*pi, 101)
    y = exp(-0.1*x)*cos(x)
    plot(x, y)
    xlabel('x'); ylabel('y')
    show()

Then Cython (with -h option so it is hidden in html/sphinx):

.. container:: toggle

    .. container:: header

        **Show/Hide Code**

    .. code-block:: cython

        cpdef f(double x):
            return x + 1

Standard Python shell sessions:

.. code-block:: python

    >>> from numpy import linspace, sin
    >>> # Some comment
    >>> x = linspace(0, 2, 11)
    >>> y = sin(x)
    >>> y[0]
    0
    >>> import matplotlib.pyplot as plt
    >>> plt.plot(x, y)

Similar IPython sessions:

.. code-block:: ipy

    In [1]: from numpy import linspace, sin
    In [2]: # Some comment
    In [3]: x = linspace(0, 2, 11)
    In [4]: y = sin(x)
    In [5]: y[0]
    Out[5]: 0
    In [6]: import matplotlib.pyplot as plt
    In [7]: plt.plot(x, y)
    In [8]: a='multiple-\nline\noutput'
    In [9]: a
    Out[9]: 'multiple-\nline\noutput'
    In [10]: print(a)
    multiple-
    line
    output

Here is the interactive session again, but with ``pyshell-t``.

.. code-block:: python

    >>> from numpy import linspace, sin
    >>> # Some comment
    >>> x = linspace(0, 2, 11)
    >>> y = sin(x)
    >>> y[0]
    0
    >>> import matplotlib.pyplot as plt
    >>> plt.plot(x, y)

.. This one tests a + sign before a code environment

C++:

.. code-block:: c++

    #include <iostream>
    
    int main()
    {
       std::cout << "Sample output" << std::endl;
       return 0
    }

.. The next should get correctly typset in sphinx (cod is fcod)

.. It also tests emoji before code

And a little bit of Fortran: :dizzy_face:

.. code-block:: text

    !bc cod
          subroutine midpt(x, length, a, b)
          real*8 a, b, x
          x = (a + b)/2
          length = b - a
          return
          end
    !ec

which then is typeset as

.. code-block:: fortran

          subroutine midpt(x, length, a, b)
          real*8 a, b, x
          x = (a + b)/2
          length = b - a
          return
          end

HTML:

.. code-block:: html

    <table>
    <tr><td>Column 1</td><td>Column 2</td></tr>
    <tr><td>0.67526 </td><td>0.92871 </td></tr>
    <!-- comment -->
    </table>

But inline HTML code is also important, like text that starts with
``<a href="`` (which can destroy the following text if not properly
quoted).

Matlab with comments requires special typesetting:

.. code-block:: matlab

    % Comment on the beginning of the line can be escaped by %%
    if a > b
      % Indented comment needs this trick
      c = a + b
    end

And here is a system call:

.. code-block:: console

    Terminal> mkdir test
    Terminal> cd test
    Terminal> myprog -f
    output1
    output2

Any valid pygments lexer/language name can appear to, e.g.,

.. code-block:: text

    !bc restructuredtext
    =======
    Heading
    =======
    
    Some text.
    !ec

results in

.. code-block:: restructuredtext

    =======
    Heading
    =======
    
    Some text.

.. Here goes hidden code.

.. Python can be treated by some formats, Fortran is always out.

Finally, ``!bc do`` supports highlighting of DocOnce source:

.. code-block:: doconce

    ======= DocOnce test file =======
    
    ===== Computer code =====
    
    Inline verbatim code, as in `import numpy as np`, is allowed, as well as
    code blocks:
    
    !bc pycod
    from math import sin
    
    def f(x):
        """Example on a function."""
        return sin(x) + 1
    
    print(f(0))
    !ec
    
    
    ===== Mathematics =====
    
    Formulas can be inline, as in $\nabla\cdot\boldsymbol{u} = 0$, or typeset
    as equations:
    
    !bt
    \begin{align*}
    \nabla\cdot\boldsymbol{u} &= 0,\\ 
    \boldsymbol{u} &= \nabla\phi .
    \end{align*}
    !et
    
    === Subsubsection heading ===
    
    DocOnce files can have chapters, sections, subsections, and subsubsections.
    
    __Paragraph heading.__ Paragraphs may have headings.

It is time to test ``verbatim inline font`` especially with ``a newline
inside the text`` and an exclamation mark at the end: ``BEGIN``! For
spellcheck, test ``a verbatim expression`` in ``another`` in a ``third``.
Also test exclamation mark as in ``!bc`` and ``!ec`` as well as ``a != b``.
Also test backslashes and braces like ``\begin``, ``\begin{enumerate}``,
``\end{this}\end{that}``, and ``{something \inside braces}``.

The following attempt to exemplify colored text does not work in
format sphinx.
Here is some **red color** and an attempt to write **with
green color containing a linebreak

| code.** Some formats will only display 
| this correctly when ``html`` 
| is the output format.

But here some more running text is added which is not part of
the previous blocks with line breaks.

Running OS commands
~~~~~~~~~~~~~~~~~~~

.. code-block:: console

    Terminal> python -c 'print("Testing\noutput\nfrom\nPython.")'
    Testing
    output
    from
    Python.

Footnotes
~~~~~~~~~

Here is a test of footnotes [#footnote]_, which are handy in text.
They are used in different flavors, now in

 * list items (note below that footnotes work after math, verbatim, and URLs - bin fact old and emphasize too!)

 * even with math :math:`\nabla^2u` [#math1]_

 * and code ``h[i] += 1`` [#code]_
   (*must* have space between inline code and footnote!)

 * and `links <https://google.com>`__ [#google-search]_

which gives flexibility in writing.
This is the third [#example-of-the-third-footnote]_ example.

.. [#footnote] Typesetting of the footnote depends on the format.
   Plain text does nothing, LaTeX removes the
   definition and inserts the footnote as part of the LaTeX text.
   reStructuredText and Sphinx employ a similar type of typesetting
   as Extended Markdown and DocOnce, and in HTML we keep the same
   syntax, just displayed properly in HTML.

.. [#math1] Math footnotes can be dangerous since it
   interferes with an exponent.

.. [#code] One-line footnote.

.. [#google-search] `<google.com>`_ is perhaps the most famous
   web site today.

Here is some more text before a new definition of a footnote that was
used above.


.. admonition:: Non-breaking space character

   This paragraph aims to test `non-breaking space character <https://en.wikipedia.org/wiki/Non-breaking_space>`__, and a typical
   example where this is needed is in physical units: 7.4 |nbsp| km is traveled
   in |nbsp| :math:`7.4/5.5\approx 1.345` |nbsp| s.  Also check that a |nbsp| `link <https://google.com>`__ |nbsp| is
   not broken across lines (drag the browser window to test this).
   (On the other hand, the tilde is used in
   computer code, e.g., as in ``[~x for x in y]`` or in ``y=~x``, and should
   of course remain a tilde in those contexts.)




.. _subsec:ex:

Subsection 2: Testing figures
-----------------------------

.. index:: figures

Test of figures. In particular we refer to Figure :ref:`fig:impact` in which
there is a flow.

.. _fig:impact:

.. figure:: ../doc/src/manual/fig/wave1D.png
   :width: 200

   Visualization **of** a *wave*

Figures without captions are allowed and will be inlined.

.. figure:: ../doc/src/manual/fig/wave1D.png
   :width: 200

.. index:: movies

.. Test multi-line caption in figure with sidecap=True

Here is figure :ref:`myfig` with a long (illegal) multi-line caption
containing inline verbatim text:

.. _myfig:

.. figure:: ../doc/src/manual/fig/wave1D.png
   :width: 500

   A long caption spanning several lines and containing verbatim words like ``my_file_v1`` and ``my_file_v2`` as well as math with subscript as in :math:`t_{i+1}`

.. Must be a blank line after MOVIE or FIGURE to detect this problem

Test URL as figure name:

.. figure:: https://raw.github.com/doconce/doconce/master/doc/src/blog/f_plot.png
   :width: 500

Test SVG figure:

.. figure:: https://openclipart.org/people/jpneok/junebug.svg
   :width: 200

.. Test wikimedia type of files that otherwise reside in subdirs

**Remark.**
Movies are tested in separate file ``movies.do.txt``.

.. Somewhat challenging heading with latex math, \t, \n, ? and parenthesis

.. _decay:sec:theta:

The :math:`\theta` parameter (not :math:`\nabla`?)
--------------------------------------------------

Functions do not always need to be advanced, here is one
involving :math:`\theta`:

.. code-block:: text

    def f(theta):
        return theta**2

**More on :math:`\theta`.**
Here is more text following headline with math.

Newcommands must also be tested in this test report:
:math:`\frac{1}{2}`, :math:`{1/2}`, :math:`\pmb{x}`, :math:`\frac{Du}{dt}`,
both inline and in block:

.. math::
        
        \frac{Du}{dt} = 0\nonumber
        

.. _Eq:_auto1:

.. math::

    \tag{1}
    \frac{1}{2} = {1/2}
        
        

.. _Eq:_auto2:

.. math::

    \tag{2}
    \frac{1}{2}\pmb{x} = \pmb{n}
        
        

Or with align with label and numbers:

.. _Eq:aligneq1:

.. math::

    \tag{3}
    \frac{Du}{dt} = 0
        
        

.. _Eq:_auto3:

.. math::

    \tag{4}
    \frac{1}{2} = {1/2}
        
        

.. _Eq:aligneq2:

.. math::

    \tag{5}
    \frac{1}{2}\pmb{x} = \pmb{n}
        
        

Sphinx makes a fix here and splits align into multiple equation
environments.

Custom Environments
-------------------

Here is an attempt to create a theorem environment via Mako
(for counting theorems) and comment lines to help replacing lines in
the ``.tex`` by proper begin-end LaTeX environments for theorems.
Should look nice in most formats!

.. begin theorem

**Theorem 5.**
Let :math:`a=1` and :math:`b=2`. Then :math:`c=3`.

.. end theorem

.. begin proof

**Proof.**
Since :math:`c=a+b`, the result follows from straightforward addition.
:math:`\Diamond`

.. end proof

As we see, the proof of Theorem 5 is a modest
achievement.

.. _subsec:table:

Tables
------

.. index:: test index with verbatim text which is possible

.. index:: test two (separate) verbatim expressions which is also possible

.. index::
   single: index with; subindex

.. index:: boldface word in index

.. index:: index with boldface word

.. index::
   single: index with; boldface word in subentry

.. index::
   single: double boldface word;  boldface word in subentry too

.. index with comma could fool sphinx

.. index::
   single: index, with comma, and one more

Let us take this table from the manual:

====  ========  ============  
time  velocity  acceleration  
====  ========  ============  
0.0     1.4186         -5.01  
2.0   1.376512        11.919  
4.0     1.1E+1     14.717624  
====  ========  ============  

The DocOnce source code reads

.. code-block:: text

      |--------------------------------|
      |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    |
      |--------------------------------|
    

Here is yet another table to test that we can handle more than
one table:

====  ========  ============  
time  velocity  acceleration  
====  ========  ============  
0.0   1.4186    -5.01         
1.0   1.376512  11.919        
3.0   1.1E+1    14.717624     
====  ========  ============  

And one with math headings (that are expanded and must be treated
accordingly), verbatim heading and entry, and no space around the pipe
symbol:

=========  ===========  ================  =======  
:math:`i`  :math:`h_i`  :math:`\bar T_i`  ``L_i``  
=========  ===========  ================  =======  
0                    0               288  -0.0065  
1               11,000               216      0.0  
2               20,000               216    0.001  
3               32,000               228   0.0028  
4               47,000               270      0.0  
5               51,000               270  -0.0028  
6               71,000               214  ``NaN``  
=========  ===========  ================  =======  

And add one with verbatim headings (with underscores),
and rows starting with ``|-`` because of a negative number,
and ``|`` right before and after verbatim word (with no space):

=====  =======  =====================  ===========  
exact  ``v_1``  :math:`a_i` + ``v_2``  ``verb_3_``  
=====  =======  =====================  ===========  
    9     9.62                   5.57         8.98  
  -20   -23.39                  -7.65       -19.93  
   10    17.74                  -4.50         9.96  
    0    -9.19                   4.13        -0.26  
=====  =======  =====================  ===========  

Pipe symbols in verbatim and math text in tables used to pose difficulties,
but not
anymore:

===============  ===============  
   :math:`S`         command      
===============  ===============  
$ ||a_0|| $      ``norm|length``  
:math:`x\cap y`          ``x|y``  
===============  ===============  

Here is a table with X alignment:

=====  ==========================================================================================================================================================================================================================  
 Type                                                                                                         Description                                                                                                          
=====  ==========================================================================================================================================================================================================================  
  X    Alignment character that is used for specifying a potentially very long text in a column in a table. It makes use of the ``tabularx`` package in LaTeX, otherwise (for other formats) it means ``l`` (centered alignment).  
l,r,c  standard alignment characters                                                                                                                                                                                               
=====  ==========================================================================================================================================================================================================================  

Finally, a table with math
(``bm`` that expands to ``boldsymbol``, was tricky, but
cleanly handled now)
and URLs.

.. Mako code to expand URLs in the table

.. (These types of tables did not work before Jan 2014)

====================================  ==========================================================  ==========================================================  
                                                                                                                                                              
====================================  ==========================================================  ==========================================================  
       :math:`\mathcal{L}=0`          `080 <../doc/src/manual/mov/wave_frames/frame_0080.png>`__  `085 <../doc/src/manual/mov/wave_frames/frame_0085.png>`__  
            :math:`a=b`               `090 <../doc/src/manual/mov/wave_frames/frame_0090.png>`__  `095 <../doc/src/manual/mov/wave_frames/frame_0095.png>`__  
:math:`\nabla\cdot\boldsymbol{u} =0`  `100 <../doc/src/manual/mov/wave_frames/frame_0100.png>`__  `105 <../doc/src/manual/mov/wave_frames/frame_0105.png>`__  
====================================  ==========================================================  ==========================================================  

A test of verbatim words in heading with subscript :math:`a_i`: ``my_file_v1`` and ``my_file_v2``
-------------------------------------------------------------------------------------------------

**Paragraph with verbatim and math: ``my_file_v1.py`` and ``my_file_v2.py`` define some math :math:`a_{i-1}`.**
Here is more ``__verbatim__`` code and
some plain text on a new line.

.. Test various types of headlines

**Just bold**
-------------

Some text.

*Just emphasize*
----------------

Some text.

``Just verbatim``
-----------------

Some text.

**Bold** beginning
------------------

Some text.

*Emphasize* beginning
---------------------

Some text.

``Verbatim`` beginning
----------------------

Some text.

Maybe **bold end**
------------------

Some text.

Maybe *emphasize end*
---------------------

Some text.

Maybe ``verbatim end``
----------------------

Some text.

The middle has **bold** word
----------------------------

Some text.

The middle has *emphasize* word
-------------------------------

Some text.

The middle has ``verbatim`` word
--------------------------------

Some text.

***Just emphasize*.**
Some text.

**``Just verbatim``.**
Some text.

***Emphasize* beginning.**
Some text.

**``Verbatim beginning``.**
Some text.

**Maybe *emphasize end*.**
Some text.

**Maybe ``verbatim end``.**
Some text.

**The middle has *emphasize* word.**
Some text.

**The middle has ``verbatim`` word.**
Some text.

**Ampersand.**
We can test Hennes & Mauritz, often abbreviated H&M, but written
as ``Hennes & Mauritz`` and ``H & M``.
A sole ``&`` must also work.

.. Note: substitutions must not occur inside verbatim, just in ordinary text.

.. code-block:: text

    # Just to check that ampersand works in code blocks:
    c = a & b

**Quotes.**
Let us also add a test of quotes such as "double quotes, with numbers
like 3.14 and newline/comma and hyphen (as in double-quote)"; written
in the standard LaTeX-style that gives correct LaTeX formatting and
ordinary double quotes for all non-LaTeX formats.  Here is another
sentence that "caused" a bug in the past because double backtick
quotes could imply verbatim text up to a verbatim word starting with
period, like ``.txt``.

More quotes to be tested for spellcheck:
("with parenthesis"), "with newline"
and "with comma", "hyphen"-wise, and "period".

Bibliography test
-----------------

Here is an example: [Ref01]_ discussed propagation of
large destructive water waves, [Ref02]_ gave
an overview of numerical methods for solving the Navier - Stokes equations,
while the use of Backward Kolmogorov equations for analyzing
random vibrations was investigated in [Ref03]_.
The book chapter [Ref04]_ contains information on
C++ software tools for programming multigrid methods. A real retro
reference is [Ref05]_ about a big FORTRAN package.
Multiple references are also possible, e.g., see
[Ref01]_ [Ref04]_.

We need to cite more than 10 papers to reproduce an old formatting
problem with blanks in the keys in reST format:
[Ref06]_ [Ref03]_ [Ref07]_ [Ref01]_
and
[Ref02]_ [Ref08]_ [Ref09]_ [Ref10]_ [Ref11]_ [Ref12]_ [Ref13]_
and all the work of
[Ref14]_ [Ref04]_ [Ref15]_ as well as
old work [Ref05]_ and [Ref16]_, and the
talk [Ref17]_.
Langtangen also had two thesis [Ref18]_ [Ref16]_
back in the days.
More retro citations are
the old ME-IN323 book [Ref19]_ and the
[Ref20]_ OONSKI '94 paper.

.. --- begin exercise ---

.. _Example:

Example 1: Examples can be typeset as exercises
-----------------------------------------------

Examples can start with a subsection heading starting with ``Example:``
and then, with the command-line option ``--examples_as_exercises`` be
typeset as exercises. This is useful if one has solution
environments as part of the example.

**a)**
State some problem.

**Solution.**
The answer to this subproblem can be written here.

**b)**
State some other problem.

**Hint 1.**
A hint can be given.

**Hint 2.**
Maybe even another hint?

**Solution.**
The answer to this other subproblem goes here,
maybe over multiple doconce input lines.

.. --- end exercise ---

User-defined environments
-------------------------

The example in the section :ref:`ex:test:1p1` demonstrates how to write a test function.
That is, a special test function for a function ``add`` appears in
the example in the section :ref:`ex:test:1p1`.

.. _ex:test:1p1:

Example 1: A test function
--------------------------

Suppose we want to write a test function for checking the
implementation of a Python function for addition.

.. code-block:: python

    def add(a, b):
        return a + b
    
    def test_add():
        a = 1; b = 1
        expected = a + b
        computed = add(a, b)
        assert expected == computed

.. _ex:math:1p1:

Example 2: Addition
-------------------

We have

.. math::
         1 + 1 = 2 

or in tabular form:

===========  =========  
  Problem      Result   
===========  =========  
:math:`1+1`  :math:`2`  
===========  =========  


.. admonition:: Highlight box

   This environment is used to highlight something:
   
   .. math::
            E = mc^2




.. _subsubsec:ex:

URLs
----

Testing of URLs: hpl's home page `hpl <https://folk.uio.no/hpl>`__, or
the entire URL if desired, `<https://folk.uio.no/hpl>`_.  Here is a
plain file link `<testdoc.do.txt>`_, or `<testdoc.do.txt>`_, or
`<testdoc.do.txt>`_ or `<testdoc.do.txt>`_ or `a link with
newline <testdoc.do.txt>`__. Can test spaces with the link with word
too: `hpl <https://folk.uio.no/hpl>`__ or `hpl <https://folk.uio.no/hpl>`__. Also ``file:///`` works: `link to a
file <file:///home/hpl/vc/doconce/doc/demos/manual/manual.html>`__ is
fine to have. Moreover, "loose" URLs work, i.e., no quotes, just
the plain URL as in `<https://folk.uio.no/hpl>`_, if followed by space, comma,
colon, semi-colon, question mark, exclamation mark, but not a period
(which gets confused with the periods inside the URL).

Mail addresses can also be used: `hpl@simula.no <mailto:hpl@simula.no>`__, or just a `mail link <mailto:hpl@simula.no>`__, or a raw `<mailto:hpl@simula.no>`_.

Here are some tough tests of URLs, especially for the ``latex`` format:
`Newton-Cotes <https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas>`__ formulas
and a `good book <https://www.springer.com/mathematics/computational+science+%26+engineering/book/978-3-642-23098-1>`__. Need to test
Newton-Cotes with percentage in URL too:
`<https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas>`_
and `<https://en.wikipedia.org/wiki/Newton-Cotes#Open_Newton.E2.80.93Cotes_formulae>`_ which has a shebang.

For the ``--device=paper`` option it is important to test that URLs with
monospace font link text get a footnote
(unless the ``--latex_no_program_footnotelink``
is used), as in this reference to
`decay_mod <https://github.com/hplgit/INF5620/tree/gh-pages/src/decay/experiments/decay_mod.py>`__, `ball1.py <https://tinyurl.com/pwyasaa/formulas.ball1.py>`__,
and `ball2.py <https://tinyurl.com/pwyasaa/formulas.ball2.py>`__.

.. Comments should be inserted outside paragraphs (because in the rst

.. format extra blanks make a paragraph break).

.. Note that when there is no https: or file:, it can be a file link

.. if the link name is URL, url, "URL", or "url". Such files should,

.. if rst output is desired, but placed in a ``_static*`` folder.

More tough tests: repeated URLs whose footnotes when using the
``--device=paper`` option must be correct. We have
`google <https://google.com>`__, `google <https://google.com>`__, and
`google <https://google.com>`__, which should result in exactly three
footnotes.


************** File: ._testdoc002.rst *****************
.. !split and check if these extra words are included properly in the comment


************** File: admon.p.tex *****************
%%
%% Automatically generated file from DocOnce source
%% (https://github.com/hplgit/doconce/)
%%
%%
% #ifdef PTEX2TEX_EXPLANATION
%%
%% The file follows the ptex2tex extended LaTeX format, see
%% ptex2tex: https://code.google.com/p/ptex2tex/
%%
%% Run
%%      ptex2tex myfile
%% or
%%      doconce ptex2tex myfile
%%
%% to turn myfile.p.tex into an ordinary LaTeX file myfile.tex.
%% (The ptex2tex program: https://code.google.com/p/ptex2tex)
%% Many preprocess options can be added to ptex2tex or doconce ptex2tex
%%
%%      ptex2tex -DMINTED myfile
%%      doconce ptex2tex myfile envir=minted
%%
%% ptex2tex will typeset code environments according to a global or local
%% .ptex2tex.cfg configure file. doconce ptex2tex will typeset code
%% according to options on the command line (just type doconce ptex2tex to
%% see examples). If doconce ptex2tex has envir=minted, it enables the
%% minted style without needing -DMINTED.
% #endif

% #define PREAMBLE

% #ifdef PREAMBLE
%-------------------- begin preamble ----------------------

\documentclass[%
oneside,                 % oneside: electronic viewing, twoside: printing
final,                   % draft: marks overfull hboxes, figures with paths
10pt]{article}

\listfiles               %  print all files needed to compile this document

\usepackage{relsize,makeidx,color,setspace,amsmath,amsfonts,amssymb}
\usepackage[table]{xcolor}
\usepackage{bm,ltablex,microtype}

\usepackage[pdftex]{graphicx}

\usepackage{fancybox}  % make sure fancybox is loaded before fancyvrb
%\setlength{\fboxsep}{8pt}  % may clash with need in pre/cod envirs

\usepackage{ptex2tex}
% #ifdef MINTED
\usepackage{minted}
\usemintedstyle{default}
% #endif
\usepackage{fancyvrb}

\usepackage[T1]{fontenc}
%\usepackage[latin1]{inputenc}
\usepackage{ucs}
\usepackage[utf8x]{inputenc}

\usepackage{lmodern}         % Latin Modern fonts derived from Computer Modern

% Hyperlinks in PDF:
\definecolor{linkcolor}{rgb}{0,0,0.4}
\usepackage{hyperref}
\hypersetup{
    breaklinks=true,
    colorlinks=true,
    linkcolor=linkcolor,
    urlcolor=linkcolor,
    citecolor=black,
    filecolor=black,
    %filecolor=blue,
    pdfmenubar=true,
    pdftoolbar=true,
    bookmarksdepth=3   % Uncomment (and tweak) for PDF bookmarks with more levels than the TOC
    }
%\hyperbaseurl{}   % hyperlinks are relative to this root

\setcounter{tocdepth}{2}  % levels in table of contents

% Tricks for having figures close to where they are defined:
% 1. define less restrictive rules for where to put figures
\setcounter{topnumber}{2}
\setcounter{bottomnumber}{2}
\setcounter{totalnumber}{4}
\renewcommand{\topfraction}{0.95}
\renewcommand{\bottomfraction}{0.95}
\renewcommand{\textfraction}{0}
\renewcommand{\floatpagefraction}{0.75}
% floatpagefraction must always be less than topfraction!
% 2. ensure all figures are flushed before next section
\usepackage[section]{placeins}
% 3. enable begin{figure}[H] (often leads to ugly pagebreaks)
%\usepackage{float}\restylefloat{figure}

% --- fancyhdr package for fancy headers ---
\usepackage{fancyhdr}
\fancyhf{} % sets both header and footer to nothing
\renewcommand{\headrulewidth}{0pt}
\fancyfoot[LE,RO]{\thepage}
% Ensure copyright on titlepage (article style) and chapter pages (book style)
\fancypagestyle{plain}{
  \fancyhf{}
  \fancyfoot[C]{{\footnotesize \copyright\ 2021, H. P. Langtangen. Made with \href{https://github.com/hplgit/doconce}{DocOnce}}}
%  \renewcommand{\footrulewidth}{0mm}
  \renewcommand{\headrulewidth}{0mm}
}
% Ensure copyright on titlepages with \thispagestyle{empty}
\fancypagestyle{empty}{
  \fancyhf{}
  \fancyfoot[C]{{\footnotesize \copyright\ 2021, H. P. Langtangen. Made with \href{https://github.com/hplgit/doconce}{DocOnce}}}
  \renewcommand{\footrulewidth}{0mm}
  \renewcommand{\headrulewidth}{0mm}
}

\pagestyle{fancy}


\usepackage[framemethod=TikZ]{mdframed}

% --- begin definitions of admonition environments ---

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "notice" admon
\definecolor{mdfbox_notice_background}{rgb}{1,1,1}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_notice_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=mdfbox_notice_background,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{notice_mdfboxmdframed}

\newenvironment{notice_mdfboxadmon}[1][]{
\begin{notice_mdfboxmdframed}[frametitle=#1]
}
{
\end{notice_mdfboxmdframed}
}

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "summary" admon
\definecolor{mdfbox_summary_background}{rgb}{1,1,1}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_summary_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=mdfbox_summary_background,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{summary_mdfboxmdframed}

\newenvironment{summary_mdfboxadmon}[1][]{
\begin{summary_mdfboxmdframed}[frametitle=#1]
}
{
\end{summary_mdfboxmdframed}
}

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "warning" admon
\definecolor{mdfbox_warning_background}{rgb}{1,1,1}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_warning_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=mdfbox_warning_background,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{warning_mdfboxmdframed}

\newenvironment{warning_mdfboxadmon}[1][]{
\begin{warning_mdfboxmdframed}[frametitle=#1]
}
{
\end{warning_mdfboxmdframed}
}

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "question" admon
\definecolor{mdfbox_question_background}{rgb}{1,1,1}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_question_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=mdfbox_question_background,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{question_mdfboxmdframed}

\newenvironment{question_mdfboxadmon}[1][]{
\begin{question_mdfboxmdframed}[frametitle=#1]
}
{
\end{question_mdfboxmdframed}
}

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "block" admon
\definecolor{mdfbox_block_background}{rgb}{1,1,1}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_block_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=mdfbox_block_background,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{block_mdfboxmdframed}

\newenvironment{block_mdfboxadmon}[1][]{
\begin{block_mdfboxmdframed}[frametitle=#1]
}
{
\end{block_mdfboxmdframed}
}

% --- end of definitions of admonition environments ---

% prevent orhpans and widows
\clubpenalty = 10000
\widowpenalty = 10000

% --- end of standard preamble for documents ---


% insert custom LaTeX commands...

\raggedbottom
\makeindex
\usepackage[totoc]{idxlayout}   % for index in the toc
\usepackage[nottoc]{tocbibind}  % for references/bibliography in the toc

%-------------------- end preamble ----------------------

\begin{document}

% matching end for #ifdef PREAMBLE
% #endif

\newcommand{\exercisesection}[1]{\subsection*{#1}}

\input{newcommands_bfmath}
\input{newcommands_replace}

% ------------------- main content ----------------------



% ----------------- title -------------------------

\thispagestyle{empty}

\begin{center}
{\LARGE\bf
\begin{spacing}{1.25}
Testing admons
\end{spacing}
}
\end{center}

% ----------------- author(s) -------------------------

\begin{center}
{\bf H. P. Langtangen${}^{}$} \\ [0mm]
\end{center}

\begin{center}
% List of all institutions:
\end{center}
    
% ----------------- end author(s) -------------------------

% --- begin date ---
\begin{center}
Jan 32, 2100
\end{center}
% --- end date ---

\vspace{1cm}


% !split
\section{Introduction}
First some ordinary text to compare font sizes in admonitions
and the surrounding text.


\subsection{Code}

Need some code outside admons for color and font comparisons:

\bpycod
def some_code(x):
    return sin(x)*exp(1-x)
\epycod

And some plain text verbatim:

\bccq
x=1.0 y=0.9 z=0.4
x=1.1 y=0.3 z=0.1
\eccq

\subsection{Quotes and boxes}

Here is a plain quote environment.


\begin{quote}
Sayre's law states that
``in any dispute the intensity of feeling is inversely
proportional to the value of the issues at stake.'' \\
By way of corollary, it adds: \\
``That is why academic politics are so bitter.'' \\
\emph{Source}: \href{{https://en.wikipedia.org/wiki/Sayre's_law}}{wikipedia}
\end{quote}


Does quotes with title also work? No...cannot work in {\LaTeX} and HTML
and then it does not make sense to support it.


A plain \emph{box} is sometimes useful. Let's show it here for comparison
with admons (especially the block admon has much in common with a box).
The box is more aimed at framing a law or an equation.

First a simple block with text, an equation, and a list:


\begin{center}
\begin{Sbox}
\begin{minipage}{0.85\linewidth}
A generic equation

\[ f(x) = 0 \]
must be solved by a numerical method, such as

\begin{itemize}
 \item Newton's method

 \item The Bisection method

 \item Fixed-point (Picard) iteration by rewriting $f(x)=x - g(x)$

 \item The Secant method
\end{itemize}

\noindent
\end{minipage}
\end{Sbox}
\fbox{\TheSbox}
\end{center}
Now test a box with equation only (note that this line continues the
box, it is not a new paragraph):


\begin{center}
\begin{Sbox}
\begin{minipage}{0.85\linewidth}
\begin{equation} f(x) = \sin(x)e^{1-x} \end{equation}
\end{minipage}
\end{Sbox}
\fbox{\TheSbox}
\end{center}

\\paragraph{Hint.}\n
Newton's method requires a good start vector to converge fast.



Let's begin a new paragraph and show a box with code only:


\begin{center}
\begin{Sbox}
\begin{minipage}{0.85\linewidth}
\bpycod
def some_code(x):
    return sin(x)*exp(1-x)
\epycod
\end{minipage}
\end{Sbox}
\fbox{\TheSbox}
\end{center}



\subsection{Admonitions}

Let us start with a plain warning environment.


\begin{warning_mdfboxadmon}[Warning.]
And here is a warning about something to pay attention to. We
test how the heading behave and add quite some extra texts
in comparison with the other admons.

\begin{itemize}
  \item and a list

  \item with items
\end{itemize}

\noindent
We continue with more text to see how that affects the layout.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
\end{warning_mdfboxadmon} % title: Warning.



Test warning with title:


\begin{warning_mdfboxadmon}[{\large Title ending with math $\sqrt{2}\approx 1.4$}.]
{\large And here comes some text with bad news in larger font.

Also some code:

\bpycod2
def f(x):
    return x
\epycod2
And a complete program

\bpypro2
print("Hello, World!")
\epypro2
\par}
\end{warning_mdfboxadmon} % title: {\large Title ending with math $\sqrt{2}\approx 1.4$}.



Test warning with large title with math:


\begin{warning_mdfboxadmon}[{\large Watch out for $\nabla\cdot\bm{u}=0$ equations}.]
{\large Divergence freedom is often problematic from a numerical point
of view.
\par}
\end{warning_mdfboxadmon} % title: {\large Watch out for $\nabla\cdot\bm{u}=0$ equations}.



Then we test a block, which is guaranteed to never have any admon icon.


\begin{block_mdfboxadmon}[Block with title.]
\vspace{0.5mm}\par\noindent
{\footnotesize Here is a block of text with title. It is typeset
\emph{without any icon} and is useful when you want some admons with icon
and some without. With the small font size, as used here, one can have
more comment-style text or text that really goes deeper or talks
about fun facts that are not strictly necessary for the main flow
of understanding.
\par}
\end{block_mdfboxadmon} % title: Block with title.





\begin{block_mdfboxadmon}[]
Here is a block of text with no title. As above, it is typeset without any icon
and is useful when you want some admons with icon and some without.
\end{block_mdfboxadmon} % title: 



% Note that the final ! does not appear in Sphinx and reST since
% those formats automatically add : to the admonition title.


\begin{notice_mdfboxadmon}[Note eventually!]
Ah, we are soon close to the end (with illegal font size specification!).
But first a bit of math where we define $\theta$ and $\bm{r}$:

\begin{align*}
\theta &= q^2,\\
\bm{r} &= \varrho\bm{i}
\end{align*}
\end{notice_mdfboxadmon} % title: Note eventually!



% Test one word with a number


\begin{notice_mdfboxadmon}[Point1.]
Ah, we are soon close to the end.
\end{notice_mdfboxadmon} % title: Point1.




\begin{question_mdfboxadmon}[Question.]
So, how many admonition environments does DocOnce support?
\end{question_mdfboxadmon} % title: Question.




\begin{question_mdfboxadmon}[Question.]
\begin{enumerate}
 \item Once more, how many admonition environments does DocOnce support?
\end{enumerate}

\noindent
\end{question_mdfboxadmon} % title: Question.




\begin{warning_mdfboxadmon}[Tip.]
It is of outmost important to

\begin{enumerate}
\item stay cool

\item read hints and tips carefully
\end{enumerate}

\noindent
Because here the thing is to do

\bpycod2
import urllib

def grab(url, filename):
    urllib.urlretrieve(url, filename=filename)
\epycod2
\end{warning_mdfboxadmon} % title: Tip.



Next is a warning without a title ("none" implies no title).


\begin{warning_mdfboxadmon}[]
And here comes some text with bad news.
\end{warning_mdfboxadmon} % title: 



\subsection{Going deeper environments}

Here is a long notice environment with a custom title and much
text, math and code.


\begin{notice_mdfboxadmon}[Going deeper.]
We have some equations that should be preceded by much text, so the
task is to write and write. The number of words, and not the
meaning, is what counts here. We need desperately to fill up the
page in the hope that some admonitions will experience a page break,
which the {\LaTeX} environment should handle with ease.

Let us start with some equations:

\begin{align*}
\Ddt{u} &= 0
\\
\half &= \halfi\\
\half\x &= \normalvec
\end{align*}

The implementation of such complicated equations in computer
code is task that this "Going deeper" environment targets.

\bpycod2
def Dudt(u):
    r = diff(u, t) + u*grad(u)
    return r

half = 0.5
x = 2*n
\epycod2
And some more text that can help going into the next page.
Longer computer code requires vertical space:

\bpycod2
class Diff:
    def __init__(self, f, h=1E-5):
        self.f = f
        self.h = float(h)

class Forward1(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (f(x+h) - f(x))/h

class Backward1(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (f(x) - f(x-h))/h

class Central2(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (f(x+h) - f(x-h))/(2*h)

class Central4(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (4./3)*(f(x+h)   - f(x-h))  /(2*h) - \
               (1./3)*(f(x+2*h) - f(x-2*h))/(4*h)

class Central6(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (3./2) *(f(x+h)   - f(x-h))  /(2*h) - \
               (3./5) *(f(x+2*h) - f(x-2*h))/(4*h) + \
               (1./10)*(f(x+3*h) - f(x-3*h))/(6*h)

class Forward3(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (-(1./6)*f(x+2*h) + f(x+h) - 0.5*f(x) - \
                (1./3)*f(x-h))/h
\epycod2
And then we add a figure too.



\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=0.7\linewidth]{../doc/src/manual/fig/wave1D.pdf}}

\vspace{6mm}
\end{notice_mdfboxadmon} % title: Going deeper.




\subsection{The end}

A bit of text before the summary, which we now call "Concluding remarks,
for the novice",
just because we can.


\begin{summary_mdfboxadmon}[Concluding remarks for the novice.]
We can summarize the most important things with admons: they have
a different typesetting, and they may have a symbol.
Titles should be optional.
\end{summary_mdfboxadmon} % title: Concluding remarks for the novice.



\paragraph{Remark.}
The \texttt{remarks} and \texttt{hint} environments are not allowed outside
exercises (and problems and projects too).

% ------------------- end of main content ---------------

% #ifdef PREAMBLE
\end{document}
% #endif


************** File: admon_colors1.tex *****************
%%
%% Automatically generated file from DocOnce source
%% (https://github.com/hplgit/doconce/)
%%

% #define PREAMBLE

% #ifdef PREAMBLE
%-------------------- begin preamble ----------------------

\documentclass[%
oneside,                 % oneside: electronic viewing, twoside: printing
final,                   % draft: marks overfull hboxes, figures with paths
10pt]{article}

\listfiles               %  print all files needed to compile this document

\usepackage{relsize,makeidx,color,setspace,amsmath,amsfonts,amssymb}
\usepackage[table]{xcolor}
\usepackage{bm,ltablex,microtype}

\usepackage[pdftex]{graphicx}

\usepackage{fancybox}  % make sure fancybox is loaded before fancyvrb
%\setlength{\fboxsep}{8pt}  % may clash with need in pre/cod envirs

% Packages for typesetting blocks of computer code
\usepackage{fancyvrb,framed,moreverb}

% Define colors
\definecolor{orange}{cmyk}{0,0.4,0.8,0.2}
\definecolor{tucorange}{rgb}{1.0,0.64,0}
\definecolor{darkorange}{rgb}{.71,0.21,0.01}
\definecolor{darkgreen}{rgb}{.12,.54,.11}
\definecolor{myteal}{rgb}{.26, .44, .56}
\definecolor{gray}{gray}{0.45}
\definecolor{mediumgray}{gray}{.8}
\definecolor{lightgray}{gray}{.95}
\definecolor{brown}{rgb}{0.54,0.27,0.07}
\definecolor{purple}{rgb}{0.5,0.0,0.5}
\definecolor{darkgray}{gray}{0.25}
\definecolor{darkblue}{rgb}{0,0.08,0.45}
\definecolor{darkblue2}{rgb}{0,0,0.8}
\definecolor{lightred}{rgb}{1.0,0.39,0.28}
\definecolor{lightgreen}{rgb}{0.48,0.99,0.0}
\definecolor{lightblue}{rgb}{0.53,0.81,0.92}
\definecolor{lightblue2}{rgb}{0.3,0.3,1.0}
\definecolor{lightpurple}{rgb}{0.87,0.63,0.87}
\definecolor{lightcyan}{rgb}{0.5,1.0,0.83}

\colorlet{comment_green}{green!50!black}
\colorlet{string_red}{red!60!black}
\colorlet{keyword_pink}{magenta!70!black}
\colorlet{indendifier_green}{green!70!white}

% Backgrounds for code
\definecolor{cbg_gray}{rgb}{.95, .95, .95}
\definecolor{bar_gray}{rgb}{.92, .92, .92}

\definecolor{cbg_yellowgray}{rgb}{.95, .95, .85}
\definecolor{bar_yellowgray}{rgb}{.95, .95, .65}

\colorlet{cbg_yellow2}{yellow!10}
\colorlet{bar_yellow2}{yellow!20}

\definecolor{cbg_yellow1}{rgb}{.98, .98, 0.8}
\definecolor{bar_yellow1}{rgb}{.98, .98, 0.4}

\definecolor{cbg_red1}{rgb}{1, 0.85, 0.85}
\definecolor{bar_red1}{rgb}{1, 0.75, 0.85}

\definecolor{cbg_blue1}{rgb}{0.87843, 0.95686, 1.0}
\definecolor{bar_blue1}{rgb}{0.7,     0.95686, 1}

\usepackage{listingsutf8}

% Common lstlisting parameters

\usepackage{calc}
\newlength{\lstboxwidth}  % width of lst box
\newlength{\framethickness}
\setlength{\framethickness}{0.5mm}
% for frame=trbl and a framerule that has significant size, set
% xleftmargin=5mm and xrightmargin=5mm.

\lstset{
  basicstyle=\small \ttfamily,
  breaklines=false,          % break/wrap lines
  breakatwhitespace=true,    % let linebreaks happen at whitespace
  breakindent=40pt,
  tab=,
  tabsize=4,                 % tab means 4 spaces
  %belowskip=\smallskipamount,  % space between code and text below
  xleftmargin=2mm,           % indentation of code frame
  xrightmargin=0mm,
  framexleftmargin=2mm,      % add frame space to the left of the code box
  %numbers=left,             % put line numbers on the left
  %stepnumber=2,             % stepnumber=1 numbers each line, =n every n lines
  framerule=\framethickness, % thickness of frame
  aboveskip=2ex,             % vertical space above code frame
  showstringspaces=false,    % show spaces in strings with an underscore
  showspaces=false,          % show spaces with an underscore
  showtabs=false,
  keepspaces=true,
  columns=fullflexible,      % tighter character kerning, like verb
  escapeinside={(*@}{@*)},   % (*@ \pause @*) in slides and math in code blocks
  extendedchars=\true,       % allows non-ascii chars, does not work with utf-8
}

% Internally defined styles for lstlisting

\lstdefinestyle{simple}{
commentstyle={},
}

% end of custom lstdefinestyles

\usepackage[T1]{fontenc}
%\usepackage[latin1]{inputenc}
\usepackage{ucs}
\usepackage[utf8x]{inputenc}

\usepackage{lmodern}         % Latin Modern fonts derived from Computer Modern

% Hyperlinks in PDF:
\definecolor{linkcolor}{rgb}{0,0,0.4}
\usepackage{hyperref}
\hypersetup{
    breaklinks=true,
    colorlinks=true,
    linkcolor=linkcolor,
    urlcolor=linkcolor,
    citecolor=black,
    filecolor=black,
    %filecolor=blue,
    pdfmenubar=true,
    pdftoolbar=true,
    bookmarksdepth=3   % Uncomment (and tweak) for PDF bookmarks with more levels than the TOC
    }
%\hyperbaseurl{}   % hyperlinks are relative to this root

\setcounter{tocdepth}{2}  % levels in table of contents

% Tricks for having figures close to where they are defined:
% 1. define less restrictive rules for where to put figures
\setcounter{topnumber}{2}
\setcounter{bottomnumber}{2}
\setcounter{totalnumber}{4}
\renewcommand{\topfraction}{0.95}
\renewcommand{\bottomfraction}{0.95}
\renewcommand{\textfraction}{0}
\renewcommand{\floatpagefraction}{0.75}
% floatpagefraction must always be less than topfraction!
% 2. ensure all figures are flushed before next section
\usepackage[section]{placeins}
% 3. enable begin{figure}[H] (often leads to ugly pagebreaks)
%\usepackage{float}\restylefloat{figure}

% --- fancyhdr package for fancy headers ---
\usepackage{fancyhdr}
\fancyhf{} % sets both header and footer to nothing
\renewcommand{\headrulewidth}{0pt}
\fancyfoot[LE,RO]{\thepage}
% Ensure copyright on titlepage (article style) and chapter pages (book style)
\fancypagestyle{plain}{
  \fancyhf{}
  \fancyfoot[C]{{\footnotesize \copyright\ 2021, H. P. Langtangen. Made with \href{https://github.com/hplgit/doconce}{DocOnce}}}
%  \renewcommand{\footrulewidth}{0mm}
  \renewcommand{\headrulewidth}{0mm}
}
% Ensure copyright on titlepages with \thispagestyle{empty}
\fancypagestyle{empty}{
  \fancyhf{}
  \fancyfoot[C]{{\footnotesize \copyright\ 2021, H. P. Langtangen. Made with \href{https://github.com/hplgit/doconce}{DocOnce}}}
  \renewcommand{\footrulewidth}{0mm}
  \renewcommand{\headrulewidth}{0mm}
}

\pagestyle{fancy}


\usepackage{framed}

% --- begin definitions of admonition environments ---

% Admonition style "colors1" has its style taken from the NumPy User Guide
% "notice" admon
\definecolor{colors1_notice_background}{rgb}{0.988235,0.964706,0.862745}
% \fboxsep sets the space between the text and the box
\newenvironment{noticeshaded}
{\def\FrameCommand{\fboxsep=3mm\colorbox{colors1_notice_background}}
 \MakeFramed {\advance\hsize-\width \FrameRestore}}{\endMakeFramed}

\newenvironment{notice_colors1admon}[1][Notice]{
\begin{noticeshaded}
\noindent
\includegraphics[height=0.3in]{latex_figs/notice}\ \ \   \textbf{#1}\\ \par
\vspace{-3mm}\nobreak\noindent\ignorespaces
}
{
\end{noticeshaded}
}

% Admonition style "colors1" has its style taken from the NumPy User Guide
% "summary" admon
\definecolor{colors1_summary_background}{rgb}{0.988235,0.964706,0.862745}
% \fboxsep sets the space between the text and the box
\newenvironment{summaryshaded}
{\def\FrameCommand{\fboxsep=3mm\colorbox{colors1_summary_background}}
 \MakeFramed {\advance\hsize-\width \FrameRestore}}{\endMakeFramed}

\newenvironment{summary_colors1admon}[1][Summary]{
\begin{summaryshaded}
\noindent
\includegraphics[height=0.3in]{latex_figs/summary}\ \ \   \textbf{#1}\\ \par
\vspace{-3mm}\nobreak\noindent\ignorespaces
}
{
\end{summaryshaded}
}

% Admonition style "colors1" has its style taken from the NumPy User Guide
% "warning" admon
\definecolor{colors1_warning_background}{rgb}{1.0,0.8235294,0.8235294}
% \fboxsep sets the space between the text and the box
\newenvironment{warningshaded}
{\def\FrameCommand{\fboxsep=3mm\colorbox{colors1_warning_background}}
 \MakeFramed {\advance\hsize-\width \FrameRestore}}{\endMakeFramed}

\newenvironment{warning_colors1admon}[1][Warning]{
\begin{warningshaded}
\noindent
\includegraphics[height=0.3in]{latex_figs/warning}\ \ \   \textbf{#1}\\ \par
\vspace{-3mm}\nobreak\noindent\ignorespaces
}
{
\end{warningshaded}
}

% Admonition style "colors1" has its style taken from the NumPy User Guide
% "question" admon
\definecolor{colors1_question_background}{rgb}{0.988235,0.964706,0.862745}
% \fboxsep sets the space between the text and the box
\newenvironment{questionshaded}
{\def\FrameCommand{\fboxsep=3mm\colorbox{colors1_question_background}}
 \MakeFramed {\advance\hsize-\width \FrameRestore}}{\endMakeFramed}

\newenvironment{question_colors1admon}[1][Question]{
\begin{questionshaded}
\noindent
\includegraphics[height=0.3in]{latex_figs/question}\ \ \   \textbf{#1}\\ \par
\vspace{-3mm}\nobreak\noindent\ignorespaces
}
{
\end{questionshaded}
}

% Admonition style "colors1" has its style taken from the NumPy User Guide
% "block" admon
\definecolor{colors1_block_background}{rgb}{0.988235,0.964706,0.862745}
% \fboxsep sets the space between the text and the box
\newenvironment{blockshaded}
{\def\FrameCommand{\fboxsep=3mm\colorbox{colors1_block_background}}
 \MakeFramed {\advance\hsize-\width \FrameRestore}}{\endMakeFramed}

\newenvironment{block_colors1admon}[1][Block]{
\begin{blockshaded}
\noindent
  \textbf{#1}\\ \par
\vspace{-3mm}\nobreak\noindent\ignorespaces
}
{
\end{blockshaded}
}

% --- end of definitions of admonition environments ---

% prevent orhpans and widows
\clubpenalty = 10000
\widowpenalty = 10000

% --- end of standard preamble for documents ---


% insert custom LaTeX commands...

\raggedbottom
\makeindex
\usepackage[totoc]{idxlayout}   % for index in the toc
\usepackage[nottoc]{tocbibind}  % for references/bibliography in the toc

%-------------------- end preamble ----------------------

\begin{document}

% matching end for #ifdef PREAMBLE
% #endif

\newcommand{\exercisesection}[1]{\subsection*{#1}}

\input{newcommands_bfmath}
\input{newcommands_replace}

% ------------------- main content ----------------------



% ----------------- title -------------------------

\thispagestyle{empty}

\begin{center}
{\LARGE\bf
\begin{spacing}{1.25}
Testing admons
\end{spacing}
}
\end{center}

% ----------------- author(s) -------------------------

\begin{center}
{\bf H. P. Langtangen${}^{}$} \\ [0mm]
\end{center}

\begin{center}
% List of all institutions:
\end{center}
    
% ----------------- end author(s) -------------------------

% --- begin date ---
\begin{center}
Jan 32, 2100
\end{center}
% --- end date ---

\vspace{1cm}


% !split
\section{Introduction}
First some ordinary text to compare font sizes in admonitions
and the surrounding text.


\subsection{Code}

Need some code outside admons for color and font comparisons:

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
def some_code(x):
    return sin(x)*exp(1-x)
\end{lstlisting}

And some plain text verbatim:

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
x=1.0 y=0.9 z=0.4
x=1.1 y=0.3 z=0.1
\end{lstlisting}

\subsection{Quotes and boxes}

Here is a plain quote environment.


\begin{quote}
Sayre's law states that
``in any dispute the intensity of feeling is inversely
proportional to the value of the issues at stake.'' \\
By way of corollary, it adds: \\
``That is why academic politics are so bitter.'' \\
\emph{Source}: \href{{https://en.wikipedia.org/wiki/Sayre's_law}}{wikipedia}
\end{quote}


Does quotes with title also work? No...cannot work in {\LaTeX} and HTML
and then it does not make sense to support it.


A plain \emph{box} is sometimes useful. Let's show it here for comparison
with admons (especially the block admon has much in common with a box).
The box is more aimed at framing a law or an equation.

First a simple block with text, an equation, and a list:


\begin{center}
\begin{Sbox}
\begin{minipage}{0.85\linewidth}
A generic equation

\[ f(x) = 0 \]
must be solved by a numerical method, such as

\begin{itemize}
 \item Newton's method

 \item The Bisection method

 \item Fixed-point (Picard) iteration by rewriting $f(x)=x - g(x)$

 \item The Secant method
\end{itemize}

\noindent
\end{minipage}
\end{Sbox}
\fbox{\TheSbox}
\end{center}
Now test a box with equation only (note that this line continues the
box, it is not a new paragraph):


\begin{center}
\begin{Sbox}
\begin{minipage}{0.85\linewidth}
\begin{equation} f(x) = \sin(x)e^{1-x} \end{equation}
\end{minipage}
\end{Sbox}
\fbox{\TheSbox}
\end{center}

\paragraph{Hint.}
Newton's method requires a good start vector to converge fast.



Let's begin a new paragraph and show a box with code only:


\begin{center}
\begin{Sbox}
\begin{minipage}{0.85\linewidth}
\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
def some_code(x):
    return sin(x)*exp(1-x)
\end{lstlisting}
\end{minipage}
\end{Sbox}
\fbox{\TheSbox}
\end{center}



\subsection{Admonitions}

Let us start with a plain warning environment.


\begin{warning_colors1admon}[Warning]
And here is a warning about something to pay attention to. We
test how the heading behave and add quite some extra texts
in comparison with the other admons.

\begin{itemize}
  \item and a list

  \item with items
\end{itemize}

\noindent
We continue with more text to see how that affects the layout.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
\end{warning_colors1admon} % title: Warning



Test warning with title:


\begin{warning_colors1admon}[{\large Title ending with math $\sqrt{2}\approx 1.4$}]
{\large And here comes some text with bad news in larger font.

Also some code:

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
def f(x):
    return x
\end{lstlisting}
And a complete program

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
print("Hello, World!")
\end{lstlisting}
\par}
\end{warning_colors1admon} % title: {\large Title ending with math $\sqrt{2}\approx 1.4$}



Test warning with large title with math:


\begin{warning_colors1admon}[{\large Watch out for $\nabla\cdot\bm{u}=0$ equations}]
{\large Divergence freedom is often problematic from a numerical point
of view.
\par}
\end{warning_colors1admon} % title: {\large Watch out for $\nabla\cdot\bm{u}=0$ equations}



Then we test a block, which is guaranteed to never have any admon icon.


\begin{block_colors1admon}[Block with title]
\vspace{-3.5mm}\par\noindent
{\footnotesize Here is a block of text with title. It is typeset
\emph{without any icon} and is useful when you want some admons with icon
and some without. With the small font size, as used here, one can have
more comment-style text or text that really goes deeper or talks
about fun facts that are not strictly necessary for the main flow
of understanding.
\par}
\end{block_colors1admon} % title: Block with title





\begin{block_colors1admon}[]
Here is a block of text with no title. As above, it is typeset without any icon
and is useful when you want some admons with icon and some without.
\end{block_colors1admon} % title: 



% Note that the final ! does not appear in Sphinx and reST since
% those formats automatically add : to the admonition title.


\begin{notice_colors1admon}[Note, eventually!]
Ah, we are soon close to the end (with illegal font size specification!).
But first a bit of math where we define $\theta$ and $\bm{r}$:

\begin{align*}
\theta &= q^2,\\
\bm{r} &= \varrho\bm{i}
\end{align*}
\end{notice_colors1admon} % title: Note, eventually!



% Test one word with a number


\begin{notice_colors1admon}[Point1]
Ah, we are soon close to the end.
\end{notice_colors1admon} % title: Point1




\begin{question_colors1admon}[Question]
So, how many admonition environments does DocOnce support?
\end{question_colors1admon} % title: Question




\begin{question_colors1admon}[Question]
\begin{enumerate}
 \item Once more, how many admonition environments does DocOnce support?
\end{enumerate}

\noindent
\end{question_colors1admon} % title: Question




\begin{warning_colors1admon}[Tip]
It is of outmost important to

\begin{enumerate}
\item stay cool

\item read hints and tips carefully
\end{enumerate}

\noindent
Because here the thing is to do

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
import urllib

def grab(url, filename):
    urllib.urlretrieve(url, filename=filename)
\end{lstlisting}
\end{warning_colors1admon} % title: Tip



Next is a warning without a title ("none" implies no title).


\begin{warning_colors1admon}[]
And here comes some text with bad news.
\end{warning_colors1admon} % title: 



\subsection{Going deeper environments}

Here is a long notice environment with a custom title and much
text, math and code.


\begin{notice_colors1admon}[Going deeper.]
We have some equations that should be preceded by much text, so the
task is to write and write. The number of words, and not the
meaning, is what counts here. We need desperately to fill up the
page in the hope that some admonitions will experience a page break,
which the {\LaTeX} environment should handle with ease.

Let us start with some equations:

\begin{align*}
\Ddt{u} &= 0
\\
\half &= \halfi\\
\half\x &= \normalvec
\end{align*}

The implementation of such complicated equations in computer
code is task that this "Going deeper" environment targets.

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
def Dudt(u):
    r = diff(u, t) + u*grad(u)
    return r

half = 0.5
x = 2*n
\end{lstlisting}
And some more text that can help going into the next page.
Longer computer code requires vertical space:

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
class Diff:
    def __init__(self, f, h=1E-5):
        self.f = f
        self.h = float(h)

class Forward1(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (f(x+h) - f(x))/h

class Backward1(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (f(x) - f(x-h))/h

class Central2(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (f(x+h) - f(x-h))/(2*h)

class Central4(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (4./3)*(f(x+h)   - f(x-h))  /(2*h) - \
               (1./3)*(f(x+2*h) - f(x-2*h))/(4*h)

class Central6(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (3./2) *(f(x+h)   - f(x-h))  /(2*h) - \
               (3./5) *(f(x+2*h) - f(x-2*h))/(4*h) + \
               (1./10)*(f(x+3*h) - f(x-3*h))/(6*h)

class Forward3(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (-(1./6)*f(x+2*h) + f(x+h) - 0.5*f(x) - \
                (1./3)*f(x-h))/h
\end{lstlisting}
And then we add a figure too.



\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=0.7\linewidth]{../doc/src/manual/fig/wave1D.pdf}}

\vspace{6mm}
\end{notice_colors1admon} % title: Going deeper.




\subsection{The end}

A bit of text before the summary, which we now call "Concluding remarks,
for the novice",
just because we can.


\begin{summary_colors1admon}[Concluding remarks, for the novice]
We can summarize the most important things with admons: they have
a different typesetting, and they may have a symbol.
Titles should be optional.
\end{summary_colors1admon} % title: Concluding remarks, for the novice



\paragraph{Remark.}
The \texttt{remarks} and \texttt{hint} environments are not allowed outside
exercises (and problems and projects too).

% ------------------- end of main content ---------------

% #ifdef PREAMBLE
\end{document}
% #endif


************** File: admon_colors2.tex *****************
%%
%% Automatically generated file from DocOnce source
%% (https://github.com/hplgit/doconce/)
%%

% #define PREAMBLE

% #ifdef PREAMBLE
%-------------------- begin preamble ----------------------

\documentclass[%
oneside,                 % oneside: electronic viewing, twoside: printing
final,                   % draft: marks overfull hboxes, figures with paths
10pt]{article}

\listfiles               %  print all files needed to compile this document

\usepackage{relsize,makeidx,color,setspace,amsmath,amsfonts,amssymb}
\usepackage[table]{xcolor}
\usepackage{bm,ltablex,microtype}

\usepackage[pdftex]{graphicx}

\usepackage{fancybox}  % make sure fancybox is loaded before fancyvrb
%\setlength{\fboxsep}{8pt}  % may clash with need in pre/cod envirs

% Packages for typesetting blocks of computer code
\usepackage{fancyvrb,framed,moreverb}

% Define colors
\definecolor{orange}{cmyk}{0,0.4,0.8,0.2}
\definecolor{tucorange}{rgb}{1.0,0.64,0}
\definecolor{darkorange}{rgb}{.71,0.21,0.01}
\definecolor{darkgreen}{rgb}{.12,.54,.11}
\definecolor{myteal}{rgb}{.26, .44, .56}
\definecolor{gray}{gray}{0.45}
\definecolor{mediumgray}{gray}{.8}
\definecolor{lightgray}{gray}{.95}
\definecolor{brown}{rgb}{0.54,0.27,0.07}
\definecolor{purple}{rgb}{0.5,0.0,0.5}
\definecolor{darkgray}{gray}{0.25}
\definecolor{darkblue}{rgb}{0,0.08,0.45}
\definecolor{darkblue2}{rgb}{0,0,0.8}
\definecolor{lightred}{rgb}{1.0,0.39,0.28}
\definecolor{lightgreen}{rgb}{0.48,0.99,0.0}
\definecolor{lightblue}{rgb}{0.53,0.81,0.92}
\definecolor{lightblue2}{rgb}{0.3,0.3,1.0}
\definecolor{lightpurple}{rgb}{0.87,0.63,0.87}
\definecolor{lightcyan}{rgb}{0.5,1.0,0.83}

\colorlet{comment_green}{green!50!black}
\colorlet{string_red}{red!60!black}
\colorlet{keyword_pink}{magenta!70!black}
\colorlet{indendifier_green}{green!70!white}

% Backgrounds for code
\definecolor{cbg_gray}{rgb}{.95, .95, .95}
\definecolor{bar_gray}{rgb}{.92, .92, .92}

\definecolor{cbg_yellowgray}{rgb}{.95, .95, .85}
\definecolor{bar_yellowgray}{rgb}{.95, .95, .65}

\colorlet{cbg_yellow2}{yellow!10}
\colorlet{bar_yellow2}{yellow!20}

\definecolor{cbg_yellow1}{rgb}{.98, .98, 0.8}
\definecolor{bar_yellow1}{rgb}{.98, .98, 0.4}

\definecolor{cbg_red1}{rgb}{1, 0.85, 0.85}
\definecolor{bar_red1}{rgb}{1, 0.75, 0.85}

\definecolor{cbg_blue1}{rgb}{0.87843, 0.95686, 1.0}
\definecolor{bar_blue1}{rgb}{0.7,     0.95686, 1}

\usepackage{listingsutf8}

% Common lstlisting parameters

\usepackage{calc}
\newlength{\lstboxwidth}  % width of lst box
\newlength{\framethickness}
\setlength{\framethickness}{0.5mm}
% for frame=trbl and a framerule that has significant size, set
% xleftmargin=5mm and xrightmargin=5mm.

\lstset{
  basicstyle=\small \ttfamily,
  breaklines=false,          % break/wrap lines
  breakatwhitespace=true,    % let linebreaks happen at whitespace
  breakindent=40pt,
  tab=,
  tabsize=4,                 % tab means 4 spaces
  %belowskip=\smallskipamount,  % space between code and text below
  xleftmargin=2mm,           % indentation of code frame
  xrightmargin=0mm,
  framexleftmargin=2mm,      % add frame space to the left of the code box
  %numbers=left,             % put line numbers on the left
  %stepnumber=2,             % stepnumber=1 numbers each line, =n every n lines
  framerule=\framethickness, % thickness of frame
  aboveskip=2ex,             % vertical space above code frame
  showstringspaces=false,    % show spaces in strings with an underscore
  showspaces=false,          % show spaces with an underscore
  showtabs=false,
  keepspaces=true,
  columns=fullflexible,      % tighter character kerning, like verb
  escapeinside={(*@}{@*)},   % (*@ \pause @*) in slides and math in code blocks
  extendedchars=\true,       % allows non-ascii chars, does not work with utf-8
}

% Internally defined styles for lstlisting

\lstdefinestyle{simple}{
commentstyle={},
}

% end of custom lstdefinestyles

\usepackage[T1]{fontenc}
%\usepackage[latin1]{inputenc}
\usepackage{ucs}
\usepackage[utf8x]{inputenc}

\usepackage{lmodern}         % Latin Modern fonts derived from Computer Modern

% Hyperlinks in PDF:
\definecolor{linkcolor}{rgb}{0,0,0.4}
\usepackage{hyperref}
\hypersetup{
    breaklinks=true,
    colorlinks=true,
    linkcolor=linkcolor,
    urlcolor=linkcolor,
    citecolor=black,
    filecolor=black,
    %filecolor=blue,
    pdfmenubar=true,
    pdftoolbar=true,
    bookmarksdepth=3   % Uncomment (and tweak) for PDF bookmarks with more levels than the TOC
    }
%\hyperbaseurl{}   % hyperlinks are relative to this root

\setcounter{tocdepth}{2}  % levels in table of contents

% Tricks for having figures close to where they are defined:
% 1. define less restrictive rules for where to put figures
\setcounter{topnumber}{2}
\setcounter{bottomnumber}{2}
\setcounter{totalnumber}{4}
\renewcommand{\topfraction}{0.95}
\renewcommand{\bottomfraction}{0.95}
\renewcommand{\textfraction}{0}
\renewcommand{\floatpagefraction}{0.75}
% floatpagefraction must always be less than topfraction!
% 2. ensure all figures are flushed before next section
\usepackage[section]{placeins}
% 3. enable begin{figure}[H] (often leads to ugly pagebreaks)
%\usepackage{float}\restylefloat{figure}

% --- fancyhdr package for fancy headers ---
\usepackage{fancyhdr}
\fancyhf{} % sets both header and footer to nothing
\renewcommand{\headrulewidth}{0pt}
\fancyfoot[LE,RO]{\thepage}
% Ensure copyright on titlepage (article style) and chapter pages (book style)
\fancypagestyle{plain}{
  \fancyhf{}
  \fancyfoot[C]{{\footnotesize \copyright\ 2021, H. P. Langtangen. Made with \href{https://github.com/hplgit/doconce}{DocOnce}}}
%  \renewcommand{\footrulewidth}{0mm}
  \renewcommand{\headrulewidth}{0mm}
}
% Ensure copyright on titlepages with \thispagestyle{empty}
\fancypagestyle{empty}{
  \fancyhf{}
  \fancyfoot[C]{{\footnotesize \copyright\ 2021, H. P. Langtangen. Made with \href{https://github.com/hplgit/doconce}{DocOnce}}}
  \renewcommand{\footrulewidth}{0mm}
  \renewcommand{\headrulewidth}{0mm}
}

\pagestyle{fancy}


\usepackage{framed,wrapfig}

% --- begin definitions of admonition environments ---

% Admonition style "colors2", admon "notice"
\definecolor{colors2_notice_background}{rgb}{0.988235,0.964706,0.862745}
% \fboxsep sets the space between the text and the box
\newenvironment{noticeshaded}
{\def\FrameCommand{\fboxsep=3mm\colorbox{colors2_notice_background}}
 \MakeFramed {\advance\hsize-\width \FrameRestore}}{\endMakeFramed}

\newenvironment{notice_colors2admon}[1][Notice]{
\begin{noticeshaded}
\noindent
\begin{wrapfigure}{l}{0.07\textwidth}
\vspace{-13pt}
\includegraphics[width=0.07\textwidth]{latex_figs/notice}
\end{wrapfigure} \textbf{#1}\par
\nobreak\noindent\ignorespaces
}
{
\end{noticeshaded}
}

% Admonition style "colors2", admon "summary"
\definecolor{colors2_summary_background}{rgb}{0.988235,0.964706,0.862745}
% \fboxsep sets the space between the text and the box
\newenvironment{summaryshaded}
{\def\FrameCommand{\fboxsep=3mm\colorbox{colors2_summary_background}}
 \MakeFramed {\advance\hsize-\width \FrameRestore}}{\endMakeFramed}

\newenvironment{summary_colors2admon}[1][Summary]{
\begin{summaryshaded}
\noindent
\begin{wrapfigure}{l}{0.07\textwidth}
\vspace{-13pt}
\includegraphics[width=0.07\textwidth]{latex_figs/summary}
\end{wrapfigure} \textbf{#1}\par
\nobreak\noindent\ignorespaces
}
{
\end{summaryshaded}
}

% Admonition style "colors2", admon "warning"
\definecolor{colors2_warning_background}{rgb}{1.0,0.8235294,0.8235294}
% \fboxsep sets the space between the text and the box
\newenvironment{warningshaded}
{\def\FrameCommand{\fboxsep=3mm\colorbox{colors2_warning_background}}
 \MakeFramed {\advance\hsize-\width \FrameRestore}}{\endMakeFramed}

\newenvironment{warning_colors2admon}[1][Warning]{
\begin{warningshaded}
\noindent
\begin{wrapfigure}{l}{0.07\textwidth}
\vspace{-13pt}
\includegraphics[width=0.07\textwidth]{latex_figs/warning}
\end{wrapfigure} \textbf{#1}\par
\nobreak\noindent\ignorespaces
}
{
\end{warningshaded}
}

% Admonition style "colors2", admon "question"
\definecolor{colors2_question_background}{rgb}{0.988235,0.964706,0.862745}
% \fboxsep sets the space between the text and the box
\newenvironment{questionshaded}
{\def\FrameCommand{\fboxsep=3mm\colorbox{colors2_question_background}}
 \MakeFramed {\advance\hsize-\width \FrameRestore}}{\endMakeFramed}

\newenvironment{question_colors2admon}[1][Question]{
\begin{questionshaded}
\noindent
\begin{wrapfigure}{l}{0.07\textwidth}
\vspace{-13pt}
\includegraphics[width=0.07\textwidth]{latex_figs/question}
\end{wrapfigure} \textbf{#1}\par
\nobreak\noindent\ignorespaces
}
{
\end{questionshaded}
}

% Admonition style "colors2", admon "block"
\definecolor{colors2_block_background}{rgb}{0.988235,0.964706,0.862745}
% \fboxsep sets the space between the text and the box
\newenvironment{blockshaded}
{\def\FrameCommand{\fboxsep=3mm\colorbox{colors2_block_background}}
 \MakeFramed {\advance\hsize-\width \FrameRestore}}{\endMakeFramed}

\newenvironment{block_colors2admon}[1][Block]{
\begin{blockshaded}
\noindent
 \textbf{#1}\par
\nobreak\noindent\ignorespaces
}
{
\end{blockshaded}
}

% --- end of definitions of admonition environments ---

% prevent orhpans and widows
\clubpenalty = 10000
\widowpenalty = 10000

% --- end of standard preamble for documents ---


% insert custom LaTeX commands...

\raggedbottom
\makeindex
\usepackage[totoc]{idxlayout}   % for index in the toc
\usepackage[nottoc]{tocbibind}  % for references/bibliography in the toc

%-------------------- end preamble ----------------------

\begin{document}

% matching end for #ifdef PREAMBLE
% #endif

\newcommand{\exercisesection}[1]{\subsection*{#1}}

\input{newcommands_bfmath}
\input{newcommands_replace}

% ------------------- main content ----------------------



% ----------------- title -------------------------

\thispagestyle{empty}

\begin{center}
{\LARGE\bf
\begin{spacing}{1.25}
Testing admons
\end{spacing}
}
\end{center}

% ----------------- author(s) -------------------------

\begin{center}
{\bf H. P. Langtangen${}^{}$} \\ [0mm]
\end{center}

\begin{center}
% List of all institutions:
\end{center}
    
% ----------------- end author(s) -------------------------

% --- begin date ---
\begin{center}
Jan 32, 2100
\end{center}
% --- end date ---

\vspace{1cm}


% !split
\section{Introduction}
First some ordinary text to compare font sizes in admonitions
and the surrounding text.


\subsection{Code}

Need some code outside admons for color and font comparisons:

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
def some_code(x):
    return sin(x)*exp(1-x)
\end{lstlisting}

And some plain text verbatim:

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
x=1.0 y=0.9 z=0.4
x=1.1 y=0.3 z=0.1
\end{lstlisting}

\subsection{Quotes and boxes}

Here is a plain quote environment.


\begin{quote}
Sayre's law states that
``in any dispute the intensity of feeling is inversely
proportional to the value of the issues at stake.'' \\
By way of corollary, it adds: \\
``That is why academic politics are so bitter.'' \\
\emph{Source}: \href{{https://en.wikipedia.org/wiki/Sayre's_law}}{wikipedia}
\end{quote}


Does quotes with title also work? No...cannot work in {\LaTeX} and HTML
and then it does not make sense to support it.


A plain \emph{box} is sometimes useful. Let's show it here for comparison
with admons (especially the block admon has much in common with a box).
The box is more aimed at framing a law or an equation.

First a simple block with text, an equation, and a list:


\begin{center}
\begin{Sbox}
\begin{minipage}{0.85\linewidth}
A generic equation

\[ f(x) = 0 \]
must be solved by a numerical method, such as

\begin{itemize}
 \item Newton's method

 \item The Bisection method

 \item Fixed-point (Picard) iteration by rewriting $f(x)=x - g(x)$

 \item The Secant method
\end{itemize}

\noindent
\end{minipage}
\end{Sbox}
\fbox{\TheSbox}
\end{center}
Now test a box with equation only (note that this line continues the
box, it is not a new paragraph):


\begin{center}
\begin{Sbox}
\begin{minipage}{0.85\linewidth}
\begin{equation} f(x) = \sin(x)e^{1-x} \end{equation}
\end{minipage}
\end{Sbox}
\fbox{\TheSbox}
\end{center}

\paragraph{Hint.}
Newton's method requires a good start vector to converge fast.



Let's begin a new paragraph and show a box with code only:


\begin{center}
\begin{Sbox}
\begin{minipage}{0.85\linewidth}
\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
def some_code(x):
    return sin(x)*exp(1-x)
\end{lstlisting}
\end{minipage}
\end{Sbox}
\fbox{\TheSbox}
\end{center}



\subsection{Admonitions}

Let us start with a plain warning environment.


\begin{warning_colors2admon}[Warning]
And here is a warning about something to pay attention to. We
test how the heading behave and add quite some extra texts
in comparison with the other admons.

\begin{itemize}
  \item and a list

  \item with items
\end{itemize}

\noindent
We continue with more text to see how that affects the layout.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
\end{warning_colors2admon} % title: Warning



Test warning with title:


\begin{warning_colors2admon}[{\large Title ending with math $\sqrt{2}\approx 1.4$}]
{\large And here comes some text with bad news in larger font.

Also some code:

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
def f(x):
    return x
\end{lstlisting}
And a complete program

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
print("Hello, World!")
\end{lstlisting}
\par}
\end{warning_colors2admon} % title: {\large Title ending with math $\sqrt{2}\approx 1.4$}



Test warning with large title with math:


\begin{warning_colors2admon}[{\large Watch out for $\nabla\cdot\bm{u}=0$ equations}]
{\large Divergence freedom is often problematic from a numerical point
of view.
\par}
\end{warning_colors2admon} % title: {\large Watch out for $\nabla\cdot\bm{u}=0$ equations}



Then we test a block, which is guaranteed to never have any admon icon.


\begin{block_colors2admon}[Block with title]
\vspace{-2.5mm}\par\noindent
{\footnotesize Here is a block of text with title. It is typeset
\emph{without any icon} and is useful when you want some admons with icon
and some without. With the small font size, as used here, one can have
more comment-style text or text that really goes deeper or talks
about fun facts that are not strictly necessary for the main flow
of understanding.
\par}
\end{block_colors2admon} % title: Block with title





\begin{block_colors2admon}[]
Here is a block of text with no title. As above, it is typeset without any icon
and is useful when you want some admons with icon and some without.
\end{block_colors2admon} % title: 



% Note that the final ! does not appear in Sphinx and reST since
% those formats automatically add : to the admonition title.


\begin{notice_colors2admon}[Note, eventually!]
Ah, we are soon close to the end (with illegal font size specification!).
But first a bit of math where we define $\theta$ and $\bm{r}$:

\begin{align*}
\theta &= q^2,\\
\bm{r} &= \varrho\bm{i}
\end{align*}
\end{notice_colors2admon} % title: Note, eventually!



% Test one word with a number


\begin{notice_colors2admon}[Point1]
Ah, we are soon close to the end.
\end{notice_colors2admon} % title: Point1




\begin{question_colors2admon}[Question]
So, how many admonition environments does DocOnce support?
\end{question_colors2admon} % title: Question




\begin{question_colors2admon}[Question]
\begin{enumerate}
 \item Once more, how many admonition environments does DocOnce support?
\end{enumerate}

\noindent
\end{question_colors2admon} % title: Question




\begin{warning_colors2admon}[Tip]
It is of outmost important to

\begin{enumerate}
\item stay cool

\item read hints and tips carefully
\end{enumerate}

\noindent
Because here the thing is to do

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
import urllib

def grab(url, filename):
    urllib.urlretrieve(url, filename=filename)
\end{lstlisting}
\end{warning_colors2admon} % title: Tip



Next is a warning without a title ("none" implies no title).


\begin{warning_colors2admon}[]
And here comes some text with bad news.
\end{warning_colors2admon} % title: 



\subsection{Going deeper environments}

Here is a long notice environment with a custom title and much
text, math and code.


\begin{notice_colors2admon}[Going deeper.]
We have some equations that should be preceded by much text, so the
task is to write and write. The number of words, and not the
meaning, is what counts here. We need desperately to fill up the
page in the hope that some admonitions will experience a page break,
which the {\LaTeX} environment should handle with ease.

Let us start with some equations:

\begin{align*}
\Ddt{u} &= 0
\\
\half &= \halfi\\
\half\x &= \normalvec
\end{align*}

The implementation of such complicated equations in computer
code is task that this "Going deeper" environment targets.

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
def Dudt(u):
    r = diff(u, t) + u*grad(u)
    return r

half = 0.5
x = 2*n
\end{lstlisting}
And some more text that can help going into the next page.
Longer computer code requires vertical space:

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
class Diff:
    def __init__(self, f, h=1E-5):
        self.f = f
        self.h = float(h)

class Forward1(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (f(x+h) - f(x))/h

class Backward1(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (f(x) - f(x-h))/h

class Central2(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (f(x+h) - f(x-h))/(2*h)

class Central4(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (4./3)*(f(x+h)   - f(x-h))  /(2*h) - \
               (1./3)*(f(x+2*h) - f(x-2*h))/(4*h)

class Central6(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (3./2) *(f(x+h)   - f(x-h))  /(2*h) - \
               (3./5) *(f(x+2*h) - f(x-2*h))/(4*h) + \
               (1./10)*(f(x+3*h) - f(x-3*h))/(6*h)

class Forward3(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (-(1./6)*f(x+2*h) + f(x+h) - 0.5*f(x) - \
                (1./3)*f(x-h))/h
\end{lstlisting}
And then we add a figure too.



\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=0.7\linewidth]{../doc/src/manual/fig/wave1D.pdf}}

\vspace{6mm}
\end{notice_colors2admon} % title: Going deeper.




\subsection{The end}

A bit of text before the summary, which we now call "Concluding remarks,
for the novice",
just because we can.


\begin{summary_colors2admon}[Concluding remarks, for the novice]
We can summarize the most important things with admons: they have
a different typesetting, and they may have a symbol.
Titles should be optional.
\end{summary_colors2admon} % title: Concluding remarks, for the novice



\paragraph{Remark.}
The \texttt{remarks} and \texttt{hint} environments are not allowed outside
exercises (and problems and projects too).

% ------------------- end of main content ---------------

% #ifdef PREAMBLE
\end{document}
% #endif


************** File: admon_mdfbox.tex *****************
%%
%% Automatically generated file from DocOnce source
%% (https://github.com/hplgit/doconce/)
%%

% #define PREAMBLE

% #ifdef PREAMBLE
%-------------------- begin preamble ----------------------

\documentclass[%
oneside,                 % oneside: electronic viewing, twoside: printing
final,                   % draft: marks overfull hboxes, figures with paths
10pt]{article}

\listfiles               %  print all files needed to compile this document

\usepackage{relsize,makeidx,color,setspace,amsmath,amsfonts,amssymb}
\usepackage[table]{xcolor}
\usepackage{bm,ltablex,microtype}

\usepackage[pdftex]{graphicx}

\usepackage{fancybox}  % make sure fancybox is loaded before fancyvrb
%\setlength{\fboxsep}{8pt}  % may clash with need in pre/cod envirs

% Packages for typesetting blocks of computer code
\usepackage{fancyvrb,framed,moreverb}

% Define colors
\definecolor{orange}{cmyk}{0,0.4,0.8,0.2}
\definecolor{tucorange}{rgb}{1.0,0.64,0}
\definecolor{darkorange}{rgb}{.71,0.21,0.01}
\definecolor{darkgreen}{rgb}{.12,.54,.11}
\definecolor{myteal}{rgb}{.26, .44, .56}
\definecolor{gray}{gray}{0.45}
\definecolor{mediumgray}{gray}{.8}
\definecolor{lightgray}{gray}{.95}
\definecolor{brown}{rgb}{0.54,0.27,0.07}
\definecolor{purple}{rgb}{0.5,0.0,0.5}
\definecolor{darkgray}{gray}{0.25}
\definecolor{darkblue}{rgb}{0,0.08,0.45}
\definecolor{darkblue2}{rgb}{0,0,0.8}
\definecolor{lightred}{rgb}{1.0,0.39,0.28}
\definecolor{lightgreen}{rgb}{0.48,0.99,0.0}
\definecolor{lightblue}{rgb}{0.53,0.81,0.92}
\definecolor{lightblue2}{rgb}{0.3,0.3,1.0}
\definecolor{lightpurple}{rgb}{0.87,0.63,0.87}
\definecolor{lightcyan}{rgb}{0.5,1.0,0.83}

\colorlet{comment_green}{green!50!black}
\colorlet{string_red}{red!60!black}
\colorlet{keyword_pink}{magenta!70!black}
\colorlet{indendifier_green}{green!70!white}

% Backgrounds for code
\definecolor{cbg_gray}{rgb}{.95, .95, .95}
\definecolor{bar_gray}{rgb}{.92, .92, .92}

\definecolor{cbg_yellowgray}{rgb}{.95, .95, .85}
\definecolor{bar_yellowgray}{rgb}{.95, .95, .65}

\colorlet{cbg_yellow2}{yellow!10}
\colorlet{bar_yellow2}{yellow!20}

\definecolor{cbg_yellow1}{rgb}{.98, .98, 0.8}
\definecolor{bar_yellow1}{rgb}{.98, .98, 0.4}

\definecolor{cbg_red1}{rgb}{1, 0.85, 0.85}
\definecolor{bar_red1}{rgb}{1, 0.75, 0.85}

\definecolor{cbg_blue1}{rgb}{0.87843, 0.95686, 1.0}
\definecolor{bar_blue1}{rgb}{0.7,     0.95686, 1}

\usepackage{listingsutf8}

% Common lstlisting parameters

\usepackage{calc}
\newlength{\lstboxwidth}  % width of lst box
\newlength{\framethickness}
\setlength{\framethickness}{0.5mm}
% for frame=trbl and a framerule that has significant size, set
% xleftmargin=5mm and xrightmargin=5mm.

\lstset{
  basicstyle=\small \ttfamily,
  breaklines=false,          % break/wrap lines
  breakatwhitespace=true,    % let linebreaks happen at whitespace
  breakindent=40pt,
  tab=,
  tabsize=4,                 % tab means 4 spaces
  %belowskip=\smallskipamount,  % space between code and text below
  xleftmargin=2mm,           % indentation of code frame
  xrightmargin=0mm,
  framexleftmargin=2mm,      % add frame space to the left of the code box
  %numbers=left,             % put line numbers on the left
  %stepnumber=2,             % stepnumber=1 numbers each line, =n every n lines
  framerule=\framethickness, % thickness of frame
  aboveskip=2ex,             % vertical space above code frame
  showstringspaces=false,    % show spaces in strings with an underscore
  showspaces=false,          % show spaces with an underscore
  showtabs=false,
  keepspaces=true,
  columns=fullflexible,      % tighter character kerning, like verb
  escapeinside={(*@}{@*)},   % (*@ \pause @*) in slides and math in code blocks
  extendedchars=\true,       % allows non-ascii chars, does not work with utf-8
}

% Internally defined styles for lstlisting

\lstdefinestyle{simple}{
commentstyle={},
}

% end of custom lstdefinestyles

\usepackage[T1]{fontenc}
%\usepackage[latin1]{inputenc}
\usepackage{ucs}
\usepackage[utf8x]{inputenc}

\usepackage{lmodern}         % Latin Modern fonts derived from Computer Modern

% Hyperlinks in PDF:
\definecolor{linkcolor}{rgb}{0,0,0.4}
\usepackage{hyperref}
\hypersetup{
    breaklinks=true,
    colorlinks=true,
    linkcolor=linkcolor,
    urlcolor=linkcolor,
    citecolor=black,
    filecolor=black,
    %filecolor=blue,
    pdfmenubar=true,
    pdftoolbar=true,
    bookmarksdepth=3   % Uncomment (and tweak) for PDF bookmarks with more levels than the TOC
    }
%\hyperbaseurl{}   % hyperlinks are relative to this root

\setcounter{tocdepth}{2}  % levels in table of contents

% Tricks for having figures close to where they are defined:
% 1. define less restrictive rules for where to put figures
\setcounter{topnumber}{2}
\setcounter{bottomnumber}{2}
\setcounter{totalnumber}{4}
\renewcommand{\topfraction}{0.95}
\renewcommand{\bottomfraction}{0.95}
\renewcommand{\textfraction}{0}
\renewcommand{\floatpagefraction}{0.75}
% floatpagefraction must always be less than topfraction!
% 2. ensure all figures are flushed before next section
\usepackage[section]{placeins}
% 3. enable begin{figure}[H] (often leads to ugly pagebreaks)
%\usepackage{float}\restylefloat{figure}

% --- fancyhdr package for fancy headers ---
\usepackage{fancyhdr}
\fancyhf{} % sets both header and footer to nothing
\renewcommand{\headrulewidth}{0pt}
\fancyfoot[LE,RO]{\thepage}
% Ensure copyright on titlepage (article style) and chapter pages (book style)
\fancypagestyle{plain}{
  \fancyhf{}
  \fancyfoot[C]{{\footnotesize \copyright\ 2021, H. P. Langtangen. Made with \href{https://github.com/hplgit/doconce}{DocOnce}}}
%  \renewcommand{\footrulewidth}{0mm}
  \renewcommand{\headrulewidth}{0mm}
}
% Ensure copyright on titlepages with \thispagestyle{empty}
\fancypagestyle{empty}{
  \fancyhf{}
  \fancyfoot[C]{{\footnotesize \copyright\ 2021, H. P. Langtangen. Made with \href{https://github.com/hplgit/doconce}{DocOnce}}}
  \renewcommand{\footrulewidth}{0mm}
  \renewcommand{\headrulewidth}{0mm}
}

\pagestyle{fancy}


\usepackage[framemethod=TikZ]{mdframed}

% --- begin definitions of admonition environments ---

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "notice" admon
\colorlet{mdfbox_notice_background}{darkgray!20!white}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_notice_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=darkgray!40!white,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{notice_mdfboxmdframed}

\newenvironment{notice_mdfboxadmon}[1][]{
\begin{notice_mdfboxmdframed}[frametitle=#1]
}
{
\end{notice_mdfboxmdframed}
}

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "summary" admon
\colorlet{mdfbox_summary_background}{tucorange!20!white}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_summary_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=tucorange!40!white,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{summary_mdfboxmdframed}

\newenvironment{summary_mdfboxadmon}[1][]{
\begin{summary_mdfboxmdframed}[frametitle=#1]
}
{
\end{summary_mdfboxmdframed}
}

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "warning" admon
\colorlet{mdfbox_warning_background}{darkgreen!40!white}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_warning_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=darkgreen!80!white,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{warning_mdfboxmdframed}

\newenvironment{warning_mdfboxadmon}[1][]{
\begin{warning_mdfboxmdframed}[frametitle=#1]
}
{
\end{warning_mdfboxmdframed}
}

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "question" admon
\colorlet{mdfbox_question_background}{red!50!white}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_question_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=red!90!white,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{question_mdfboxmdframed}

\newenvironment{question_mdfboxadmon}[1][]{
\begin{question_mdfboxmdframed}[frametitle=#1]
}
{
\end{question_mdfboxmdframed}
}

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "block" admon
\colorlet{mdfbox_block_background}{darkgreen!40!white}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_block_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=darkgreen!80!white,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{block_mdfboxmdframed}

\newenvironment{block_mdfboxadmon}[1][]{
\begin{block_mdfboxmdframed}[frametitle=#1]
}
{
\end{block_mdfboxmdframed}
}

% --- end of definitions of admonition environments ---

% prevent orhpans and widows
\clubpenalty = 10000
\widowpenalty = 10000

% --- end of standard preamble for documents ---


% insert custom LaTeX commands...

\raggedbottom
\makeindex
\usepackage[totoc]{idxlayout}   % for index in the toc
\usepackage[nottoc]{tocbibind}  % for references/bibliography in the toc

%-------------------- end preamble ----------------------

\begin{document}

% matching end for #ifdef PREAMBLE
% #endif

\newcommand{\exercisesection}[1]{\subsection*{#1}}

\input{newcommands_bfmath}
\input{newcommands_replace}

% ------------------- main content ----------------------



% ----------------- title -------------------------

\thispagestyle{empty}

\begin{center}
{\LARGE\bf
\begin{spacing}{1.25}
Testing admons
\end{spacing}
}
\end{center}

% ----------------- author(s) -------------------------

\begin{center}
{\bf H. P. Langtangen${}^{}$} \\ [0mm]
\end{center}

\begin{center}
% List of all institutions:
\end{center}
    
% ----------------- end author(s) -------------------------

% --- begin date ---
\begin{center}
Jan 32, 2100
\end{center}
% --- end date ---

\vspace{1cm}


% !split
\section{Introduction}
First some ordinary text to compare font sizes in admonitions
and the surrounding text.


\subsection{Code}

Need some code outside admons for color and font comparisons:

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
def some_code(x):
    return sin(x)*exp(1-x)
\end{lstlisting}

And some plain text verbatim:

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
x=1.0 y=0.9 z=0.4
x=1.1 y=0.3 z=0.1
\end{lstlisting}

\subsection{Quotes and boxes}

Here is a plain quote environment.


\begin{quote}
Sayre's law states that
``in any dispute the intensity of feeling is inversely
proportional to the value of the issues at stake.'' \\
By way of corollary, it adds: \\
``That is why academic politics are so bitter.'' \\
\emph{Source}: \href{{https://en.wikipedia.org/wiki/Sayre's_law}}{wikipedia}
\end{quote}


Does quotes with title also work? No...cannot work in {\LaTeX} and HTML
and then it does not make sense to support it.


A plain \emph{box} is sometimes useful. Let's show it here for comparison
with admons (especially the block admon has much in common with a box).
The box is more aimed at framing a law or an equation.

First a simple block with text, an equation, and a list:


\begin{center}
\begin{Sbox}
\begin{minipage}{0.85\linewidth}
A generic equation

\[ f(x) = 0 \]
must be solved by a numerical method, such as

\begin{itemize}
 \item Newton's method

 \item The Bisection method

 \item Fixed-point (Picard) iteration by rewriting $f(x)=x - g(x)$

 \item The Secant method
\end{itemize}

\noindent
\end{minipage}
\end{Sbox}
\fbox{\TheSbox}
\end{center}
Now test a box with equation only (note that this line continues the
box, it is not a new paragraph):


\begin{center}
\begin{Sbox}
\begin{minipage}{0.85\linewidth}
\begin{equation} f(x) = \sin(x)e^{1-x} \end{equation}
\end{minipage}
\end{Sbox}
\fbox{\TheSbox}
\end{center}

\paragraph{Hint.}
Newton's method requires a good start vector to converge fast.



Let's begin a new paragraph and show a box with code only:


\begin{center}
\begin{Sbox}
\begin{minipage}{0.85\linewidth}
\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
def some_code(x):
    return sin(x)*exp(1-x)
\end{lstlisting}
\end{minipage}
\end{Sbox}
\fbox{\TheSbox}
\end{center}



\subsection{Admonitions}

Let us start with a plain warning environment.


\begin{warning_mdfboxadmon}[Warning.]
And here is a warning about something to pay attention to. We
test how the heading behave and add quite some extra texts
in comparison with the other admons.

\begin{itemize}
  \item and a list

  \item with items
\end{itemize}

\noindent
We continue with more text to see how that affects the layout.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
\end{warning_mdfboxadmon} % title: Warning.



Test warning with title:


\begin{warning_mdfboxadmon}[{\large Title ending with math $\sqrt{2}\approx 1.4$}.]
{\large And here comes some text with bad news in larger font.

Also some code:

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
def f(x):
    return x
\end{lstlisting}
And a complete program

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
print("Hello, World!")
\end{lstlisting}
\par}
\end{warning_mdfboxadmon} % title: {\large Title ending with math $\sqrt{2}\approx 1.4$}.



Test warning with large title with math:


\begin{warning_mdfboxadmon}[{\large Watch out for $\nabla\cdot\bm{u}=0$ equations}.]
{\large Divergence freedom is often problematic from a numerical point
of view.
\par}
\end{warning_mdfboxadmon} % title: {\large Watch out for $\nabla\cdot\bm{u}=0$ equations}.



Then we test a block, which is guaranteed to never have any admon icon.


\begin{block_mdfboxadmon}[Block with title.]
\vspace{0.5mm}\par\noindent
{\footnotesize Here is a block of text with title. It is typeset
\emph{without any icon} and is useful when you want some admons with icon
and some without. With the small font size, as used here, one can have
more comment-style text or text that really goes deeper or talks
about fun facts that are not strictly necessary for the main flow
of understanding.
\par}
\end{block_mdfboxadmon} % title: Block with title.





\begin{block_mdfboxadmon}[]
Here is a block of text with no title. As above, it is typeset without any icon
and is useful when you want some admons with icon and some without.
\end{block_mdfboxadmon} % title: 



% Note that the final ! does not appear in Sphinx and reST since
% those formats automatically add : to the admonition title.


\begin{notice_mdfboxadmon}[Note eventually!]
Ah, we are soon close to the end (with illegal font size specification!).
But first a bit of math where we define $\theta$ and $\bm{r}$:

\begin{align*}
\theta &= q^2,\\
\bm{r} &= \varrho\bm{i}
\end{align*}
\end{notice_mdfboxadmon} % title: Note eventually!



% Test one word with a number


\begin{notice_mdfboxadmon}[Point1.]
Ah, we are soon close to the end.
\end{notice_mdfboxadmon} % title: Point1.




\begin{question_mdfboxadmon}[Question.]
So, how many admonition environments does DocOnce support?
\end{question_mdfboxadmon} % title: Question.




\begin{question_mdfboxadmon}[Question.]
\begin{enumerate}
 \item Once more, how many admonition environments does DocOnce support?
\end{enumerate}

\noindent
\end{question_mdfboxadmon} % title: Question.




\begin{warning_mdfboxadmon}[Tip.]
It is of outmost important to

\begin{enumerate}
\item stay cool

\item read hints and tips carefully
\end{enumerate}

\noindent
Because here the thing is to do

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
import urllib

def grab(url, filename):
    urllib.urlretrieve(url, filename=filename)
\end{lstlisting}
\end{warning_mdfboxadmon} % title: Tip.



Next is a warning without a title ("none" implies no title).


\begin{warning_mdfboxadmon}[]
And here comes some text with bad news.
\end{warning_mdfboxadmon} % title: 



\subsection{Going deeper environments}

Here is a long notice environment with a custom title and much
text, math and code.


\begin{notice_mdfboxadmon}[Going deeper.]
We have some equations that should be preceded by much text, so the
task is to write and write. The number of words, and not the
meaning, is what counts here. We need desperately to fill up the
page in the hope that some admonitions will experience a page break,
which the {\LaTeX} environment should handle with ease.

Let us start with some equations:

\begin{align*}
\Ddt{u} &= 0
\\
\half &= \halfi\\
\half\x &= \normalvec
\end{align*}

The implementation of such complicated equations in computer
code is task that this "Going deeper" environment targets.

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
def Dudt(u):
    r = diff(u, t) + u*grad(u)
    return r

half = 0.5
x = 2*n
\end{lstlisting}
And some more text that can help going into the next page.
Longer computer code requires vertical space:

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
class Diff:
    def __init__(self, f, h=1E-5):
        self.f = f
        self.h = float(h)

class Forward1(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (f(x+h) - f(x))/h

class Backward1(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (f(x) - f(x-h))/h

class Central2(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (f(x+h) - f(x-h))/(2*h)

class Central4(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (4./3)*(f(x+h)   - f(x-h))  /(2*h) - \
               (1./3)*(f(x+2*h) - f(x-2*h))/(4*h)

class Central6(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (3./2) *(f(x+h)   - f(x-h))  /(2*h) - \
               (3./5) *(f(x+2*h) - f(x-2*h))/(4*h) + \
               (1./10)*(f(x+3*h) - f(x-3*h))/(6*h)

class Forward3(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (-(1./6)*f(x+2*h) + f(x+h) - 0.5*f(x) - \
                (1./3)*f(x-h))/h
\end{lstlisting}
And then we add a figure too.



\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=0.7\linewidth]{../doc/src/manual/fig/wave1D.pdf}}

\vspace{6mm}
\end{notice_mdfboxadmon} % title: Going deeper.




\subsection{The end}

A bit of text before the summary, which we now call "Concluding remarks,
for the novice",
just because we can.


\begin{summary_mdfboxadmon}[Concluding remarks for the novice.]
We can summarize the most important things with admons: they have
a different typesetting, and they may have a symbol.
Titles should be optional.
\end{summary_mdfboxadmon} % title: Concluding remarks for the novice.



\paragraph{Remark.}
The \texttt{remarks} and \texttt{hint} environments are not allowed outside
exercises (and problems and projects too).

% ------------------- end of main content ---------------

% #ifdef PREAMBLE
\end{document}
% #endif


************** File: admon_graybox2.tex *****************
%%
%% Automatically generated file from DocOnce source
%% (https://github.com/hplgit/doconce/)
%%

% #define PREAMBLE

% #ifdef PREAMBLE
%-------------------- begin preamble ----------------------

\documentclass[%
oneside,                 % oneside: electronic viewing, twoside: printing
final,                   % draft: marks overfull hboxes, figures with paths
10pt]{article}

\listfiles               %  print all files needed to compile this document

\usepackage{relsize,makeidx,color,setspace,amsmath,amsfonts,amssymb}
\usepackage[table]{xcolor}
\usepackage{bm,ltablex,microtype}

\usepackage[pdftex]{graphicx}

\usepackage{fancybox}  % make sure fancybox is loaded before fancyvrb
%\setlength{\fboxsep}{8pt}  % may clash with need in pre/cod envirs

% Packages for typesetting blocks of computer code
\usepackage{fancyvrb,framed,moreverb}

% Define colors
\definecolor{orange}{cmyk}{0,0.4,0.8,0.2}
\definecolor{tucorange}{rgb}{1.0,0.64,0}
\definecolor{darkorange}{rgb}{.71,0.21,0.01}
\definecolor{darkgreen}{rgb}{.12,.54,.11}
\definecolor{myteal}{rgb}{.26, .44, .56}
\definecolor{gray}{gray}{0.45}
\definecolor{mediumgray}{gray}{.8}
\definecolor{lightgray}{gray}{.95}
\definecolor{brown}{rgb}{0.54,0.27,0.07}
\definecolor{purple}{rgb}{0.5,0.0,0.5}
\definecolor{darkgray}{gray}{0.25}
\definecolor{darkblue}{rgb}{0,0.08,0.45}
\definecolor{darkblue2}{rgb}{0,0,0.8}
\definecolor{lightred}{rgb}{1.0,0.39,0.28}
\definecolor{lightgreen}{rgb}{0.48,0.99,0.0}
\definecolor{lightblue}{rgb}{0.53,0.81,0.92}
\definecolor{lightblue2}{rgb}{0.3,0.3,1.0}
\definecolor{lightpurple}{rgb}{0.87,0.63,0.87}
\definecolor{lightcyan}{rgb}{0.5,1.0,0.83}

\colorlet{comment_green}{green!50!black}
\colorlet{string_red}{red!60!black}
\colorlet{keyword_pink}{magenta!70!black}
\colorlet{indendifier_green}{green!70!white}

% Backgrounds for code
\definecolor{cbg_gray}{rgb}{.95, .95, .95}
\definecolor{bar_gray}{rgb}{.92, .92, .92}

\definecolor{cbg_yellowgray}{rgb}{.95, .95, .85}
\definecolor{bar_yellowgray}{rgb}{.95, .95, .65}

\colorlet{cbg_yellow2}{yellow!10}
\colorlet{bar_yellow2}{yellow!20}

\definecolor{cbg_yellow1}{rgb}{.98, .98, 0.8}
\definecolor{bar_yellow1}{rgb}{.98, .98, 0.4}

\definecolor{cbg_red1}{rgb}{1, 0.85, 0.85}
\definecolor{bar_red1}{rgb}{1, 0.75, 0.85}

\definecolor{cbg_blue1}{rgb}{0.87843, 0.95686, 1.0}
\definecolor{bar_blue1}{rgb}{0.7,     0.95686, 1}

\usepackage{listingsutf8}

% Common lstlisting parameters

\usepackage{calc}
\newlength{\lstboxwidth}  % width of lst box
\newlength{\framethickness}
\setlength{\framethickness}{0.5mm}
% for frame=trbl and a framerule that has significant size, set
% xleftmargin=5mm and xrightmargin=5mm.

\lstset{
  basicstyle=\small \ttfamily,
  breaklines=false,          % break/wrap lines
  breakatwhitespace=true,    % let linebreaks happen at whitespace
  breakindent=40pt,
  tab=,
  tabsize=4,                 % tab means 4 spaces
  %belowskip=\smallskipamount,  % space between code and text below
  xleftmargin=2mm,           % indentation of code frame
  xrightmargin=0mm,
  framexleftmargin=2mm,      % add frame space to the left of the code box
  %numbers=left,             % put line numbers on the left
  %stepnumber=2,             % stepnumber=1 numbers each line, =n every n lines
  framerule=\framethickness, % thickness of frame
  aboveskip=2ex,             % vertical space above code frame
  showstringspaces=false,    % show spaces in strings with an underscore
  showspaces=false,          % show spaces with an underscore
  showtabs=false,
  keepspaces=true,
  columns=fullflexible,      % tighter character kerning, like verb
  escapeinside={(*@}{@*)},   % (*@ \pause @*) in slides and math in code blocks
  extendedchars=\true,       % allows non-ascii chars, does not work with utf-8
}

% Internally defined styles for lstlisting

\lstdefinestyle{simple}{
commentstyle={},
}

% end of custom lstdefinestyles

\usepackage[T1]{fontenc}
%\usepackage[latin1]{inputenc}
\usepackage{ucs}
\usepackage[utf8x]{inputenc}

\usepackage{lmodern}         % Latin Modern fonts derived from Computer Modern

% Hyperlinks in PDF:
\definecolor{linkcolor}{rgb}{0,0,0.4}
\usepackage{hyperref}
\hypersetup{
    breaklinks=true,
    colorlinks=true,
    linkcolor=linkcolor,
    urlcolor=linkcolor,
    citecolor=black,
    filecolor=black,
    %filecolor=blue,
    pdfmenubar=true,
    pdftoolbar=true,
    bookmarksdepth=3   % Uncomment (and tweak) for PDF bookmarks with more levels than the TOC
    }
%\hyperbaseurl{}   % hyperlinks are relative to this root

\setcounter{tocdepth}{2}  % levels in table of contents

% Tricks for having figures close to where they are defined:
% 1. define less restrictive rules for where to put figures
\setcounter{topnumber}{2}
\setcounter{bottomnumber}{2}
\setcounter{totalnumber}{4}
\renewcommand{\topfraction}{0.95}
\renewcommand{\bottomfraction}{0.95}
\renewcommand{\textfraction}{0}
\renewcommand{\floatpagefraction}{0.75}
% floatpagefraction must always be less than topfraction!
% 2. ensure all figures are flushed before next section
\usepackage[section]{placeins}
% 3. enable begin{figure}[H] (often leads to ugly pagebreaks)
%\usepackage{float}\restylefloat{figure}

% --- fancyhdr package for fancy headers ---
\usepackage{fancyhdr}
\fancyhf{} % sets both header and footer to nothing
\renewcommand{\headrulewidth}{0pt}
\fancyfoot[LE,RO]{\thepage}
% Ensure copyright on titlepage (article style) and chapter pages (book style)
\fancypagestyle{plain}{
  \fancyhf{}
  \fancyfoot[C]{{\footnotesize \copyright\ 2021, H. P. Langtangen. Made with \href{https://github.com/hplgit/doconce}{DocOnce}}}
%  \renewcommand{\footrulewidth}{0mm}
  \renewcommand{\headrulewidth}{0mm}
}
% Ensure copyright on titlepages with \thispagestyle{empty}
\fancypagestyle{empty}{
  \fancyhf{}
  \fancyfoot[C]{{\footnotesize \copyright\ 2021, H. P. Langtangen. Made with \href{https://github.com/hplgit/doconce}{DocOnce}}}
  \renewcommand{\footrulewidth}{0mm}
  \renewcommand{\headrulewidth}{0mm}
}

\pagestyle{fancy}


\usepackage{wrapfig,calc}
\usepackage[framemethod=TikZ]{mdframed}  % use latest version: https://github.com/marcodaniel/mdframed

% --- begin definitions of admonition environments ---

% Admonition style "graybox2" is a gray or colored box with a square
% frame, except for the summary admon which has horizontal rules only
% Note: this admonition type cannot handle verbatim text!
\definecolor{graybox2_warning_background}{rgb}{0.94,0.94,0.94}

% colored box of 80% width
\newcommand{\grayboxhrules}[1]{\begin{center}
\colorbox{graybox2_warning_background}{\rule{6pt}{0pt}
\begin{minipage}{0.8\linewidth}
\parbox[t]{0mm}{\rule[0pt]{0mm}{0.5\baselineskip}}\hrule
\vspace*{0.5\baselineskip}\noindent #1
\parbox[t]{0mm}{\rule[-0.5\baselineskip]{0mm}%
{\baselineskip}}\hrule\vspace*{0.5\baselineskip}\end{minipage}
\rule{6pt}{0pt}}\end{center}}

% Fallback for verbatim content in \grayboxhrules
\newmdenv[
  backgroundcolor=graybox2_warning_background,
  skipabove=15pt,
  skipbelow=15pt,
  leftmargin=23,
  rightmargin=23,
  needspace=0pt,
]{graybox2mdframed}

\newenvironment{graybox2admon}[1][]{
\begin{graybox2mdframed}[frametitle=#1]
}
{
\end{graybox2mdframed}
}

% --- end of definitions of admonition environments ---

% prevent orhpans and widows
\clubpenalty = 10000
\widowpenalty = 10000

% --- end of standard preamble for documents ---


% insert custom LaTeX commands...

\raggedbottom
\makeindex
\usepackage[totoc]{idxlayout}   % for index in the toc
\usepackage[nottoc]{tocbibind}  % for references/bibliography in the toc

%-------------------- end preamble ----------------------

\begin{document}

% matching end for #ifdef PREAMBLE
% #endif

\newcommand{\exercisesection}[1]{\subsection*{#1}}

\input{newcommands_bfmath}
\input{newcommands_replace}

% ------------------- main content ----------------------



% ----------------- title -------------------------

\thispagestyle{empty}

\begin{center}
{\LARGE\bf
\begin{spacing}{1.25}
Testing admons
\end{spacing}
}
\end{center}

% ----------------- author(s) -------------------------

\begin{center}
{\bf H. P. Langtangen${}^{}$} \\ [0mm]
\end{center}

\begin{center}
% List of all institutions:
\end{center}
    
% ----------------- end author(s) -------------------------

% --- begin date ---
\begin{center}
Jan 32, 2100
\end{center}
% --- end date ---

\vspace{1cm}


% !split
\section{Introduction}
First some ordinary text to compare font sizes in admonitions
and the surrounding text.


\subsection{Code}

Need some code outside admons for color and font comparisons:

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
def some_code(x):
    return sin(x)*exp(1-x)
\end{lstlisting}

And some plain text verbatim:

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
x=1.0 y=0.9 z=0.4
x=1.1 y=0.3 z=0.1
\end{lstlisting}

\subsection{Quotes and boxes}

Here is a plain quote environment.


\begin{quote}
Sayre's law states that
``in any dispute the intensity of feeling is inversely
proportional to the value of the issues at stake.'' \\
By way of corollary, it adds: \\
``That is why academic politics are so bitter.'' \\
\emph{Source}: \href{{https://en.wikipedia.org/wiki/Sayre's_law}}{wikipedia}
\end{quote}


Does quotes with title also work? No...cannot work in {\LaTeX} and HTML
and then it does not make sense to support it.


A plain \emph{box} is sometimes useful. Let's show it here for comparison
with admons (especially the block admon has much in common with a box).
The box is more aimed at framing a law or an equation.

First a simple block with text, an equation, and a list:


\begin{center}
\begin{Sbox}
\begin{minipage}{0.85\linewidth}
A generic equation

\[ f(x) = 0 \]
must be solved by a numerical method, such as

\begin{itemize}
 \item Newton's method

 \item The Bisection method

 \item Fixed-point (Picard) iteration by rewriting $f(x)=x - g(x)$

 \item The Secant method
\end{itemize}

\noindent
\end{minipage}
\end{Sbox}
\fbox{\TheSbox}
\end{center}
Now test a box with equation only (note that this line continues the
box, it is not a new paragraph):


\begin{center}
\begin{Sbox}
\begin{minipage}{0.85\linewidth}
\begin{equation} f(x) = \sin(x)e^{1-x} \end{equation}
\end{minipage}
\end{Sbox}
\fbox{\TheSbox}
\end{center}

\paragraph{Hint.}
Newton's method requires a good start vector to converge fast.



Let's begin a new paragraph and show a box with code only:


\begin{center}
\begin{Sbox}
\begin{minipage}{0.85\linewidth}
\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
def some_code(x):
    return sin(x)*exp(1-x)
\end{lstlisting}
\end{minipage}
\end{Sbox}
\fbox{\TheSbox}
\end{center}



\subsection{Admonitions}

Let us start with a plain warning environment.



\begin{graybox2admon}[Warning.]
And here is a warning about something to pay attention to. We
test how the heading behave and add quite some extra texts
in comparison with the other admons.

\begin{itemize}
  \item and a list

  \item with items
\end{itemize}

\noindent
We continue with more text to see how that affects the layout.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
\end{graybox2admon}




Test warning with title:



\begin{graybox2admon}[{\large Title ending with math $\sqrt{2}\approx 1.4$}.]
{\large And here comes some text with bad news in larger font.

Also some code:

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
def f(x):
    return x
\end{lstlisting}
And a complete program

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
print("Hello, World!")
\end{lstlisting}
\par}
\end{graybox2admon}




Test warning with large title with math:



\begin{graybox2admon}[{\large Watch out for $\nabla\cdot\bm{u}=0$ equations}.]
{\large Divergence freedom is often problematic from a numerical point
of view.
\par}
\end{graybox2admon}




Then we test a block, which is guaranteed to never have any admon icon.



\begin{graybox2admon}[Block with title.]
\vspace{0.5mm}\par\noindent
{\footnotesize Here is a block of text with title. It is typeset
\emph{without any icon} and is useful when you want some admons with icon
and some without. With the small font size, as used here, one can have
more comment-style text or text that really goes deeper or talks
about fun facts that are not strictly necessary for the main flow
of understanding.
\par}
\end{graybox2admon}







\begin{graybox2admon}[]
Here is a block of text with no title. As above, it is typeset without any icon
and is useful when you want some admons with icon and some without.
\end{graybox2admon}




% Note that the final ! does not appear in Sphinx and reST since
% those formats automatically add : to the admonition title.



\begin{graybox2admon}[Note eventually!]
Ah, we are soon close to the end (with illegal font size specification!).
But first a bit of math where we define $\theta$ and $\bm{r}$:

\begin{align*}
\theta &= q^2,\\
\bm{r} &= \varrho\bm{i}
\end{align*}
\end{graybox2admon}




% Test one word with a number



\begin{graybox2admon}[Point1.]
Ah, we are soon close to the end.
\end{graybox2admon}






\begin{graybox2admon}[Question.]
So, how many admonition environments does DocOnce support?
\end{graybox2admon}






\begin{graybox2admon}[Question.]
\begin{enumerate}
 \item Once more, how many admonition environments does DocOnce support?
\end{enumerate}

\noindent
\end{graybox2admon}






\begin{graybox2admon}[Tip.]
It is of outmost important to

\begin{enumerate}
\item stay cool

\item read hints and tips carefully
\end{enumerate}

\noindent
Because here the thing is to do

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
import urllib

def grab(url, filename):
    urllib.urlretrieve(url, filename=filename)
\end{lstlisting}
\end{graybox2admon}




Next is a warning without a title ("none" implies no title).



\begin{graybox2admon}[]
And here comes some text with bad news.
\end{graybox2admon}




\subsection{Going deeper environments}

Here is a long notice environment with a custom title and much
text, math and code.



\begin{graybox2admon}[Going deeper.]
We have some equations that should be preceded by much text, so the
task is to write and write. The number of words, and not the
meaning, is what counts here. We need desperately to fill up the
page in the hope that some admonitions will experience a page break,
which the {\LaTeX} environment should handle with ease.

Let us start with some equations:

\begin{align*}
\Ddt{u} &= 0
\\
\half &= \halfi\\
\half\x &= \normalvec
\end{align*}

The implementation of such complicated equations in computer
code is task that this "Going deeper" environment targets.

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
def Dudt(u):
    r = diff(u, t) + u*grad(u)
    return r

half = 0.5
x = 2*n
\end{lstlisting}
And some more text that can help going into the next page.
Longer computer code requires vertical space:

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
class Diff:
    def __init__(self, f, h=1E-5):
        self.f = f
        self.h = float(h)

class Forward1(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (f(x+h) - f(x))/h

class Backward1(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (f(x) - f(x-h))/h

class Central2(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (f(x+h) - f(x-h))/(2*h)

class Central4(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (4./3)*(f(x+h)   - f(x-h))  /(2*h) - \
               (1./3)*(f(x+2*h) - f(x-2*h))/(4*h)

class Central6(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (3./2) *(f(x+h)   - f(x-h))  /(2*h) - \
               (3./5) *(f(x+2*h) - f(x-2*h))/(4*h) + \
               (1./10)*(f(x+3*h) - f(x-3*h))/(6*h)

class Forward3(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (-(1./6)*f(x+2*h) + f(x+h) - 0.5*f(x) - \
                (1./3)*f(x-h))/h
\end{lstlisting}
And then we add a figure too.



\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=0.7\linewidth]{../doc/src/manual/fig/wave1D.pdf}}

\vspace{6mm}
\end{graybox2admon}





\subsection{The end}

A bit of text before the summary, which we now call "Concluding remarks,
for the novice",
just because we can.


\grayboxhrules{
\textbf{Concluding remarks, for the novice:} We can summarize the most important things with admons: they have
a different typesetting, and they may have a symbol.
Titles should be optional.
}


\paragraph{Remark.}
The \texttt{remarks} and \texttt{hint} environments are not allowed outside
exercises (and problems and projects too).

% ------------------- end of main content ---------------

% #ifdef PREAMBLE
\end{document}
% #endif


************** File: admon_grayicon.tex *****************
%%
%% Automatically generated file from DocOnce source
%% (https://github.com/hplgit/doconce/)
%%

% #define PREAMBLE

% #ifdef PREAMBLE
%-------------------- begin preamble ----------------------

\documentclass[%
oneside,                 % oneside: electronic viewing, twoside: printing
final,                   % draft: marks overfull hboxes, figures with paths
10pt]{article}

\listfiles               %  print all files needed to compile this document

\usepackage{relsize,makeidx,color,setspace,amsmath,amsfonts,amssymb}
\usepackage[table]{xcolor}
\usepackage{bm,ltablex,microtype}

\usepackage[pdftex]{graphicx}

\usepackage{fancybox}  % make sure fancybox is loaded before fancyvrb
%\setlength{\fboxsep}{8pt}  % may clash with need in pre/cod envirs

% Packages for typesetting blocks of computer code
\usepackage{fancyvrb,framed,moreverb}

% Define colors
\definecolor{orange}{cmyk}{0,0.4,0.8,0.2}
\definecolor{tucorange}{rgb}{1.0,0.64,0}
\definecolor{darkorange}{rgb}{.71,0.21,0.01}
\definecolor{darkgreen}{rgb}{.12,.54,.11}
\definecolor{myteal}{rgb}{.26, .44, .56}
\definecolor{gray}{gray}{0.45}
\definecolor{mediumgray}{gray}{.8}
\definecolor{lightgray}{gray}{.95}
\definecolor{brown}{rgb}{0.54,0.27,0.07}
\definecolor{purple}{rgb}{0.5,0.0,0.5}
\definecolor{darkgray}{gray}{0.25}
\definecolor{darkblue}{rgb}{0,0.08,0.45}
\definecolor{darkblue2}{rgb}{0,0,0.8}
\definecolor{lightred}{rgb}{1.0,0.39,0.28}
\definecolor{lightgreen}{rgb}{0.48,0.99,0.0}
\definecolor{lightblue}{rgb}{0.53,0.81,0.92}
\definecolor{lightblue2}{rgb}{0.3,0.3,1.0}
\definecolor{lightpurple}{rgb}{0.87,0.63,0.87}
\definecolor{lightcyan}{rgb}{0.5,1.0,0.83}

\colorlet{comment_green}{green!50!black}
\colorlet{string_red}{red!60!black}
\colorlet{keyword_pink}{magenta!70!black}
\colorlet{indendifier_green}{green!70!white}

% Backgrounds for code
\definecolor{cbg_gray}{rgb}{.95, .95, .95}
\definecolor{bar_gray}{rgb}{.92, .92, .92}

\definecolor{cbg_yellowgray}{rgb}{.95, .95, .85}
\definecolor{bar_yellowgray}{rgb}{.95, .95, .65}

\colorlet{cbg_yellow2}{yellow!10}
\colorlet{bar_yellow2}{yellow!20}

\definecolor{cbg_yellow1}{rgb}{.98, .98, 0.8}
\definecolor{bar_yellow1}{rgb}{.98, .98, 0.4}

\definecolor{cbg_red1}{rgb}{1, 0.85, 0.85}
\definecolor{bar_red1}{rgb}{1, 0.75, 0.85}

\definecolor{cbg_blue1}{rgb}{0.87843, 0.95686, 1.0}
\definecolor{bar_blue1}{rgb}{0.7,     0.95686, 1}

\usepackage{listingsutf8}

% Common lstlisting parameters

\usepackage{calc}
\newlength{\lstboxwidth}  % width of lst box
\newlength{\framethickness}
\setlength{\framethickness}{0.5mm}
% for frame=trbl and a framerule that has significant size, set
% xleftmargin=5mm and xrightmargin=5mm.

\lstset{
  basicstyle=\small \ttfamily,
  breaklines=false,          % break/wrap lines
  breakatwhitespace=true,    % let linebreaks happen at whitespace
  breakindent=40pt,
  tab=,
  tabsize=4,                 % tab means 4 spaces
  %belowskip=\smallskipamount,  % space between code and text below
  xleftmargin=2mm,           % indentation of code frame
  xrightmargin=0mm,
  framexleftmargin=2mm,      % add frame space to the left of the code box
  %numbers=left,             % put line numbers on the left
  %stepnumber=2,             % stepnumber=1 numbers each line, =n every n lines
  framerule=\framethickness, % thickness of frame
  aboveskip=2ex,             % vertical space above code frame
  showstringspaces=false,    % show spaces in strings with an underscore
  showspaces=false,          % show spaces with an underscore
  showtabs=false,
  keepspaces=true,
  columns=fullflexible,      % tighter character kerning, like verb
  escapeinside={(*@}{@*)},   % (*@ \pause @*) in slides and math in code blocks
  extendedchars=\true,       % allows non-ascii chars, does not work with utf-8
}

% Internally defined styles for lstlisting

\lstdefinestyle{simple}{
commentstyle={},
}

% end of custom lstdefinestyles

\usepackage[T1]{fontenc}
%\usepackage[latin1]{inputenc}
\usepackage{ucs}
\usepackage[utf8x]{inputenc}

\usepackage{lmodern}         % Latin Modern fonts derived from Computer Modern

% Hyperlinks in PDF:
\definecolor{linkcolor}{rgb}{0,0,0.4}
\usepackage{hyperref}
\hypersetup{
    breaklinks=true,
    colorlinks=true,
    linkcolor=linkcolor,
    urlcolor=linkcolor,
    citecolor=black,
    filecolor=black,
    %filecolor=blue,
    pdfmenubar=true,
    pdftoolbar=true,
    bookmarksdepth=3   % Uncomment (and tweak) for PDF bookmarks with more levels than the TOC
    }
%\hyperbaseurl{}   % hyperlinks are relative to this root

\setcounter{tocdepth}{2}  % levels in table of contents

% Tricks for having figures close to where they are defined:
% 1. define less restrictive rules for where to put figures
\setcounter{topnumber}{2}
\setcounter{bottomnumber}{2}
\setcounter{totalnumber}{4}
\renewcommand{\topfraction}{0.95}
\renewcommand{\bottomfraction}{0.95}
\renewcommand{\textfraction}{0}
\renewcommand{\floatpagefraction}{0.75}
% floatpagefraction must always be less than topfraction!
% 2. ensure all figures are flushed before next section
\usepackage[section]{placeins}
% 3. enable begin{figure}[H] (often leads to ugly pagebreaks)
%\usepackage{float}\restylefloat{figure}

% --- fancyhdr package for fancy headers ---
\usepackage{fancyhdr}
\fancyhf{} % sets both header and footer to nothing
\renewcommand{\headrulewidth}{0pt}
\fancyfoot[LE,RO]{\thepage}
% Ensure copyright on titlepage (article style) and chapter pages (book style)
\fancypagestyle{plain}{
  \fancyhf{}
  \fancyfoot[C]{{\footnotesize \copyright\ 2021, H. P. Langtangen. Made with \href{https://github.com/hplgit/doconce}{DocOnce}}}
%  \renewcommand{\footrulewidth}{0mm}
  \renewcommand{\headrulewidth}{0mm}
}
% Ensure copyright on titlepages with \thispagestyle{empty}
\fancypagestyle{empty}{
  \fancyhf{}
  \fancyfoot[C]{{\footnotesize \copyright\ 2021, H. P. Langtangen. Made with \href{https://github.com/hplgit/doconce}{DocOnce}}}
  \renewcommand{\footrulewidth}{0mm}
  \renewcommand{\headrulewidth}{0mm}
}

\pagestyle{fancy}


\usepackage{framed,wrapfig}

% --- begin definitions of admonition environments ---

% Admonition style "grayicon" has colored background, no frame, and an icon
% Admon "notice"
\colorlet{grayicon_notice_background}{gray!20}
% \fboxsep sets the space between the text and the box
\newenvironment{noticeshaded}
{\def\FrameCommand{\fboxsep=3mm\colorbox{grayicon_notice_background}}
 \MakeFramed {\advance\hsize-\width \FrameRestore}}{\endMakeFramed}

\newenvironment{notice_grayiconadmon}[1][Notice]{
\begin{noticeshaded}
\noindent
\begin{wrapfigure}{l}{0.07\textwidth}
\vspace{-13pt}
\includegraphics[width=0.07\textwidth]{latex_figs/small_gray_notice}
\end{wrapfigure} \textbf{#1}\par
\nobreak\noindent\ignorespaces
}
{
\end{noticeshaded}
}

% Admonition style "grayicon" has colored background, no frame, and an icon
% Admon "summary"
\colorlet{grayicon_summary_background}{gray!20}
% \fboxsep sets the space between the text and the box
\newenvironment{summaryshaded}
{\def\FrameCommand{\fboxsep=3mm\colorbox{grayicon_summary_background}}
 \MakeFramed {\advance\hsize-\width \FrameRestore}}{\endMakeFramed}

\newenvironment{summary_grayiconadmon}[1][Summary]{
\begin{summaryshaded}
\noindent
\begin{wrapfigure}{l}{0.07\textwidth}
\vspace{-13pt}
\includegraphics[width=0.07\textwidth]{latex_figs/small_gray_summary}
\end{wrapfigure} \textbf{#1}\par
\nobreak\noindent\ignorespaces
}
{
\end{summaryshaded}
}

% Admonition style "grayicon" has colored background, no frame, and an icon
% Admon "warning"
\colorlet{grayicon_warning_background}{gray!20}
% \fboxsep sets the space between the text and the box
\newenvironment{warningshaded}
{\def\FrameCommand{\fboxsep=3mm\colorbox{grayicon_warning_background}}
 \MakeFramed {\advance\hsize-\width \FrameRestore}}{\endMakeFramed}

\newenvironment{warning_grayiconadmon}[1][Warning]{
\begin{warningshaded}
\noindent
\begin{wrapfigure}{l}{0.07\textwidth}
\vspace{-13pt}
\includegraphics[width=0.07\textwidth]{latex_figs/small_gray_warning}
\end{wrapfigure} \textbf{#1}\par
\nobreak\noindent\ignorespaces
}
{
\end{warningshaded}
}

% Admonition style "grayicon" has colored background, no frame, and an icon
% Admon "question"
\colorlet{grayicon_question_background}{gray!20}
% \fboxsep sets the space between the text and the box
\newenvironment{questionshaded}
{\def\FrameCommand{\fboxsep=3mm\colorbox{grayicon_question_background}}
 \MakeFramed {\advance\hsize-\width \FrameRestore}}{\endMakeFramed}

\newenvironment{question_grayiconadmon}[1][Question]{
\begin{questionshaded}
\noindent
\begin{wrapfigure}{l}{0.07\textwidth}
\vspace{-13pt}
\includegraphics[width=0.07\textwidth]{latex_figs/small_gray_question2}
\end{wrapfigure} \textbf{#1}\par
\nobreak\noindent\ignorespaces
}
{
\end{questionshaded}
}

% Admonition style "grayicon" has colored background, no frame, and an icon
% Admon "block"
\colorlet{grayicon_block_background}{gray!20}
% \fboxsep sets the space between the text and the box
\newenvironment{blockshaded}
{\def\FrameCommand{\fboxsep=3mm\colorbox{grayicon_block_background}}
 \MakeFramed {\advance\hsize-\width \FrameRestore}}{\endMakeFramed}

\newenvironment{block_grayiconadmon}[1][Block]{
\begin{blockshaded}
\noindent
 \textbf{#1}\par
\nobreak\noindent\ignorespaces
}
{
\end{blockshaded}
}

% --- end of definitions of admonition environments ---

% prevent orhpans and widows
\clubpenalty = 10000
\widowpenalty = 10000

% --- end of standard preamble for documents ---


% insert custom LaTeX commands...

\raggedbottom
\makeindex
\usepackage[totoc]{idxlayout}   % for index in the toc
\usepackage[nottoc]{tocbibind}  % for references/bibliography in the toc

%-------------------- end preamble ----------------------

\begin{document}

% matching end for #ifdef PREAMBLE
% #endif

\newcommand{\exercisesection}[1]{\subsection*{#1}}

\input{newcommands_bfmath}
\input{newcommands_replace}

% ------------------- main content ----------------------



% ----------------- title -------------------------

\thispagestyle{empty}

\begin{center}
{\LARGE\bf
\begin{spacing}{1.25}
Testing admons
\end{spacing}
}
\end{center}

% ----------------- author(s) -------------------------

\begin{center}
{\bf H. P. Langtangen${}^{}$} \\ [0mm]
\end{center}

\begin{center}
% List of all institutions:
\end{center}
    
% ----------------- end author(s) -------------------------

% --- begin date ---
\begin{center}
Jan 32, 2100
\end{center}
% --- end date ---

\vspace{1cm}


% !split
\section{Introduction}
First some ordinary text to compare font sizes in admonitions
and the surrounding text.


\subsection{Code}

Need some code outside admons for color and font comparisons:

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
def some_code(x):
    return sin(x)*exp(1-x)
\end{lstlisting}

And some plain text verbatim:

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
x=1.0 y=0.9 z=0.4
x=1.1 y=0.3 z=0.1
\end{lstlisting}

\subsection{Quotes and boxes}

Here is a plain quote environment.


\begin{quote}
Sayre's law states that
``in any dispute the intensity of feeling is inversely
proportional to the value of the issues at stake.'' \\
By way of corollary, it adds: \\
``That is why academic politics are so bitter.'' \\
\emph{Source}: \href{{https://en.wikipedia.org/wiki/Sayre's_law}}{wikipedia}
\end{quote}


Does quotes with title also work? No...cannot work in {\LaTeX} and HTML
and then it does not make sense to support it.


A plain \emph{box} is sometimes useful. Let's show it here for comparison
with admons (especially the block admon has much in common with a box).
The box is more aimed at framing a law or an equation.

First a simple block with text, an equation, and a list:


\begin{center}
\begin{Sbox}
\begin{minipage}{0.85\linewidth}
A generic equation

\[ f(x) = 0 \]
must be solved by a numerical method, such as

\begin{itemize}
 \item Newton's method

 \item The Bisection method

 \item Fixed-point (Picard) iteration by rewriting $f(x)=x - g(x)$

 \item The Secant method
\end{itemize}

\noindent
\end{minipage}
\end{Sbox}
\fbox{\TheSbox}
\end{center}
Now test a box with equation only (note that this line continues the
box, it is not a new paragraph):


\begin{center}
\begin{Sbox}
\begin{minipage}{0.85\linewidth}
\begin{equation} f(x) = \sin(x)e^{1-x} \end{equation}
\end{minipage}
\end{Sbox}
\fbox{\TheSbox}
\end{center}

\paragraph{Hint.}
Newton's method requires a good start vector to converge fast.



Let's begin a new paragraph and show a box with code only:


\begin{center}
\begin{Sbox}
\begin{minipage}{0.85\linewidth}
\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
def some_code(x):
    return sin(x)*exp(1-x)
\end{lstlisting}
\end{minipage}
\end{Sbox}
\fbox{\TheSbox}
\end{center}



\subsection{Admonitions}

Let us start with a plain warning environment.


\begin{warning_grayiconadmon}[Warning]
And here is a warning about something to pay attention to. We
test how the heading behave and add quite some extra texts
in comparison with the other admons.

\begin{itemize}
  \item and a list

  \item with items
\end{itemize}

\noindent
We continue with more text to see how that affects the layout.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
\end{warning_grayiconadmon} % title: Warning



Test warning with title:


\begin{warning_grayiconadmon}[{\large Title ending with math $\sqrt{2}\approx 1.4$}]
{\large And here comes some text with bad news in larger font.

Also some code:

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
def f(x):
    return x
\end{lstlisting}
And a complete program

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
print("Hello, World!")
\end{lstlisting}
\par}
\end{warning_grayiconadmon} % title: {\large Title ending with math $\sqrt{2}\approx 1.4$}



Test warning with large title with math:


\begin{warning_grayiconadmon}[{\large Watch out for $\nabla\cdot\bm{u}=0$ equations}]
{\large Divergence freedom is often problematic from a numerical point
of view.
\par}
\end{warning_grayiconadmon} % title: {\large Watch out for $\nabla\cdot\bm{u}=0$ equations}



Then we test a block, which is guaranteed to never have any admon icon.


\begin{block_grayiconadmon}[Block with title]
\vspace{-2.5mm}\par\noindent
{\footnotesize Here is a block of text with title. It is typeset
\emph{without any icon} and is useful when you want some admons with icon
and some without. With the small font size, as used here, one can have
more comment-style text or text that really goes deeper or talks
about fun facts that are not strictly necessary for the main flow
of understanding.
\par}
\end{block_grayiconadmon} % title: Block with title





\begin{block_grayiconadmon}[]
Here is a block of text with no title. As above, it is typeset without any icon
and is useful when you want some admons with icon and some without.
\end{block_grayiconadmon} % title: 



% Note that the final ! does not appear in Sphinx and reST since
% those formats automatically add : to the admonition title.


\begin{notice_grayiconadmon}[Note, eventually!]
Ah, we are soon close to the end (with illegal font size specification!).
But first a bit of math where we define $\theta$ and $\bm{r}$:

\begin{align*}
\theta &= q^2,\\
\bm{r} &= \varrho\bm{i}
\end{align*}
\end{notice_grayiconadmon} % title: Note, eventually!



% Test one word with a number


\begin{notice_grayiconadmon}[Point1]
Ah, we are soon close to the end.
\end{notice_grayiconadmon} % title: Point1




\begin{question_grayiconadmon}[Question]
So, how many admonition environments does DocOnce support?
\end{question_grayiconadmon} % title: Question




\begin{question_grayiconadmon}[Question]
\begin{enumerate}
 \item Once more, how many admonition environments does DocOnce support?
\end{enumerate}

\noindent
\end{question_grayiconadmon} % title: Question




\begin{warning_grayiconadmon}[Tip]
It is of outmost important to

\begin{enumerate}
\item stay cool

\item read hints and tips carefully
\end{enumerate}

\noindent
Because here the thing is to do

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
import urllib

def grab(url, filename):
    urllib.urlretrieve(url, filename=filename)
\end{lstlisting}
\end{warning_grayiconadmon} % title: Tip



Next is a warning without a title ("none" implies no title).


\begin{warning_grayiconadmon}[]
And here comes some text with bad news.
\end{warning_grayiconadmon} % title: 



\subsection{Going deeper environments}

Here is a long notice environment with a custom title and much
text, math and code.


\begin{notice_grayiconadmon}[Going deeper.]
We have some equations that should be preceded by much text, so the
task is to write and write. The number of words, and not the
meaning, is what counts here. We need desperately to fill up the
page in the hope that some admonitions will experience a page break,
which the {\LaTeX} environment should handle with ease.

Let us start with some equations:

\begin{align*}
\Ddt{u} &= 0
\\
\half &= \halfi\\
\half\x &= \normalvec
\end{align*}

The implementation of such complicated equations in computer
code is task that this "Going deeper" environment targets.

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
def Dudt(u):
    r = diff(u, t) + u*grad(u)
    return r

half = 0.5
x = 2*n
\end{lstlisting}
And some more text that can help going into the next page.
Longer computer code requires vertical space:

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
class Diff:
    def __init__(self, f, h=1E-5):
        self.f = f
        self.h = float(h)

class Forward1(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (f(x+h) - f(x))/h

class Backward1(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (f(x) - f(x-h))/h

class Central2(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (f(x+h) - f(x-h))/(2*h)

class Central4(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (4./3)*(f(x+h)   - f(x-h))  /(2*h) - \
               (1./3)*(f(x+2*h) - f(x-2*h))/(4*h)

class Central6(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (3./2) *(f(x+h)   - f(x-h))  /(2*h) - \
               (3./5) *(f(x+2*h) - f(x-2*h))/(4*h) + \
               (1./10)*(f(x+3*h) - f(x-3*h))/(6*h)

class Forward3(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (-(1./6)*f(x+2*h) + f(x+h) - 0.5*f(x) - \
                (1./3)*f(x-h))/h
\end{lstlisting}
And then we add a figure too.



\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=0.7\linewidth]{../doc/src/manual/fig/wave1D.pdf}}

\vspace{6mm}
\end{notice_grayiconadmon} % title: Going deeper.




\subsection{The end}

A bit of text before the summary, which we now call "Concluding remarks,
for the novice",
just because we can.


\begin{summary_grayiconadmon}[Concluding remarks, for the novice]
We can summarize the most important things with admons: they have
a different typesetting, and they may have a symbol.
Titles should be optional.
\end{summary_grayiconadmon} % title: Concluding remarks, for the novice



\paragraph{Remark.}
The \texttt{remarks} and \texttt{hint} environments are not allowed outside
exercises (and problems and projects too).

% ------------------- end of main content ---------------

% #ifdef PREAMBLE
\end{document}
% #endif


************** File: admon_paragraph-footnotesize.tex *****************
%%
%% Automatically generated file from DocOnce source
%% (https://github.com/hplgit/doconce/)
%%

% #define PREAMBLE

% #ifdef PREAMBLE
%-------------------- begin preamble ----------------------

\documentclass[%
oneside,                 % oneside: electronic viewing, twoside: printing
final,                   % draft: marks overfull hboxes, figures with paths
10pt]{article}

\listfiles               %  print all files needed to compile this document

\usepackage{relsize,makeidx,color,setspace,amsmath,amsfonts,amssymb}
\usepackage[table]{xcolor}
\usepackage{bm,ltablex,microtype}

\usepackage[pdftex]{graphicx}

\usepackage{fancybox}  % make sure fancybox is loaded before fancyvrb
%\setlength{\fboxsep}{8pt}  % may clash with need in pre/cod envirs

% Packages for typesetting blocks of computer code
\usepackage{fancyvrb,framed,moreverb}

% Define colors
\definecolor{orange}{cmyk}{0,0.4,0.8,0.2}
\definecolor{tucorange}{rgb}{1.0,0.64,0}
\definecolor{darkorange}{rgb}{.71,0.21,0.01}
\definecolor{darkgreen}{rgb}{.12,.54,.11}
\definecolor{myteal}{rgb}{.26, .44, .56}
\definecolor{gray}{gray}{0.45}
\definecolor{mediumgray}{gray}{.8}
\definecolor{lightgray}{gray}{.95}
\definecolor{brown}{rgb}{0.54,0.27,0.07}
\definecolor{purple}{rgb}{0.5,0.0,0.5}
\definecolor{darkgray}{gray}{0.25}
\definecolor{darkblue}{rgb}{0,0.08,0.45}
\definecolor{darkblue2}{rgb}{0,0,0.8}
\definecolor{lightred}{rgb}{1.0,0.39,0.28}
\definecolor{lightgreen}{rgb}{0.48,0.99,0.0}
\definecolor{lightblue}{rgb}{0.53,0.81,0.92}
\definecolor{lightblue2}{rgb}{0.3,0.3,1.0}
\definecolor{lightpurple}{rgb}{0.87,0.63,0.87}
\definecolor{lightcyan}{rgb}{0.5,1.0,0.83}

\colorlet{comment_green}{green!50!black}
\colorlet{string_red}{red!60!black}
\colorlet{keyword_pink}{magenta!70!black}
\colorlet{indendifier_green}{green!70!white}

% Backgrounds for code
\definecolor{cbg_gray}{rgb}{.95, .95, .95}
\definecolor{bar_gray}{rgb}{.92, .92, .92}

\definecolor{cbg_yellowgray}{rgb}{.95, .95, .85}
\definecolor{bar_yellowgray}{rgb}{.95, .95, .65}

\colorlet{cbg_yellow2}{yellow!10}
\colorlet{bar_yellow2}{yellow!20}

\definecolor{cbg_yellow1}{rgb}{.98, .98, 0.8}
\definecolor{bar_yellow1}{rgb}{.98, .98, 0.4}

\definecolor{cbg_red1}{rgb}{1, 0.85, 0.85}
\definecolor{bar_red1}{rgb}{1, 0.75, 0.85}

\definecolor{cbg_blue1}{rgb}{0.87843, 0.95686, 1.0}
\definecolor{bar_blue1}{rgb}{0.7,     0.95686, 1}

\usepackage{listingsutf8}

% Common lstlisting parameters

\usepackage{calc}
\newlength{\lstboxwidth}  % width of lst box
\newlength{\framethickness}
\setlength{\framethickness}{0.5mm}
% for frame=trbl and a framerule that has significant size, set
% xleftmargin=5mm and xrightmargin=5mm.

\lstset{
  basicstyle=\small \ttfamily,
  breaklines=false,          % break/wrap lines
  breakatwhitespace=true,    % let linebreaks happen at whitespace
  breakindent=40pt,
  tab=,
  tabsize=4,                 % tab means 4 spaces
  %belowskip=\smallskipamount,  % space between code and text below
  xleftmargin=2mm,           % indentation of code frame
  xrightmargin=0mm,
  framexleftmargin=2mm,      % add frame space to the left of the code box
  %numbers=left,             % put line numbers on the left
  %stepnumber=2,             % stepnumber=1 numbers each line, =n every n lines
  framerule=\framethickness, % thickness of frame
  aboveskip=2ex,             % vertical space above code frame
  showstringspaces=false,    % show spaces in strings with an underscore
  showspaces=false,          % show spaces with an underscore
  showtabs=false,
  keepspaces=true,
  columns=fullflexible,      % tighter character kerning, like verb
  escapeinside={(*@}{@*)},   % (*@ \pause @*) in slides and math in code blocks
  extendedchars=\true,       % allows non-ascii chars, does not work with utf-8
}

% Internally defined styles for lstlisting

\lstdefinestyle{simple}{
commentstyle={},
}

% end of custom lstdefinestyles

\usepackage[T1]{fontenc}
%\usepackage[latin1]{inputenc}
\usepackage{ucs}
\usepackage[utf8x]{inputenc}

\usepackage{lmodern}         % Latin Modern fonts derived from Computer Modern

% Hyperlinks in PDF:
\definecolor{linkcolor}{rgb}{0,0,0.4}
\usepackage{hyperref}
\hypersetup{
    breaklinks=true,
    colorlinks=true,
    linkcolor=linkcolor,
    urlcolor=linkcolor,
    citecolor=black,
    filecolor=black,
    %filecolor=blue,
    pdfmenubar=true,
    pdftoolbar=true,
    bookmarksdepth=3   % Uncomment (and tweak) for PDF bookmarks with more levels than the TOC
    }
%\hyperbaseurl{}   % hyperlinks are relative to this root

\setcounter{tocdepth}{2}  % levels in table of contents

% Tricks for having figures close to where they are defined:
% 1. define less restrictive rules for where to put figures
\setcounter{topnumber}{2}
\setcounter{bottomnumber}{2}
\setcounter{totalnumber}{4}
\renewcommand{\topfraction}{0.95}
\renewcommand{\bottomfraction}{0.95}
\renewcommand{\textfraction}{0}
\renewcommand{\floatpagefraction}{0.75}
% floatpagefraction must always be less than topfraction!
% 2. ensure all figures are flushed before next section
\usepackage[section]{placeins}
% 3. enable begin{figure}[H] (often leads to ugly pagebreaks)
%\usepackage{float}\restylefloat{figure}

% --- fancyhdr package for fancy headers ---
\usepackage{fancyhdr}
\fancyhf{} % sets both header and footer to nothing
\renewcommand{\headrulewidth}{0pt}
\fancyfoot[LE,RO]{\thepage}
% Ensure copyright on titlepage (article style) and chapter pages (book style)
\fancypagestyle{plain}{
  \fancyhf{}
  \fancyfoot[C]{{\footnotesize \copyright\ 2021, H. P. Langtangen. Made with \href{https://github.com/hplgit/doconce}{DocOnce}}}
%  \renewcommand{\footrulewidth}{0mm}
  \renewcommand{\headrulewidth}{0mm}
}
% Ensure copyright on titlepages with \thispagestyle{empty}
\fancypagestyle{empty}{
  \fancyhf{}
  \fancyfoot[C]{{\footnotesize \copyright\ 2021, H. P. Langtangen. Made with \href{https://github.com/hplgit/doconce}{DocOnce}}}
  \renewcommand{\footrulewidth}{0mm}
  \renewcommand{\headrulewidth}{0mm}
}

\pagestyle{fancy}


\usepackage[framemethod=TikZ]{mdframed}

% --- begin definitions of admonition environments ---

% --- end of definitions of admonition environments ---

% prevent orhpans and widows
\clubpenalty = 10000
\widowpenalty = 10000

% --- end of standard preamble for documents ---


% insert custom LaTeX commands...

\raggedbottom
\makeindex
\usepackage[totoc]{idxlayout}   % for index in the toc
\usepackage[nottoc]{tocbibind}  % for references/bibliography in the toc

%-------------------- end preamble ----------------------

\begin{document}

% matching end for #ifdef PREAMBLE
% #endif

\newcommand{\exercisesection}[1]{\subsection*{#1}}

\input{newcommands_bfmath}
\input{newcommands_replace}

% ------------------- main content ----------------------



% ----------------- title -------------------------

\thispagestyle{empty}

\begin{center}
{\LARGE\bf
\begin{spacing}{1.25}
Testing admons
\end{spacing}
}
\end{center}

% ----------------- author(s) -------------------------

\begin{center}
{\bf H. P. Langtangen${}^{}$} \\ [0mm]
\end{center}

\begin{center}
% List of all institutions:
\end{center}
    
% ----------------- end author(s) -------------------------

% --- begin date ---
\begin{center}
Jan 32, 2100
\end{center}
% --- end date ---

\vspace{1cm}


% !split
\section{Introduction}
First some ordinary text to compare font sizes in admonitions
and the surrounding text.


\subsection{Code}

Need some code outside admons for color and font comparisons:

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
def some_code(x):
    return sin(x)*exp(1-x)
\end{lstlisting}

And some plain text verbatim:

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
x=1.0 y=0.9 z=0.4
x=1.1 y=0.3 z=0.1
\end{lstlisting}

\subsection{Quotes and boxes}

Here is a plain quote environment.


\begin{quote}
Sayre's law states that
``in any dispute the intensity of feeling is inversely
proportional to the value of the issues at stake.'' \\
By way of corollary, it adds: \\
``That is why academic politics are so bitter.'' \\
\emph{Source}: \href{{https://en.wikipedia.org/wiki/Sayre's_law}}{wikipedia}
\end{quote}


Does quotes with title also work? No...cannot work in {\LaTeX} and HTML
and then it does not make sense to support it.


A plain \emph{box} is sometimes useful. Let's show it here for comparison
with admons (especially the block admon has much in common with a box).
The box is more aimed at framing a law or an equation.

First a simple block with text, an equation, and a list:


\begin{center}
\begin{Sbox}
\begin{minipage}{0.85\linewidth}
A generic equation

\[ f(x) = 0 \]
must be solved by a numerical method, such as

\begin{itemize}
 \item Newton's method

 \item The Bisection method

 \item Fixed-point (Picard) iteration by rewriting $f(x)=x - g(x)$

 \item The Secant method
\end{itemize}

\noindent
\end{minipage}
\end{Sbox}
\fbox{\TheSbox}
\end{center}
Now test a box with equation only (note that this line continues the
box, it is not a new paragraph):


\begin{center}
\begin{Sbox}
\begin{minipage}{0.85\linewidth}
\begin{equation} f(x) = \sin(x)e^{1-x} \end{equation}
\end{minipage}
\end{Sbox}
\fbox{\TheSbox}
\end{center}

\paragraph{Hint.}
Newton's method requires a good start vector to converge fast.



Let's begin a new paragraph and show a box with code only:


\begin{center}
\begin{Sbox}
\begin{minipage}{0.85\linewidth}
\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
def some_code(x):
    return sin(x)*exp(1-x)
\end{lstlisting}
\end{minipage}
\end{Sbox}
\fbox{\TheSbox}
\end{center}



\subsection{Admonitions}

Let us start with a plain warning environment.


% --- begin paragraph admon ---
\vspace{3mm}{\footnotesize
\noindent\textbf{Warning.}
And here is a warning about something to pay attention to. We
test how the heading behave and add quite some extra texts
in comparison with the other admons.

\begin{itemize}
  \item and a list

  \item with items
\end{itemize}

\noindent
We continue with more text to see how that affects the layout.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
\vspace{3mm}}
% --- end paragraph admon ---



Test warning with title:


% --- begin paragraph admon ---
\vspace{3mm}{\footnotesize
\noindent\textbf{{\large Title ending with math $\sqrt{2}\approx 1.4$}.}
{\large And here comes some text with bad news in larger font.

Also some code:

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
def f(x):
    return x
\end{lstlisting}
And a complete program

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
print("Hello, World!")
\end{lstlisting}
\par}
\vspace{3mm}}
% --- end paragraph admon ---



Test warning with large title with math:


% --- begin paragraph admon ---
\vspace{3mm}{\footnotesize
\noindent\textbf{{\large Watch out for $\nabla\cdot\bm{u}=0$ equations}.}
{\large Divergence freedom is often problematic from a numerical point
of view.
\par}
\vspace{3mm}}
% --- end paragraph admon ---



Then we test a block, which is guaranteed to never have any admon icon.


% --- begin paragraph admon ---
\vspace{3mm}{\footnotesize
\noindent\textbf{Block with title.}
{\footnotesize Here is a block of text with title. It is typeset
\emph{without any icon} and is useful when you want some admons with icon
and some without. With the small font size, as used here, one can have
more comment-style text or text that really goes deeper or talks
about fun facts that are not strictly necessary for the main flow
of understanding.
\par}
\vspace{3mm}}
% --- end paragraph admon ---





% --- begin paragraph admon ---
\vspace{3mm}{\footnotesize
\noindent\textbf{}
Here is a block of text with no title. As above, it is typeset without any icon
and is useful when you want some admons with icon and some without.
\vspace{3mm}}
% --- end paragraph admon ---



% Note that the final ! does not appear in Sphinx and reST since
% those formats automatically add : to the admonition title.


% --- begin paragraph admon ---
\vspace{3mm}{\footnotesize
\noindent\textbf{Note, eventually!}
Ah, we are soon close to the end (with illegal font size specification!).
But first a bit of math where we define $\theta$ and $\bm{r}$:

\begin{align*}
\theta &= q^2,\\
\bm{r} &= \varrho\bm{i}
\end{align*}
\vspace{3mm}}
% --- end paragraph admon ---



% Test one word with a number


% --- begin paragraph admon ---
\vspace{3mm}{\footnotesize
\noindent\textbf{Point1.}
Ah, we are soon close to the end.
\vspace{3mm}}
% --- end paragraph admon ---




% --- begin paragraph admon ---
\vspace{3mm}{\footnotesize
\noindent\textbf{Question.}
So, how many admonition environments does DocOnce support?
\vspace{3mm}}
% --- end paragraph admon ---




% --- begin paragraph admon ---
\vspace{3mm}{\footnotesize
\noindent\textbf{Question.}
\begin{enumerate}
 \item Once more, how many admonition environments does DocOnce support?
\end{enumerate}

\noindent
\vspace{3mm}}
% --- end paragraph admon ---




% --- begin paragraph admon ---
\vspace{3mm}{\footnotesize
\noindent\textbf{Tip.}
It is of outmost important to

\begin{enumerate}
\item stay cool

\item read hints and tips carefully
\end{enumerate}

\noindent
Because here the thing is to do

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
import urllib

def grab(url, filename):
    urllib.urlretrieve(url, filename=filename)
\end{lstlisting}
\vspace{3mm}}
% --- end paragraph admon ---



Next is a warning without a title ("none" implies no title).


% --- begin paragraph admon ---
\vspace{3mm}{\footnotesize
\noindent\textbf{}
And here comes some text with bad news.
\vspace{3mm}}
% --- end paragraph admon ---



\subsection{Going deeper environments}

Here is a long notice environment with a custom title and much
text, math and code.


% --- begin paragraph admon ---
\vspace{3mm}{\footnotesize
\noindent\textbf{Going deeper.}
We have some equations that should be preceded by much text, so the
task is to write and write. The number of words, and not the
meaning, is what counts here. We need desperately to fill up the
page in the hope that some admonitions will experience a page break,
which the {\LaTeX} environment should handle with ease.

Let us start with some equations:

\begin{align*}
\Ddt{u} &= 0
\\
\half &= \halfi\\
\half\x &= \normalvec
\end{align*}

The implementation of such complicated equations in computer
code is task that this "Going deeper" environment targets.

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
def Dudt(u):
    r = diff(u, t) + u*grad(u)
    return r

half = 0.5
x = 2*n
\end{lstlisting}
And some more text that can help going into the next page.
Longer computer code requires vertical space:

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
class Diff:
    def __init__(self, f, h=1E-5):
        self.f = f
        self.h = float(h)

class Forward1(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (f(x+h) - f(x))/h

class Backward1(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (f(x) - f(x-h))/h

class Central2(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (f(x+h) - f(x-h))/(2*h)

class Central4(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (4./3)*(f(x+h)   - f(x-h))  /(2*h) - \
               (1./3)*(f(x+2*h) - f(x-2*h))/(4*h)

class Central6(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (3./2) *(f(x+h)   - f(x-h))  /(2*h) - \
               (3./5) *(f(x+2*h) - f(x-2*h))/(4*h) + \
               (1./10)*(f(x+3*h) - f(x-3*h))/(6*h)

class Forward3(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (-(1./6)*f(x+2*h) + f(x+h) - 0.5*f(x) - \
                (1./3)*f(x-h))/h
\end{lstlisting}
And then we add a figure too.



\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=0.7\linewidth]{../doc/src/manual/fig/wave1D.pdf}}

\vspace{6mm}
\vspace{3mm}}
% --- end paragraph admon ---




\subsection{The end}

A bit of text before the summary, which we now call "Concluding remarks,
for the novice",
just because we can.


% --- begin paragraph admon ---
\vspace{3mm}{\footnotesize
\noindent\textbf{Concluding remarks, for the novice.}
We can summarize the most important things with admons: they have
a different typesetting, and they may have a symbol.
Titles should be optional.
\vspace{3mm}}
% --- end paragraph admon ---



\paragraph{Remark.}
The \texttt{remarks} and \texttt{hint} environments are not allowed outside
exercises (and problems and projects too).

% ------------------- end of main content ---------------

% #ifdef PREAMBLE
\end{document}
% #endif


************** File: admon_yellowicon.tex *****************
%%
%% Automatically generated file from DocOnce source
%% (https://github.com/hplgit/doconce/)
%%

% #define PREAMBLE

% #ifdef PREAMBLE
%-------------------- begin preamble ----------------------

\documentclass[%
oneside,                 % oneside: electronic viewing, twoside: printing
final,                   % draft: marks overfull hboxes, figures with paths
10pt]{article}

\listfiles               %  print all files needed to compile this document

\usepackage{relsize,makeidx,color,setspace,amsmath,amsfonts,amssymb}
\usepackage[table]{xcolor}
\usepackage{bm,ltablex,microtype}

\usepackage[pdftex]{graphicx}

\usepackage{fancybox}  % make sure fancybox is loaded before fancyvrb
%\setlength{\fboxsep}{8pt}  % may clash with need in pre/cod envirs

% Packages for typesetting blocks of computer code
\usepackage{fancyvrb,framed,moreverb}

% Define colors
\definecolor{orange}{cmyk}{0,0.4,0.8,0.2}
\definecolor{tucorange}{rgb}{1.0,0.64,0}
\definecolor{darkorange}{rgb}{.71,0.21,0.01}
\definecolor{darkgreen}{rgb}{.12,.54,.11}
\definecolor{myteal}{rgb}{.26, .44, .56}
\definecolor{gray}{gray}{0.45}
\definecolor{mediumgray}{gray}{.8}
\definecolor{lightgray}{gray}{.95}
\definecolor{brown}{rgb}{0.54,0.27,0.07}
\definecolor{purple}{rgb}{0.5,0.0,0.5}
\definecolor{darkgray}{gray}{0.25}
\definecolor{darkblue}{rgb}{0,0.08,0.45}
\definecolor{darkblue2}{rgb}{0,0,0.8}
\definecolor{lightred}{rgb}{1.0,0.39,0.28}
\definecolor{lightgreen}{rgb}{0.48,0.99,0.0}
\definecolor{lightblue}{rgb}{0.53,0.81,0.92}
\definecolor{lightblue2}{rgb}{0.3,0.3,1.0}
\definecolor{lightpurple}{rgb}{0.87,0.63,0.87}
\definecolor{lightcyan}{rgb}{0.5,1.0,0.83}

\colorlet{comment_green}{green!50!black}
\colorlet{string_red}{red!60!black}
\colorlet{keyword_pink}{magenta!70!black}
\colorlet{indendifier_green}{green!70!white}

% Backgrounds for code
\definecolor{cbg_gray}{rgb}{.95, .95, .95}
\definecolor{bar_gray}{rgb}{.92, .92, .92}

\definecolor{cbg_yellowgray}{rgb}{.95, .95, .85}
\definecolor{bar_yellowgray}{rgb}{.95, .95, .65}

\colorlet{cbg_yellow2}{yellow!10}
\colorlet{bar_yellow2}{yellow!20}

\definecolor{cbg_yellow1}{rgb}{.98, .98, 0.8}
\definecolor{bar_yellow1}{rgb}{.98, .98, 0.4}

\definecolor{cbg_red1}{rgb}{1, 0.85, 0.85}
\definecolor{bar_red1}{rgb}{1, 0.75, 0.85}

\definecolor{cbg_blue1}{rgb}{0.87843, 0.95686, 1.0}
\definecolor{bar_blue1}{rgb}{0.7,     0.95686, 1}

\usepackage{listingsutf8}

% Common lstlisting parameters

\usepackage{calc}
\newlength{\lstboxwidth}  % width of lst box
\newlength{\framethickness}
\setlength{\framethickness}{0.5mm}
% for frame=trbl and a framerule that has significant size, set
% xleftmargin=5mm and xrightmargin=5mm.

\lstset{
  basicstyle=\small \ttfamily,
  breaklines=false,          % break/wrap lines
  breakatwhitespace=true,    % let linebreaks happen at whitespace
  breakindent=40pt,
  tab=,
  tabsize=4,                 % tab means 4 spaces
  %belowskip=\smallskipamount,  % space between code and text below
  xleftmargin=2mm,           % indentation of code frame
  xrightmargin=0mm,
  framexleftmargin=2mm,      % add frame space to the left of the code box
  %numbers=left,             % put line numbers on the left
  %stepnumber=2,             % stepnumber=1 numbers each line, =n every n lines
  framerule=\framethickness, % thickness of frame
  aboveskip=2ex,             % vertical space above code frame
  showstringspaces=false,    % show spaces in strings with an underscore
  showspaces=false,          % show spaces with an underscore
  showtabs=false,
  keepspaces=true,
  columns=fullflexible,      % tighter character kerning, like verb
  escapeinside={(*@}{@*)},   % (*@ \pause @*) in slides and math in code blocks
  extendedchars=\true,       % allows non-ascii chars, does not work with utf-8
}

% Internally defined styles for lstlisting

\lstdefinestyle{simple}{
commentstyle={},
}

% end of custom lstdefinestyles

\usepackage[T1]{fontenc}
%\usepackage[latin1]{inputenc}
\usepackage{ucs}
\usepackage[utf8x]{inputenc}

\usepackage{lmodern}         % Latin Modern fonts derived from Computer Modern

% Hyperlinks in PDF:
\definecolor{linkcolor}{rgb}{0,0,0.4}
\usepackage{hyperref}
\hypersetup{
    breaklinks=true,
    colorlinks=true,
    linkcolor=linkcolor,
    urlcolor=linkcolor,
    citecolor=black,
    filecolor=black,
    %filecolor=blue,
    pdfmenubar=true,
    pdftoolbar=true,
    bookmarksdepth=3   % Uncomment (and tweak) for PDF bookmarks with more levels than the TOC
    }
%\hyperbaseurl{}   % hyperlinks are relative to this root

\setcounter{tocdepth}{2}  % levels in table of contents

% Tricks for having figures close to where they are defined:
% 1. define less restrictive rules for where to put figures
\setcounter{topnumber}{2}
\setcounter{bottomnumber}{2}
\setcounter{totalnumber}{4}
\renewcommand{\topfraction}{0.95}
\renewcommand{\bottomfraction}{0.95}
\renewcommand{\textfraction}{0}
\renewcommand{\floatpagefraction}{0.75}
% floatpagefraction must always be less than topfraction!
% 2. ensure all figures are flushed before next section
\usepackage[section]{placeins}
% 3. enable begin{figure}[H] (often leads to ugly pagebreaks)
%\usepackage{float}\restylefloat{figure}

% --- fancyhdr package for fancy headers ---
\usepackage{fancyhdr}
\fancyhf{} % sets both header and footer to nothing
\renewcommand{\headrulewidth}{0pt}
\fancyfoot[LE,RO]{\thepage}
% Ensure copyright on titlepage (article style) and chapter pages (book style)
\fancypagestyle{plain}{
  \fancyhf{}
  \fancyfoot[C]{{\footnotesize \copyright\ 2021, H. P. Langtangen. Made with \href{https://github.com/hplgit/doconce}{DocOnce}}}
%  \renewcommand{\footrulewidth}{0mm}
  \renewcommand{\headrulewidth}{0mm}
}
% Ensure copyright on titlepages with \thispagestyle{empty}
\fancypagestyle{empty}{
  \fancyhf{}
  \fancyfoot[C]{{\footnotesize \copyright\ 2021, H. P. Langtangen. Made with \href{https://github.com/hplgit/doconce}{DocOnce}}}
  \renewcommand{\footrulewidth}{0mm}
  \renewcommand{\headrulewidth}{0mm}
}

\pagestyle{fancy}


\usepackage{framed,wrapfig}

% --- begin definitions of admonition environments ---

% Admonition style "yellowicon" has colored background, yellow icons, and no farme
% Admon "notice"
\definecolor{yellowicon_notice_background}{rgb}{0.988235,0.964706,0.862745}
% \fboxsep sets the space between the text and the box
\newenvironment{noticeshaded}
{\def\FrameCommand{\fboxsep=3mm\colorbox{yellowicon_notice_background}}
 \MakeFramed {\advance\hsize-\width \FrameRestore}}{\endMakeFramed}

\newenvironment{notice_yellowiconadmon}[1][Notice]{
\begin{noticeshaded}
\noindent
\begin{wrapfigure}{l}{0.07\textwidth}
\vspace{-13pt}
\includegraphics[width=0.07\textwidth]{latex_figs/small_yellow_notice}
\end{wrapfigure} \textbf{#1}\par
\nobreak\noindent\ignorespaces
}
{
\end{noticeshaded}
}

% Admonition style "yellowicon" has colored background, yellow icons, and no farme
% Admon "summary"
\definecolor{yellowicon_summary_background}{rgb}{0.988235,0.964706,0.862745}
% \fboxsep sets the space between the text and the box
\newenvironment{summaryshaded}
{\def\FrameCommand{\fboxsep=3mm\colorbox{yellowicon_summary_background}}
 \MakeFramed {\advance\hsize-\width \FrameRestore}}{\endMakeFramed}

\newenvironment{summary_yellowiconadmon}[1][Summary]{
\begin{summaryshaded}
\noindent
\begin{wrapfigure}{l}{0.07\textwidth}
\vspace{-13pt}
\includegraphics[width=0.07\textwidth]{latex_figs/small_yellow_summary}
\end{wrapfigure} \textbf{#1}\par
\nobreak\noindent\ignorespaces
}
{
\end{summaryshaded}
}

% Admonition style "yellowicon" has colored background, yellow icons, and no farme
% Admon "warning"
\definecolor{yellowicon_warning_background}{rgb}{0.988235,0.964706,0.862745}
% \fboxsep sets the space between the text and the box
\newenvironment{warningshaded}
{\def\FrameCommand{\fboxsep=3mm\colorbox{yellowicon_warning_background}}
 \MakeFramed {\advance\hsize-\width \FrameRestore}}{\endMakeFramed}

\newenvironment{warning_yellowiconadmon}[1][Warning]{
\begin{warningshaded}
\noindent
\begin{wrapfigure}{l}{0.07\textwidth}
\vspace{-13pt}
\includegraphics[width=0.07\textwidth]{latex_figs/small_yellow_warning}
\end{wrapfigure} \textbf{#1}\par
\nobreak\noindent\ignorespaces
}
{
\end{warningshaded}
}

% Admonition style "yellowicon" has colored background, yellow icons, and no farme
% Admon "question"
\definecolor{yellowicon_question_background}{rgb}{0.988235,0.964706,0.862745}
% \fboxsep sets the space between the text and the box
\newenvironment{questionshaded}
{\def\FrameCommand{\fboxsep=3mm\colorbox{yellowicon_question_background}}
 \MakeFramed {\advance\hsize-\width \FrameRestore}}{\endMakeFramed}

\newenvironment{question_yellowiconadmon}[1][Question]{
\begin{questionshaded}
\noindent
\begin{wrapfigure}{l}{0.07\textwidth}
\vspace{-13pt}
\includegraphics[width=0.07\textwidth]{latex_figs/small_yellow_question}
\end{wrapfigure} \textbf{#1}\par
\nobreak\noindent\ignorespaces
}
{
\end{questionshaded}
}

% Admonition style "yellowicon" has colored background, yellow icons, and no farme
% Admon "block"
\definecolor{yellowicon_block_background}{rgb}{0.988235,0.964706,0.862745}
% \fboxsep sets the space between the text and the box
\newenvironment{blockshaded}
{\def\FrameCommand{\fboxsep=3mm\colorbox{yellowicon_block_background}}
 \MakeFramed {\advance\hsize-\width \FrameRestore}}{\endMakeFramed}

\newenvironment{block_yellowiconadmon}[1][Block]{
\begin{blockshaded}
\noindent
 \textbf{#1}\par
\nobreak\noindent\ignorespaces
}
{
\end{blockshaded}
}

% --- end of definitions of admonition environments ---

% prevent orhpans and widows
\clubpenalty = 10000
\widowpenalty = 10000

% --- end of standard preamble for documents ---


% insert custom LaTeX commands...

\raggedbottom
\makeindex
\usepackage[totoc]{idxlayout}   % for index in the toc
\usepackage[nottoc]{tocbibind}  % for references/bibliography in the toc

%-------------------- end preamble ----------------------

\begin{document}

% matching end for #ifdef PREAMBLE
% #endif

\newcommand{\exercisesection}[1]{\subsection*{#1}}

\input{newcommands_bfmath}
\input{newcommands_replace}

% ------------------- main content ----------------------



% ----------------- title -------------------------

\thispagestyle{empty}

\begin{center}
{\LARGE\bf
\begin{spacing}{1.25}
Testing admons
\end{spacing}
}
\end{center}

% ----------------- author(s) -------------------------

\begin{center}
{\bf H. P. Langtangen${}^{}$} \\ [0mm]
\end{center}

\begin{center}
% List of all institutions:
\end{center}
    
% ----------------- end author(s) -------------------------

% --- begin date ---
\begin{center}
Jan 32, 2100
\end{center}
% --- end date ---

\vspace{1cm}


% !split
\section{Introduction}
First some ordinary text to compare font sizes in admonitions
and the surrounding text.


\subsection{Code}

Need some code outside admons for color and font comparisons:

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
def some_code(x):
    return sin(x)*exp(1-x)
\end{lstlisting}

And some plain text verbatim:

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
x=1.0 y=0.9 z=0.4
x=1.1 y=0.3 z=0.1
\end{lstlisting}

\subsection{Quotes and boxes}

Here is a plain quote environment.


\begin{quote}
Sayre's law states that
``in any dispute the intensity of feeling is inversely
proportional to the value of the issues at stake.'' \\
By way of corollary, it adds: \\
``That is why academic politics are so bitter.'' \\
\emph{Source}: \href{{https://en.wikipedia.org/wiki/Sayre's_law}}{wikipedia}
\end{quote}


Does quotes with title also work? No...cannot work in {\LaTeX} and HTML
and then it does not make sense to support it.


A plain \emph{box} is sometimes useful. Let's show it here for comparison
with admons (especially the block admon has much in common with a box).
The box is more aimed at framing a law or an equation.

First a simple block with text, an equation, and a list:


\begin{center}
\begin{Sbox}
\begin{minipage}{0.85\linewidth}
A generic equation

\[ f(x) = 0 \]
must be solved by a numerical method, such as

\begin{itemize}
 \item Newton's method

 \item The Bisection method

 \item Fixed-point (Picard) iteration by rewriting $f(x)=x - g(x)$

 \item The Secant method
\end{itemize}

\noindent
\end{minipage}
\end{Sbox}
\fbox{\TheSbox}
\end{center}
Now test a box with equation only (note that this line continues the
box, it is not a new paragraph):


\begin{center}
\begin{Sbox}
\begin{minipage}{0.85\linewidth}
\begin{equation} f(x) = \sin(x)e^{1-x} \end{equation}
\end{minipage}
\end{Sbox}
\fbox{\TheSbox}
\end{center}

\paragraph{Hint.}
Newton's method requires a good start vector to converge fast.



Let's begin a new paragraph and show a box with code only:


\begin{center}
\begin{Sbox}
\begin{minipage}{0.85\linewidth}
\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
def some_code(x):
    return sin(x)*exp(1-x)
\end{lstlisting}
\end{minipage}
\end{Sbox}
\fbox{\TheSbox}
\end{center}



\subsection{Admonitions}

Let us start with a plain warning environment.


\begin{warning_yellowiconadmon}[Warning]
And here is a warning about something to pay attention to. We
test how the heading behave and add quite some extra texts
in comparison with the other admons.

\begin{itemize}
  \item and a list

  \item with items
\end{itemize}

\noindent
We continue with more text to see how that affects the layout.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
\end{warning_yellowiconadmon} % title: Warning



Test warning with title:


\begin{warning_yellowiconadmon}[{\large Title ending with math $\sqrt{2}\approx 1.4$}]
{\large And here comes some text with bad news in larger font.

Also some code:

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
def f(x):
    return x
\end{lstlisting}
And a complete program

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
print("Hello, World!")
\end{lstlisting}
\par}
\end{warning_yellowiconadmon} % title: {\large Title ending with math $\sqrt{2}\approx 1.4$}



Test warning with large title with math:


\begin{warning_yellowiconadmon}[{\large Watch out for $\nabla\cdot\bm{u}=0$ equations}]
{\large Divergence freedom is often problematic from a numerical point
of view.
\par}
\end{warning_yellowiconadmon} % title: {\large Watch out for $\nabla\cdot\bm{u}=0$ equations}



Then we test a block, which is guaranteed to never have any admon icon.


\begin{block_yellowiconadmon}[Block with title]
\vspace{-2.5mm}\par\noindent
{\footnotesize Here is a block of text with title. It is typeset
\emph{without any icon} and is useful when you want some admons with icon
and some without. With the small font size, as used here, one can have
more comment-style text or text that really goes deeper or talks
about fun facts that are not strictly necessary for the main flow
of understanding.
\par}
\end{block_yellowiconadmon} % title: Block with title





\begin{block_yellowiconadmon}[]
Here is a block of text with no title. As above, it is typeset without any icon
and is useful when you want some admons with icon and some without.
\end{block_yellowiconadmon} % title: 



% Note that the final ! does not appear in Sphinx and reST since
% those formats automatically add : to the admonition title.


\begin{notice_yellowiconadmon}[Note, eventually!]
Ah, we are soon close to the end (with illegal font size specification!).
But first a bit of math where we define $\theta$ and $\bm{r}$:

\begin{align*}
\theta &= q^2,\\
\bm{r} &= \varrho\bm{i}
\end{align*}
\end{notice_yellowiconadmon} % title: Note, eventually!



% Test one word with a number


\begin{notice_yellowiconadmon}[Point1]
Ah, we are soon close to the end.
\end{notice_yellowiconadmon} % title: Point1




\begin{question_yellowiconadmon}[Question]
So, how many admonition environments does DocOnce support?
\end{question_yellowiconadmon} % title: Question




\begin{question_yellowiconadmon}[Question]
\begin{enumerate}
 \item Once more, how many admonition environments does DocOnce support?
\end{enumerate}

\noindent
\end{question_yellowiconadmon} % title: Question




\begin{warning_yellowiconadmon}[Tip]
It is of outmost important to

\begin{enumerate}
\item stay cool

\item read hints and tips carefully
\end{enumerate}

\noindent
Because here the thing is to do

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
import urllib

def grab(url, filename):
    urllib.urlretrieve(url, filename=filename)
\end{lstlisting}
\end{warning_yellowiconadmon} % title: Tip



Next is a warning without a title ("none" implies no title).


\begin{warning_yellowiconadmon}[]
And here comes some text with bad news.
\end{warning_yellowiconadmon} % title: 



\subsection{Going deeper environments}

Here is a long notice environment with a custom title and much
text, math and code.


\begin{notice_yellowiconadmon}[Going deeper.]
We have some equations that should be preceded by much text, so the
task is to write and write. The number of words, and not the
meaning, is what counts here. We need desperately to fill up the
page in the hope that some admonitions will experience a page break,
which the {\LaTeX} environment should handle with ease.

Let us start with some equations:

\begin{align*}
\Ddt{u} &= 0
\\
\half &= \halfi\\
\half\x &= \normalvec
\end{align*}

The implementation of such complicated equations in computer
code is task that this "Going deeper" environment targets.

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
def Dudt(u):
    r = diff(u, t) + u*grad(u)
    return r

half = 0.5
x = 2*n
\end{lstlisting}
And some more text that can help going into the next page.
Longer computer code requires vertical space:

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
class Diff:
    def __init__(self, f, h=1E-5):
        self.f = f
        self.h = float(h)

class Forward1(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (f(x+h) - f(x))/h

class Backward1(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (f(x) - f(x-h))/h

class Central2(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (f(x+h) - f(x-h))/(2*h)

class Central4(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (4./3)*(f(x+h)   - f(x-h))  /(2*h) - \
               (1./3)*(f(x+2*h) - f(x-2*h))/(4*h)

class Central6(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (3./2) *(f(x+h)   - f(x-h))  /(2*h) - \
               (3./5) *(f(x+2*h) - f(x-2*h))/(4*h) + \
               (1./10)*(f(x+3*h) - f(x-3*h))/(6*h)

class Forward3(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (-(1./6)*f(x+2*h) + f(x+h) - 0.5*f(x) - \
                (1./3)*f(x-h))/h
\end{lstlisting}
And then we add a figure too.



\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=0.7\linewidth]{../doc/src/manual/fig/wave1D.pdf}}

\vspace{6mm}
\end{notice_yellowiconadmon} % title: Going deeper.




\subsection{The end}

A bit of text before the summary, which we now call "Concluding remarks,
for the novice",
just because we can.


\begin{summary_yellowiconadmon}[Concluding remarks, for the novice]
We can summarize the most important things with admons: they have
a different typesetting, and they may have a symbol.
Titles should be optional.
\end{summary_yellowiconadmon} % title: Concluding remarks, for the novice



\paragraph{Remark.}
The \texttt{remarks} and \texttt{hint} environments are not allowed outside
exercises (and problems and projects too).

% ------------------- end of main content ---------------

% #ifdef PREAMBLE
\end{document}
% #endif


************** File: admon_double_envirs.tex *****************
%%
%% Automatically generated file from DocOnce source
%% (https://github.com/hplgit/doconce/)
%%
%%


%-------------------- begin preamble ----------------------

\documentclass[%
oneside,                 % oneside: electronic viewing, twoside: printing
final,                   % draft: marks overfull hboxes, figures with paths
10pt]{article}

\listfiles               %  print all files needed to compile this document

\usepackage{relsize,makeidx,color,setspace,amsmath,amsfonts,amssymb}
\usepackage[table]{xcolor}
\usepackage{bm,ltablex,microtype}

\usepackage[pdftex]{graphicx}

\usepackage{fancybox}  % make sure fancybox is loaded before fancyvrb
%\setlength{\fboxsep}{8pt}  % may clash with need in pre/cod envirs

\usepackage{fancyvrb} % packages needed for verbatim environments
\usepackage{minted}
\usemintedstyle{default}
\usepackage{fancyvrb}

\usepackage[T1]{fontenc}
%\usepackage[latin1]{inputenc}
\usepackage{ucs}
\usepackage[utf8x]{inputenc}

\usepackage{lmodern}         % Latin Modern fonts derived from Computer Modern

% Hyperlinks in PDF:
\definecolor{linkcolor}{rgb}{0,0,0.4}
\usepackage{hyperref}
\hypersetup{
    breaklinks=true,
    colorlinks=true,
    linkcolor=linkcolor,
    urlcolor=linkcolor,
    citecolor=black,
    filecolor=black,
    %filecolor=blue,
    pdfmenubar=true,
    pdftoolbar=true,
    bookmarksdepth=3   % Uncomment (and tweak) for PDF bookmarks with more levels than the TOC
    }
%\hyperbaseurl{}   % hyperlinks are relative to this root

\setcounter{tocdepth}{2}  % levels in table of contents

% Tricks for having figures close to where they are defined:
% 1. define less restrictive rules for where to put figures
\setcounter{topnumber}{2}
\setcounter{bottomnumber}{2}
\setcounter{totalnumber}{4}
\renewcommand{\topfraction}{0.95}
\renewcommand{\bottomfraction}{0.95}
\renewcommand{\textfraction}{0}
\renewcommand{\floatpagefraction}{0.75}
% floatpagefraction must always be less than topfraction!
% 2. ensure all figures are flushed before next section
\usepackage[section]{placeins}
% 3. enable begin{figure}[H] (often leads to ugly pagebreaks)
%\usepackage{float}\restylefloat{figure}

% --- fancyhdr package for fancy headers ---
\usepackage{fancyhdr}
\fancyhf{} % sets both header and footer to nothing
\renewcommand{\headrulewidth}{0pt}
\fancyfoot[LE,RO]{\thepage}
% Ensure copyright on titlepage (article style) and chapter pages (book style)
\fancypagestyle{plain}{
  \fancyhf{}
  \fancyfoot[C]{{\footnotesize \copyright\ 2021, H. P. Langtangen. Made with \href{https://github.com/hplgit/doconce}{DocOnce}}}
%  \renewcommand{\footrulewidth}{0mm}
  \renewcommand{\headrulewidth}{0mm}
}
% Ensure copyright on titlepages with \thispagestyle{empty}
\fancypagestyle{empty}{
  \fancyhf{}
  \fancyfoot[C]{{\footnotesize \copyright\ 2021, H. P. Langtangen. Made with \href{https://github.com/hplgit/doconce}{DocOnce}}}
  \renewcommand{\footrulewidth}{0mm}
  \renewcommand{\headrulewidth}{0mm}
}

\pagestyle{fancy}


\usepackage[framemethod=TikZ]{mdframed}

% --- begin definitions of admonition environments ---

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "notice" admon
\definecolor{mdfbox_notice_background}{rgb}{1,1,1}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_notice_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=mdfbox_notice_background,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{notice_mdfboxmdframed}

\newenvironment{notice_mdfboxadmon}[1][]{
\begin{notice_mdfboxmdframed}[frametitle=#1]
}
{
\end{notice_mdfboxmdframed}
}

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "summary" admon
\definecolor{mdfbox_summary_background}{rgb}{1,1,1}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_summary_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=mdfbox_summary_background,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{summary_mdfboxmdframed}

\newenvironment{summary_mdfboxadmon}[1][]{
\begin{summary_mdfboxmdframed}[frametitle=#1]
}
{
\end{summary_mdfboxmdframed}
}

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "warning" admon
\definecolor{mdfbox_warning_background}{rgb}{1,1,1}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_warning_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=mdfbox_warning_background,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{warning_mdfboxmdframed}

\newenvironment{warning_mdfboxadmon}[1][]{
\begin{warning_mdfboxmdframed}[frametitle=#1]
}
{
\end{warning_mdfboxmdframed}
}

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "question" admon
\definecolor{mdfbox_question_background}{rgb}{1,1,1}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_question_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=mdfbox_question_background,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{question_mdfboxmdframed}

\newenvironment{question_mdfboxadmon}[1][]{
\begin{question_mdfboxmdframed}[frametitle=#1]
}
{
\end{question_mdfboxmdframed}
}

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "block" admon
\definecolor{mdfbox_block_background}{rgb}{1,1,1}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_block_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=mdfbox_block_background,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{block_mdfboxmdframed}

\newenvironment{block_mdfboxadmon}[1][]{
\begin{block_mdfboxmdframed}[frametitle=#1]
}
{
\end{block_mdfboxmdframed}
}

% --- end of definitions of admonition environments ---

% prevent orhpans and widows
\clubpenalty = 10000
\widowpenalty = 10000

% --- end of standard preamble for documents ---


% insert custom LaTeX commands...

\raggedbottom
\makeindex
\usepackage[totoc]{idxlayout}   % for index in the toc
\usepackage[nottoc]{tocbibind}  % for references/bibliography in the toc

%-------------------- end preamble ----------------------

\begin{document}

% matching end for #ifdef PREAMBLE

\newcommand{\exercisesection}[1]{\subsection*{#1}}

\input{newcommands_bfmath}
\input{newcommands_replace}

% ------------------- main content ----------------------



% ----------------- title -------------------------

\thispagestyle{empty}

\begin{center}
{\LARGE\bf
\begin{spacing}{1.25}
Testing admons
\end{spacing}
}
\end{center}

% ----------------- author(s) -------------------------

\begin{center}
{\bf H. P. Langtangen${}^{}$} \\ [0mm]
\end{center}

\begin{center}
% List of all institutions:
\end{center}
    
% ----------------- end author(s) -------------------------

% --- begin date ---
\begin{center}
Jan 32, 2100
\end{center}
% --- end date ---

\vspace{1cm}


% !split
\section{Introduction}
First some ordinary text to compare font sizes in admonitions
and the surrounding text.


\subsection{Code}

Need some code outside admons for color and font comparisons:

\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=0mm]
def some_code(x):
    return sin(x)*exp(1-x)
\end{Verbatim}

And some plain text verbatim:

\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95]
x=1.0 y=0.9 z=0.4
x=1.1 y=0.3 z=0.1
\end{Verbatim}

\subsection{Quotes and boxes}

Here is a plain quote environment.


\begin{quote}
Sayre's law states that
``in any dispute the intensity of feeling is inversely
proportional to the value of the issues at stake.'' \\
By way of corollary, it adds: \\
``That is why academic politics are so bitter.'' \\
\emph{Source}: \href{{https://en.wikipedia.org/wiki/Sayre's_law}}{wikipedia}
\end{quote}


Does quotes with title also work? No...cannot work in {\LaTeX} and HTML
and then it does not make sense to support it.


A plain \emph{box} is sometimes useful. Let's show it here for comparison
with admons (especially the block admon has much in common with a box).
The box is more aimed at framing a law or an equation.

First a simple block with text, an equation, and a list:


\begin{center}
\begin{Sbox}
\begin{minipage}{0.85\linewidth}
A generic equation

\[ f(x) = 0 \]
must be solved by a numerical method, such as

\begin{itemize}
 \item Newton's method

 \item The Bisection method

 \item Fixed-point (Picard) iteration by rewriting $f(x)=x - g(x)$

 \item The Secant method
\end{itemize}

\noindent
\end{minipage}
\end{Sbox}
\fbox{\TheSbox}
\end{center}
Now test a box with equation only (note that this line continues the
box, it is not a new paragraph):


\begin{center}
\begin{Sbox}
\begin{minipage}{0.85\linewidth}
\begin{equation} f(x) = \sin(x)e^{1-x} \end{equation}
\end{minipage}
\end{Sbox}
\fbox{\TheSbox}
\end{center}

\\paragraph{Hint.}\n
Newton's method requires a good start vector to converge fast.



Let's begin a new paragraph and show a box with code only:


\begin{center}
\begin{Sbox}
\begin{minipage}{0.85\linewidth}
\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=0mm]
def some_code(x):
    return sin(x)*exp(1-x)
\end{Verbatim}
\end{minipage}
\end{Sbox}
\fbox{\TheSbox}
\end{center}



\subsection{Admonitions}

Let us start with a plain warning environment.


\begin{warning_mdfboxadmon}[Warning.]
And here is a warning about something to pay attention to. We
test how the heading behave and add quite some extra texts
in comparison with the other admons.

\begin{itemize}
  \item and a list

  \item with items
\end{itemize}

\noindent
We continue with more text to see how that affects the layout.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
\end{warning_mdfboxadmon} % title: Warning.



Test warning with title:


\begin{warning_mdfboxadmon}[{\large Title ending with math $\sqrt{2}\approx 1.4$}.]
{\large And here comes some text with bad news in larger font.

Also some code:

\begin{minted}{python}
def f(x):
    return x
\end{minted}
And a complete program

\begin{minted}{python}
print("Hello, World!")
\end{minted}
\par}
\end{warning_mdfboxadmon} % title: {\large Title ending with math $\sqrt{2}\approx 1.4$}.



Test warning with large title with math:


\begin{warning_mdfboxadmon}[{\large Watch out for $\nabla\cdot\bm{u}=0$ equations}.]
{\large Divergence freedom is often problematic from a numerical point
of view.
\par}
\end{warning_mdfboxadmon} % title: {\large Watch out for $\nabla\cdot\bm{u}=0$ equations}.



Then we test a block, which is guaranteed to never have any admon icon.


\begin{block_mdfboxadmon}[Block with title.]
\vspace{0.5mm}\par\noindent
{\footnotesize Here is a block of text with title. It is typeset
\emph{without any icon} and is useful when you want some admons with icon
and some without. With the small font size, as used here, one can have
more comment-style text or text that really goes deeper or talks
about fun facts that are not strictly necessary for the main flow
of understanding.
\par}
\end{block_mdfboxadmon} % title: Block with title.





\begin{block_mdfboxadmon}[]
Here is a block of text with no title. As above, it is typeset without any icon
and is useful when you want some admons with icon and some without.
\end{block_mdfboxadmon} % title: 



% Note that the final ! does not appear in Sphinx and reST since
% those formats automatically add : to the admonition title.


\begin{notice_mdfboxadmon}[Note eventually!]
Ah, we are soon close to the end (with illegal font size specification!).
But first a bit of math where we define $\theta$ and $\bm{r}$:

\begin{align*}
\theta &= q^2,\\
\bm{r} &= \varrho\bm{i}
\end{align*}
\end{notice_mdfboxadmon} % title: Note eventually!



% Test one word with a number


\begin{notice_mdfboxadmon}[Point1.]
Ah, we are soon close to the end.
\end{notice_mdfboxadmon} % title: Point1.




\begin{question_mdfboxadmon}[Question.]
So, how many admonition environments does DocOnce support?
\end{question_mdfboxadmon} % title: Question.




\begin{question_mdfboxadmon}[Question.]
\begin{enumerate}
 \item Once more, how many admonition environments does DocOnce support?
\end{enumerate}

\noindent
\end{question_mdfboxadmon} % title: Question.




\begin{warning_mdfboxadmon}[Tip.]
It is of outmost important to

\begin{enumerate}
\item stay cool

\item read hints and tips carefully
\end{enumerate}

\noindent
Because here the thing is to do

\begin{minted}{python}
import urllib

def grab(url, filename):
    urllib.urlretrieve(url, filename=filename)
\end{minted}
\end{warning_mdfboxadmon} % title: Tip.



Next is a warning without a title ("none" implies no title).


\begin{warning_mdfboxadmon}[]
And here comes some text with bad news.
\end{warning_mdfboxadmon} % title: 



\subsection{Going deeper environments}

Here is a long notice environment with a custom title and much
text, math and code.


\begin{notice_mdfboxadmon}[Going deeper.]
We have some equations that should be preceded by much text, so the
task is to write and write. The number of words, and not the
meaning, is what counts here. We need desperately to fill up the
page in the hope that some admonitions will experience a page break,
which the {\LaTeX} environment should handle with ease.

Let us start with some equations:

\begin{align*}
\Ddt{u} &= 0
\\
\half &= \halfi\\
\half\x &= \normalvec
\end{align*}

The implementation of such complicated equations in computer
code is task that this "Going deeper" environment targets.

\begin{minted}{python}
def Dudt(u):
    r = diff(u, t) + u*grad(u)
    return r

half = 0.5
x = 2*n
\end{minted}
And some more text that can help going into the next page.
Longer computer code requires vertical space:

\begin{minted}{python}
class Diff:
    def __init__(self, f, h=1E-5):
        self.f = f
        self.h = float(h)

class Forward1(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (f(x+h) - f(x))/h

class Backward1(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (f(x) - f(x-h))/h

class Central2(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (f(x+h) - f(x-h))/(2*h)

class Central4(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (4./3)*(f(x+h)   - f(x-h))  /(2*h) - \
               (1./3)*(f(x+2*h) - f(x-2*h))/(4*h)

class Central6(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (3./2) *(f(x+h)   - f(x-h))  /(2*h) - \
               (3./5) *(f(x+2*h) - f(x-2*h))/(4*h) + \
               (1./10)*(f(x+3*h) - f(x-3*h))/(6*h)

class Forward3(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (-(1./6)*f(x+2*h) + f(x+h) - 0.5*f(x) - \
                (1./3)*f(x-h))/h
\end{minted}
And then we add a figure too.



\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=0.7\linewidth]{../doc/src/manual/fig/wave1D.pdf}}

\vspace{6mm}
\end{notice_mdfboxadmon} % title: Going deeper.




\subsection{The end}

A bit of text before the summary, which we now call "Concluding remarks,
for the novice",
just because we can.


\begin{summary_mdfboxadmon}[Concluding remarks for the novice.]
We can summarize the most important things with admons: they have
a different typesetting, and they may have a symbol.
Titles should be optional.
\end{summary_mdfboxadmon} % title: Concluding remarks for the novice.



\paragraph{Remark.}
The \texttt{remarks} and \texttt{hint} environments are not allowed outside
exercises (and problems and projects too).

% ------------------- end of main content ---------------

\end{document}


************** File: admon_colors.html *****************
<!--
Automatically generated HTML file from DocOnce source
(https://github.com/doconce/doconce/)
-->
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="DocOnce: https://github.com/doconce/doconce/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="description" content="Testing admons">

<title>Testing admons</title>


<style type="text/css">
/* blueish style */

/* Color definitions:  https://www.december.com/html/spec/color0.html
   CSS examples:       https://www.w3schools.com/css/css_examples.asp */

body {
  margin-top: 1.0em;
  background-color: #ffffff;
  font-family: Helvetica, Arial, FreeSans, san-serif;
  color: #000000;
}
h1 { font-size: 1.8em; color: #1e36ce; }
h2 { font-size: 1.6em; color: #1e36ce; }
h3 { font-size: 1.4em; color: #1e36ce; }
a { color: #1e36ce; text-decoration:none; }
tt { font-family: "Courier New", Courier; }
/* pre style removed because it will interfer with pygments */
p { text-indent: 0px; }
hr { border: 0; width: 80%; border-bottom: 1px solid #aaa}
p.caption { width: 80%; font-style: normal; text-align: left; }
hr.figure { border: 0; width: 80%; border-bottom: 1px solid #aaa}
.alert-text-small   { font-size: 80%;  }
.alert-text-large   { font-size: 130%; }
.alert-text-normal  { font-size: 90%;  }
.notice, .summary, .warning, .question, .block {
  border: 1px solid; margin: 10px 0px; padding:15px 10px 15px 50px;
  background-repeat: no-repeat; background-position: 10px center;
}
.notice   { color: #00529B; background-color: #BDE5F8;
            background-image: url(https://raw.github.com/doconce/doconce/master/bundled/html_images/Knob_Info.png); }
.summary  { color: #4F8A10; background-color: #DFF2BF;
            background-image:url(https://raw.github.com/doconce/doconce/master/bundled/html_images/Knob_Valid_Green.png); }
.warning  { color: #9F6000; background-color: #FEEFB3;
            background-image: url(https://raw.github.com/doconce/doconce/master/bundled/html_images/Knob_Attention.png); }
.question { color: #4F8A10; background-color: #DFF2BF;
            background-image:url(https://raw.github.com/doconce/doconce/master/bundled/html_images/Knob_Forward.png); }
.block    { color: #00529B; background-color: #BDE5F8; }

div { text-align: justify; text-justify: inter-word; }
</style>


</head>

<!-- tocinfo
{'highest level': 1,
 'sections': [('Introduction', 1, None, 'introduction'),
              ('Code', 2, None, 'code'),
              ('Quotes and boxes', 2, None, 'quotes-and-boxes'),
              ('Admonitions', 2, None, 'admonitions'),
              ('Going deeper environments',
               2,
               None,
               'going-deeper-environments'),
              ('The end', 2, None, 'the-end')]}
end of tocinfo -->

<body>



<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  TeX: {
     equationNumbers: {  autoNumber: "AMS"  },
     extensions: ["AMSmath.js", "AMSsymbols.js", "autobold.js", "color.js"]
  }
});
</script>
<script type="text/javascript" async
 src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>



    
<!-- ------------------- main content ---------------------- -->



<center><h1>Testing admons</h1></center>  <!-- document title -->

<p>
<!-- author(s): H. P. Langtangen -->

<center>
<b>H. P. Langtangen</b> 
</center>

<p>
<!-- institution(s) -->

<br>
<p>
<center><h4>Jan 32, 2100</h4></center> <!-- date -->
<br>
<p>
<!-- !split -->

<h1 id="introduction">Introduction </h1>
First some ordinary text to compare font sizes in admonitions
and the surrounding text.

<h2 id="code">Code </h2>

<p>
Need some code outside admons for color and font comparisons:

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">some_code</span>(x):
    <span style="color: #008000; font-weight: bold">return</span> sin(x)<span style="color: #666666">*</span>exp(<span style="color: #666666">1-</span>x)
</pre></div>
<p>
And some plain text verbatim:

<p>

<!-- code=text typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>x=1.0 y=0.9 z=0.4
x=1.1 y=0.3 z=0.1
</pre></div>

<h2 id="quotes-and-boxes">Quotes and boxes </h2>

<p>
Here is a plain quote environment.

<p>
<blockquote>
    Sayre's law states that
    &quot;in any dispute the intensity of feeling is inversely
    proportional to the value of the issues at stake.&quot; <br />
    By way of corollary, it adds: <br />
    &quot;That is why academic politics are so bitter.&quot; <br />
    <em>Source</em>: <a href="https://en.wikipedia.org/wiki/Sayre's_law" target="_self">wikipedia</a>
</blockquote>


<p>
Does quotes with title also work? No...cannot work in LaTeX and HTML
and then it does not make sense to support it.

<p>
A plain <em>box</em> is sometimes useful. Let's show it here for comparison
with admons (especially the block admon has much in common with a box).
The box is more aimed at framing a law or an equation.

<p>
First a simple block with text, an equation, and a list:

<p>

<!-- begin box -->
<div style="width: 95%; padding: 10px; border: 1px solid #000; border-radius: 4px;">
A generic equation

$$ f(x) = 0 $$

must be solved by a numerical method, such as

<ul>
 <li> Newton's method</li>
 <li> The Bisection method</li>
 <li> Fixed-point (Picard) iteration by rewriting \( f(x)=x - g(x) \)</li>
 <li> The Secant method</li>
</ul>
</div>
<!-- end box -->

Now test a box with equation only (note that this line continues the
box, it is not a new paragraph):

<p>

<!-- begin box -->
<div style="width: 95%; padding: 10px; border: 1px solid #000; border-radius: 4px;">
$$
\begin{equation} f(x) = \sin(x)e^{1-x}  \label{_auto1}
\end{equation}
$$
</div>
<!-- end box -->


<p>
<b>Hint.</b>

Newton's method requires a good start vector to converge fast.



<p>
Let's begin a new paragraph and show a box with code only:

<p>

<!-- begin box -->
<div style="width: 95%; padding: 10px; border: 1px solid #000; border-radius: 4px;">
<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">some_code</span>(x):
    <span style="color: #008000; font-weight: bold">return</span> sin(x)<span style="color: #666666">*</span>exp(<span style="color: #666666">1-</span>x)
</pre></div>
<p>
</div>
<!-- end box -->


<h2 id="admonitions">Admonitions </h2>

<p>
Let us start with a plain warning environment.

<p>
<div class="warning alert-text-normal"><b>Warning</b>
And here is a warning about something to pay attention to. We
test how the heading behave and add quite some extra texts
in comparison with the other admons.

<ul>
  <li> and a list</li>
  <li> with items</li>
</ul>

We continue with more text to see how that affects the layout.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
</div>


<p>
Test warning with title:

<p>
<div class="warning alert-text-large"><b>Title ending with math \( \sqrt{2}\approx 1.4 \)</b>
And here comes some text with bad news in larger font.

<p>
Also some code:

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #FEEFB3"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">f</span>(x):
    <span style="color: #008000; font-weight: bold">return</span> x
</pre></div>
<p>
And a complete program

<p>

<!-- code=python (!bc pypro) typeset with pygments style "default" -->
<div class="highlight" style="background: #FEEFB3"><pre style="line-height: 125%;"><span></span><span style="color: #008000">print</span>(<span style="color: #BA2121">&quot;Hello, World!&quot;</span>)
</pre></div>
<p>
</div>


<p>
Test warning with large title with math:

<p>
<div class="warning alert-text-large"><b>Watch out for \( \nabla\cdot\boldsymbol{u}=0 \) equations</b>
Divergence freedom is often problematic from a numerical point
of view.
</div>


<p>
Then we test a block, which is guaranteed to never have any admon icon.

<p>
<div class="block alert-text-small"><b>Block with title</b>
Here is a block of text with title. It is typeset
<em>without any icon</em> and is useful when you want some admons with icon
and some without. With the small font size, as used here, one can have
more comment-style text or text that really goes deeper or talks
about fun facts that are not strictly necessary for the main flow
of understanding.
</div>


<p>
<div class="block alert-text-normal"><b></b>
Here is a block of text with no title. As above, it is typeset without any icon
and is useful when you want some admons with icon and some without.
</div>


<p>
<!-- Note that the final ! does not appear in Sphinx and reST since -->
<!-- those formats automatically add : to the admonition title. -->

<p>
<div class="notice alert-text-illegal-size"><b>Note, eventually!</b>
Ah, we are soon close to the end (with illegal font size specification!).
But first a bit of math where we define \( \theta \) and \( \boldsymbol{r} \):

$$
\begin{align*}
\theta &= q^2,\\
\boldsymbol{r} &= \varrho\boldsymbol{i}
\end{align*}
$$
</div>


<p>
<!-- Test one word with a number -->

<p>
<div class="notice alert-text-normal"><b>Point1</b>
Ah, we are soon close to the end.
</div>


<p>
<div class="question alert-text-normal"><b>Question</b>
So, how many admonition environments does DocOnce support?
</div>


<p>
<div class="question alert-text-normal"><b>Question</b>

<ol>
 <li> Once more, how many admonition environments does DocOnce support?</li>
</ol>
</div>


<p>
<div class="warning alert-text-normal"><b>Tip</b>
It is of outmost important to

<ol>
<li> stay cool</li>
<li> read hints and tips carefully</li>
</ol>

Because here the thing is to do

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #FEEFB3"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">import</span> <span style="color: #0000FF; font-weight: bold">urllib</span>

<span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">grab</span>(url, filename):
    urllib<span style="color: #666666">.</span>urlretrieve(url, filename<span style="color: #666666">=</span>filename)
</pre></div>
<p>
</div>


<p>
Next is a warning without a title ("none" implies no title).

<p>
<div class="warning alert-text-normal"><b></b>
And here comes some text with bad news.
</div>


<h2 id="going-deeper-environments">Going deeper environments </h2>

<p>
Here is a long notice environment with a custom title and much
text, math and code.

<p>
<div class="notice alert-text-normal"><b>Going deeper.</b>
We have some equations that should be preceded by much text, so the
task is to write and write. The number of words, and not the
meaning, is what counts here. We need desperately to fill up the
page in the hope that some admonitions will experience a page break,
which the LaTeX environment should handle with ease.

<p>
Let us start with some equations:

$$
\begin{align*}
\frac{Du}{dt} &= 0
\\
\frac{1}{2} &= {1/2}\\
\frac{1}{2}\pmb{x} &= \pmb{n}
\end{align*}
$$

<p>
The implementation of such complicated equations in computer
code is task that this "Going deeper" environment targets.

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #BDE5F8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">Dudt</span>(u):
    r <span style="color: #666666">=</span> diff(u, t) <span style="color: #666666">+</span> u<span style="color: #666666">*</span>grad(u)
    <span style="color: #008000; font-weight: bold">return</span> r

half <span style="color: #666666">=</span> <span style="color: #666666">0.5</span>
x <span style="color: #666666">=</span> <span style="color: #666666">2*</span>n
</pre></div>
<p>
And some more text that can help going into the next page.
Longer computer code requires vertical space:

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #BDE5F8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Diff</span>:
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__init__</span>(<span style="color: #008000">self</span>, f, h<span style="color: #666666">=1E-5</span>):
        <span style="color: #008000">self</span><span style="color: #666666">.</span>f <span style="color: #666666">=</span> f
        <span style="color: #008000">self</span><span style="color: #666666">.</span>h <span style="color: #666666">=</span> <span style="color: #008000">float</span>(h)

<span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Forward1</span>(Diff):
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__call__</span>(<span style="color: #008000">self</span>, x):
        f, h <span style="color: #666666">=</span> <span style="color: #008000">self</span><span style="color: #666666">.</span>f, <span style="color: #008000">self</span><span style="color: #666666">.</span>h
        <span style="color: #008000; font-weight: bold">return</span> (f(x<span style="color: #666666">+</span>h) <span style="color: #666666">-</span> f(x))<span style="color: #666666">/</span>h

<span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Backward1</span>(Diff):
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__call__</span>(<span style="color: #008000">self</span>, x):
        f, h <span style="color: #666666">=</span> <span style="color: #008000">self</span><span style="color: #666666">.</span>f, <span style="color: #008000">self</span><span style="color: #666666">.</span>h
        <span style="color: #008000; font-weight: bold">return</span> (f(x) <span style="color: #666666">-</span> f(x<span style="color: #666666">-</span>h))<span style="color: #666666">/</span>h

<span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Central2</span>(Diff):
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__call__</span>(<span style="color: #008000">self</span>, x):
        f, h <span style="color: #666666">=</span> <span style="color: #008000">self</span><span style="color: #666666">.</span>f, <span style="color: #008000">self</span><span style="color: #666666">.</span>h
        <span style="color: #008000; font-weight: bold">return</span> (f(x<span style="color: #666666">+</span>h) <span style="color: #666666">-</span> f(x<span style="color: #666666">-</span>h))<span style="color: #666666">/</span>(<span style="color: #666666">2*</span>h)

<span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Central4</span>(Diff):
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__call__</span>(<span style="color: #008000">self</span>, x):
        f, h <span style="color: #666666">=</span> <span style="color: #008000">self</span><span style="color: #666666">.</span>f, <span style="color: #008000">self</span><span style="color: #666666">.</span>h
        <span style="color: #008000; font-weight: bold">return</span> (<span style="color: #666666">4./3</span>)<span style="color: #666666">*</span>(f(x<span style="color: #666666">+</span>h)   <span style="color: #666666">-</span> f(x<span style="color: #666666">-</span>h))  <span style="color: #666666">/</span>(<span style="color: #666666">2*</span>h) <span style="color: #666666">-</span> \
               (<span style="color: #666666">1./3</span>)<span style="color: #666666">*</span>(f(x<span style="color: #666666">+2*</span>h) <span style="color: #666666">-</span> f(x<span style="color: #666666">-2*</span>h))<span style="color: #666666">/</span>(<span style="color: #666666">4*</span>h)

<span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Central6</span>(Diff):
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__call__</span>(<span style="color: #008000">self</span>, x):
        f, h <span style="color: #666666">=</span> <span style="color: #008000">self</span><span style="color: #666666">.</span>f, <span style="color: #008000">self</span><span style="color: #666666">.</span>h
        <span style="color: #008000; font-weight: bold">return</span> (<span style="color: #666666">3./2</span>) <span style="color: #666666">*</span>(f(x<span style="color: #666666">+</span>h)   <span style="color: #666666">-</span> f(x<span style="color: #666666">-</span>h))  <span style="color: #666666">/</span>(<span style="color: #666666">2*</span>h) <span style="color: #666666">-</span> \
               (<span style="color: #666666">3./5</span>) <span style="color: #666666">*</span>(f(x<span style="color: #666666">+2*</span>h) <span style="color: #666666">-</span> f(x<span style="color: #666666">-2*</span>h))<span style="color: #666666">/</span>(<span style="color: #666666">4*</span>h) <span style="color: #666666">+</span> \
               (<span style="color: #666666">1./10</span>)<span style="color: #666666">*</span>(f(x<span style="color: #666666">+3*</span>h) <span style="color: #666666">-</span> f(x<span style="color: #666666">-3*</span>h))<span style="color: #666666">/</span>(<span style="color: #666666">6*</span>h)

<span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Forward3</span>(Diff):
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__call__</span>(<span style="color: #008000">self</span>, x):
        f, h <span style="color: #666666">=</span> <span style="color: #008000">self</span><span style="color: #666666">.</span>f, <span style="color: #008000">self</span><span style="color: #666666">.</span>h
        <span style="color: #008000; font-weight: bold">return</span> (<span style="color: #666666">-</span>(<span style="color: #666666">1./6</span>)<span style="color: #666666">*</span>f(x<span style="color: #666666">+2*</span>h) <span style="color: #666666">+</span> f(x<span style="color: #666666">+</span>h) <span style="color: #666666">-</span> <span style="color: #666666">0.5*</span>f(x) <span style="color: #666666">-</span> \
                (<span style="color: #666666">1./3</span>)<span style="color: #666666">*</span>f(x<span style="color: #666666">-</span>h))<span style="color: #666666">/</span>h
</pre></div>
<p>
And then we add a figure too.

<p>
<br /><br /><center><p><img src="../doc/src/manual/fig/wave1D.png" align="bottom" width=400></p></center><br /><br />
</div>


<h2 id="the-end">The end </h2>

<p>
A bit of text before the summary, which we now call "Concluding remarks,
for the novice",
just because we can.

<p>
<div class="summary alert-text-normal"><b>Concluding remarks, for the novice</b>
We can summarize the most important things with admons: they have
a different typesetting, and they may have a symbol.
Titles should be optional.
</div>


<p>
<b>Remark.</b>
The <code>remarks</code> and <code>hint</code> environments are not allowed outside
exercises (and problems and projects too).

<!-- ------------------- end of main content --------------- -->


<center style="font-size:80%">
<!-- copyright --> &copy; 2021, H. P. Langtangen. Made with <a href="https://github.com/hplgit/doconce">DocOnce</a>
</center>


</body>
</html>
    


************** File: admon_gray.html *****************
<!--
Automatically generated HTML file from DocOnce source
(https://github.com/doconce/doconce/)
-->
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="DocOnce: https://github.com/doconce/doconce/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="description" content="Testing admons">

<title>Testing admons</title>


<style type="text/css">
/* blueish2 style (as blueish style, but different pre and code tags
   (only effective if not pygments is used))
*/

/* Color definitions:  https://www.december.com/html/spec/color0.html
   CSS examples:       https://www.w3schools.com/css/css_examples.asp */

body {
  margin-top: 1.0em;
  background-color: #ffffff;
  font-family: Helvetica, Arial, FreeSans, san-serif;
  color: #000000;
}
h1 { font-size: 1.8em; color: #1e36ce; }
h2 { font-size: 1.6em; color: #1e36ce; }
h3 { font-size: 1.4em; color: #1e36ce; }
a { color: #1e36ce; text-decoration:none; }
tt { font-family: "Courier New", Courier; }
/* pre style removed because it will interfer with pygments */
/* pre, code style removed because it will interfer with pygments */
p { text-indent: 0px; }
hr { border: 0; width: 80%; border-bottom: 1px solid #aaa}
p.caption { width: 80%; font-style: normal; text-align: left; }
hr.figure { border: 0; width: 80%; border-bottom: 1px solid #aaa}
.alert-text-small   { font-size: 80%;  }
.alert-text-large   { font-size: 130%; }
.alert-text-normal  { font-size: 90%;  }
.alert {
  padding:8px 35px 8px 14px; margin-bottom:18px;
  text-shadow:0 1px 0 rgba(255,255,255,0.5);
  border:1px solid #bababa;
  border-radius: 4px; box-shadow: 8px 8px 5px #888888;
  -webkit-border-radius: 4px; -webkit-box-shadow: 8px 8px 5px #888888;
  -moz-border-radius: 4px; -moz-box-shadow: 8px 8px 5px #888888;
  color: #555;
  background-color: #f8f8f8;
  background-position: 10px 5px;
  background-repeat: no-repeat;
  background-size: 38px;
  padding-left: 55px;
  width: 75%;
 }
.alert-block {padding-top:14px; padding-bottom:14px}
.alert-block > p, .alert-block > ul {margin-bottom:1em}
.alert li {margin-top: 1em}
.alert-block p+p {margin-top:5px}
.alert-notice { background-image: url(https://raw.github.com/doconce/doconce/master/bundled/html_images/small_gray_notice.png); }
.alert-summary  { background-image:url(https://raw.github.com/doconce/doconce/master/bundled/html_images/small_gray_summary.png); }
.alert-warning { background-image: url(https://raw.github.com/doconce/doconce/master/bundled/html_images/small_gray_warning.png); }
.alert-question {background-image:url(https://raw.github.com/doconce/doconce/master/bundled/html_images/small_gray_question.png); }

div { text-align: justify; text-justify: inter-word; }
</style>


</head>

<!-- tocinfo
{'highest level': 1,
 'sections': [('Introduction', 1, None, 'introduction'),
              ('Code', 2, None, 'code'),
              ('Quotes and boxes', 2, None, 'quotes-and-boxes'),
              ('Admonitions', 2, None, 'admonitions'),
              ('Going deeper environments',
               2,
               None,
               'going-deeper-environments'),
              ('The end', 2, None, 'the-end')]}
end of tocinfo -->

<body>



<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  TeX: {
     equationNumbers: {  autoNumber: "AMS"  },
     extensions: ["AMSmath.js", "AMSsymbols.js", "autobold.js", "color.js"]
  }
});
</script>
<script type="text/javascript" async
 src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>



    
<!-- ------------------- main content ---------------------- -->



<center><h1>Testing admons</h1></center>  <!-- document title -->

<p>
<!-- author(s): H. P. Langtangen -->

<center>
<b>H. P. Langtangen</b> 
</center>

<p>
<!-- institution(s) -->

<br>
<p>
<center><h4>Jan 32, 2100</h4></center> <!-- date -->
<br>
<p>
<!-- !split -->

<h1 id="introduction">Introduction </h1>
First some ordinary text to compare font sizes in admonitions
and the surrounding text.

<h2 id="code">Code </h2>

<p>
Need some code outside admons for color and font comparisons:

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">some_code</span>(x):
    <span style="color: #008000; font-weight: bold">return</span> sin(x)<span style="color: #666666">*</span>exp(<span style="color: #666666">1-</span>x)
</pre></div>
<p>
And some plain text verbatim:

<p>

<!-- code=text typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>x=1.0 y=0.9 z=0.4
x=1.1 y=0.3 z=0.1
</pre></div>

<h2 id="quotes-and-boxes">Quotes and boxes </h2>

<p>
Here is a plain quote environment.

<p>
<blockquote>
    Sayre's law states that
    &quot;in any dispute the intensity of feeling is inversely
    proportional to the value of the issues at stake.&quot; <br />
    By way of corollary, it adds: <br />
    &quot;That is why academic politics are so bitter.&quot; <br />
    <em>Source</em>: <a href="https://en.wikipedia.org/wiki/Sayre's_law" target="_self">wikipedia</a>
</blockquote>


<p>
Does quotes with title also work? No...cannot work in LaTeX and HTML
and then it does not make sense to support it.

<p>
A plain <em>box</em> is sometimes useful. Let's show it here for comparison
with admons (especially the block admon has much in common with a box).
The box is more aimed at framing a law or an equation.

<p>
First a simple block with text, an equation, and a list:

<p>

<!-- begin box -->
<div style="width: 95%; padding: 10px; border: 1px solid #000; border-radius: 4px; box-shadow: 8px 8px 5px #888888;">
A generic equation

$$ f(x) = 0 $$

must be solved by a numerical method, such as

<ul>
 <li> Newton's method</li>
 <li> The Bisection method</li>
 <li> Fixed-point (Picard) iteration by rewriting \( f(x)=x - g(x) \)</li>
 <li> The Secant method</li>
</ul>
</div>
<!-- end box -->

Now test a box with equation only (note that this line continues the
box, it is not a new paragraph):

<p>

<!-- begin box -->
<div style="width: 95%; padding: 10px; border: 1px solid #000; border-radius: 4px; box-shadow: 8px 8px 5px #888888;">
$$
\begin{equation} f(x) = \sin(x)e^{1-x}  \label{_auto1}
\end{equation}
$$
</div>
<!-- end box -->


<p>
<b>Hint.</b>

Newton's method requires a good start vector to converge fast.



<p>
Let's begin a new paragraph and show a box with code only:

<p>

<!-- begin box -->
<div style="width: 95%; padding: 10px; border: 1px solid #000; border-radius: 4px; box-shadow: 8px 8px 5px #888888;">
<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">some_code</span>(x):
    <span style="color: #008000; font-weight: bold">return</span> sin(x)<span style="color: #666666">*</span>exp(<span style="color: #666666">1-</span>x)
</pre></div>
<p>
</div>
<!-- end box -->


<h2 id="admonitions">Admonitions </h2>

<p>
Let us start with a plain warning environment.

<p>
<div class="alert alert-block alert-warning alert-text-normal">
<b>Warning</b>
<p>
And here is a warning about something to pay attention to. We
test how the heading behave and add quite some extra texts
in comparison with the other admons.

<ul>
  <li> and a list</li>
  <li> with items</li>
</ul>

We continue with more text to see how that affects the layout.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
</div>


<p>
Test warning with title:

<p>
<div class="alert alert-block alert-warning alert-text-large">
<b>Title ending with math \( \sqrt{2}\approx 1.4 \)</b>
<p>
And here comes some text with bad news in larger font.

<p>
Also some code:

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">f</span>(x):
    <span style="color: #008000; font-weight: bold">return</span> x
</pre></div>
<p>
And a complete program

<p>

<!-- code=python (!bc pypro) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000">print</span>(<span style="color: #BA2121">&quot;Hello, World!&quot;</span>)
</pre></div>

</div>


<p>
Test warning with large title with math:

<p>
<div class="alert alert-block alert-warning alert-text-large">
<b>Watch out for \( \nabla\cdot\boldsymbol{u}=0 \) equations</b>
<p>
Divergence freedom is often problematic from a numerical point
of view.
</div>


<p>
Then we test a block, which is guaranteed to never have any admon icon.

<p>
<div class="alert alert-block alert-block alert-text-small">
<b>Block with title</b>
<p>
Here is a block of text with title. It is typeset
<em>without any icon</em> and is useful when you want some admons with icon
and some without. With the small font size, as used here, one can have
more comment-style text or text that really goes deeper or talks
about fun facts that are not strictly necessary for the main flow
of understanding.
</div>


<p>
<div class="alert alert-block alert-block alert-text-normal">
<b></b>
<p>
Here is a block of text with no title. As above, it is typeset without any icon
and is useful when you want some admons with icon and some without.
</div>


<p>
<!-- Note that the final ! does not appear in Sphinx and reST since -->
<!-- those formats automatically add : to the admonition title. -->

<p>
<div class="alert alert-block alert-notice alert-text-illegal-size">
<b>Note, eventually!</b>
<p>
Ah, we are soon close to the end (with illegal font size specification!).
But first a bit of math where we define \( \theta \) and \( \boldsymbol{r} \):

$$
\begin{align*}
\theta &= q^2,\\
\boldsymbol{r} &= \varrho\boldsymbol{i}
\end{align*}
$$
</div>


<p>
<!-- Test one word with a number -->

<p>
<div class="alert alert-block alert-notice alert-text-normal">
<b>Point1</b>
<p>
Ah, we are soon close to the end.
</div>


<p>
<div class="alert alert-block alert-question alert-text-normal">
<b>Question</b>
<p>
So, how many admonition environments does DocOnce support?
</div>


<p>
<div class="alert alert-block alert-question alert-text-normal">
<b>Question</b>
<p>

<ol>
 <li> Once more, how many admonition environments does DocOnce support?</li>
</ol>
</div>


<p>
<div class="alert alert-block alert-warning alert-text-normal">
<b>Tip</b>
<p>
It is of outmost important to

<ol>
<li> stay cool</li>
<li> read hints and tips carefully</li>
</ol>

Because here the thing is to do

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">import</span> <span style="color: #0000FF; font-weight: bold">urllib</span>

<span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">grab</span>(url, filename):
    urllib<span style="color: #666666">.</span>urlretrieve(url, filename<span style="color: #666666">=</span>filename)
</pre></div>

</div>


<p>
Next is a warning without a title ("none" implies no title).

<p>
<div class="alert alert-block alert-warning alert-text-normal">
<b></b>
<p>
And here comes some text with bad news.
</div>


<h2 id="going-deeper-environments">Going deeper environments </h2>

<p>
Here is a long notice environment with a custom title and much
text, math and code.

<p>
<div class="alert alert-block alert-notice alert-text-normal">
<b>Going deeper.</b>
<p>
We have some equations that should be preceded by much text, so the
task is to write and write. The number of words, and not the
meaning, is what counts here. We need desperately to fill up the
page in the hope that some admonitions will experience a page break,
which the LaTeX environment should handle with ease.

<p>
Let us start with some equations:

$$
\begin{align*}
\frac{Du}{dt} &= 0
\\
\frac{1}{2} &= {1/2}\\
\frac{1}{2}\pmb{x} &= \pmb{n}
\end{align*}
$$

<p>
The implementation of such complicated equations in computer
code is task that this "Going deeper" environment targets.

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">Dudt</span>(u):
    r <span style="color: #666666">=</span> diff(u, t) <span style="color: #666666">+</span> u<span style="color: #666666">*</span>grad(u)
    <span style="color: #008000; font-weight: bold">return</span> r

half <span style="color: #666666">=</span> <span style="color: #666666">0.5</span>
x <span style="color: #666666">=</span> <span style="color: #666666">2*</span>n
</pre></div>
<p>
And some more text that can help going into the next page.
Longer computer code requires vertical space:

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Diff</span>:
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__init__</span>(<span style="color: #008000">self</span>, f, h<span style="color: #666666">=1E-5</span>):
        <span style="color: #008000">self</span><span style="color: #666666">.</span>f <span style="color: #666666">=</span> f
        <span style="color: #008000">self</span><span style="color: #666666">.</span>h <span style="color: #666666">=</span> <span style="color: #008000">float</span>(h)

<span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Forward1</span>(Diff):
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__call__</span>(<span style="color: #008000">self</span>, x):
        f, h <span style="color: #666666">=</span> <span style="color: #008000">self</span><span style="color: #666666">.</span>f, <span style="color: #008000">self</span><span style="color: #666666">.</span>h
        <span style="color: #008000; font-weight: bold">return</span> (f(x<span style="color: #666666">+</span>h) <span style="color: #666666">-</span> f(x))<span style="color: #666666">/</span>h

<span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Backward1</span>(Diff):
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__call__</span>(<span style="color: #008000">self</span>, x):
        f, h <span style="color: #666666">=</span> <span style="color: #008000">self</span><span style="color: #666666">.</span>f, <span style="color: #008000">self</span><span style="color: #666666">.</span>h
        <span style="color: #008000; font-weight: bold">return</span> (f(x) <span style="color: #666666">-</span> f(x<span style="color: #666666">-</span>h))<span style="color: #666666">/</span>h

<span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Central2</span>(Diff):
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__call__</span>(<span style="color: #008000">self</span>, x):
        f, h <span style="color: #666666">=</span> <span style="color: #008000">self</span><span style="color: #666666">.</span>f, <span style="color: #008000">self</span><span style="color: #666666">.</span>h
        <span style="color: #008000; font-weight: bold">return</span> (f(x<span style="color: #666666">+</span>h) <span style="color: #666666">-</span> f(x<span style="color: #666666">-</span>h))<span style="color: #666666">/</span>(<span style="color: #666666">2*</span>h)

<span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Central4</span>(Diff):
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__call__</span>(<span style="color: #008000">self</span>, x):
        f, h <span style="color: #666666">=</span> <span style="color: #008000">self</span><span style="color: #666666">.</span>f, <span style="color: #008000">self</span><span style="color: #666666">.</span>h
        <span style="color: #008000; font-weight: bold">return</span> (<span style="color: #666666">4./3</span>)<span style="color: #666666">*</span>(f(x<span style="color: #666666">+</span>h)   <span style="color: #666666">-</span> f(x<span style="color: #666666">-</span>h))  <span style="color: #666666">/</span>(<span style="color: #666666">2*</span>h) <span style="color: #666666">-</span> \
               (<span style="color: #666666">1./3</span>)<span style="color: #666666">*</span>(f(x<span style="color: #666666">+2*</span>h) <span style="color: #666666">-</span> f(x<span style="color: #666666">-2*</span>h))<span style="color: #666666">/</span>(<span style="color: #666666">4*</span>h)

<span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Central6</span>(Diff):
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__call__</span>(<span style="color: #008000">self</span>, x):
        f, h <span style="color: #666666">=</span> <span style="color: #008000">self</span><span style="color: #666666">.</span>f, <span style="color: #008000">self</span><span style="color: #666666">.</span>h
        <span style="color: #008000; font-weight: bold">return</span> (<span style="color: #666666">3./2</span>) <span style="color: #666666">*</span>(f(x<span style="color: #666666">+</span>h)   <span style="color: #666666">-</span> f(x<span style="color: #666666">-</span>h))  <span style="color: #666666">/</span>(<span style="color: #666666">2*</span>h) <span style="color: #666666">-</span> \
               (<span style="color: #666666">3./5</span>) <span style="color: #666666">*</span>(f(x<span style="color: #666666">+2*</span>h) <span style="color: #666666">-</span> f(x<span style="color: #666666">-2*</span>h))<span style="color: #666666">/</span>(<span style="color: #666666">4*</span>h) <span style="color: #666666">+</span> \
               (<span style="color: #666666">1./10</span>)<span style="color: #666666">*</span>(f(x<span style="color: #666666">+3*</span>h) <span style="color: #666666">-</span> f(x<span style="color: #666666">-3*</span>h))<span style="color: #666666">/</span>(<span style="color: #666666">6*</span>h)

<span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Forward3</span>(Diff):
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__call__</span>(<span style="color: #008000">self</span>, x):
        f, h <span style="color: #666666">=</span> <span style="color: #008000">self</span><span style="color: #666666">.</span>f, <span style="color: #008000">self</span><span style="color: #666666">.</span>h
        <span style="color: #008000; font-weight: bold">return</span> (<span style="color: #666666">-</span>(<span style="color: #666666">1./6</span>)<span style="color: #666666">*</span>f(x<span style="color: #666666">+2*</span>h) <span style="color: #666666">+</span> f(x<span style="color: #666666">+</span>h) <span style="color: #666666">-</span> <span style="color: #666666">0.5*</span>f(x) <span style="color: #666666">-</span> \
                (<span style="color: #666666">1./3</span>)<span style="color: #666666">*</span>f(x<span style="color: #666666">-</span>h))<span style="color: #666666">/</span>h
</pre></div>
<p>
And then we add a figure too.

<p>
<br /><br /><center><p><img src="../doc/src/manual/fig/wave1D.png" align="bottom" width=400></p></center><br /><br />
</div>


<h2 id="the-end">The end </h2>

<p>
A bit of text before the summary, which we now call "Concluding remarks,
for the novice",
just because we can.

<p>
<div class="alert alert-block alert-summary alert-text-normal">
<b>Concluding remarks, for the novice</b>
<p>
We can summarize the most important things with admons: they have
a different typesetting, and they may have a symbol.
Titles should be optional.
</div>


<p>
<b>Remark.</b>
The <code>remarks</code> and <code>hint</code> environments are not allowed outside
exercises (and problems and projects too).

<!-- ------------------- end of main content --------------- -->


<center style="font-size:80%">
<!-- copyright --> &copy; 2021, H. P. Langtangen. Made with <a href="https://github.com/hplgit/doconce">DocOnce</a>
</center>


</body>
</html>
    


************** File: admon_yellow.html *****************
<!--
Automatically generated HTML file from DocOnce source
(https://github.com/doconce/doconce/)
-->
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="DocOnce: https://github.com/doconce/doconce/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="description" content="Testing admons">

<title>Testing admons</title>


<style type="text/css">
/* blueish style */

/* Color definitions:  https://www.december.com/html/spec/color0.html
   CSS examples:       https://www.w3schools.com/css/css_examples.asp */

body {
  margin-top: 1.0em;
  background-color: #ffffff;
  font-family: Helvetica, Arial, FreeSans, san-serif;
  color: #000000;
}
h1 { font-size: 1.8em; color: #1e36ce; }
h2 { font-size: 1.6em; color: #1e36ce; }
h3 { font-size: 1.4em; color: #1e36ce; }
a { color: #1e36ce; text-decoration:none; }
tt { font-family: "Courier New", Courier; }
/* pre style removed because it will interfer with pygments */
p { text-indent: 0px; }
hr { border: 0; width: 80%; border-bottom: 1px solid #aaa}
p.caption { width: 80%; font-style: normal; text-align: left; }
hr.figure { border: 0; width: 80%; border-bottom: 1px solid #aaa}
.alert-text-small   { font-size: 80%;  }
.alert-text-large   { font-size: 130%; }
.alert-text-normal  { font-size: 90%;  }
.alert {
  padding:8px 35px 8px 14px; margin-bottom:18px;
  text-shadow:0 1px 0 rgba(255,255,255,0.5);
  border:1px solid #fbeed5;
  border-radius: 4px; box-shadow: 8px 8px 5px #888888;
  -webkit-border-radius: 4px; -webkit-box-shadow: 8px 8px 5px #888888;
  -moz-border-radius: 4px; -moz-box-shadow: 8px 8px 5px #888888;
  color: #555;
  background-color: #fcf8e3;
  background-position: 10px 5px;
  background-repeat: no-repeat;
  background-size: 38px;
  padding-left: 55px;
  width: 75%;
 }
.alert-block {padding-top:14px; padding-bottom:14px}
.alert-block > p, .alert-block > ul {margin-bottom:1em}
.alert li {margin-top: 1em}
.alert-block p+p {margin-top:5px}
.alert-notice { background-image: url(https://raw.github.com/doconce/doconce/master/bundled/html_images/small_yellow_notice.png); }
.alert-summary  { background-image:url(https://raw.github.com/doconce/doconce/master/bundled/html_images/small_yellow_summary.png); }
.alert-warning { background-image: url(https://raw.github.com/doconce/doconce/master/bundled/html_images/small_yellow_warning.png); }
.alert-question {background-image:url(https://raw.github.com/doconce/doconce/master/bundled/html_images/small_yellow_question.png); }

div { text-align: justify; text-justify: inter-word; }
</style>


</head>

<!-- tocinfo
{'highest level': 1,
 'sections': [('Introduction', 1, None, 'introduction'),
              ('Code', 2, None, 'code'),
              ('Quotes and boxes', 2, None, 'quotes-and-boxes'),
              ('Admonitions', 2, None, 'admonitions'),
              ('Going deeper environments',
               2,
               None,
               'going-deeper-environments'),
              ('The end', 2, None, 'the-end')]}
end of tocinfo -->

<body>



<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  TeX: {
     equationNumbers: {  autoNumber: "AMS"  },
     extensions: ["AMSmath.js", "AMSsymbols.js", "autobold.js", "color.js"]
  }
});
</script>
<script type="text/javascript" async
 src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>



    
<!-- ------------------- main content ---------------------- -->



<center><h1>Testing admons</h1></center>  <!-- document title -->

<p>
<!-- author(s): H. P. Langtangen -->

<center>
<b>H. P. Langtangen</b> 
</center>

<p>
<!-- institution(s) -->

<br>
<p>
<center><h4>Jan 32, 2100</h4></center> <!-- date -->
<br>
<p>
<!-- !split -->

<h1 id="introduction">Introduction </h1>
First some ordinary text to compare font sizes in admonitions
and the surrounding text.

<h2 id="code">Code </h2>

<p>
Need some code outside admons for color and font comparisons:

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">some_code</span>(x):
    <span style="color: #008000; font-weight: bold">return</span> sin(x)<span style="color: #666666">*</span>exp(<span style="color: #666666">1-</span>x)
</pre></div>
<p>
And some plain text verbatim:

<p>

<!-- code=text typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>x=1.0 y=0.9 z=0.4
x=1.1 y=0.3 z=0.1
</pre></div>

<h2 id="quotes-and-boxes">Quotes and boxes </h2>

<p>
Here is a plain quote environment.

<p>
<blockquote>
    Sayre's law states that
    &quot;in any dispute the intensity of feeling is inversely
    proportional to the value of the issues at stake.&quot; <br />
    By way of corollary, it adds: <br />
    &quot;That is why academic politics are so bitter.&quot; <br />
    <em>Source</em>: <a href="https://en.wikipedia.org/wiki/Sayre's_law" target="_self">wikipedia</a>
</blockquote>


<p>
Does quotes with title also work? No...cannot work in LaTeX and HTML
and then it does not make sense to support it.

<p>
A plain <em>box</em> is sometimes useful. Let's show it here for comparison
with admons (especially the block admon has much in common with a box).
The box is more aimed at framing a law or an equation.

<p>
First a simple block with text, an equation, and a list:

<p>

<!-- begin box -->
<div style="width: 95%; padding: 10px; border: 1px solid #000; border-radius: 4px; box-shadow: 8px 8px 5px #888888;">
A generic equation

$$ f(x) = 0 $$

must be solved by a numerical method, such as

<ul>
 <li> Newton's method</li>
 <li> The Bisection method</li>
 <li> Fixed-point (Picard) iteration by rewriting \( f(x)=x - g(x) \)</li>
 <li> The Secant method</li>
</ul>
</div>
<!-- end box -->

Now test a box with equation only (note that this line continues the
box, it is not a new paragraph):

<p>

<!-- begin box -->
<div style="width: 95%; padding: 10px; border: 1px solid #000; border-radius: 4px; box-shadow: 8px 8px 5px #888888;">
$$
\begin{equation} f(x) = \sin(x)e^{1-x}  \label{_auto1}
\end{equation}
$$
</div>
<!-- end box -->


<p>
<b>Hint.</b>

Newton's method requires a good start vector to converge fast.



<p>
Let's begin a new paragraph and show a box with code only:

<p>

<!-- begin box -->
<div style="width: 95%; padding: 10px; border: 1px solid #000; border-radius: 4px; box-shadow: 8px 8px 5px #888888;">
<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">some_code</span>(x):
    <span style="color: #008000; font-weight: bold">return</span> sin(x)<span style="color: #666666">*</span>exp(<span style="color: #666666">1-</span>x)
</pre></div>
<p>
</div>
<!-- end box -->


<h2 id="admonitions">Admonitions </h2>

<p>
Let us start with a plain warning environment.

<p>
<div class="alert alert-block alert-warning alert-text-normal">
<b>Warning</b>
<p>
And here is a warning about something to pay attention to. We
test how the heading behave and add quite some extra texts
in comparison with the other admons.

<ul>
  <li> and a list</li>
  <li> with items</li>
</ul>

We continue with more text to see how that affects the layout.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
</div>


<p>
Test warning with title:

<p>
<div class="alert alert-block alert-warning alert-text-large">
<b>Title ending with math \( \sqrt{2}\approx 1.4 \)</b>
<p>
And here comes some text with bad news in larger font.

<p>
Also some code:

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #fcf8e3"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">f</span>(x):
    <span style="color: #008000; font-weight: bold">return</span> x
</pre></div>
<p>
And a complete program

<p>

<!-- code=python (!bc pypro) typeset with pygments style "default" -->
<div class="highlight" style="background: #fcf8e3"><pre style="line-height: 125%;"><span></span><span style="color: #008000">print</span>(<span style="color: #BA2121">&quot;Hello, World!&quot;</span>)
</pre></div>

</div>


<p>
Test warning with large title with math:

<p>
<div class="alert alert-block alert-warning alert-text-large">
<b>Watch out for \( \nabla\cdot\boldsymbol{u}=0 \) equations</b>
<p>
Divergence freedom is often problematic from a numerical point
of view.
</div>


<p>
Then we test a block, which is guaranteed to never have any admon icon.

<p>
<div class="alert alert-block alert-block alert-text-small">
<b>Block with title</b>
<p>
Here is a block of text with title. It is typeset
<em>without any icon</em> and is useful when you want some admons with icon
and some without. With the small font size, as used here, one can have
more comment-style text or text that really goes deeper or talks
about fun facts that are not strictly necessary for the main flow
of understanding.
</div>


<p>
<div class="alert alert-block alert-block alert-text-normal">
<b></b>
<p>
Here is a block of text with no title. As above, it is typeset without any icon
and is useful when you want some admons with icon and some without.
</div>


<p>
<!-- Note that the final ! does not appear in Sphinx and reST since -->
<!-- those formats automatically add : to the admonition title. -->

<p>
<div class="alert alert-block alert-notice alert-text-illegal-size">
<b>Note, eventually!</b>
<p>
Ah, we are soon close to the end (with illegal font size specification!).
But first a bit of math where we define \( \theta \) and \( \boldsymbol{r} \):

$$
\begin{align*}
\theta &= q^2,\\
\boldsymbol{r} &= \varrho\boldsymbol{i}
\end{align*}
$$
</div>


<p>
<!-- Test one word with a number -->

<p>
<div class="alert alert-block alert-notice alert-text-normal">
<b>Point1</b>
<p>
Ah, we are soon close to the end.
</div>


<p>
<div class="alert alert-block alert-question alert-text-normal">
<b>Question</b>
<p>
So, how many admonition environments does DocOnce support?
</div>


<p>
<div class="alert alert-block alert-question alert-text-normal">
<b>Question</b>
<p>

<ol>
 <li> Once more, how many admonition environments does DocOnce support?</li>
</ol>
</div>


<p>
<div class="alert alert-block alert-warning alert-text-normal">
<b>Tip</b>
<p>
It is of outmost important to

<ol>
<li> stay cool</li>
<li> read hints and tips carefully</li>
</ol>

Because here the thing is to do

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #fcf8e3"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">import</span> <span style="color: #0000FF; font-weight: bold">urllib</span>

<span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">grab</span>(url, filename):
    urllib<span style="color: #666666">.</span>urlretrieve(url, filename<span style="color: #666666">=</span>filename)
</pre></div>

</div>


<p>
Next is a warning without a title ("none" implies no title).

<p>
<div class="alert alert-block alert-warning alert-text-normal">
<b></b>
<p>
And here comes some text with bad news.
</div>


<h2 id="going-deeper-environments">Going deeper environments </h2>

<p>
Here is a long notice environment with a custom title and much
text, math and code.

<p>
<div class="alert alert-block alert-notice alert-text-normal">
<b>Going deeper.</b>
<p>
We have some equations that should be preceded by much text, so the
task is to write and write. The number of words, and not the
meaning, is what counts here. We need desperately to fill up the
page in the hope that some admonitions will experience a page break,
which the LaTeX environment should handle with ease.

<p>
Let us start with some equations:

$$
\begin{align*}
\frac{Du}{dt} &= 0
\\
\frac{1}{2} &= {1/2}\\
\frac{1}{2}\pmb{x} &= \pmb{n}
\end{align*}
$$

<p>
The implementation of such complicated equations in computer
code is task that this "Going deeper" environment targets.

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #fcf8e3"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">Dudt</span>(u):
    r <span style="color: #666666">=</span> diff(u, t) <span style="color: #666666">+</span> u<span style="color: #666666">*</span>grad(u)
    <span style="color: #008000; font-weight: bold">return</span> r

half <span style="color: #666666">=</span> <span style="color: #666666">0.5</span>
x <span style="color: #666666">=</span> <span style="color: #666666">2*</span>n
</pre></div>
<p>
And some more text that can help going into the next page.
Longer computer code requires vertical space:

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #fcf8e3"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Diff</span>:
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__init__</span>(<span style="color: #008000">self</span>, f, h<span style="color: #666666">=1E-5</span>):
        <span style="color: #008000">self</span><span style="color: #666666">.</span>f <span style="color: #666666">=</span> f
        <span style="color: #008000">self</span><span style="color: #666666">.</span>h <span style="color: #666666">=</span> <span style="color: #008000">float</span>(h)

<span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Forward1</span>(Diff):
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__call__</span>(<span style="color: #008000">self</span>, x):
        f, h <span style="color: #666666">=</span> <span style="color: #008000">self</span><span style="color: #666666">.</span>f, <span style="color: #008000">self</span><span style="color: #666666">.</span>h
        <span style="color: #008000; font-weight: bold">return</span> (f(x<span style="color: #666666">+</span>h) <span style="color: #666666">-</span> f(x))<span style="color: #666666">/</span>h

<span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Backward1</span>(Diff):
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__call__</span>(<span style="color: #008000">self</span>, x):
        f, h <span style="color: #666666">=</span> <span style="color: #008000">self</span><span style="color: #666666">.</span>f, <span style="color: #008000">self</span><span style="color: #666666">.</span>h
        <span style="color: #008000; font-weight: bold">return</span> (f(x) <span style="color: #666666">-</span> f(x<span style="color: #666666">-</span>h))<span style="color: #666666">/</span>h

<span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Central2</span>(Diff):
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__call__</span>(<span style="color: #008000">self</span>, x):
        f, h <span style="color: #666666">=</span> <span style="color: #008000">self</span><span style="color: #666666">.</span>f, <span style="color: #008000">self</span><span style="color: #666666">.</span>h
        <span style="color: #008000; font-weight: bold">return</span> (f(x<span style="color: #666666">+</span>h) <span style="color: #666666">-</span> f(x<span style="color: #666666">-</span>h))<span style="color: #666666">/</span>(<span style="color: #666666">2*</span>h)

<span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Central4</span>(Diff):
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__call__</span>(<span style="color: #008000">self</span>, x):
        f, h <span style="color: #666666">=</span> <span style="color: #008000">self</span><span style="color: #666666">.</span>f, <span style="color: #008000">self</span><span style="color: #666666">.</span>h
        <span style="color: #008000; font-weight: bold">return</span> (<span style="color: #666666">4./3</span>)<span style="color: #666666">*</span>(f(x<span style="color: #666666">+</span>h)   <span style="color: #666666">-</span> f(x<span style="color: #666666">-</span>h))  <span style="color: #666666">/</span>(<span style="color: #666666">2*</span>h) <span style="color: #666666">-</span> \
               (<span style="color: #666666">1./3</span>)<span style="color: #666666">*</span>(f(x<span style="color: #666666">+2*</span>h) <span style="color: #666666">-</span> f(x<span style="color: #666666">-2*</span>h))<span style="color: #666666">/</span>(<span style="color: #666666">4*</span>h)

<span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Central6</span>(Diff):
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__call__</span>(<span style="color: #008000">self</span>, x):
        f, h <span style="color: #666666">=</span> <span style="color: #008000">self</span><span style="color: #666666">.</span>f, <span style="color: #008000">self</span><span style="color: #666666">.</span>h
        <span style="color: #008000; font-weight: bold">return</span> (<span style="color: #666666">3./2</span>) <span style="color: #666666">*</span>(f(x<span style="color: #666666">+</span>h)   <span style="color: #666666">-</span> f(x<span style="color: #666666">-</span>h))  <span style="color: #666666">/</span>(<span style="color: #666666">2*</span>h) <span style="color: #666666">-</span> \
               (<span style="color: #666666">3./5</span>) <span style="color: #666666">*</span>(f(x<span style="color: #666666">+2*</span>h) <span style="color: #666666">-</span> f(x<span style="color: #666666">-2*</span>h))<span style="color: #666666">/</span>(<span style="color: #666666">4*</span>h) <span style="color: #666666">+</span> \
               (<span style="color: #666666">1./10</span>)<span style="color: #666666">*</span>(f(x<span style="color: #666666">+3*</span>h) <span style="color: #666666">-</span> f(x<span style="color: #666666">-3*</span>h))<span style="color: #666666">/</span>(<span style="color: #666666">6*</span>h)

<span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Forward3</span>(Diff):
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__call__</span>(<span style="color: #008000">self</span>, x):
        f, h <span style="color: #666666">=</span> <span style="color: #008000">self</span><span style="color: #666666">.</span>f, <span style="color: #008000">self</span><span style="color: #666666">.</span>h
        <span style="color: #008000; font-weight: bold">return</span> (<span style="color: #666666">-</span>(<span style="color: #666666">1./6</span>)<span style="color: #666666">*</span>f(x<span style="color: #666666">+2*</span>h) <span style="color: #666666">+</span> f(x<span style="color: #666666">+</span>h) <span style="color: #666666">-</span> <span style="color: #666666">0.5*</span>f(x) <span style="color: #666666">-</span> \
                (<span style="color: #666666">1./3</span>)<span style="color: #666666">*</span>f(x<span style="color: #666666">-</span>h))<span style="color: #666666">/</span>h
</pre></div>
<p>
And then we add a figure too.

<p>
<br /><br /><center><p><img src="../doc/src/manual/fig/wave1D.png" align="bottom" width=400></p></center><br /><br />
</div>


<h2 id="the-end">The end </h2>

<p>
A bit of text before the summary, which we now call "Concluding remarks,
for the novice",
just because we can.

<p>
<div class="alert alert-block alert-summary alert-text-normal">
<b>Concluding remarks, for the novice</b>
<p>
We can summarize the most important things with admons: they have
a different typesetting, and they may have a symbol.
Titles should be optional.
</div>


<p>
<b>Remark.</b>
The <code>remarks</code> and <code>hint</code> environments are not allowed outside
exercises (and problems and projects too).

<!-- ------------------- end of main content --------------- -->


<center style="font-size:80%">
<!-- copyright --> &copy; 2021, H. P. Langtangen. Made with <a href="https://github.com/hplgit/doconce">DocOnce</a>
</center>


</body>
</html>
    


************** File: admon_sphinx/admon.html *****************

<!DOCTYPE html>

<html lang="1.0">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Testing admons &#8212; _ H. P. Langtangen documentation</title>
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    <link rel="stylesheet" href="_static/classic.css" type="text/css" />
    <link rel="stylesheet" type="text/css" href="_static/graphviz.css" />
    
    <script id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
    <script src="_static/jquery.js"></script>
    <script src="_static/underscore.js"></script>
    <script src="_static/doctools.js"></script>
    <script src="_static/language_data.js"></script>
    <script async="async" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/latest.js?config=TeX-AMS-MML_HTMLorMML"></script>
    
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="prev" title="Testing admons" href="index.html" /> 
  
       <style type="text/css">
         div.admonition {
           background-color: whiteSmoke;
           border: 1px solid #bababa;
         }
       </style>
      </head>
    <body>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="index.html" title="Testing admons"
             accesskey="P">previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="index.html">_ H. P. Langtangen documentation</a> &#187;</li>
        <li class="nav-item nav-item-this"><a href="">Testing admons</a></li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <div class="section" id="testing-admons">
<h1>Testing admons<a class="headerlink" href="#testing-admons" title="Permalink to this headline">¶</a></h1>
<dl class="field-list simple">
<dt class="field-odd">Authors</dt>
<dd class="field-odd"><ol class="upperalpha simple" start="8">
<li><ol class="upperalpha simple" start="16">
<li><p>Langtangen</p></li>
</ol>
</li>
</ol>
</dd>
<dt class="field-even">Date</dt>
<dd class="field-even"><p>Jan 32, 2100</p>
</dd>
</dl>
<div class="section" id="introduction">
<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
<p>First some ordinary text to compare font sizes in admonitions
and the surrounding text.</p>
<p>Note that <code class="docutils literal notranslate"><span class="pre">automake_sphinx.py</span></code> fixes the HTML file generated by Sphinx
so that all styles for admonitions have a colored background.</p>
<div class="section" id="code">
<h3>Code<a class="headerlink" href="#code" title="Permalink to this headline">¶</a></h3>
<p>Need some code outside admons for color and font comparisons:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">some_code</span><span class="p">(</span><span class="n">x</span><span class="p">):</span>
    <span class="k">return</span> <span class="n">sin</span><span class="p">(</span><span class="n">x</span><span class="p">)</span><span class="o">*</span><span class="n">exp</span><span class="p">(</span><span class="mi">1</span><span class="o">-</span><span class="n">x</span><span class="p">)</span>
</pre></div>
</div>
<p>And some plain text verbatim:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>x=1.0 y=0.9 z=0.4
x=1.1 y=0.3 z=0.1
</pre></div>
</div>
</div>
<div class="section" id="quotes-and-boxes">
<h3>Quotes and boxes<a class="headerlink" href="#quotes-and-boxes" title="Permalink to this headline">¶</a></h3>
<p>Here is a plain quote environment.</p>
<blockquote>
<div><p>Sayre's law states that
&quot;in any dispute the intensity of feeling is inversely
proportional to the value of the issues at stake.&quot;</p>
<div class="line-block">
<div class="line">By way of corollary, it adds:</div>
<div class="line">&quot;That is why academic politics are so bitter.&quot;</div>
<div class="line"><em>Source</em>: <a class="reference external" href="https://en.wikipedia.org/wiki/Sayre's_law">wikipedia</a></div>
</div>
</div></blockquote>
<p>Does quotes with title also work? No...cannot work in LaTeX and HTML
and then it does not make sense to support it.</p>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>The boxes below are shown without any extra formatting in reST
and Sphinx. We could use an admonition environment, but requires
a title.</p>
</div>
<p>A plain <em>box</em> is sometimes useful. Let's show it here for comparison
with admons (especially the block admon has much in common with a box).
The box is more aimed at framing a law or an equation.</p>
<p>First a simple block with text, an equation, and a list:</p>
<p>A generic equation</p>
<div class="math notranslate nohighlight">
\[f(x) = 0\]</div>
<p>must be solved by a numerical method, such as</p>
<blockquote>
<div><ul class="simple">
<li><p>Newton's method</p></li>
<li><p>The Bisection method</p></li>
<li><p>Fixed-point (Picard) iteration by rewriting <span class="math notranslate nohighlight">\(f(x)=x - g(x)\)</span></p></li>
<li><p>The Secant method</p></li>
</ul>
</div></blockquote>
<p>Now test a box with equation only (note that this line continues the
box, it is not a new paragraph):</p>
<div class="math notranslate nohighlight" id="equation-auto1">
<span class="eqno">(1)<a class="headerlink" href="#equation-auto1" title="Permalink to this equation">¶</a></span>\[      f(x) = \sin(x)e^{1-x}\]</div>
<p><strong>Hint.</strong></p>
<p>Newton's method requires a good start vector to converge fast.</p>
<p>Let's begin a new paragraph and show a box with code only:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">some_code</span><span class="p">(</span><span class="n">x</span><span class="p">):</span>
    <span class="k">return</span> <span class="n">sin</span><span class="p">(</span><span class="n">x</span><span class="p">)</span><span class="o">*</span><span class="n">exp</span><span class="p">(</span><span class="mi">1</span><span class="o">-</span><span class="n">x</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="admonitions">
<h3>Admonitions<a class="headerlink" href="#admonitions" title="Permalink to this headline">¶</a></h3>
<p>Let us start with a plain warning environment.</p>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>And here is a warning about something to pay attention to. We
test how the heading behave and add quite some extra texts
in comparison with the other admons.</p>
<blockquote>
<div><ul class="simple">
<li><p>and a list</p></li>
<li><p>with items</p></li>
</ul>
</div></blockquote>
<p>We continue with more text to see how that affects the layout.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
And more and more text.</p>
</div>
<p>Test warning with title:</p>
<div class="admonition-title-ending-with-math-math-sqrt-2-approx-1-4 admonition">
<p class="admonition-title">Title ending with math <span class="math notranslate nohighlight">\(\sqrt{2}\approx 1.4\)</span></p>
<p>And here comes some text with bad news in larger font.</p>
<p>Also some code:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">f</span><span class="p">(</span><span class="n">x</span><span class="p">):</span>
    <span class="k">return</span> <span class="n">x</span>
</pre></div>
</div>
<p>And a complete program</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Hello, World!&quot;</span><span class="p">)</span>
</pre></div>
</div>
</div>
<p>Test warning with large title with math:
(we have no impact on the font size in the title in Sphinx)</p>
<div class="admonition-watch-out-for-math-nabla-cdot-boldsymbol-u-0-equations admonition">
<p class="admonition-title">Watch out for <span class="math notranslate nohighlight">\(\nabla\cdot\boldsymbol{u}=0\)</span> equations</p>
<p>Divergence freedom is often problematic from a numerical point
of view.</p>
</div>
<p>Then we test a block, which is guaranteed to never have any admon icon.</p>
<div class="admonition-block-with-title admonition">
<p class="admonition-title">Block with title</p>
<p>Here is a block of text with title. It is typeset
<em>without any icon</em> and is useful when you want some admons with icon
and some without. With the small font size, as used here, one can have
more comment-style text or text that really goes deeper or talks
about fun facts that are not strictly necessary for the main flow
of understanding.</p>
</div>
<p>Admonitions must have a title in Sphinx, otherwise they are not
shown. Here, for the following <em>block admon</em> (<code class="docutils literal notranslate"><span class="pre">!bblock</span></code>)
we have not specified any title, and DocOnce then
applies the generic title &quot;Notice:&quot; for the Sphinx format:</p>
<div class="admonition-notice admonition">
<p class="admonition-title">Notice</p>
<p>Here is a block of text with no title. As above, it is typeset without any icon
and is useful when you want some admons with icon and some without.</p>
</div>
<div class="admonition-note-eventually admonition">
<p class="admonition-title">Note, eventually</p>
<p>Ah, we are soon close to the end (with illegal font size specification!).
But first a bit of math where we define <span class="math notranslate nohighlight">\(\theta\)</span> and <span class="math notranslate nohighlight">\(\boldsymbol{r}\)</span>:</p>
<div class="math notranslate nohighlight">
\[\begin{split}\begin{align*}
\theta &amp;= q^2,\\
\boldsymbol{r} &amp;= \varrho\boldsymbol{i}
\end{align*}\end{split}\]</div>
</div>
<div class="admonition-point1 admonition">
<p class="admonition-title">Point1</p>
<p>Ah, we are soon close to the end.</p>
</div>
<div class="admonition-question admonition">
<p class="admonition-title">Question</p>
<p>So, how many admonition environments does DocOnce support?</p>
</div>
<div class="admonition-question admonition">
<p class="admonition-title">Question</p>
<ol class="arabic simple">
<li><p>Once more, how many admonition environments does DocOnce support?</p></li>
</ol>
</div>
<div class="admonition-tip admonition">
<p class="admonition-title">Tip</p>
<p>It is of outmost important to</p>
<ol class="arabic simple">
<li><p>stay cool</p></li>
<li><p>read hints and tips carefully</p></li>
</ol>
<p>Because here the thing is to do</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">urllib</span>

<span class="k">def</span> <span class="nf">grab</span><span class="p">(</span><span class="n">url</span><span class="p">,</span> <span class="n">filename</span><span class="p">):</span>
    <span class="n">urllib</span><span class="o">.</span><span class="n">urlretrieve</span><span class="p">(</span><span class="n">url</span><span class="p">,</span> <span class="n">filename</span><span class="o">=</span><span class="n">filename</span><span class="p">)</span>
</pre></div>
</div>
</div>
<p>Next is a warning without a title (&quot;none&quot; implies no title).
Admonitions must have a title in Sphinx, otherwise they are not
shown. Here, we have not specified any title, and DocOnce then
applies the generic title &quot;Notice:&quot;</p>
<div class="admonition-notice admonition">
<p class="admonition-title">Notice</p>
<p>And here comes some text with bad news.</p>
</div>
</div>
<div class="section" id="going-deeper-environments">
<h3>Going deeper environments<a class="headerlink" href="#going-deeper-environments" title="Permalink to this headline">¶</a></h3>
<p>Here is a long notice environment with a custom title and much
text, math and code.</p>
<div class="admonition-going-deeper admonition">
<p class="admonition-title">Going deeper</p>
<p>We have some equations that should be preceded by much text, so the
task is to write and write. The number of words, and not the
meaning, is what counts here. We need desperately to fill up the
page in the hope that some admonitions will experience a page break,
which the LaTeX environment should handle with ease.</p>
<p>Let us start with some equations:</p>
<div class="math notranslate nohighlight">
\[\begin{split}\begin{align*}
\frac{Du}{dt} &amp;= 0
\\
\frac{1}{2} &amp;= {1/2}\\
\frac{1}{2}\pmb{x} &amp;= \pmb{n}
\end{align*}\end{split}\]</div>
<p>The implementation of such complicated equations in computer
code is task that this &quot;Going deeper&quot; environment targets.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">Dudt</span><span class="p">(</span><span class="n">u</span><span class="p">):</span>
    <span class="n">r</span> <span class="o">=</span> <span class="n">diff</span><span class="p">(</span><span class="n">u</span><span class="p">,</span> <span class="n">t</span><span class="p">)</span> <span class="o">+</span> <span class="n">u</span><span class="o">*</span><span class="n">grad</span><span class="p">(</span><span class="n">u</span><span class="p">)</span>
    <span class="k">return</span> <span class="n">r</span>

<span class="n">half</span> <span class="o">=</span> <span class="mf">0.5</span>
<span class="n">x</span> <span class="o">=</span> <span class="mi">2</span><span class="o">*</span><span class="n">n</span>
</pre></div>
</div>
<p>And some more text that can help going into the next page.
Longer computer code requires vertical space:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Diff</span><span class="p">:</span>
    <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">f</span><span class="p">,</span> <span class="n">h</span><span class="o">=</span><span class="mf">1E-5</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">f</span> <span class="o">=</span> <span class="n">f</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">h</span> <span class="o">=</span> <span class="nb">float</span><span class="p">(</span><span class="n">h</span><span class="p">)</span>

<span class="k">class</span> <span class="nc">Forward1</span><span class="p">(</span><span class="n">Diff</span><span class="p">):</span>
    <span class="k">def</span> <span class="fm">__call__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">x</span><span class="p">):</span>
        <span class="n">f</span><span class="p">,</span> <span class="n">h</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">f</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">h</span>
        <span class="k">return</span> <span class="p">(</span><span class="n">f</span><span class="p">(</span><span class="n">x</span><span class="o">+</span><span class="n">h</span><span class="p">)</span> <span class="o">-</span> <span class="n">f</span><span class="p">(</span><span class="n">x</span><span class="p">))</span><span class="o">/</span><span class="n">h</span>

<span class="k">class</span> <span class="nc">Backward1</span><span class="p">(</span><span class="n">Diff</span><span class="p">):</span>
    <span class="k">def</span> <span class="fm">__call__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">x</span><span class="p">):</span>
        <span class="n">f</span><span class="p">,</span> <span class="n">h</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">f</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">h</span>
        <span class="k">return</span> <span class="p">(</span><span class="n">f</span><span class="p">(</span><span class="n">x</span><span class="p">)</span> <span class="o">-</span> <span class="n">f</span><span class="p">(</span><span class="n">x</span><span class="o">-</span><span class="n">h</span><span class="p">))</span><span class="o">/</span><span class="n">h</span>

<span class="k">class</span> <span class="nc">Central2</span><span class="p">(</span><span class="n">Diff</span><span class="p">):</span>
    <span class="k">def</span> <span class="fm">__call__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">x</span><span class="p">):</span>
        <span class="n">f</span><span class="p">,</span> <span class="n">h</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">f</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">h</span>
        <span class="k">return</span> <span class="p">(</span><span class="n">f</span><span class="p">(</span><span class="n">x</span><span class="o">+</span><span class="n">h</span><span class="p">)</span> <span class="o">-</span> <span class="n">f</span><span class="p">(</span><span class="n">x</span><span class="o">-</span><span class="n">h</span><span class="p">))</span><span class="o">/</span><span class="p">(</span><span class="mi">2</span><span class="o">*</span><span class="n">h</span><span class="p">)</span>

<span class="k">class</span> <span class="nc">Central4</span><span class="p">(</span><span class="n">Diff</span><span class="p">):</span>
    <span class="k">def</span> <span class="fm">__call__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">x</span><span class="p">):</span>
        <span class="n">f</span><span class="p">,</span> <span class="n">h</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">f</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">h</span>
        <span class="k">return</span> <span class="p">(</span><span class="mf">4.</span><span class="o">/</span><span class="mi">3</span><span class="p">)</span><span class="o">*</span><span class="p">(</span><span class="n">f</span><span class="p">(</span><span class="n">x</span><span class="o">+</span><span class="n">h</span><span class="p">)</span>   <span class="o">-</span> <span class="n">f</span><span class="p">(</span><span class="n">x</span><span class="o">-</span><span class="n">h</span><span class="p">))</span>  <span class="o">/</span><span class="p">(</span><span class="mi">2</span><span class="o">*</span><span class="n">h</span><span class="p">)</span> <span class="o">-</span> \
               <span class="p">(</span><span class="mf">1.</span><span class="o">/</span><span class="mi">3</span><span class="p">)</span><span class="o">*</span><span class="p">(</span><span class="n">f</span><span class="p">(</span><span class="n">x</span><span class="o">+</span><span class="mi">2</span><span class="o">*</span><span class="n">h</span><span class="p">)</span> <span class="o">-</span> <span class="n">f</span><span class="p">(</span><span class="n">x</span><span class="o">-</span><span class="mi">2</span><span class="o">*</span><span class="n">h</span><span class="p">))</span><span class="o">/</span><span class="p">(</span><span class="mi">4</span><span class="o">*</span><span class="n">h</span><span class="p">)</span>

<span class="k">class</span> <span class="nc">Central6</span><span class="p">(</span><span class="n">Diff</span><span class="p">):</span>
    <span class="k">def</span> <span class="fm">__call__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">x</span><span class="p">):</span>
        <span class="n">f</span><span class="p">,</span> <span class="n">h</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">f</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">h</span>
        <span class="k">return</span> <span class="p">(</span><span class="mf">3.</span><span class="o">/</span><span class="mi">2</span><span class="p">)</span> <span class="o">*</span><span class="p">(</span><span class="n">f</span><span class="p">(</span><span class="n">x</span><span class="o">+</span><span class="n">h</span><span class="p">)</span>   <span class="o">-</span> <span class="n">f</span><span class="p">(</span><span class="n">x</span><span class="o">-</span><span class="n">h</span><span class="p">))</span>  <span class="o">/</span><span class="p">(</span><span class="mi">2</span><span class="o">*</span><span class="n">h</span><span class="p">)</span> <span class="o">-</span> \
               <span class="p">(</span><span class="mf">3.</span><span class="o">/</span><span class="mi">5</span><span class="p">)</span> <span class="o">*</span><span class="p">(</span><span class="n">f</span><span class="p">(</span><span class="n">x</span><span class="o">+</span><span class="mi">2</span><span class="o">*</span><span class="n">h</span><span class="p">)</span> <span class="o">-</span> <span class="n">f</span><span class="p">(</span><span class="n">x</span><span class="o">-</span><span class="mi">2</span><span class="o">*</span><span class="n">h</span><span class="p">))</span><span class="o">/</span><span class="p">(</span><span class="mi">4</span><span class="o">*</span><span class="n">h</span><span class="p">)</span> <span class="o">+</span> \
               <span class="p">(</span><span class="mf">1.</span><span class="o">/</span><span class="mi">10</span><span class="p">)</span><span class="o">*</span><span class="p">(</span><span class="n">f</span><span class="p">(</span><span class="n">x</span><span class="o">+</span><span class="mi">3</span><span class="o">*</span><span class="n">h</span><span class="p">)</span> <span class="o">-</span> <span class="n">f</span><span class="p">(</span><span class="n">x</span><span class="o">-</span><span class="mi">3</span><span class="o">*</span><span class="n">h</span><span class="p">))</span><span class="o">/</span><span class="p">(</span><span class="mi">6</span><span class="o">*</span><span class="n">h</span><span class="p">)</span>

<span class="k">class</span> <span class="nc">Forward3</span><span class="p">(</span><span class="n">Diff</span><span class="p">):</span>
    <span class="k">def</span> <span class="fm">__call__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">x</span><span class="p">):</span>
        <span class="n">f</span><span class="p">,</span> <span class="n">h</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">f</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">h</span>
        <span class="k">return</span> <span class="p">(</span><span class="o">-</span><span class="p">(</span><span class="mf">1.</span><span class="o">/</span><span class="mi">6</span><span class="p">)</span><span class="o">*</span><span class="n">f</span><span class="p">(</span><span class="n">x</span><span class="o">+</span><span class="mi">2</span><span class="o">*</span><span class="n">h</span><span class="p">)</span> <span class="o">+</span> <span class="n">f</span><span class="p">(</span><span class="n">x</span><span class="o">+</span><span class="n">h</span><span class="p">)</span> <span class="o">-</span> <span class="mf">0.5</span><span class="o">*</span><span class="n">f</span><span class="p">(</span><span class="n">x</span><span class="p">)</span> <span class="o">-</span> \
                <span class="p">(</span><span class="mf">1.</span><span class="o">/</span><span class="mi">3</span><span class="p">)</span><span class="o">*</span><span class="n">f</span><span class="p">(</span><span class="n">x</span><span class="o">-</span><span class="n">h</span><span class="p">))</span><span class="o">/</span><span class="n">h</span>
</pre></div>
</div>
<p>And then we add a figure too.</p>
<div class="figure align-default">
<a class="reference internal image-reference" href="_images/wave1D.png"><img alt="_images/wave1D.png" src="_images/wave1D.png" style="width: 400px;" /></a>
</div>
</div>
</div>
<div class="section" id="the-end">
<h3>The end<a class="headerlink" href="#the-end" title="Permalink to this headline">¶</a></h3>
<p>A bit of text before the summary, which we now call &quot;Concluding remarks,
for the novice&quot;,
just because we can.</p>
<div class="admonition-concluding-remarks-for-the-novice admonition">
<p class="admonition-title">Concluding remarks, for the novice</p>
<p>We can summarize the most important things with admons: they have
a different typesetting, and they may have a symbol.
Titles should be optional.</p>
</div>
<p><strong>Remark.</strong>
The <code class="docutils literal notranslate"><span class="pre">remarks</span></code> and <code class="docutils literal notranslate"><span class="pre">hint</span></code> environments are not allowed outside
exercises (and problems and projects too).</p>
</div>
</div>
</div>


            <div class="clearer"></div>
          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
  <h3><a href="index.html">Table of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">Testing admons</a><ul>
<li><a class="reference internal" href="#introduction">Introduction</a><ul>
<li><a class="reference internal" href="#code">Code</a></li>
<li><a class="reference internal" href="#quotes-and-boxes">Quotes and boxes</a></li>
<li><a class="reference internal" href="#admonitions">Admonitions</a></li>
<li><a class="reference internal" href="#going-deeper-environments">Going deeper environments</a></li>
<li><a class="reference internal" href="#the-end">The end</a></li>
</ul>
</li>
</ul>
</li>
</ul>

  <h4>Previous topic</h4>
  <p class="topless"><a href="index.html"
                        title="previous chapter">Testing admons</a></p>
  <div role="note" aria-label="source link">
    <h3>This Page</h3>
    <ul class="this-page-menu">
      <li><a href="_sources/admon.rst.txt"
            rel="nofollow">Show Source</a></li>
    </ul>
   </div>
<div id="searchbox" style="display: none" role="search">
  <h3 id="searchlabel">Quick search</h3>
    <div class="searchformwrapper">
    <form class="search" action="search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" />
      <input type="submit" value="Go" />
    </form>
    </div>
</div>
<script>$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="index.html" title="Testing admons"
             >previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="index.html">_ H. P. Langtangen documentation</a> &#187;</li>
        <li class="nav-item nav-item-this"><a href="">Testing admons</a></li> 
      </ul>
    </div>
    <div class="footer" role="contentinfo">
        &#169; Copyright 2021, Testing admons.
      Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.3.1.
    </div>
  </body>
</html>
************** File: admon_lyx.html *****************
<!--
Automatically generated HTML file from DocOnce source
(https://github.com/doconce/doconce/)
-->
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="DocOnce: https://github.com/doconce/doconce/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="description" content="Testing admons">

<title>Testing admons</title>


<style type="text/css">
/* blueish2 style (as blueish style, but different pre and code tags
   (only effective if not pygments is used))
*/

/* Color definitions:  https://www.december.com/html/spec/color0.html
   CSS examples:       https://www.w3schools.com/css/css_examples.asp */

body {
  margin-top: 1.0em;
  background-color: #ffffff;
  font-family: Helvetica, Arial, FreeSans, san-serif;
  color: #000000;
}
h1 { font-size: 1.8em; color: #1e36ce; }
h2 { font-size: 1.6em; color: #1e36ce; }
h3 { font-size: 1.4em; color: #1e36ce; }
a { color: #1e36ce; text-decoration:none; }
tt { font-family: "Courier New", Courier; }
/* pre style removed because it will interfer with pygments */
/* pre, code style removed because it will interfer with pygments */
p { text-indent: 0px; }
hr { border: 0; width: 80%; border-bottom: 1px solid #aaa}
p.caption { width: 80%; font-style: normal; text-align: left; }
hr.figure { border: 0; width: 80%; border-bottom: 1px solid #aaa}
.alert-text-small   { font-size: 80%;  }
.alert-text-large   { font-size: 130%; }
.alert-text-normal  { font-size: 90%;  }

div { text-align: justify; text-justify: inter-word; }
</style>


</head>

<!-- tocinfo
{'highest level': 1,
 'sections': [('Introduction', 1, None, 'introduction'),
              ('Code', 2, None, 'code'),
              ('Quotes and boxes', 2, None, 'quotes-and-boxes'),
              ('Admonitions', 2, None, 'admonitions'),
              ('Going deeper environments',
               2,
               None,
               'going-deeper-environments'),
              ('The end', 2, None, 'the-end')]}
end of tocinfo -->

<body>



<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  TeX: {
     equationNumbers: {  autoNumber: "AMS"  },
     extensions: ["AMSmath.js", "AMSsymbols.js", "autobold.js", "color.js"]
  }
});
</script>
<script type="text/javascript" async
 src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>



    
<!-- ------------------- main content ---------------------- -->



<center><h1>Testing admons</h1></center>  <!-- document title -->

<p>
<!-- author(s): H. P. Langtangen -->

<center>
<b>H. P. Langtangen</b> 
</center>

<p>
<!-- institution(s) -->

<br>
<p>
<center><h4>Jan 32, 2100</h4></center> <!-- date -->
<br>
<p>
<!-- !split -->

<h1 id="introduction">Introduction </h1>
First some ordinary text to compare font sizes in admonitions
and the surrounding text.

<h2 id="code">Code </h2>

<p>
Need some code outside admons for color and font comparisons:

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">some_code</span>(x):
    <span style="color: #008000; font-weight: bold">return</span> sin(x)<span style="color: #666666">*</span>exp(<span style="color: #666666">1-</span>x)
</pre></div>
<p>
And some plain text verbatim:

<p>

<!-- code=text typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>x=1.0 y=0.9 z=0.4
x=1.1 y=0.3 z=0.1
</pre></div>

<h2 id="quotes-and-boxes">Quotes and boxes </h2>

<p>
Here is a plain quote environment.

<p>
<blockquote>
    Sayre's law states that
    &quot;in any dispute the intensity of feeling is inversely
    proportional to the value of the issues at stake.&quot; <br />
    By way of corollary, it adds: <br />
    &quot;That is why academic politics are so bitter.&quot; <br />
    <em>Source</em>: <a href="https://en.wikipedia.org/wiki/Sayre's_law" target="_self">wikipedia</a>
</blockquote>


<p>
Does quotes with title also work? No...cannot work in LaTeX and HTML
and then it does not make sense to support it.

<p>
A plain <em>box</em> is sometimes useful. Let's show it here for comparison
with admons (especially the block admon has much in common with a box).
The box is more aimed at framing a law or an equation.

<p>
First a simple block with text, an equation, and a list:

<p>

<!-- begin box -->
<div style="width: 95%; padding: 10px; border: 1px solid #000; border-radius: 4px;">
A generic equation

$$ f(x) = 0 $$

must be solved by a numerical method, such as

<ul>
 <li> Newton's method</li>
 <li> The Bisection method</li>
 <li> Fixed-point (Picard) iteration by rewriting \( f(x)=x - g(x) \)</li>
 <li> The Secant method</li>
</ul>
</div>
<!-- end box -->

Now test a box with equation only (note that this line continues the
box, it is not a new paragraph):

<p>

<!-- begin box -->
<div style="width: 95%; padding: 10px; border: 1px solid #000; border-radius: 4px;">
$$
\begin{equation} f(x) = \sin(x)e^{1-x}  \label{_auto1}
\end{equation}
$$
</div>
<!-- end box -->


<p>
<b>Hint.</b>

Newton's method requires a good start vector to converge fast.



<p>
Let's begin a new paragraph and show a box with code only:

<p>

<!-- begin box -->
<div style="width: 95%; padding: 10px; border: 1px solid #000; border-radius: 4px;">
<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">some_code</span>(x):
    <span style="color: #008000; font-weight: bold">return</span> sin(x)<span style="color: #666666">*</span>exp(<span style="color: #666666">1-</span>x)
</pre></div>
<p>
</div>
<!-- end box -->


<h2 id="admonitions">Admonitions </h2>

<p>
Let us start with a plain warning environment.

<p>

<table width="95%" border="0">
<tr>
<td width="25" align="center" valign="top">
<img src="https://raw.github.com/doconce/doconce/master/bundled/html_images/lyx_warning.png" hspace="5" alt="warning"></td>
<th align="left" valign="middle"><b>Warning</b></th>
</tr>
<tr><td>&nbsp;</td> <td align="left" valign="top"><p>
<div class="alert-text-normal">And here is a warning about something to pay attention to. We
test how the heading behave and add quite some extra texts
in comparison with the other admons.

<ul>
  <li> and a list</li>
  <li> with items</li>
</ul>

We continue with more text to see how that affects the layout.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
And more and more text.</div>
</p></td></tr>
</table>


<p>
Test warning with title:

<p>

<table width="95%" border="0">
<tr>
<td width="25" align="center" valign="top">
<img src="https://raw.github.com/doconce/doconce/master/bundled/html_images/lyx_warning.png" hspace="5" alt="warning"></td>
<th align="left" valign="middle"><b>Title ending with math \( \sqrt{2}\approx 1.4 \)</b></th>
</tr>
<tr><td>&nbsp;</td> <td align="left" valign="top"><p>
<div class="alert-text-large">And here comes some text with bad news in larger font.

<p>
Also some code:

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">f</span>(x):
    <span style="color: #008000; font-weight: bold">return</span> x
</pre></div>
<p>
And a complete program

<p>

<!-- code=python (!bc pypro) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000">print</span>(<span style="color: #BA2121">&quot;Hello, World!&quot;</span>)
</pre></div>
<p></div>
</p></td></tr>
</table>


<p>
Test warning with large title with math:

<p>

<table width="95%" border="0">
<tr>
<td width="25" align="center" valign="top">
<img src="https://raw.github.com/doconce/doconce/master/bundled/html_images/lyx_warning.png" hspace="5" alt="warning"></td>
<th align="left" valign="middle"><b>Watch out for \( \nabla\cdot\boldsymbol{u}=0 \) equations</b></th>
</tr>
<tr><td>&nbsp;</td> <td align="left" valign="top"><p>
<div class="alert-text-large">Divergence freedom is often problematic from a numerical point
of view.</div>
</p></td></tr>
</table>


<p>
Then we test a block, which is guaranteed to never have any admon icon.

<p>

<table width="95%" border="0">
<tr><th align="left" valign="middle"><b>Block with title</b></th>
</tr>
<tr><td>&nbsp;&nbsp;&nbsp;&nbsp;</td> <td align="left" valign="top"><p>
<div class="alert-text-small">Here is a block of text with title. It is typeset
<em>without any icon</em> and is useful when you want some admons with icon
and some without. With the small font size, as used here, one can have
more comment-style text or text that really goes deeper or talks
about fun facts that are not strictly necessary for the main flow
of understanding.</div>
</p></td></tr>
</table>


<p>

<table width="95%" border="0">
<tr><th align="left" valign="middle"><b></b></th>
</tr>
<tr><td>&nbsp;&nbsp;&nbsp;&nbsp;</td> <td align="left" valign="top"><p>
<div class="alert-text-normal">Here is a block of text with no title. As above, it is typeset without any icon
and is useful when you want some admons with icon and some without.</div>
</p></td></tr>
</table>


<p>
<!-- Note that the final ! does not appear in Sphinx and reST since -->
<!-- those formats automatically add : to the admonition title. -->

<p>

<table width="95%" border="0">
<tr>
<td width="25" align="center" valign="top">
<img src="https://raw.github.com/doconce/doconce/master/bundled/html_images/lyx_notice.png" hspace="5" alt="notice"></td>
<th align="left" valign="middle"><b>Note, eventually!</b></th>
</tr>
<tr><td>&nbsp;</td> <td align="left" valign="top"><p>
<div class="alert-text-illegal-size">Ah, we are soon close to the end (with illegal font size specification!).
But first a bit of math where we define \( \theta \) and \( \boldsymbol{r} \):

$$
\begin{align*}
\theta &= q^2,\\
\boldsymbol{r} &= \varrho\boldsymbol{i}
\end{align*}
$$</div>
</p></td></tr>
</table>


<p>
<!-- Test one word with a number -->

<p>

<table width="95%" border="0">
<tr>
<td width="25" align="center" valign="top">
<img src="https://raw.github.com/doconce/doconce/master/bundled/html_images/lyx_notice.png" hspace="5" alt="notice"></td>
<th align="left" valign="middle"><b>Point1</b></th>
</tr>
<tr><td>&nbsp;</td> <td align="left" valign="top"><p>
<div class="alert-text-normal">Ah, we are soon close to the end.</div>
</p></td></tr>
</table>


<p>

<table width="95%" border="0">
<tr>
<td width="25" align="center" valign="top">
<img src="https://raw.github.com/doconce/doconce/master/bundled/html_images/lyx_question.png" hspace="5" alt="question"></td>
<th align="left" valign="middle"><b>Question</b></th>
</tr>
<tr><td>&nbsp;</td> <td align="left" valign="top"><p>
<div class="alert-text-normal">So, how many admonition environments does DocOnce support?</div>
</p></td></tr>
</table>


<p>

<table width="95%" border="0">
<tr>
<td width="25" align="center" valign="top">
<img src="https://raw.github.com/doconce/doconce/master/bundled/html_images/lyx_question.png" hspace="5" alt="question"></td>
<th align="left" valign="middle"><b>Question</b></th>
</tr>
<tr><td>&nbsp;</td> <td align="left" valign="top"><p>
<div class="alert-text-normal">
<ol>
 <li> Once more, how many admonition environments does DocOnce support?</li>
</ol></div>
</p></td></tr>
</table>


<p>

<table width="95%" border="0">
<tr>
<td width="25" align="center" valign="top">
<img src="https://raw.github.com/doconce/doconce/master/bundled/html_images/lyx_warning.png" hspace="5" alt="warning"></td>
<th align="left" valign="middle"><b>Tip</b></th>
</tr>
<tr><td>&nbsp;</td> <td align="left" valign="top"><p>
<div class="alert-text-normal">It is of outmost important to

<ol>
<li> stay cool</li>
<li> read hints and tips carefully</li>
</ol>

Because here the thing is to do

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">import</span> <span style="color: #0000FF; font-weight: bold">urllib</span>

<span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">grab</span>(url, filename):
    urllib<span style="color: #666666">.</span>urlretrieve(url, filename<span style="color: #666666">=</span>filename)
</pre></div>
<p></div>
</p></td></tr>
</table>


<p>
Next is a warning without a title ("none" implies no title).

<p>

<table width="95%" border="0">
<tr>
<td width="25" align="center" valign="top">
<img src="https://raw.github.com/doconce/doconce/master/bundled/html_images/lyx_warning.png" hspace="5" alt="warning"></td>
<th align="left" valign="middle"><b></b></th>
</tr>
<tr><td>&nbsp;</td> <td align="left" valign="top"><p>
<div class="alert-text-normal">And here comes some text with bad news.</div>
</p></td></tr>
</table>


<h2 id="going-deeper-environments">Going deeper environments </h2>

<p>
Here is a long notice environment with a custom title and much
text, math and code.

<p>

<table width="95%" border="0">
<tr>
<td width="25" align="center" valign="top">
<img src="https://raw.github.com/doconce/doconce/master/bundled/html_images/lyx_notice.png" hspace="5" alt="notice"></td>
<th align="left" valign="middle"><b>Going deeper.</b></th>
</tr>
<tr><td>&nbsp;</td> <td align="left" valign="top"><p>
<div class="alert-text-normal">We have some equations that should be preceded by much text, so the
task is to write and write. The number of words, and not the
meaning, is what counts here. We need desperately to fill up the
page in the hope that some admonitions will experience a page break,
which the LaTeX environment should handle with ease.

<p>
Let us start with some equations:

$$
\begin{align*}
\frac{Du}{dt} &= 0
\\
\frac{1}{2} &= {1/2}\\
\frac{1}{2}\pmb{x} &= \pmb{n}
\end{align*}
$$

<p>
The implementation of such complicated equations in computer
code is task that this "Going deeper" environment targets.

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">Dudt</span>(u):
    r <span style="color: #666666">=</span> diff(u, t) <span style="color: #666666">+</span> u<span style="color: #666666">*</span>grad(u)
    <span style="color: #008000; font-weight: bold">return</span> r

half <span style="color: #666666">=</span> <span style="color: #666666">0.5</span>
x <span style="color: #666666">=</span> <span style="color: #666666">2*</span>n
</pre></div>
<p>
And some more text that can help going into the next page.
Longer computer code requires vertical space:

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Diff</span>:
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__init__</span>(<span style="color: #008000">self</span>, f, h<span style="color: #666666">=1E-5</span>):
        <span style="color: #008000">self</span><span style="color: #666666">.</span>f <span style="color: #666666">=</span> f
        <span style="color: #008000">self</span><span style="color: #666666">.</span>h <span style="color: #666666">=</span> <span style="color: #008000">float</span>(h)

<span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Forward1</span>(Diff):
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__call__</span>(<span style="color: #008000">self</span>, x):
        f, h <span style="color: #666666">=</span> <span style="color: #008000">self</span><span style="color: #666666">.</span>f, <span style="color: #008000">self</span><span style="color: #666666">.</span>h
        <span style="color: #008000; font-weight: bold">return</span> (f(x<span style="color: #666666">+</span>h) <span style="color: #666666">-</span> f(x))<span style="color: #666666">/</span>h

<span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Backward1</span>(Diff):
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__call__</span>(<span style="color: #008000">self</span>, x):
        f, h <span style="color: #666666">=</span> <span style="color: #008000">self</span><span style="color: #666666">.</span>f, <span style="color: #008000">self</span><span style="color: #666666">.</span>h
        <span style="color: #008000; font-weight: bold">return</span> (f(x) <span style="color: #666666">-</span> f(x<span style="color: #666666">-</span>h))<span style="color: #666666">/</span>h

<span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Central2</span>(Diff):
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__call__</span>(<span style="color: #008000">self</span>, x):
        f, h <span style="color: #666666">=</span> <span style="color: #008000">self</span><span style="color: #666666">.</span>f, <span style="color: #008000">self</span><span style="color: #666666">.</span>h
        <span style="color: #008000; font-weight: bold">return</span> (f(x<span style="color: #666666">+</span>h) <span style="color: #666666">-</span> f(x<span style="color: #666666">-</span>h))<span style="color: #666666">/</span>(<span style="color: #666666">2*</span>h)

<span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Central4</span>(Diff):
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__call__</span>(<span style="color: #008000">self</span>, x):
        f, h <span style="color: #666666">=</span> <span style="color: #008000">self</span><span style="color: #666666">.</span>f, <span style="color: #008000">self</span><span style="color: #666666">.</span>h
        <span style="color: #008000; font-weight: bold">return</span> (<span style="color: #666666">4./3</span>)<span style="color: #666666">*</span>(f(x<span style="color: #666666">+</span>h)   <span style="color: #666666">-</span> f(x<span style="color: #666666">-</span>h))  <span style="color: #666666">/</span>(<span style="color: #666666">2*</span>h) <span style="color: #666666">-</span> \
               (<span style="color: #666666">1./3</span>)<span style="color: #666666">*</span>(f(x<span style="color: #666666">+2*</span>h) <span style="color: #666666">-</span> f(x<span style="color: #666666">-2*</span>h))<span style="color: #666666">/</span>(<span style="color: #666666">4*</span>h)

<span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Central6</span>(Diff):
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__call__</span>(<span style="color: #008000">self</span>, x):
        f, h <span style="color: #666666">=</span> <span style="color: #008000">self</span><span style="color: #666666">.</span>f, <span style="color: #008000">self</span><span style="color: #666666">.</span>h
        <span style="color: #008000; font-weight: bold">return</span> (<span style="color: #666666">3./2</span>) <span style="color: #666666">*</span>(f(x<span style="color: #666666">+</span>h)   <span style="color: #666666">-</span> f(x<span style="color: #666666">-</span>h))  <span style="color: #666666">/</span>(<span style="color: #666666">2*</span>h) <span style="color: #666666">-</span> \
               (<span style="color: #666666">3./5</span>) <span style="color: #666666">*</span>(f(x<span style="color: #666666">+2*</span>h) <span style="color: #666666">-</span> f(x<span style="color: #666666">-2*</span>h))<span style="color: #666666">/</span>(<span style="color: #666666">4*</span>h) <span style="color: #666666">+</span> \
               (<span style="color: #666666">1./10</span>)<span style="color: #666666">*</span>(f(x<span style="color: #666666">+3*</span>h) <span style="color: #666666">-</span> f(x<span style="color: #666666">-3*</span>h))<span style="color: #666666">/</span>(<span style="color: #666666">6*</span>h)

<span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Forward3</span>(Diff):
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__call__</span>(<span style="color: #008000">self</span>, x):
        f, h <span style="color: #666666">=</span> <span style="color: #008000">self</span><span style="color: #666666">.</span>f, <span style="color: #008000">self</span><span style="color: #666666">.</span>h
        <span style="color: #008000; font-weight: bold">return</span> (<span style="color: #666666">-</span>(<span style="color: #666666">1./6</span>)<span style="color: #666666">*</span>f(x<span style="color: #666666">+2*</span>h) <span style="color: #666666">+</span> f(x<span style="color: #666666">+</span>h) <span style="color: #666666">-</span> <span style="color: #666666">0.5*</span>f(x) <span style="color: #666666">-</span> \
                (<span style="color: #666666">1./3</span>)<span style="color: #666666">*</span>f(x<span style="color: #666666">-</span>h))<span style="color: #666666">/</span>h
</pre></div>
<p>
And then we add a figure too.

<p>
<br /><br /><center><p><img src="../doc/src/manual/fig/wave1D.png" align="bottom" width=400></p></center><br /><br /></div>
</p></td></tr>
</table>


<h2 id="the-end">The end </h2>

<p>
A bit of text before the summary, which we now call "Concluding remarks,
for the novice",
just because we can.

<p>

<table width="95%" border="0">
<tr>
<td width="25" align="center" valign="top">
<img src="https://raw.github.com/doconce/doconce/master/bundled/html_images/lyx_summary.png" hspace="5" alt="summary"></td>
<th align="left" valign="middle"><b>Concluding remarks, for the novice</b></th>
</tr>
<tr><td>&nbsp;</td> <td align="left" valign="top"><p>
<div class="alert-text-normal">We can summarize the most important things with admons: they have
a different typesetting, and they may have a symbol.
Titles should be optional.</div>
</p></td></tr>
</table>


<p>
<b>Remark.</b>
The <code>remarks</code> and <code>hint</code> environments are not allowed outside
exercises (and problems and projects too).

<!-- ------------------- end of main content --------------- -->


<center style="font-size:80%">
<!-- copyright --> &copy; 2021, H. P. Langtangen. Made with <a href="https://github.com/hplgit/doconce">DocOnce</a>
</center>


</body>
</html>
    


************** File: admon_paragraph.html *****************
<!--
Automatically generated HTML file from DocOnce source
(https://github.com/doconce/doconce/)
-->
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="DocOnce: https://github.com/doconce/doconce/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="description" content="Testing admons">

<title>Testing admons</title>


<style type="text/css">
/* blueish2 style (as blueish style, but different pre and code tags
   (only effective if not pygments is used))
*/

/* Color definitions:  https://www.december.com/html/spec/color0.html
   CSS examples:       https://www.w3schools.com/css/css_examples.asp */

body {
  margin-top: 1.0em;
  background-color: #ffffff;
  font-family: Helvetica, Arial, FreeSans, san-serif;
  color: #000000;
}
h1 { font-size: 1.8em; color: #1e36ce; }
h2 { font-size: 1.6em; color: #1e36ce; }
h3 { font-size: 1.4em; color: #1e36ce; }
a { color: #1e36ce; text-decoration:none; }
tt { font-family: "Courier New", Courier; }
/* pre style removed because it will interfer with pygments */
/* pre, code style removed because it will interfer with pygments */
p { text-indent: 0px; }
hr { border: 0; width: 80%; border-bottom: 1px solid #aaa}
p.caption { width: 80%; font-style: normal; text-align: left; }
hr.figure { border: 0; width: 80%; border-bottom: 1px solid #aaa}
.alert-text-small   { font-size: 80%;  }
.alert-text-large   { font-size: 130%; }
.alert-text-normal  { font-size: 90%;  }

div { text-align: justify; text-justify: inter-word; }
</style>


</head>

<!-- tocinfo
{'highest level': 1,
 'sections': [('Introduction', 1, None, 'introduction'),
              ('Code', 2, None, 'code'),
              ('Quotes and boxes', 2, None, 'quotes-and-boxes'),
              ('Admonitions', 2, None, 'admonitions'),
              ('Going deeper environments',
               2,
               None,
               'going-deeper-environments'),
              ('The end', 2, None, 'the-end')]}
end of tocinfo -->

<body>



<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  TeX: {
     equationNumbers: {  autoNumber: "AMS"  },
     extensions: ["AMSmath.js", "AMSsymbols.js", "autobold.js", "color.js"]
  }
});
</script>
<script type="text/javascript" async
 src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>



    
<!-- ------------------- main content ---------------------- -->



<center><h1>Testing admons</h1></center>  <!-- document title -->

<p>
<!-- author(s): H. P. Langtangen -->

<center>
<b>H. P. Langtangen</b> 
</center>

<p>
<!-- institution(s) -->

<br>
<p>
<center><h4>Jan 32, 2100</h4></center> <!-- date -->
<br>
<p>
<!-- !split -->

<h1 id="introduction">Introduction </h1>
First some ordinary text to compare font sizes in admonitions
and the surrounding text.

<h2 id="code">Code </h2>

<p>
Need some code outside admons for color and font comparisons:

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">some_code</span>(x):
    <span style="color: #008000; font-weight: bold">return</span> sin(x)<span style="color: #666666">*</span>exp(<span style="color: #666666">1-</span>x)
</pre></div>
<p>
And some plain text verbatim:

<p>

<!-- code=text typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>x=1.0 y=0.9 z=0.4
x=1.1 y=0.3 z=0.1
</pre></div>

<h2 id="quotes-and-boxes">Quotes and boxes </h2>

<p>
Here is a plain quote environment.

<p>
<blockquote>
    Sayre's law states that
    &quot;in any dispute the intensity of feeling is inversely
    proportional to the value of the issues at stake.&quot; <br />
    By way of corollary, it adds: <br />
    &quot;That is why academic politics are so bitter.&quot; <br />
    <em>Source</em>: <a href="https://en.wikipedia.org/wiki/Sayre's_law" target="_self">wikipedia</a>
</blockquote>


<p>
Does quotes with title also work? No...cannot work in LaTeX and HTML
and then it does not make sense to support it.

<p>
A plain <em>box</em> is sometimes useful. Let's show it here for comparison
with admons (especially the block admon has much in common with a box).
The box is more aimed at framing a law or an equation.

<p>
First a simple block with text, an equation, and a list:

<p>

<!-- begin box -->
<div style="width: 95%; padding: 10px; border: 1px solid #000; border-radius: 4px;">
A generic equation

$$ f(x) = 0 $$

must be solved by a numerical method, such as

<ul>
 <li> Newton's method</li>
 <li> The Bisection method</li>
 <li> Fixed-point (Picard) iteration by rewriting \( f(x)=x - g(x) \)</li>
 <li> The Secant method</li>
</ul>
</div>
<!-- end box -->

Now test a box with equation only (note that this line continues the
box, it is not a new paragraph):

<p>

<!-- begin box -->
<div style="width: 95%; padding: 10px; border: 1px solid #000; border-radius: 4px;">
$$
\begin{equation} f(x) = \sin(x)e^{1-x}  \label{_auto1}
\end{equation}
$$
</div>
<!-- end box -->


<p>
<b>Hint.</b>

Newton's method requires a good start vector to converge fast.



<p>
Let's begin a new paragraph and show a box with code only:

<p>

<!-- begin box -->
<div style="width: 95%; padding: 10px; border: 1px solid #000; border-radius: 4px;">
<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">some_code</span>(x):
    <span style="color: #008000; font-weight: bold">return</span> sin(x)<span style="color: #666666">*</span>exp(<span style="color: #666666">1-</span>x)
</pre></div>
<p>
</div>
<!-- end box -->


<h2 id="admonitions">Admonitions </h2>

<p>
Let us start with a plain warning environment.

<p>


<!-- admonition: warning, typeset as paragraph -->
<div class="alert-text-normal"><b>Warning</b>
And here is a warning about something to pay attention to. We
test how the heading behave and add quite some extra texts
in comparison with the other admons.

<ul>
  <li> and a list</li>
  <li> with items</li>
</ul>

We continue with more text to see how that affects the layout.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
</div>


<p>
Test warning with title:

<p>


<!-- admonition: warning, typeset as paragraph -->
<div class="alert-text-large"><b>Title ending with math \( \sqrt{2}\approx 1.4 \)</b>
And here comes some text with bad news in larger font.

<p>
Also some code:

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">f</span>(x):
    <span style="color: #008000; font-weight: bold">return</span> x
</pre></div>
<p>
And a complete program

<p>

<!-- code=python (!bc pypro) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000">print</span>(<span style="color: #BA2121">&quot;Hello, World!&quot;</span>)
</pre></div>
<p>
</div>


<p>
Test warning with large title with math:

<p>


<!-- admonition: warning, typeset as paragraph -->
<div class="alert-text-large"><b>Watch out for \( \nabla\cdot\boldsymbol{u}=0 \) equations</b>
Divergence freedom is often problematic from a numerical point
of view.
</div>


<p>
Then we test a block, which is guaranteed to never have any admon icon.

<p>


<!-- admonition: block, typeset as paragraph -->
<div class="alert-text-small"><b>Block with title</b>
Here is a block of text with title. It is typeset
<em>without any icon</em> and is useful when you want some admons with icon
and some without. With the small font size, as used here, one can have
more comment-style text or text that really goes deeper or talks
about fun facts that are not strictly necessary for the main flow
of understanding.
</div>


<p>


<!-- admonition: block, typeset as paragraph -->
<div class="alert-text-normal"><b></b>
Here is a block of text with no title. As above, it is typeset without any icon
and is useful when you want some admons with icon and some without.
</div>


<p>
<!-- Note that the final ! does not appear in Sphinx and reST since -->
<!-- those formats automatically add : to the admonition title. -->

<p>


<!-- admonition: notice, typeset as paragraph -->
<div class="alert-text-illegal-size"><b>Note, eventually!</b>
Ah, we are soon close to the end (with illegal font size specification!).
But first a bit of math where we define \( \theta \) and \( \boldsymbol{r} \):

$$
\begin{align*}
\theta &= q^2,\\
\boldsymbol{r} &= \varrho\boldsymbol{i}
\end{align*}
$$
</div>


<p>
<!-- Test one word with a number -->

<p>


<!-- admonition: notice, typeset as paragraph -->
<div class="alert-text-normal"><b>Point1</b>
Ah, we are soon close to the end.
</div>


<p>


<!-- admonition: question, typeset as paragraph -->
<div class="alert-text-normal"><b>Question</b>
So, how many admonition environments does DocOnce support?
</div>


<p>


<!-- admonition: question, typeset as paragraph -->
<div class="alert-text-normal"><b>Question</b>

<ol>
 <li> Once more, how many admonition environments does DocOnce support?</li>
</ol>
</div>


<p>


<!-- admonition: warning, typeset as paragraph -->
<div class="alert-text-normal"><b>Tip</b>
It is of outmost important to

<ol>
<li> stay cool</li>
<li> read hints and tips carefully</li>
</ol>

Because here the thing is to do

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">import</span> <span style="color: #0000FF; font-weight: bold">urllib</span>

<span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">grab</span>(url, filename):
    urllib<span style="color: #666666">.</span>urlretrieve(url, filename<span style="color: #666666">=</span>filename)
</pre></div>
<p>
</div>


<p>
Next is a warning without a title ("none" implies no title).

<p>


<!-- admonition: warning, typeset as paragraph -->
<div class="alert-text-normal"><b></b>
And here comes some text with bad news.
</div>


<h2 id="going-deeper-environments">Going deeper environments </h2>

<p>
Here is a long notice environment with a custom title and much
text, math and code.

<p>


<!-- admonition: notice, typeset as paragraph -->
<div class="alert-text-normal"><b>Going deeper.</b>
We have some equations that should be preceded by much text, so the
task is to write and write. The number of words, and not the
meaning, is what counts here. We need desperately to fill up the
page in the hope that some admonitions will experience a page break,
which the LaTeX environment should handle with ease.

<p>
Let us start with some equations:

$$
\begin{align*}
\frac{Du}{dt} &= 0
\\
\frac{1}{2} &= {1/2}\\
\frac{1}{2}\pmb{x} &= \pmb{n}
\end{align*}
$$

<p>
The implementation of such complicated equations in computer
code is task that this "Going deeper" environment targets.

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">Dudt</span>(u):
    r <span style="color: #666666">=</span> diff(u, t) <span style="color: #666666">+</span> u<span style="color: #666666">*</span>grad(u)
    <span style="color: #008000; font-weight: bold">return</span> r

half <span style="color: #666666">=</span> <span style="color: #666666">0.5</span>
x <span style="color: #666666">=</span> <span style="color: #666666">2*</span>n
</pre></div>
<p>
And some more text that can help going into the next page.
Longer computer code requires vertical space:

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Diff</span>:
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__init__</span>(<span style="color: #008000">self</span>, f, h<span style="color: #666666">=1E-5</span>):
        <span style="color: #008000">self</span><span style="color: #666666">.</span>f <span style="color: #666666">=</span> f
        <span style="color: #008000">self</span><span style="color: #666666">.</span>h <span style="color: #666666">=</span> <span style="color: #008000">float</span>(h)

<span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Forward1</span>(Diff):
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__call__</span>(<span style="color: #008000">self</span>, x):
        f, h <span style="color: #666666">=</span> <span style="color: #008000">self</span><span style="color: #666666">.</span>f, <span style="color: #008000">self</span><span style="color: #666666">.</span>h
        <span style="color: #008000; font-weight: bold">return</span> (f(x<span style="color: #666666">+</span>h) <span style="color: #666666">-</span> f(x))<span style="color: #666666">/</span>h

<span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Backward1</span>(Diff):
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__call__</span>(<span style="color: #008000">self</span>, x):
        f, h <span style="color: #666666">=</span> <span style="color: #008000">self</span><span style="color: #666666">.</span>f, <span style="color: #008000">self</span><span style="color: #666666">.</span>h
        <span style="color: #008000; font-weight: bold">return</span> (f(x) <span style="color: #666666">-</span> f(x<span style="color: #666666">-</span>h))<span style="color: #666666">/</span>h

<span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Central2</span>(Diff):
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__call__</span>(<span style="color: #008000">self</span>, x):
        f, h <span style="color: #666666">=</span> <span style="color: #008000">self</span><span style="color: #666666">.</span>f, <span style="color: #008000">self</span><span style="color: #666666">.</span>h
        <span style="color: #008000; font-weight: bold">return</span> (f(x<span style="color: #666666">+</span>h) <span style="color: #666666">-</span> f(x<span style="color: #666666">-</span>h))<span style="color: #666666">/</span>(<span style="color: #666666">2*</span>h)

<span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Central4</span>(Diff):
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__call__</span>(<span style="color: #008000">self</span>, x):
        f, h <span style="color: #666666">=</span> <span style="color: #008000">self</span><span style="color: #666666">.</span>f, <span style="color: #008000">self</span><span style="color: #666666">.</span>h
        <span style="color: #008000; font-weight: bold">return</span> (<span style="color: #666666">4./3</span>)<span style="color: #666666">*</span>(f(x<span style="color: #666666">+</span>h)   <span style="color: #666666">-</span> f(x<span style="color: #666666">-</span>h))  <span style="color: #666666">/</span>(<span style="color: #666666">2*</span>h) <span style="color: #666666">-</span> \
               (<span style="color: #666666">1./3</span>)<span style="color: #666666">*</span>(f(x<span style="color: #666666">+2*</span>h) <span style="color: #666666">-</span> f(x<span style="color: #666666">-2*</span>h))<span style="color: #666666">/</span>(<span style="color: #666666">4*</span>h)

<span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Central6</span>(Diff):
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__call__</span>(<span style="color: #008000">self</span>, x):
        f, h <span style="color: #666666">=</span> <span style="color: #008000">self</span><span style="color: #666666">.</span>f, <span style="color: #008000">self</span><span style="color: #666666">.</span>h
        <span style="color: #008000; font-weight: bold">return</span> (<span style="color: #666666">3./2</span>) <span style="color: #666666">*</span>(f(x<span style="color: #666666">+</span>h)   <span style="color: #666666">-</span> f(x<span style="color: #666666">-</span>h))  <span style="color: #666666">/</span>(<span style="color: #666666">2*</span>h) <span style="color: #666666">-</span> \
               (<span style="color: #666666">3./5</span>) <span style="color: #666666">*</span>(f(x<span style="color: #666666">+2*</span>h) <span style="color: #666666">-</span> f(x<span style="color: #666666">-2*</span>h))<span style="color: #666666">/</span>(<span style="color: #666666">4*</span>h) <span style="color: #666666">+</span> \
               (<span style="color: #666666">1./10</span>)<span style="color: #666666">*</span>(f(x<span style="color: #666666">+3*</span>h) <span style="color: #666666">-</span> f(x<span style="color: #666666">-3*</span>h))<span style="color: #666666">/</span>(<span style="color: #666666">6*</span>h)

<span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Forward3</span>(Diff):
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__call__</span>(<span style="color: #008000">self</span>, x):
        f, h <span style="color: #666666">=</span> <span style="color: #008000">self</span><span style="color: #666666">.</span>f, <span style="color: #008000">self</span><span style="color: #666666">.</span>h
        <span style="color: #008000; font-weight: bold">return</span> (<span style="color: #666666">-</span>(<span style="color: #666666">1./6</span>)<span style="color: #666666">*</span>f(x<span style="color: #666666">+2*</span>h) <span style="color: #666666">+</span> f(x<span style="color: #666666">+</span>h) <span style="color: #666666">-</span> <span style="color: #666666">0.5*</span>f(x) <span style="color: #666666">-</span> \
                (<span style="color: #666666">1./3</span>)<span style="color: #666666">*</span>f(x<span style="color: #666666">-</span>h))<span style="color: #666666">/</span>h
</pre></div>
<p>
And then we add a figure too.

<p>
<br /><br /><center><p><img src="../doc/src/manual/fig/wave1D.png" align="bottom" width=400></p></center><br /><br />
</div>


<h2 id="the-end">The end </h2>

<p>
A bit of text before the summary, which we now call "Concluding remarks,
for the novice",
just because we can.

<p>


<!-- admonition: summary, typeset as paragraph -->
<div class="alert-text-normal"><b>Concluding remarks, for the novice</b>
We can summarize the most important things with admons: they have
a different typesetting, and they may have a symbol.
Titles should be optional.
</div>


<p>
<b>Remark.</b>
The <code>remarks</code> and <code>hint</code> environments are not allowed outside
exercises (and problems and projects too).

<!-- ------------------- end of main content --------------- -->


<center style="font-size:80%">
<!-- copyright --> &copy; 2021, H. P. Langtangen. Made with <a href="https://github.com/hplgit/doconce">DocOnce</a>
</center>


</body>
</html>
    


************** File: admon_apricot.html *****************
<!--
Automatically generated HTML file from DocOnce source
(https://github.com/doconce/doconce/)
-->
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="DocOnce: https://github.com/doconce/doconce/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="description" content="Testing admons">

<title>Testing admons</title>


<link href="https://raw.github.com/doconce/doconce/master/bundled/html_styles/style_solarized_box/css/solarized_light_code.css" rel="stylesheet" type="text/css" title="light"/>
<script src="https://raw.github.com/doconce/doconce/master/bundled/html_styles/style_solarized_box/js/highlight.pack.js"></script>
<script>hljs.initHighlightingOnLoad();</script>

<style type="text/css">
/* solarized style */
body {
  margin:5;
  padding:0;
  border:0; /* Remove the border around the viewport in old versions of IE */
  width:100%;
  background: #fdf6e3;
  min-width:600px;	/* Minimum width of layout - remove if not required */
  font-family: Verdana, Helvetica, Arial, sans-serif;
  font-size: 1.0em;
  line-height: 1.3em;
  color: #657b83;
}
a { color: #859900; text-decoration: underline; }
a:hover, a:active { outline:none }
a, a:active, a:visited { color: #859900; }
a:hover { color: #268bd2; }
h1, h2, h3 { margin:.8em 0 .2em 0; padding:0; line-height: 125%; }
h2 { font-variant: small-caps; }
tt, code { font-family: monospace, sans-serif; box-shadow: none; }
hr { border: 0; width: 80%; border-bottom: 1px solid #aaa; }
p { text-indent: 0px; }
p.caption { width: 80%; font-style: normal; text-align: left; }
hr.figure { border: 0; width: 80%; border-bottom: 1px solid #aaa; }
.alert-text-small   { font-size: 80%;  }
.alert-text-large   { font-size: 130%; }
.alert-text-normal  { font-size: 90%;  }
.alert {
  padding:8px 35px 8px 14px; margin-bottom:18px;
  text-shadow:0 1px 0 rgba(255,255,255,0.5);
  border:1px solid #FFBF00;
  border-radius: 4px;
  -webkit-border-radius: 4px;
  -moz-border-radius: 4px;
  color: #555;
  background-color: #fbeed5;
  background-position: 10px 5px;
  background-repeat: no-repeat;
  background-size: 38px;
  padding-left: 55px;
  width: 75%;
 }
.alert-block {padding-top:14px; padding-bottom:14px}
.alert-block > p, .alert-block > ul {margin-bottom:1em}
.alert li {margin-top: 1em}
.alert-block p+p {margin-top:5px}
.alert-notice { background-image: url(https://raw.github.com/doconce/doconce/master/bundled/html_images/small_yellow_notice.png); }
.alert-summary  { background-image:url(https://raw.github.com/doconce/doconce/master/bundled/html_images/small_yellow_summary.png); }
.alert-warning { background-image: url(https://raw.github.com/doconce/doconce/master/bundled/html_images/small_yellow_warning.png); }
.alert-question {background-image:url(https://raw.github.com/doconce/doconce/master/bundled/html_images/small_yellow_question.png); }

div { text-align: justify; text-justify: inter-word; }
</style>


</head>

<!-- tocinfo
{'highest level': 1,
 'sections': [('Introduction', 1, None, 'introduction'),
              ('Code', 2, None, 'code'),
              ('Quotes and boxes', 2, None, 'quotes-and-boxes'),
              ('Admonitions', 2, None, 'admonitions'),
              ('Going deeper environments',
               2,
               None,
               'going-deeper-environments'),
              ('The end', 2, None, 'the-end')]}
end of tocinfo -->

<body>



<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  TeX: {
     equationNumbers: {  autoNumber: "AMS"  },
     extensions: ["AMSmath.js", "AMSsymbols.js", "autobold.js", "color.js"]
  }
});
</script>
<script type="text/javascript" async
 src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>



    
<!-- ------------------- main content ---------------------- -->



<center><h1>Testing admons</h1></center>  <!-- document title -->

<p>
<!-- author(s): H. P. Langtangen -->

<center>
<b>H. P. Langtangen</b> 
</center>

<p>
<!-- institution(s) -->

<br>
<p>
<center><h4>Jan 32, 2100</h4></center> <!-- date -->
<br>
<p>
<!-- !split -->

<h1 id="introduction">Introduction </h1>
First some ordinary text to compare font sizes in admonitions
and the surrounding text.

<h2 id="code">Code </h2>

<p>
Need some code outside admons for color and font comparisons:

<p>
<!-- begin verbatim block  pycod-->
<pre><code>def some_code(x):
    return sin(x)*exp(1-x)
</code></pre>
<!-- end verbatim block -->

<p>
And some plain text verbatim:

<p>
<!-- begin verbatim block -->
<pre><code>x=1.0 y=0.9 z=0.4
x=1.1 y=0.3 z=0.1
</code></pre>
<!-- end verbatim block -->

<h2 id="quotes-and-boxes">Quotes and boxes </h2>

<p>
Here is a plain quote environment.

<p>
<blockquote>
    Sayre's law states that
    &quot;in any dispute the intensity of feeling is inversely
    proportional to the value of the issues at stake.&quot; <br />
    By way of corollary, it adds: <br />
    &quot;That is why academic politics are so bitter.&quot; <br />
    <em>Source</em>: <a href="https://en.wikipedia.org/wiki/Sayre's_law" target="_self">wikipedia</a>
</blockquote>


<p>
Does quotes with title also work? No...cannot work in LaTeX and HTML
and then it does not make sense to support it.

<p>
A plain <em>box</em> is sometimes useful. Let's show it here for comparison
with admons (especially the block admon has much in common with a box).
The box is more aimed at framing a law or an equation.

<p>
First a simple block with text, an equation, and a list:

<p>

<!-- begin box -->
<div style="width: 95%; padding: 10px; border: 1px solid #000; border-radius: 4px;">
A generic equation

$$ f(x) = 0 $$

must be solved by a numerical method, such as

<ul>
 <li> Newton's method</li>
 <li> The Bisection method</li>
 <li> Fixed-point (Picard) iteration by rewriting \( f(x)=x - g(x) \)</li>
 <li> The Secant method</li>
</ul>
</div>
<!-- end box -->

Now test a box with equation only (note that this line continues the
box, it is not a new paragraph):

<p>

<!-- begin box -->
<div style="width: 95%; padding: 10px; border: 1px solid #000; border-radius: 4px;">
$$
\begin{equation} f(x) = \sin(x)e^{1-x}  \label{_auto1}
\end{equation}
$$
</div>
<!-- end box -->


<p>
<b>Hint.</b>

Newton's method requires a good start vector to converge fast.



<p>
Let's begin a new paragraph and show a box with code only:

<p>

<!-- begin box -->
<div style="width: 95%; padding: 10px; border: 1px solid #000; border-radius: 4px;">
<!-- begin verbatim block  pycod-->
<pre><code>def some_code(x):
    return sin(x)*exp(1-x)
</code></pre>
<!-- end verbatim block -->
</div>
<!-- end box -->


<h2 id="admonitions">Admonitions </h2>

<p>
Let us start with a plain warning environment.

<p>
<div class="alert alert-block alert-warning alert-text-normal">
<b>Warning</b>
<p>
And here is a warning about something to pay attention to. We
test how the heading behave and add quite some extra texts
in comparison with the other admons.

<ul>
  <li> and a list</li>
  <li> with items</li>
</ul>

We continue with more text to see how that affects the layout.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
</div>


<p>
Test warning with title:

<p>
<div class="alert alert-block alert-warning alert-text-large">
<b>Title ending with math \( \sqrt{2}\approx 1.4 \)</b>
<p>
And here comes some text with bad news in larger font.

<p>
Also some code:

<p>
<!-- begin verbatim block  pycod-->
<pre><code>def f(x):
    return x
</code></pre>
<!-- end verbatim block -->
And a complete program

<p>
<!-- begin verbatim block  pypro-->
<pre><code>print(&quot;Hello, World!&quot;)
</code></pre>
<!-- end verbatim block -->
</div>


<p>
Test warning with large title with math:

<p>
<div class="alert alert-block alert-warning alert-text-large">
<b>Watch out for \( \nabla\cdot\boldsymbol{u}=0 \) equations</b>
<p>
Divergence freedom is often problematic from a numerical point
of view.
</div>


<p>
Then we test a block, which is guaranteed to never have any admon icon.

<p>
<div class="alert alert-block alert-block alert-text-small">
<b>Block with title</b>
<p>
Here is a block of text with title. It is typeset
<em>without any icon</em> and is useful when you want some admons with icon
and some without. With the small font size, as used here, one can have
more comment-style text or text that really goes deeper or talks
about fun facts that are not strictly necessary for the main flow
of understanding.
</div>


<p>
<div class="alert alert-block alert-block alert-text-normal">
<b></b>
<p>
Here is a block of text with no title. As above, it is typeset without any icon
and is useful when you want some admons with icon and some without.
</div>


<p>
<!-- Note that the final ! does not appear in Sphinx and reST since -->
<!-- those formats automatically add : to the admonition title. -->

<p>
<div class="alert alert-block alert-notice alert-text-illegal-size">
<b>Note, eventually!</b>
<p>
Ah, we are soon close to the end (with illegal font size specification!).
But first a bit of math where we define \( \theta \) and \( \boldsymbol{r} \):

$$
\begin{align*}
\theta &= q^2,\\
\boldsymbol{r} &= \varrho\boldsymbol{i}
\end{align*}
$$
</div>


<p>
<!-- Test one word with a number -->

<p>
<div class="alert alert-block alert-notice alert-text-normal">
<b>Point1</b>
<p>
Ah, we are soon close to the end.
</div>


<p>
<div class="alert alert-block alert-question alert-text-normal">
<b>Question</b>
<p>
So, how many admonition environments does DocOnce support?
</div>


<p>
<div class="alert alert-block alert-question alert-text-normal">
<b>Question</b>
<p>

<ol>
 <li> Once more, how many admonition environments does DocOnce support?</li>
</ol>
</div>


<p>
<div class="alert alert-block alert-warning alert-text-normal">
<b>Tip</b>
<p>
It is of outmost important to

<ol>
<li> stay cool</li>
<li> read hints and tips carefully</li>
</ol>

Because here the thing is to do

<p>
<!-- begin verbatim block  pycod-->
<pre><code>import urllib

def grab(url, filename):
    urllib.urlretrieve(url, filename=filename)
</code></pre>
<!-- end verbatim block -->
</div>


<p>
Next is a warning without a title ("none" implies no title).

<p>
<div class="alert alert-block alert-warning alert-text-normal">
<b></b>
<p>
And here comes some text with bad news.
</div>


<h2 id="going-deeper-environments">Going deeper environments </h2>

<p>
Here is a long notice environment with a custom title and much
text, math and code.

<p>
<div class="alert alert-block alert-notice alert-text-normal">
<b>Going deeper.</b>
<p>
We have some equations that should be preceded by much text, so the
task is to write and write. The number of words, and not the
meaning, is what counts here. We need desperately to fill up the
page in the hope that some admonitions will experience a page break,
which the LaTeX environment should handle with ease.

<p>
Let us start with some equations:

$$
\begin{align*}
\frac{Du}{dt} &= 0
\\
\frac{1}{2} &= {1/2}\\
\frac{1}{2}\pmb{x} &= \pmb{n}
\end{align*}
$$

<p>
The implementation of such complicated equations in computer
code is task that this "Going deeper" environment targets.

<p>
<!-- begin verbatim block  pycod-->
<pre><code>def Dudt(u):
    r = diff(u, t) + u*grad(u)
    return r

half = 0.5
x = 2*n
</code></pre>
<!-- end verbatim block -->
And some more text that can help going into the next page.
Longer computer code requires vertical space:

<p>
<!-- begin verbatim block  pycod-->
<pre><code>class Diff:
    def __init__(self, f, h=1E-5):
        self.f = f
        self.h = float(h)

class Forward1(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (f(x+h) - f(x))/h

class Backward1(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (f(x) - f(x-h))/h

class Central2(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (f(x+h) - f(x-h))/(2*h)

class Central4(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (4./3)*(f(x+h)   - f(x-h))  /(2*h) - \
               (1./3)*(f(x+2*h) - f(x-2*h))/(4*h)

class Central6(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (3./2) *(f(x+h)   - f(x-h))  /(2*h) - \
               (3./5) *(f(x+2*h) - f(x-2*h))/(4*h) + \
               (1./10)*(f(x+3*h) - f(x-3*h))/(6*h)

class Forward3(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (-(1./6)*f(x+2*h) + f(x+h) - 0.5*f(x) - \
                (1./3)*f(x-h))/h
</code></pre>
<!-- end verbatim block -->
And then we add a figure too.

<p>
<br /><br /><center><p><img src="../doc/src/manual/fig/wave1D.png" align="bottom" width=400></p></center><br /><br />
</div>


<h2 id="the-end">The end </h2>

<p>
A bit of text before the summary, which we now call "Concluding remarks,
for the novice",
just because we can.

<p>
<div class="alert alert-block alert-summary alert-text-normal">
<b>Concluding remarks, for the novice</b>
<p>
We can summarize the most important things with admons: they have
a different typesetting, and they may have a symbol.
Titles should be optional.
</div>


<p>
<b>Remark.</b>
The <code>remarks</code> and <code>hint</code> environments are not allowed outside
exercises (and problems and projects too).

<!-- ------------------- end of main content --------------- -->


<center style="font-size:80%">
<!-- copyright --> &copy; 2021, H. P. Langtangen. Made with <a href="https://github.com/hplgit/doconce">DocOnce</a>
</center>


</body>
</html>
    


************** File: admon_vagrant.html *****************
<html>
<head>
<!-- Bootstrap style: vagrant 1.0 web pages -->

<!--
This style is adopted from the (now old) vagrant 1.0 web pages.

This style file should be copied and the following elements edited:

Logo heading:

 LogoWord
 withSubWord

Navigation links at the top:

 GO TO 1
 GO TO 2

Footer at the end
-->

<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Doconce: http://code.google.com/p/doconce/" />

<title>Testing admons</title>

<!-- If you copy the css subdirectory (and, e.g., make optional edits):
<link rel="stylesheet" href="css/twitter_bootstrap.css">
<link rel="stylesheet" href="css/vagrant.css">
Otherwise, rely on the URLs below (vagrant.css adapted to Doconce layout)
-->

<link rel="stylesheet" href="https://raw.githubusercontent.com/hplgit/doconce/master/bundled/html_styles/style_vagrant/css/twitter_bootstrap.css">
<link rel="stylesheet" href="https://raw.githubusercontent.com/hplgit/doconce/master/bundled/html_styles/style_vagrant/css/vagrant.css">

<!-- Define color of headings here (last definition counts) -->
<style type="text/css">
h1, h2, h3, h4, h5, h6 {
  color: #000;     /* black */
  color: #999;     /* gray */
  color: #005580;  /* dark blue */
  color: #08c;     /* characteristic blue */
</style>
</head>
<body>

<div class="container">
 <div class="row Header with-border">
  <div class="span3 Module logo">
   <h1><a href="/">LogoWord<span class="subtitle">withSubWord</span></a></h1>
  </div>
  <div class="span9">
   <div class="Module navigation">
   <!-- Navigation at the top of the page -->
    <ul>
     <li> <a href="">GO TO 1</a></li>
     <li> <a href="">GO TO 2</a></li>
    </ul>
   </div>
  </div>
 </div>
</div>


<!-- Here goes the table of contents in the sidebar
     <li class="active"> means dark blue background for current section
-->
<div class="row">
 <div class="span3 Module sidebar">
  <div class="well" style="padding: 8px 0px;">
   <ul class="nav nav-list">
     <!-- navigation toc: --> <li><a href="#introduction" style="font-size: 80%;"><b>Introduction</b></a></li>
     <!-- navigation toc: --> <li><a href="#code" style="font-size: 80%;">&nbsp;&nbsp;&nbsp;Code</a></li>
     <!-- navigation toc: --> <li><a href="#quotes-and-boxes" style="font-size: 80%;">&nbsp;&nbsp;&nbsp;Quotes and boxes</a></li>
     <!-- navigation toc: --> <li><a href="#admonitions" style="font-size: 80%;">&nbsp;&nbsp;&nbsp;Admonitions</a></li>
     <!-- navigation toc: --> <li><a href="#going-deeper-environments" style="font-size: 80%;">&nbsp;&nbsp;&nbsp;Going deeper environments</a></li>
     <!-- navigation toc: --> <li><a href="#the-end" style="font-size: 80%;">&nbsp;&nbsp;&nbsp;The end</a></li>

   </ul>
  </div>
 </div>

 <div class="span9">

<!-- tocinfo
{'highest level': 1,
 'sections': [('Introduction', 1, None, 'introduction'),
              ('Code', 2, None, 'code'),
              ('Quotes and boxes', 2, None, 'quotes-and-boxes'),
              ('Admonitions', 2, None, 'admonitions'),
              ('Going deeper environments',
               2,
               None,
               'going-deeper-environments'),
              ('The end', 2, None, 'the-end')]}
end of tocinfo -->





<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  TeX: {
     equationNumbers: {  autoNumber: "AMS"  },
     extensions: ["AMSmath.js", "AMSsymbols.js", "autobold.js", "color.js"]
  }
});
</script>
<script type="text/javascript" async
 src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>



<!-- ------------------- main content ---------------------- -->



<div class="jumbotron">
<center><h1>Testing admons</h1></center>  <!-- document title -->

<p>
<!-- author(s): H. P. Langtangen -->

<center>
<b>H. P. Langtangen</b> 
</center>

<p>
<!-- institution(s) -->

<br>
<p>

<br>
<p>
<!-- potential-jumbotron-button -->
</div> <!-- end jumbotron -->

<!-- !split -->

<h1 id="introduction" class="anchor">Introduction </h1>
First some ordinary text to compare font sizes in admonitions
and the surrounding text.

<h2 id="code" class="anchor">Code </h2>

<p>
Need some code outside admons for color and font comparisons:

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">some_code</span>(x):
    <span style="color: #008000; font-weight: bold">return</span> sin(x)<span style="color: #666666">*</span>exp(<span style="color: #666666">1-</span>x)
</pre></div>
<p>
And some plain text verbatim:

<p>

<!-- code=text typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>x=1.0 y=0.9 z=0.4
x=1.1 y=0.3 z=0.1
</pre></div>

<h2 id="quotes-and-boxes" class="anchor">Quotes and boxes </h2>

<p>
Here is a plain quote environment.

<p>
<blockquote>
    Sayre's law states that
    &quot;in any dispute the intensity of feeling is inversely
    proportional to the value of the issues at stake.&quot; <br />
    By way of corollary, it adds: <br />
    &quot;That is why academic politics are so bitter.&quot; <br />
    <em>Source</em>: <a href="https://en.wikipedia.org/wiki/Sayre's_law" target="_self">wikipedia</a>
</blockquote>


<p>
Does quotes with title also work? No...cannot work in LaTeX and HTML
and then it does not make sense to support it.

<p>
A plain <em>box</em> is sometimes useful. Let's show it here for comparison
with admons (especially the block admon has much in common with a box).
The box is more aimed at framing a law or an equation.

<p>
First a simple block with text, an equation, and a list:

<p>

<!-- begin box -->
<div style="width: 95%; padding: 10px; border: 1px solid #000; border-radius: 4px;">
A generic equation

$$ f(x) = 0 $$

must be solved by a numerical method, such as

<ul>
 <li> Newton's method</li>
 <li> The Bisection method</li>
 <li> Fixed-point (Picard) iteration by rewriting \( f(x)=x - g(x) \)</li>
 <li> The Secant method</li>
</ul>
</div>
<!-- end box -->

Now test a box with equation only (note that this line continues the
box, it is not a new paragraph):

<p>

<!-- begin box -->
<div style="width: 95%; padding: 10px; border: 1px solid #000; border-radius: 4px;">
$$
\begin{equation} f(x) = \sin(x)e^{1-x}  \label{_auto1}
\end{equation}
$$
</div>
<!-- end box -->


<p>
<b>Hint.</b>

Newton's method requires a good start vector to converge fast.



<p>
Let's begin a new paragraph and show a box with code only:

<p>

<!-- begin box -->
<div style="width: 95%; padding: 10px; border: 1px solid #000; border-radius: 4px;">
<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">some_code</span>(x):
    <span style="color: #008000; font-weight: bold">return</span> sin(x)<span style="color: #666666">*</span>exp(<span style="color: #666666">1-</span>x)
</pre></div>
<p>
</div>
<!-- end box -->


<h2 id="admonitions" class="anchor">Admonitions </h2>

<p>
Let us start with a plain warning environment.

<p>
<div class="alert alert-block alert-danger alert-text-normal"><b>Warning</b>
And here is a warning about something to pay attention to. We
test how the heading behave and add quite some extra texts
in comparison with the other admons.

<ul>
  <li> and a list</li>
  <li> with items</li>
</ul>

We continue with more text to see how that affects the layout.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
</div>


<p>
Test warning with title:

<p>
<div class="alert alert-block alert-danger alert-text-large"><b>Title ending with math \( \sqrt{2}\approx 1.4 \)</b>
And here comes some text with bad news in larger font.

<p>
Also some code:

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">f</span>(x):
    <span style="color: #008000; font-weight: bold">return</span> x
</pre></div>
<p>
And a complete program

<p>

<!-- code=python (!bc pypro) typeset with pygments style "default" -->
<div class="highlight" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><span style="color: #008000">print</span>(<span style="color: #BA2121">&quot;Hello, World!&quot;</span>)
</pre></div>
<p>
</div>


<p>
Test warning with large title with math:

<p>
<div class="alert alert-block alert-danger alert-text-large"><b>Watch out for \( \nabla\cdot\boldsymbol{u}=0 \) equations</b>
Divergence freedom is often problematic from a numerical point
of view.
</div>


<p>
Then we test a block, which is guaranteed to never have any admon icon.

<p>
<div class="alert alert-block alert-success alert-text-small"><b>Block with title</b>
Here is a block of text with title. It is typeset
<em>without any icon</em> and is useful when you want some admons with icon
and some without. With the small font size, as used here, one can have
more comment-style text or text that really goes deeper or talks
about fun facts that are not strictly necessary for the main flow
of understanding.
</div>


<p>
<div class="alert alert-block alert-success alert-text-normal"><b></b>
Here is a block of text with no title. As above, it is typeset without any icon
and is useful when you want some admons with icon and some without.
</div>


<p>
<!-- Note that the final ! does not appear in Sphinx and reST since -->
<!-- those formats automatically add : to the admonition title. -->

<p>
<div class="alert alert-block alert-success alert-text-illegal-size"><b>Note, eventually!</b>
Ah, we are soon close to the end (with illegal font size specification!).
But first a bit of math where we define \( \theta \) and \( \boldsymbol{r} \):

$$
\begin{align*}
\theta &= q^2,\\
\boldsymbol{r} &= \varrho\boldsymbol{i}
\end{align*}
$$
</div>


<p>
<!-- Test one word with a number -->

<p>
<div class="alert alert-block alert-success alert-text-normal"><b>Point1</b>
Ah, we are soon close to the end.
</div>


<p>
<div class="alert alert-block alert-info alert-text-normal"><b>Question</b>
So, how many admonition environments does DocOnce support?
</div>


<p>
<div class="alert alert-block alert-info alert-text-normal"><b>Question</b>

<ol>
 <li> Once more, how many admonition environments does DocOnce support?</li>
</ol>
</div>


<p>
<div class="alert alert-block alert-danger alert-text-normal"><b>Tip</b>
It is of outmost important to

<ol>
<li> stay cool</li>
<li> read hints and tips carefully</li>
</ol>

Because here the thing is to do

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">import</span> <span style="color: #0000FF; font-weight: bold">urllib</span>

<span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">grab</span>(url, filename):
    urllib<span style="color: #666666">.</span>urlretrieve(url, filename<span style="color: #666666">=</span>filename)
</pre></div>
<p>
</div>


<p>
Next is a warning without a title ("none" implies no title).

<p>
<div class="alert alert-block alert-danger alert-text-normal"><b></b>
And here comes some text with bad news.
</div>


<h2 id="going-deeper-environments" class="anchor">Going deeper environments </h2>

<p>
Here is a long notice environment with a custom title and much
text, math and code.

<p>
<div class="alert alert-block alert-success alert-text-normal"><b>Going deeper.</b>
We have some equations that should be preceded by much text, so the
task is to write and write. The number of words, and not the
meaning, is what counts here. We need desperately to fill up the
page in the hope that some admonitions will experience a page break,
which the LaTeX environment should handle with ease.

<p>
Let us start with some equations:

$$
\begin{align*}
\frac{Du}{dt} &= 0
\\
\frac{1}{2} &= {1/2}\\
\frac{1}{2}\pmb{x} &= \pmb{n}
\end{align*}
$$

<p>
The implementation of such complicated equations in computer
code is task that this "Going deeper" environment targets.

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">Dudt</span>(u):
    r <span style="color: #666666">=</span> diff(u, t) <span style="color: #666666">+</span> u<span style="color: #666666">*</span>grad(u)
    <span style="color: #008000; font-weight: bold">return</span> r

half <span style="color: #666666">=</span> <span style="color: #666666">0.5</span>
x <span style="color: #666666">=</span> <span style="color: #666666">2*</span>n
</pre></div>
<p>
And some more text that can help going into the next page.
Longer computer code requires vertical space:

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Diff</span>:
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__init__</span>(<span style="color: #008000">self</span>, f, h<span style="color: #666666">=1E-5</span>):
        <span style="color: #008000">self</span><span style="color: #666666">.</span>f <span style="color: #666666">=</span> f
        <span style="color: #008000">self</span><span style="color: #666666">.</span>h <span style="color: #666666">=</span> <span style="color: #008000">float</span>(h)

<span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Forward1</span>(Diff):
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__call__</span>(<span style="color: #008000">self</span>, x):
        f, h <span style="color: #666666">=</span> <span style="color: #008000">self</span><span style="color: #666666">.</span>f, <span style="color: #008000">self</span><span style="color: #666666">.</span>h
        <span style="color: #008000; font-weight: bold">return</span> (f(x<span style="color: #666666">+</span>h) <span style="color: #666666">-</span> f(x))<span style="color: #666666">/</span>h

<span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Backward1</span>(Diff):
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__call__</span>(<span style="color: #008000">self</span>, x):
        f, h <span style="color: #666666">=</span> <span style="color: #008000">self</span><span style="color: #666666">.</span>f, <span style="color: #008000">self</span><span style="color: #666666">.</span>h
        <span style="color: #008000; font-weight: bold">return</span> (f(x) <span style="color: #666666">-</span> f(x<span style="color: #666666">-</span>h))<span style="color: #666666">/</span>h

<span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Central2</span>(Diff):
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__call__</span>(<span style="color: #008000">self</span>, x):
        f, h <span style="color: #666666">=</span> <span style="color: #008000">self</span><span style="color: #666666">.</span>f, <span style="color: #008000">self</span><span style="color: #666666">.</span>h
        <span style="color: #008000; font-weight: bold">return</span> (f(x<span style="color: #666666">+</span>h) <span style="color: #666666">-</span> f(x<span style="color: #666666">-</span>h))<span style="color: #666666">/</span>(<span style="color: #666666">2*</span>h)

<span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Central4</span>(Diff):
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__call__</span>(<span style="color: #008000">self</span>, x):
        f, h <span style="color: #666666">=</span> <span style="color: #008000">self</span><span style="color: #666666">.</span>f, <span style="color: #008000">self</span><span style="color: #666666">.</span>h
        <span style="color: #008000; font-weight: bold">return</span> (<span style="color: #666666">4./3</span>)<span style="color: #666666">*</span>(f(x<span style="color: #666666">+</span>h)   <span style="color: #666666">-</span> f(x<span style="color: #666666">-</span>h))  <span style="color: #666666">/</span>(<span style="color: #666666">2*</span>h) <span style="color: #666666">-</span> \
               (<span style="color: #666666">1./3</span>)<span style="color: #666666">*</span>(f(x<span style="color: #666666">+2*</span>h) <span style="color: #666666">-</span> f(x<span style="color: #666666">-2*</span>h))<span style="color: #666666">/</span>(<span style="color: #666666">4*</span>h)

<span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Central6</span>(Diff):
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__call__</span>(<span style="color: #008000">self</span>, x):
        f, h <span style="color: #666666">=</span> <span style="color: #008000">self</span><span style="color: #666666">.</span>f, <span style="color: #008000">self</span><span style="color: #666666">.</span>h
        <span style="color: #008000; font-weight: bold">return</span> (<span style="color: #666666">3./2</span>) <span style="color: #666666">*</span>(f(x<span style="color: #666666">+</span>h)   <span style="color: #666666">-</span> f(x<span style="color: #666666">-</span>h))  <span style="color: #666666">/</span>(<span style="color: #666666">2*</span>h) <span style="color: #666666">-</span> \
               (<span style="color: #666666">3./5</span>) <span style="color: #666666">*</span>(f(x<span style="color: #666666">+2*</span>h) <span style="color: #666666">-</span> f(x<span style="color: #666666">-2*</span>h))<span style="color: #666666">/</span>(<span style="color: #666666">4*</span>h) <span style="color: #666666">+</span> \
               (<span style="color: #666666">1./10</span>)<span style="color: #666666">*</span>(f(x<span style="color: #666666">+3*</span>h) <span style="color: #666666">-</span> f(x<span style="color: #666666">-3*</span>h))<span style="color: #666666">/</span>(<span style="color: #666666">6*</span>h)

<span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Forward3</span>(Diff):
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__call__</span>(<span style="color: #008000">self</span>, x):
        f, h <span style="color: #666666">=</span> <span style="color: #008000">self</span><span style="color: #666666">.</span>f, <span style="color: #008000">self</span><span style="color: #666666">.</span>h
        <span style="color: #008000; font-weight: bold">return</span> (<span style="color: #666666">-</span>(<span style="color: #666666">1./6</span>)<span style="color: #666666">*</span>f(x<span style="color: #666666">+2*</span>h) <span style="color: #666666">+</span> f(x<span style="color: #666666">+</span>h) <span style="color: #666666">-</span> <span style="color: #666666">0.5*</span>f(x) <span style="color: #666666">-</span> \
                (<span style="color: #666666">1./3</span>)<span style="color: #666666">*</span>f(x<span style="color: #666666">-</span>h))<span style="color: #666666">/</span>h
</pre></div>
<p>
And then we add a figure too.

<p>
<br /><br /><center><p><img src="../doc/src/manual/fig/wave1D.png" align="bottom" width=400></p></center><br /><br />
</div>


<h2 id="the-end" class="anchor">The end </h2>

<p>
A bit of text before the summary, which we now call "Concluding remarks,
for the novice",
just because we can.

<p>
<div class="alert alert-block alert-warning alert-text-normal"><b>Concluding remarks, for the novice</b>
We can summarize the most important things with admons: they have
a different typesetting, and they may have a symbol.
Titles should be optional.
</div>


<p>
<b>Remark.</b>
The <code>remarks</code> and <code>hint</code> environments are not allowed outside
exercises (and problems and projects too).

<!-- ------------------- end of main content --------------- -->

 </div>

 <div class="row Footer">
  <div class="span12">
  <!-- footer --> Here goes a footer, if desired, maybe with author(s) and a copyright &copy;
  </div>
 </div>
</div>
</body>
</html>


************** File: admon_bootstrap_alert.html *****************
<!--
Automatically generated HTML file from DocOnce source
(https://github.com/doconce/doconce/)
-->
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="DocOnce: https://github.com/doconce/doconce/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="description" content="Testing admons">

<title>Testing admons</title>

<!-- Bootstrap style: bootstrap -->
<link href="https://netdna.bootstrapcdn.com/bootstrap/3.1.1/css/bootstrap.min.css" rel="stylesheet">
<!-- not necessary
<link href="https://netdna.bootstrapcdn.com/font-awesome/4.0.3/css/font-awesome.css" rel="stylesheet">
-->

<style type="text/css">

/* Add scrollbar to dropdown menus in bootstrap navigation bar */
.dropdown-menu {
   height: auto;
   max-height: 400px;
   overflow-x: hidden;
}

/* Adds an invisible element before each target to offset for the navigation
   bar */
.anchor::before {
  content:"";
  display:block;
  height:50px;      /* fixed header height for style bootstrap */
  margin:-50px 0 0; /* negative fixed header height */
}
</style>


</head>

<!-- tocinfo
{'highest level': 1,
 'sections': [('Introduction', 1, None, 'introduction'),
              ('Code', 2, None, 'code'),
              ('Quotes and boxes', 2, None, 'quotes-and-boxes'),
              ('Admonitions', 2, None, 'admonitions'),
              ('Going deeper environments',
               2,
               None,
               'going-deeper-environments'),
              ('The end', 2, None, 'the-end')]}
end of tocinfo -->

<body>



<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  TeX: {
     equationNumbers: {  autoNumber: "none"  },
     extensions: ["AMSmath.js", "AMSsymbols.js", "autobold.js", "color.js"]
  }
});
</script>
<script type="text/javascript" async
 src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>



    
<!-- Bootstrap navigation bar -->
<div class="navbar navbar-default navbar-fixed-top">
  <div class="navbar-header">
    <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-responsive-collapse">
      <span class="icon-bar"></span>
      <span class="icon-bar"></span>
      <span class="icon-bar"></span>
    </button>
    <a class="navbar-brand" href="admon.html">Testing admons</a>
  </div>

  <div class="navbar-header">
    <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-responsive-collapse">
      <span class="icon-bar"></span>
      <span class="icon-bar"></span>
      <span class="icon-bar"></span>
    </button>
    <a class="navbar-brand" href="https://google.com">Google</a>
  </div>

  <div class="navbar-header">
    <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-responsive-collapse">
      <span class="icon-bar"></span>
      <span class="icon-bar"></span>
      <span class="icon-bar"></span>
    </button>
    <a class="navbar-brand" href="https://hplgit.github.io/teamods/writing_reports/index.html">DocOnce formats</a>
  </div>

  <div class="navbar-collapse collapse navbar-responsive-collapse">
    <ul class="nav navbar-nav navbar-right">
      <li class="dropdown">
        <a href="#" class="dropdown-toggle" data-toggle="dropdown">Contents <b class="caret"></b></a>
        <ul class="dropdown-menu">
     <!-- navigation toc: --> <li><a href="._admon_bootstrap_alert001.html#introduction" style="font-size: 80%;"><b>Introduction</b></a></li>
     <!-- navigation toc: --> <li><a href="._admon_bootstrap_alert001.html#code" style="font-size: 80%;">&nbsp;&nbsp;&nbsp;Code</a></li>
     <!-- navigation toc: --> <li><a href="._admon_bootstrap_alert001.html#quotes-and-boxes" style="font-size: 80%;">&nbsp;&nbsp;&nbsp;Quotes and boxes</a></li>
     <!-- navigation toc: --> <li><a href="._admon_bootstrap_alert001.html#admonitions" style="font-size: 80%;">&nbsp;&nbsp;&nbsp;Admonitions</a></li>
     <!-- navigation toc: --> <li><a href="._admon_bootstrap_alert001.html#going-deeper-environments" style="font-size: 80%;">&nbsp;&nbsp;&nbsp;Going deeper environments</a></li>
     <!-- navigation toc: --> <li><a href="._admon_bootstrap_alert001.html#the-end" style="font-size: 80%;">&nbsp;&nbsp;&nbsp;The end</a></li>

        </ul>
      </li>
    </ul>
  </div>
</div>
</div> <!-- end of navigation bar -->

<div class="container">

<p>&nbsp;</p><p>&nbsp;</p><p>&nbsp;</p> <!-- add vertical space -->

<a name="part0000"></a>
<!-- navigation buttons at the bottom of the page -->
<ul class="pagination">
  <li class="active"><a href="._admon_bootstrap_alert000.html">1</a></li>
  <li><a href="._admon_bootstrap_alert001.html">2</a></li>
  <li><a href="._admon_bootstrap_alert001.html">&raquo;</a></li>
</ul>
<!-- ------------------- main content ---------------------- -->



<div class="jumbotron">
<center><h1>Testing admons</h1></center>  <!-- document title -->

<p>
<!-- author(s): H. P. Langtangen -->

<center>
<b>H. P. Langtangen</b> 
</center>

<p>
<!-- institution(s) -->

<br>
<p>
<center><h4>Jan 32, 2100</h4></center> <!-- date -->
<br>
<p>


<p><a href="._admon_bootstrap_alert001.html" class="btn btn-primary btn-lg">Read &raquo;</a></p>


</div> <!-- end jumbotron -->

<p>
<!-- navigation buttons at the bottom of the page -->
<ul class="pagination">
  <li class="active"><a href="._admon_bootstrap_alert000.html">1</a></li>
  <li><a href="._admon_bootstrap_alert001.html">2</a></li>
  <li><a href="._admon_bootstrap_alert001.html">&raquo;</a></li>
</ul>
<!-- ------------------- end of main content --------------- -->

</div>  <!-- end container -->
<!-- include javascript, jQuery *first* -->
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>
<script src="https://netdna.bootstrapcdn.com/bootstrap/3.0.0/js/bootstrap.min.js"></script>

<!-- Bootstrap footer
<footer>
<a href="https://..."><img width="250" align=right src="https://..."></a>
</footer>
-->


<center style="font-size:80%">
<!-- copyright --> &copy; 2021, H. P. Langtangen. Made with <a href="https://github.com/hplgit/doconce">DocOnce</a>
</center>


</body>
</html>
    


************** File: admon_bootswatch_panel.html *****************
<!--
Automatically generated HTML file from DocOnce source
(https://github.com/doconce/doconce/)
-->
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="DocOnce: https://github.com/doconce/doconce/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="description" content="Testing admons">

<title>Testing admons</title>

<!-- Bootstrap style: bootswatch -->
<link href="https://netdna.bootstrapcdn.com/bootswatch/3.1.1/cosmo/bootstrap.min.css" rel="stylesheet">
<!-- not necessary
<link href="https://netdna.bootstrapcdn.com/font-awesome/4.0.3/css/font-awesome.css" rel="stylesheet">
-->

<style type="text/css">

/* Add scrollbar to dropdown menus in bootstrap navigation bar */
.dropdown-menu {
   height: auto;
   max-height: 400px;
   overflow-x: hidden;
}

/* Adds an invisible element before each target to offset for the navigation
   bar */
.anchor::before {
  content:"";
  display:block;
  height:50px;      /* fixed header height for style bootswatch */
  margin:-50px 0 0; /* negative fixed header height */
}
</style>


</head>

<!-- tocinfo
{'highest level': 1,
 'sections': [('Introduction', 1, None, 'introduction'),
              ('Code', 2, None, 'code'),
              ('Quotes and boxes', 2, None, 'quotes-and-boxes'),
              ('Admonitions', 2, None, 'admonitions'),
              ('Going deeper environments',
               2,
               None,
               'going-deeper-environments'),
              ('The end', 2, None, 'the-end')]}
end of tocinfo -->

<body>



<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  TeX: {
     equationNumbers: {  autoNumber: "AMS"  },
     extensions: ["AMSmath.js", "AMSsymbols.js", "autobold.js", "color.js"]
  }
});
</script>
<script type="text/javascript" async
 src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>



    
<!-- Bootstrap navigation bar -->
<div class="navbar navbar-default navbar-fixed-top">
  <div class="navbar-header">
    <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-responsive-collapse">
      <span class="icon-bar"></span>
      <span class="icon-bar"></span>
      <span class="icon-bar"></span>
    </button>
    <a class="navbar-brand" href="admon.html">Testing admons</a>
  </div>

  <div class="navbar-collapse collapse navbar-responsive-collapse">
    <ul class="nav navbar-nav navbar-right">
      <li class="dropdown">
        <a href="#" class="dropdown-toggle" data-toggle="dropdown">Contents <b class="caret"></b></a>
        <ul class="dropdown-menu">
     <!-- navigation toc: --> <li><a href="#introduction" style="font-size: 80%;"><b>Introduction</b></a></li>
     <!-- navigation toc: --> <li><a href="#code" style="font-size: 80%;">&nbsp;&nbsp;&nbsp;Code</a></li>
     <!-- navigation toc: --> <li><a href="#quotes-and-boxes" style="font-size: 80%;">&nbsp;&nbsp;&nbsp;Quotes and boxes</a></li>
     <!-- navigation toc: --> <li><a href="#admonitions" style="font-size: 80%;">&nbsp;&nbsp;&nbsp;Admonitions</a></li>
     <!-- navigation toc: --> <li><a href="#going-deeper-environments" style="font-size: 80%;">&nbsp;&nbsp;&nbsp;Going deeper environments</a></li>
     <!-- navigation toc: --> <li><a href="#the-end" style="font-size: 80%;">&nbsp;&nbsp;&nbsp;The end</a></li>

        </ul>
      </li>
    </ul>
  </div>
</div>
</div> <!-- end of navigation bar -->

<div class="container">

<p>&nbsp;</p><p>&nbsp;</p><p>&nbsp;</p> <!-- add vertical space -->

<!-- ------------------- main content ---------------------- -->



<div class="jumbotron">
<center><h1>Testing admons</h1></center>  <!-- document title -->

<p>
<!-- author(s): H. P. Langtangen -->

<center>
<b>H. P. Langtangen</b> 
</center>

<p>
<!-- institution(s) -->

<br>
<p>
<center><h4>Jan 32, 2100</h4></center> <!-- date -->
<br>
<p>
<!-- potential-jumbotron-button -->
</div> <!-- end jumbotron -->

<!-- !split -->

<h1 id="introduction" class="anchor">Introduction </h1>
First some ordinary text to compare font sizes in admonitions
and the surrounding text.

<h2 id="code" class="anchor">Code </h2>

<p>
Need some code outside admons for color and font comparisons:

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">some_code</span>(x):
    <span style="color: #008000; font-weight: bold">return</span> sin(x)<span style="color: #666666">*</span>exp(<span style="color: #666666">1-</span>x)
</pre></div>
<p>
And some plain text verbatim:

<p>

<!-- code=text typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>x=1.0 y=0.9 z=0.4
x=1.1 y=0.3 z=0.1
</pre></div>

<h2 id="quotes-and-boxes" class="anchor">Quotes and boxes </h2>

<p>
Here is a plain quote environment.

<p>
<blockquote>
    Sayre's law states that
    &quot;in any dispute the intensity of feeling is inversely
    proportional to the value of the issues at stake.&quot; <br />
    By way of corollary, it adds: <br />
    &quot;That is why academic politics are so bitter.&quot; <br />
    <em>Source</em>: <a href="https://en.wikipedia.org/wiki/Sayre's_law" target="_self">wikipedia</a>
</blockquote>


<p>
Does quotes with title also work? No...cannot work in LaTeX and HTML
and then it does not make sense to support it.

<p>
A plain <em>box</em> is sometimes useful. Let's show it here for comparison
with admons (especially the block admon has much in common with a box).
The box is more aimed at framing a law or an equation.

<p>
First a simple block with text, an equation, and a list:

<p>

<!-- begin box -->
<div style="width: 95%; padding: 10px; border: 1px solid #000; border-radius: 4px;">
A generic equation

$$ f(x) = 0 $$

must be solved by a numerical method, such as

<ul>
 <li> Newton's method</li>
 <li> The Bisection method</li>
 <li> Fixed-point (Picard) iteration by rewriting \( f(x)=x - g(x) \)</li>
 <li> The Secant method</li>
</ul>
</div>
<!-- end box -->

Now test a box with equation only (note that this line continues the
box, it is not a new paragraph):

<p>

<!-- begin box -->
<div style="width: 95%; padding: 10px; border: 1px solid #000; border-radius: 4px;">
$$
\begin{equation} f(x) = \sin(x)e^{1-x}  \label{_auto1}
\end{equation}
$$
</div>
<!-- end box -->


<p>
<b>Hint.</b>

Newton's method requires a good start vector to converge fast.



<p>
Let's begin a new paragraph and show a box with code only:

<p>

<!-- begin box -->
<div style="width: 95%; padding: 10px; border: 1px solid #000; border-radius: 4px;">
<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">some_code</span>(x):
    <span style="color: #008000; font-weight: bold">return</span> sin(x)<span style="color: #666666">*</span>exp(<span style="color: #666666">1-</span>x)
</pre></div>
<p>
</div>
<!-- end box -->


<h2 id="admonitions" class="anchor">Admonitions </h2>

<p>
Let us start with a plain warning environment.

<p>
<div class="panel panel-warning">
  <div class="panel-heading">
  <h3 class="panel-title">Warning</h3>
  </div>
<div class="panel-body">
<p> <!-- subsequent paragraphs come in larger fonts, so start with a paragraph -->
And here is a warning about something to pay attention to. We
test how the heading behave and add quite some extra texts
in comparison with the other admons.

<ul>
  <li> and a list</li>
  <li> with items</li>
</ul>

We continue with more text to see how that affects the layout.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
</div>
</div>


<p>
Test warning with title:

<p>
<div class="panel panel-warning">
  <div class="panel-heading">
  <h3 class="panel-title">Title ending with math \( \sqrt{2}\approx 1.4 \)</h3>
  </div>
<div class="panel-body">
<p> <!-- subsequent paragraphs come in larger fonts, so start with a paragraph -->
And here comes some text with bad news in larger font.

<p>
Also some code:

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">f</span>(x):
    <span style="color: #008000; font-weight: bold">return</span> x
</pre></div>
<p>
And a complete program

<p>

<!-- code=python (!bc pypro) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000">print</span>(<span style="color: #BA2121">&quot;Hello, World!&quot;</span>)
</pre></div>
<p>
</div>
</div>


<p>
Test warning with large title with math:

<p>
<div class="panel panel-warning">
  <div class="panel-heading">
  <h3 class="panel-title">Watch out for \( \nabla\cdot\boldsymbol{u}=0 \) equations</h3>
  </div>
<div class="panel-body">
<p> <!-- subsequent paragraphs come in larger fonts, so start with a paragraph -->
Divergence freedom is often problematic from a numerical point
of view.
</div>
</div>


<p>
Then we test a block, which is guaranteed to never have any admon icon.

<p>
<div class="panel panel-default">
<div class="panel-body">
<p> <!-- subsequent paragraphs come in larger fonts, so start with a paragraph -->
Here is a block of text with title. It is typeset
<em>without any icon</em> and is useful when you want some admons with icon
and some without. With the small font size, as used here, one can have
more comment-style text or text that really goes deeper or talks
about fun facts that are not strictly necessary for the main flow
of understanding.
</div>
</div>


<p>
<div class="panel panel-default">
<div class="panel-body">
<p> <!-- subsequent paragraphs come in larger fonts, so start with a paragraph -->
Here is a block of text with no title. As above, it is typeset without any icon
and is useful when you want some admons with icon and some without.
</div>
</div>


<p>
<!-- Note that the final ! does not appear in Sphinx and reST since -->
<!-- those formats automatically add : to the admonition title. -->

<p>
<div class="panel panel-primary">
  <div class="panel-heading">
  <h3 class="panel-title">Note, eventually!</h3>
  </div>
<div class="panel-body">
<p> <!-- subsequent paragraphs come in larger fonts, so start with a paragraph -->
Ah, we are soon close to the end (with illegal font size specification!).
But first a bit of math where we define \( \theta \) and \( \boldsymbol{r} \):

$$
\begin{align*}
\theta &= q^2,\\
\boldsymbol{r} &= \varrho\boldsymbol{i}
\end{align*}
$$
</div>
</div>


<p>
<!-- Test one word with a number -->

<p>
<div class="panel panel-primary">
  <div class="panel-heading">
  <h3 class="panel-title">Point1</h3>
  </div>
<div class="panel-body">
<p> <!-- subsequent paragraphs come in larger fonts, so start with a paragraph -->
Ah, we are soon close to the end.
</div>
</div>


<p>
<div class="panel panel-success">
  <div class="panel-heading">
  <h3 class="panel-title">Question</h3>
  </div>
<div class="panel-body">
<p> <!-- subsequent paragraphs come in larger fonts, so start with a paragraph -->
So, how many admonition environments does DocOnce support?
</div>
</div>


<p>
<div class="panel panel-success">
  <div class="panel-heading">
  <h3 class="panel-title">Question</h3>
  </div>
<div class="panel-body">
<p> <!-- subsequent paragraphs come in larger fonts, so start with a paragraph -->

<ol>
 <li> Once more, how many admonition environments does DocOnce support?</li>
</ol>
</div>
</div>


<p>
<div class="panel panel-warning">
  <div class="panel-heading">
  <h3 class="panel-title">Tip</h3>
  </div>
<div class="panel-body">
<p> <!-- subsequent paragraphs come in larger fonts, so start with a paragraph -->
It is of outmost important to

<ol>
<li> stay cool</li>
<li> read hints and tips carefully</li>
</ol>

Because here the thing is to do

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">import</span> <span style="color: #0000FF; font-weight: bold">urllib</span>

<span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">grab</span>(url, filename):
    urllib<span style="color: #666666">.</span>urlretrieve(url, filename<span style="color: #666666">=</span>filename)
</pre></div>
<p>
</div>
</div>


<p>
Next is a warning without a title ("none" implies no title).

<p>
<div class="panel panel-warning">
  <div class="panel-heading">
  <h3 class="panel-title"></h3>
  </div>
<div class="panel-body">
<p> <!-- subsequent paragraphs come in larger fonts, so start with a paragraph -->
And here comes some text with bad news.
</div>
</div>


<h2 id="going-deeper-environments" class="anchor">Going deeper environments </h2>

<p>
Here is a long notice environment with a custom title and much
text, math and code.

<p>
<div class="panel panel-primary">
  <div class="panel-heading">
  <h3 class="panel-title">Going deeper.</h3>
  </div>
<div class="panel-body">
<p> <!-- subsequent paragraphs come in larger fonts, so start with a paragraph -->
We have some equations that should be preceded by much text, so the
task is to write and write. The number of words, and not the
meaning, is what counts here. We need desperately to fill up the
page in the hope that some admonitions will experience a page break,
which the LaTeX environment should handle with ease.

<p>
Let us start with some equations:

$$
\begin{align*}
\frac{Du}{dt} &= 0
\\
\frac{1}{2} &= {1/2}\\
\frac{1}{2}\pmb{x} &= \pmb{n}
\end{align*}
$$

<p>
The implementation of such complicated equations in computer
code is task that this "Going deeper" environment targets.

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">Dudt</span>(u):
    r <span style="color: #666666">=</span> diff(u, t) <span style="color: #666666">+</span> u<span style="color: #666666">*</span>grad(u)
    <span style="color: #008000; font-weight: bold">return</span> r

half <span style="color: #666666">=</span> <span style="color: #666666">0.5</span>
x <span style="color: #666666">=</span> <span style="color: #666666">2*</span>n
</pre></div>
<p>
And some more text that can help going into the next page.
Longer computer code requires vertical space:

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Diff</span>:
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__init__</span>(<span style="color: #008000">self</span>, f, h<span style="color: #666666">=1E-5</span>):
        <span style="color: #008000">self</span><span style="color: #666666">.</span>f <span style="color: #666666">=</span> f
        <span style="color: #008000">self</span><span style="color: #666666">.</span>h <span style="color: #666666">=</span> <span style="color: #008000">float</span>(h)

<span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Forward1</span>(Diff):
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__call__</span>(<span style="color: #008000">self</span>, x):
        f, h <span style="color: #666666">=</span> <span style="color: #008000">self</span><span style="color: #666666">.</span>f, <span style="color: #008000">self</span><span style="color: #666666">.</span>h
        <span style="color: #008000; font-weight: bold">return</span> (f(x<span style="color: #666666">+</span>h) <span style="color: #666666">-</span> f(x))<span style="color: #666666">/</span>h

<span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Backward1</span>(Diff):
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__call__</span>(<span style="color: #008000">self</span>, x):
        f, h <span style="color: #666666">=</span> <span style="color: #008000">self</span><span style="color: #666666">.</span>f, <span style="color: #008000">self</span><span style="color: #666666">.</span>h
        <span style="color: #008000; font-weight: bold">return</span> (f(x) <span style="color: #666666">-</span> f(x<span style="color: #666666">-</span>h))<span style="color: #666666">/</span>h

<span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Central2</span>(Diff):
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__call__</span>(<span style="color: #008000">self</span>, x):
        f, h <span style="color: #666666">=</span> <span style="color: #008000">self</span><span style="color: #666666">.</span>f, <span style="color: #008000">self</span><span style="color: #666666">.</span>h
        <span style="color: #008000; font-weight: bold">return</span> (f(x<span style="color: #666666">+</span>h) <span style="color: #666666">-</span> f(x<span style="color: #666666">-</span>h))<span style="color: #666666">/</span>(<span style="color: #666666">2*</span>h)

<span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Central4</span>(Diff):
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__call__</span>(<span style="color: #008000">self</span>, x):
        f, h <span style="color: #666666">=</span> <span style="color: #008000">self</span><span style="color: #666666">.</span>f, <span style="color: #008000">self</span><span style="color: #666666">.</span>h
        <span style="color: #008000; font-weight: bold">return</span> (<span style="color: #666666">4./3</span>)<span style="color: #666666">*</span>(f(x<span style="color: #666666">+</span>h)   <span style="color: #666666">-</span> f(x<span style="color: #666666">-</span>h))  <span style="color: #666666">/</span>(<span style="color: #666666">2*</span>h) <span style="color: #666666">-</span> \
               (<span style="color: #666666">1./3</span>)<span style="color: #666666">*</span>(f(x<span style="color: #666666">+2*</span>h) <span style="color: #666666">-</span> f(x<span style="color: #666666">-2*</span>h))<span style="color: #666666">/</span>(<span style="color: #666666">4*</span>h)

<span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Central6</span>(Diff):
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__call__</span>(<span style="color: #008000">self</span>, x):
        f, h <span style="color: #666666">=</span> <span style="color: #008000">self</span><span style="color: #666666">.</span>f, <span style="color: #008000">self</span><span style="color: #666666">.</span>h
        <span style="color: #008000; font-weight: bold">return</span> (<span style="color: #666666">3./2</span>) <span style="color: #666666">*</span>(f(x<span style="color: #666666">+</span>h)   <span style="color: #666666">-</span> f(x<span style="color: #666666">-</span>h))  <span style="color: #666666">/</span>(<span style="color: #666666">2*</span>h) <span style="color: #666666">-</span> \
               (<span style="color: #666666">3./5</span>) <span style="color: #666666">*</span>(f(x<span style="color: #666666">+2*</span>h) <span style="color: #666666">-</span> f(x<span style="color: #666666">-2*</span>h))<span style="color: #666666">/</span>(<span style="color: #666666">4*</span>h) <span style="color: #666666">+</span> \
               (<span style="color: #666666">1./10</span>)<span style="color: #666666">*</span>(f(x<span style="color: #666666">+3*</span>h) <span style="color: #666666">-</span> f(x<span style="color: #666666">-3*</span>h))<span style="color: #666666">/</span>(<span style="color: #666666">6*</span>h)

<span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Forward3</span>(Diff):
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__call__</span>(<span style="color: #008000">self</span>, x):
        f, h <span style="color: #666666">=</span> <span style="color: #008000">self</span><span style="color: #666666">.</span>f, <span style="color: #008000">self</span><span style="color: #666666">.</span>h
        <span style="color: #008000; font-weight: bold">return</span> (<span style="color: #666666">-</span>(<span style="color: #666666">1./6</span>)<span style="color: #666666">*</span>f(x<span style="color: #666666">+2*</span>h) <span style="color: #666666">+</span> f(x<span style="color: #666666">+</span>h) <span style="color: #666666">-</span> <span style="color: #666666">0.5*</span>f(x) <span style="color: #666666">-</span> \
                (<span style="color: #666666">1./3</span>)<span style="color: #666666">*</span>f(x<span style="color: #666666">-</span>h))<span style="color: #666666">/</span>h
</pre></div>
<p>
And then we add a figure too.

<p>
<br /><br /><center><p><img src="../doc/src/manual/fig/wave1D.png" align="bottom" width=400></p></center><br /><br />
</div>
</div>


<h2 id="the-end" class="anchor">The end </h2>

<p>
A bit of text before the summary, which we now call "Concluding remarks,
for the novice",
just because we can.

<p>
<div class="panel panel-danger">
  <div class="panel-heading">
  <h3 class="panel-title">Concluding remarks, for the novice</h3>
  </div>
<div class="panel-body">
<p> <!-- subsequent paragraphs come in larger fonts, so start with a paragraph -->
We can summarize the most important things with admons: they have
a different typesetting, and they may have a symbol.
Titles should be optional.
</div>
</div>


<p>
<b>Remark.</b>
The <code>remarks</code> and <code>hint</code> environments are not allowed outside
exercises (and problems and projects too).

<!-- ------------------- end of main content --------------- -->

</div>  <!-- end container -->
<!-- include javascript, jQuery *first* -->
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>
<script src="https://netdna.bootstrapcdn.com/bootstrap/3.0.0/js/bootstrap.min.js"></script>

<!-- Bootstrap footer
<footer>
<a href="https://..."><img width="250" align=right src="https://..."></a>
</footer>
-->


<center style="font-size:80%">
<!-- copyright --> &copy; 2021, H. P. Langtangen. Made with <a href="https://github.com/hplgit/doconce">DocOnce</a>
</center>


</body>
</html>
    


************** File: ._admon_bootstrap_alert001.html *****************
<!--
Automatically generated HTML file from DocOnce source
(https://github.com/doconce/doconce/)
-->
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="DocOnce: https://github.com/doconce/doconce/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="description" content="Testing admons">

<title>Testing admons</title>

<!-- Bootstrap style: bootstrap -->
<link href="https://netdna.bootstrapcdn.com/bootstrap/3.1.1/css/bootstrap.min.css" rel="stylesheet">
<!-- not necessary
<link href="https://netdna.bootstrapcdn.com/font-awesome/4.0.3/css/font-awesome.css" rel="stylesheet">
-->

<style type="text/css">

/* Add scrollbar to dropdown menus in bootstrap navigation bar */
.dropdown-menu {
   height: auto;
   max-height: 400px;
   overflow-x: hidden;
}

/* Adds an invisible element before each target to offset for the navigation
   bar */
.anchor::before {
  content:"";
  display:block;
  height:50px;      /* fixed header height for style bootstrap */
  margin:-50px 0 0; /* negative fixed header height */
}
</style>


</head>

<!-- tocinfo
{'highest level': 1,
 'sections': [('Introduction', 1, None, 'introduction'),
              ('Code', 2, None, 'code'),
              ('Quotes and boxes', 2, None, 'quotes-and-boxes'),
              ('Admonitions', 2, None, 'admonitions'),
              ('Going deeper environments',
               2,
               None,
               'going-deeper-environments'),
              ('The end', 2, None, 'the-end')]}
end of tocinfo -->

<body>



<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  TeX: {
     equationNumbers: {  autoNumber: "none"  },
     extensions: ["AMSmath.js", "AMSsymbols.js", "autobold.js", "color.js"]
  }
});
</script>
<script type="text/javascript" async
 src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>



    
<!-- Bootstrap navigation bar -->
<div class="navbar navbar-default navbar-fixed-top">
  <div class="navbar-header">
    <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-responsive-collapse">
      <span class="icon-bar"></span>
      <span class="icon-bar"></span>
      <span class="icon-bar"></span>
    </button>
    <a class="navbar-brand" href="admon.html">Testing admons</a>
  </div>

  <div class="navbar-header">
    <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-responsive-collapse">
      <span class="icon-bar"></span>
      <span class="icon-bar"></span>
      <span class="icon-bar"></span>
    </button>
    <a class="navbar-brand" href="https://google.com">Google</a>
  </div>

  <div class="navbar-header">
    <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-responsive-collapse">
      <span class="icon-bar"></span>
      <span class="icon-bar"></span>
      <span class="icon-bar"></span>
    </button>
    <a class="navbar-brand" href="https://hplgit.github.io/teamods/writing_reports/index.html">DocOnce formats</a>
  </div>

  <div class="navbar-collapse collapse navbar-responsive-collapse">
    <ul class="nav navbar-nav navbar-right">
      <li class="dropdown">
        <a href="#" class="dropdown-toggle" data-toggle="dropdown">Contents <b class="caret"></b></a>
        <ul class="dropdown-menu">
     <!-- navigation toc: --> <li><a href="#introduction" style="font-size: 80%;"><b>Introduction</b></a></li>
     <!-- navigation toc: --> <li><a href="#code" style="font-size: 80%;">&nbsp;&nbsp;&nbsp;Code</a></li>
     <!-- navigation toc: --> <li><a href="#quotes-and-boxes" style="font-size: 80%;">&nbsp;&nbsp;&nbsp;Quotes and boxes</a></li>
     <!-- navigation toc: --> <li><a href="#admonitions" style="font-size: 80%;">&nbsp;&nbsp;&nbsp;Admonitions</a></li>
     <!-- navigation toc: --> <li><a href="#going-deeper-environments" style="font-size: 80%;">&nbsp;&nbsp;&nbsp;Going deeper environments</a></li>
     <!-- navigation toc: --> <li><a href="#the-end" style="font-size: 80%;">&nbsp;&nbsp;&nbsp;The end</a></li>

        </ul>
      </li>
    </ul>
  </div>
</div>
</div> <!-- end of navigation bar -->

<div class="container">

<p>&nbsp;</p><p>&nbsp;</p><p>&nbsp;</p> <!-- add vertical space -->

<a name="part0001"></a>
<!-- navigation buttons at the bottom of the page -->
<ul class="pagination">
<li><a href="._admon_bootstrap_alert000.html">&laquo;</a></li>
  <li><a href="._admon_bootstrap_alert000.html">1</a></li>
  <li class="active"><a href="._admon_bootstrap_alert001.html">2</a></li>
</ul>
<!-- !split -->

<h1 id="introduction" class="anchor">Introduction </h1>
First some ordinary text to compare font sizes in admonitions
and the surrounding text.

<h2 id="code" class="anchor">Code </h2>

<p>
Need some code outside admons for color and font comparisons:

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">some_code</span>(x):
    <span style="color: #008000; font-weight: bold">return</span> sin(x)<span style="color: #666666">*</span>exp(<span style="color: #666666">1-</span>x)
</pre></div>
<p>
And some plain text verbatim:

<p>

<!-- code=text typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>x=1.0 y=0.9 z=0.4
x=1.1 y=0.3 z=0.1
</pre></div>

<h2 id="quotes-and-boxes" class="anchor">Quotes and boxes </h2>

<p>
Here is a plain quote environment.

<p>
<blockquote>
    Sayre's law states that
    &quot;in any dispute the intensity of feeling is inversely
    proportional to the value of the issues at stake.&quot; <br />
    By way of corollary, it adds: <br />
    &quot;That is why academic politics are so bitter.&quot; <br />
    <em>Source</em>: <a href="https://en.wikipedia.org/wiki/Sayre's_law" target="_self">wikipedia</a>
</blockquote>


<p>
Does quotes with title also work? No...cannot work in LaTeX and HTML
and then it does not make sense to support it.

<p>
A plain <em>box</em> is sometimes useful. Let's show it here for comparison
with admons (especially the block admon has much in common with a box).
The box is more aimed at framing a law or an equation.

<p>
First a simple block with text, an equation, and a list:

<p>

<!-- begin box -->
<div style="width: 95%; padding: 10px; border: 1px solid #000; border-radius: 4px;">
A generic equation

$$ f(x) = 0 $$

must be solved by a numerical method, such as

<ul>
 <li> Newton's method</li>
 <li> The Bisection method</li>
 <li> Fixed-point (Picard) iteration by rewriting \( f(x)=x - g(x) \)</li>
 <li> The Secant method</li>
</ul>
</div>
<!-- end box -->

Now test a box with equation only (note that this line continues the
box, it is not a new paragraph):

<p>

<!-- begin box -->
<div style="width: 95%; padding: 10px; border: 1px solid #000; border-radius: 4px;">
$$
\begin{equation} f(x) = \sin(x)e^{1-x}  \tag{1}
\end{equation}
$$
</div>
<!-- end box -->


<p>
<b>Hint.</b>

Newton's method requires a good start vector to converge fast.



<p>
Let's begin a new paragraph and show a box with code only:

<p>

<!-- begin box -->
<div style="width: 95%; padding: 10px; border: 1px solid #000; border-radius: 4px;">
<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">some_code</span>(x):
    <span style="color: #008000; font-weight: bold">return</span> sin(x)<span style="color: #666666">*</span>exp(<span style="color: #666666">1-</span>x)
</pre></div>
<p>
</div>
<!-- end box -->


<h2 id="admonitions" class="anchor">Admonitions </h2>

<p>
Let us start with a plain warning environment.

<p>
<div class="alert alert-block alert-danger alert-text-normal"><b>Warning</b>
And here is a warning about something to pay attention to. We
test how the heading behave and add quite some extra texts
in comparison with the other admons.

<ul>
  <li> and a list</li>
  <li> with items</li>
</ul>

We continue with more text to see how that affects the layout.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
</div>


<p>
Test warning with title:

<p>
<div class="alert alert-block alert-danger alert-text-large"><b>Title ending with math \( \sqrt{2}\approx 1.4 \)</b>
And here comes some text with bad news in larger font.

<p>
Also some code:

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">f</span>(x):
    <span style="color: #008000; font-weight: bold">return</span> x
</pre></div>
<p>
And a complete program

<p>

<!-- code=python (!bc pypro) typeset with pygments style "default" -->
<div class="highlight" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><span style="color: #008000">print</span>(<span style="color: #BA2121">&quot;Hello, World!&quot;</span>)
</pre></div>
<p>
</div>


<p>
Test warning with large title with math:

<p>
<div class="alert alert-block alert-danger alert-text-large"><b>Watch out for \( \nabla\cdot\boldsymbol{u}=0 \) equations</b>
Divergence freedom is often problematic from a numerical point
of view.
</div>


<p>
Then we test a block, which is guaranteed to never have any admon icon.

<p>
<div class="alert alert-block alert-success alert-text-small"><b>Block with title</b>
Here is a block of text with title. It is typeset
<em>without any icon</em> and is useful when you want some admons with icon
and some without. With the small font size, as used here, one can have
more comment-style text or text that really goes deeper or talks
about fun facts that are not strictly necessary for the main flow
of understanding.
</div>


<p>
<div class="alert alert-block alert-success alert-text-normal"><b></b>
Here is a block of text with no title. As above, it is typeset without any icon
and is useful when you want some admons with icon and some without.
</div>


<p>
<!-- Note that the final ! does not appear in Sphinx and reST since -->
<!-- those formats automatically add : to the admonition title. -->

<p>
<div class="alert alert-block alert-success alert-text-illegal-size"><b>Note, eventually!</b>
Ah, we are soon close to the end (with illegal font size specification!).
But first a bit of math where we define \( \theta \) and \( \boldsymbol{r} \):

$$
\begin{align*}
\theta &= q^2,\\
\boldsymbol{r} &= \varrho\boldsymbol{i}
\end{align*}
$$
</div>


<p>
<!-- Test one word with a number -->

<p>
<div class="alert alert-block alert-success alert-text-normal"><b>Point1</b>
Ah, we are soon close to the end.
</div>


<p>
<div class="alert alert-block alert-info alert-text-normal"><b>Question</b>
So, how many admonition environments does DocOnce support?
</div>


<p>
<div class="alert alert-block alert-info alert-text-normal"><b>Question</b>

<ol>
 <li> Once more, how many admonition environments does DocOnce support?</li>
</ol>
</div>


<p>
<div class="alert alert-block alert-danger alert-text-normal"><b>Tip</b>
It is of outmost important to

<ol>
<li> stay cool</li>
<li> read hints and tips carefully</li>
</ol>

Because here the thing is to do

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">import</span> <span style="color: #0000FF; font-weight: bold">urllib</span>

<span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">grab</span>(url, filename):
    urllib<span style="color: #666666">.</span>urlretrieve(url, filename<span style="color: #666666">=</span>filename)
</pre></div>
<p>
</div>


<p>
Next is a warning without a title ("none" implies no title).

<p>
<div class="alert alert-block alert-danger alert-text-normal"><b></b>
And here comes some text with bad news.
</div>


<h2 id="going-deeper-environments" class="anchor">Going deeper environments </h2>

<p>
Here is a long notice environment with a custom title and much
text, math and code.

<p>
<div class="alert alert-block alert-success alert-text-normal"><b>Going deeper.</b>
We have some equations that should be preceded by much text, so the
task is to write and write. The number of words, and not the
meaning, is what counts here. We need desperately to fill up the
page in the hope that some admonitions will experience a page break,
which the LaTeX environment should handle with ease.

<p>
Let us start with some equations:

$$
\begin{align*}
\frac{Du}{dt} &= 0
\\
\frac{1}{2} &= {1/2}\\
\frac{1}{2}\pmb{x} &= \pmb{n}
\end{align*}
$$

<p>
The implementation of such complicated equations in computer
code is task that this "Going deeper" environment targets.

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">Dudt</span>(u):
    r <span style="color: #666666">=</span> diff(u, t) <span style="color: #666666">+</span> u<span style="color: #666666">*</span>grad(u)
    <span style="color: #008000; font-weight: bold">return</span> r

half <span style="color: #666666">=</span> <span style="color: #666666">0.5</span>
x <span style="color: #666666">=</span> <span style="color: #666666">2*</span>n
</pre></div>
<p>
And some more text that can help going into the next page.
Longer computer code requires vertical space:

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Diff</span>:
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__init__</span>(<span style="color: #008000">self</span>, f, h<span style="color: #666666">=1E-5</span>):
        <span style="color: #008000">self</span><span style="color: #666666">.</span>f <span style="color: #666666">=</span> f
        <span style="color: #008000">self</span><span style="color: #666666">.</span>h <span style="color: #666666">=</span> <span style="color: #008000">float</span>(h)

<span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Forward1</span>(Diff):
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__call__</span>(<span style="color: #008000">self</span>, x):
        f, h <span style="color: #666666">=</span> <span style="color: #008000">self</span><span style="color: #666666">.</span>f, <span style="color: #008000">self</span><span style="color: #666666">.</span>h
        <span style="color: #008000; font-weight: bold">return</span> (f(x<span style="color: #666666">+</span>h) <span style="color: #666666">-</span> f(x))<span style="color: #666666">/</span>h

<span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Backward1</span>(Diff):
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__call__</span>(<span style="color: #008000">self</span>, x):
        f, h <span style="color: #666666">=</span> <span style="color: #008000">self</span><span style="color: #666666">.</span>f, <span style="color: #008000">self</span><span style="color: #666666">.</span>h
        <span style="color: #008000; font-weight: bold">return</span> (f(x) <span style="color: #666666">-</span> f(x<span style="color: #666666">-</span>h))<span style="color: #666666">/</span>h

<span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Central2</span>(Diff):
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__call__</span>(<span style="color: #008000">self</span>, x):
        f, h <span style="color: #666666">=</span> <span style="color: #008000">self</span><span style="color: #666666">.</span>f, <span style="color: #008000">self</span><span style="color: #666666">.</span>h
        <span style="color: #008000; font-weight: bold">return</span> (f(x<span style="color: #666666">+</span>h) <span style="color: #666666">-</span> f(x<span style="color: #666666">-</span>h))<span style="color: #666666">/</span>(<span style="color: #666666">2*</span>h)

<span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Central4</span>(Diff):
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__call__</span>(<span style="color: #008000">self</span>, x):
        f, h <span style="color: #666666">=</span> <span style="color: #008000">self</span><span style="color: #666666">.</span>f, <span style="color: #008000">self</span><span style="color: #666666">.</span>h
        <span style="color: #008000; font-weight: bold">return</span> (<span style="color: #666666">4./3</span>)<span style="color: #666666">*</span>(f(x<span style="color: #666666">+</span>h)   <span style="color: #666666">-</span> f(x<span style="color: #666666">-</span>h))  <span style="color: #666666">/</span>(<span style="color: #666666">2*</span>h) <span style="color: #666666">-</span> \
               (<span style="color: #666666">1./3</span>)<span style="color: #666666">*</span>(f(x<span style="color: #666666">+2*</span>h) <span style="color: #666666">-</span> f(x<span style="color: #666666">-2*</span>h))<span style="color: #666666">/</span>(<span style="color: #666666">4*</span>h)

<span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Central6</span>(Diff):
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__call__</span>(<span style="color: #008000">self</span>, x):
        f, h <span style="color: #666666">=</span> <span style="color: #008000">self</span><span style="color: #666666">.</span>f, <span style="color: #008000">self</span><span style="color: #666666">.</span>h
        <span style="color: #008000; font-weight: bold">return</span> (<span style="color: #666666">3./2</span>) <span style="color: #666666">*</span>(f(x<span style="color: #666666">+</span>h)   <span style="color: #666666">-</span> f(x<span style="color: #666666">-</span>h))  <span style="color: #666666">/</span>(<span style="color: #666666">2*</span>h) <span style="color: #666666">-</span> \
               (<span style="color: #666666">3./5</span>) <span style="color: #666666">*</span>(f(x<span style="color: #666666">+2*</span>h) <span style="color: #666666">-</span> f(x<span style="color: #666666">-2*</span>h))<span style="color: #666666">/</span>(<span style="color: #666666">4*</span>h) <span style="color: #666666">+</span> \
               (<span style="color: #666666">1./10</span>)<span style="color: #666666">*</span>(f(x<span style="color: #666666">+3*</span>h) <span style="color: #666666">-</span> f(x<span style="color: #666666">-3*</span>h))<span style="color: #666666">/</span>(<span style="color: #666666">6*</span>h)

<span style="color: #008000; font-weight: bold">class</span> <span style="color: #0000FF; font-weight: bold">Forward3</span>(Diff):
    <span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">__call__</span>(<span style="color: #008000">self</span>, x):
        f, h <span style="color: #666666">=</span> <span style="color: #008000">self</span><span style="color: #666666">.</span>f, <span style="color: #008000">self</span><span style="color: #666666">.</span>h
        <span style="color: #008000; font-weight: bold">return</span> (<span style="color: #666666">-</span>(<span style="color: #666666">1./6</span>)<span style="color: #666666">*</span>f(x<span style="color: #666666">+2*</span>h) <span style="color: #666666">+</span> f(x<span style="color: #666666">+</span>h) <span style="color: #666666">-</span> <span style="color: #666666">0.5*</span>f(x) <span style="color: #666666">-</span> \
                (<span style="color: #666666">1./3</span>)<span style="color: #666666">*</span>f(x<span style="color: #666666">-</span>h))<span style="color: #666666">/</span>h
</pre></div>
<p>
And then we add a figure too.

<p>
<br /><br /><center><p><img src="../doc/src/manual/fig/wave1D.png" align="bottom" width=400></p></center><br /><br />
</div>


<h2 id="the-end" class="anchor">The end </h2>

<p>
A bit of text before the summary, which we now call "Concluding remarks,
for the novice",
just because we can.

<p>
<div class="alert alert-block alert-warning alert-text-normal"><b>Concluding remarks, for the novice</b>
We can summarize the most important things with admons: they have
a different typesetting, and they may have a symbol.
Titles should be optional.
</div>


<p>
<b>Remark.</b>
The <code>remarks</code> and <code>hint</code> environments are not allowed outside
exercises (and problems and projects too).

<p>
<!-- navigation buttons at the bottom of the page -->
<ul class="pagination">
<li><a href="._admon_bootstrap_alert000.html">&laquo;</a></li>
  <li><a href="._admon_bootstrap_alert000.html">1</a></li>
  <li class="active"><a href="._admon_bootstrap_alert001.html">2</a></li>
</ul>
<!-- ------------------- end of main content --------------- -->

</div>  <!-- end container -->
<!-- include javascript, jQuery *first* -->
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>
<script src="https://netdna.bootstrapcdn.com/bootstrap/3.0.0/js/bootstrap.min.js"></script>

<!-- Bootstrap footer
<footer>
<a href="https://..."><img width="250" align=right src="https://..."></a>
</footer>
-->


<center style="font-size:80%">
<!-- copyright only on the titlepage -->
</center>


</body>
</html>
    


************** File: ._admon_bootstrap_alert002.html *****************
NOT FOUND!
************** File: admon_mwiki.mwiki *****************
#TITLE (actually governed by the filename): Testing admons

By '''H. P. Langtangen'''
==== Jan 32, 2100 ====

Copyright 2021, H. P. Langtangen. Made with DocOnce




<!-- !split -->
== Introduction ==
First some ordinary text to compare font sizes in admonitions
and the surrounding text.


==== Code ====

Need some code outside admons for color and font comparisons:

<syntaxhighlight lang="python">
def some_code(x):
    return sin(x)*exp(1-x)
</syntaxhighlight>

And some plain text verbatim:

<syntaxhighlight lang="text">
x=1.0 y=0.9 z=0.4
x=1.1 y=0.3 z=0.1
</syntaxhighlight>

==== Quotes and boxes ====

Here is a plain quote environment.


{{quote box
| quote = Sayre's law states that
"in any dispute the intensity of feeling is inversely
proportional to the value of the issues at stake." <br />
By way of corollary, it adds: <br />
"That is why academic politics are so bitter." <br />
''Source'': [https://en.wikipedia.org/wiki/Sayre's_law wikipedia]
| textstyle = font-size: 90%;
}}



Does quotes with title also work? No...cannot work in LaTeX and HTML
and then it does not make sense to support it.


A plain ''box'' is sometimes useful. Let's show it here for comparison
with admons (especially the block admon has much in common with a box).
The box is more aimed at framing a law or an equation.

First a simple block with text, an equation, and a list:


{{mbox
| type = 
| textstyle = font-size: 90%;
| text = '''''' A generic equation

:<math>
 f(x) = 0 
</math>
must be solved by a numerical method, such as


<ul>
 <li> Newton's method
 <li> The Bisection method
 <li> Fixed-point (Picard) iteration by rewriting <math>f(x)=x - g(x)</math>
 <li> The Secant method
</ul>
}}


Now test a box with equation only (note that this line continues the
box, it is not a new paragraph):


{{mbox
| type = 
| textstyle = font-size: 90%;
| text = '''''' :<math>
f(x) = \sin(x)e^{1-x} </math>
}}




{{mbox
| type = notice
| textstyle = font-size: 90%;
| text = '''Hint.''' Newton's method requires a good start vector to converge fast.
}}



Let's begin a new paragraph and show a box with code only:


{{mbox
| type = 
| textstyle = font-size: 90%;
| text = '''''' <syntaxhighlight lang="python">
def some_code(x):
    return sin(x)*exp(1-x)
</syntaxhighlight>
}}





==== Admonitions ====

Let us start with a plain warning environment.


{{mbox
| type = warning
| textstyle = font-size: 90%;
| text = '''Warning.''' And here is a warning about something to pay attention to. We
test how the heading behave and add quite some extra texts
in comparison with the other admons.


<ul>
  <li> and a list
  <li> with items
</ul>

We continue with more text to see how that affects the layout.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
And more and more text.
}}



Test warning with title:


{{mbox
| type = warning
| textstyle = font-size: 130%;
| text = '''Title ending with math <math>\sqrt{2}\approx 1.4</math>.''' And here comes some text with bad news in larger font.

Also some code:

<syntaxhighlight lang="python">
def f(x):
    return x
</syntaxhighlight>
And a complete program

<syntaxhighlight lang="python">
print("Hello, World!")
</syntaxhighlight>
}}



Test warning with large title with math:


{{mbox
| type = warning
| textstyle = font-size: 130%;
| text = '''Watch out for <math>\nabla\cdot\bm{u}=0</math> equations.''' Divergence freedom is often problematic from a numerical point
of view.
}}



Then we test a block, which is guaranteed to never have any admon icon.


{{mbox
| type = Block with title.
| textstyle = font-size: 80%;
| text = '''Block with title.''' Here is a block of text with title. It is typeset
''without any icon'' and is useful when you want some admons with icon
and some without. With the small font size, as used here, one can have
more comment-style text or text that really goes deeper or talks
about fun facts that are not strictly necessary for the main flow
of understanding.
}}





{{mbox
| type = 
| textstyle = font-size: 90%;
| text = '''''' Here is a block of text with no title. As above, it is typeset without any icon
and is useful when you want some admons with icon and some without.
}}



<!-- Note that the final ! does not appear in Sphinx and reST since -->
<!-- those formats automatically add : to the admonition title. -->


{{mbox
| type = notice
| textstyle = font-size: illegal-size;
| text = '''Note, eventually!''' Ah, we are soon close to the end (with illegal font size specification!).
But first a bit of math where we define <math>\theta</math> and <math>\bm{r}</math>:

:<math>
\begin{align*}
\theta &= q^2,\\
\bm{r} &= \varrho\bm{i}
\end{align*}
</math>
}}



<!-- Test one word with a number -->


{{mbox
| type = notice
| textstyle = font-size: 90%;
| text = '''Point1.''' Ah, we are soon close to the end.
}}




{{mbox
| type = Question.
| textstyle = font-size: 90%;
| text = '''Question.''' So, how many admonition environments does DocOnce support?
}}




{{mbox
| type = Question.
| textstyle = font-size: 90%;
| text = '''Question.''' 
<ol>
 <li> Once more, how many admonition environments does DocOnce support?
</ol>
}}




{{mbox
| type = warning
| textstyle = font-size: 90%;
| text = '''Tip.''' It is of outmost important to


<ol>
<li> stay cool
<li> read hints and tips carefully
</ol>

Because here the thing is to do

<syntaxhighlight lang="python">
import urllib

def grab(url, filename):
    urllib.urlretrieve(url, filename=filename)
</syntaxhighlight>
}}



Next is a warning without a title ("none" implies no title).


{{mbox
| type = warning
| textstyle = font-size: 90%;
| text = '''''' And here comes some text with bad news.
}}



==== Going deeper environments ====

Here is a long notice environment with a custom title and much
text, math and code.


{{mbox
| type = notice
| textstyle = font-size: 90%;
| text = '''Going deeper.''' We have some equations that should be preceded by much text, so the
task is to write and write. The number of words, and not the
meaning, is what counts here. We need desperately to fill up the
page in the hope that some admonitions will experience a page break,
which the LaTeX environment should handle with ease.

Let us start with some equations:

:<math>
\begin{align*}
\frac{Du}{dt} &= 0
\\
\frac{1}{2} &= {1/2}\\
\frac{1}{2}\pmb{x} &= \pmb{n}
\end{align*}
</math>

The implementation of such complicated equations in computer
code is task that this "Going deeper" environment targets.

<syntaxhighlight lang="python">
def Dudt(u):
    r = diff(u, t) + u*grad(u)
    return r

half = 0.5
x = 2*n
</syntaxhighlight>
And some more text that can help going into the next page.
Longer computer code requires vertical space:

<syntaxhighlight lang="python">
class Diff:
    def __init__(self, f, h=1E-5):
        self.f = f
        self.h = float(h)

class Forward1(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (f(x+h) - f(x))/h

class Backward1(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (f(x) - f(x-h))/h

class Central2(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (f(x+h) - f(x-h))/(2*h)

class Central4(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (4./3)*(f(x+h)   - f(x-h))  /(2*h) - \
               (1./3)*(f(x+2*h) - f(x-2*h))/(4*h)

class Central6(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (3./2) *(f(x+h)   - f(x-h))  /(2*h) - \
               (3./5) *(f(x+2*h) - f(x-2*h))/(4*h) + \
               (1./10)*(f(x+3*h) - f(x-3*h))/(6*h)

class Forward3(Diff):
    def __call__(self, x):
        f, h = self.f, self.h
        return (-(1./6)*f(x+2*h) + f(x+h) - 0.5*f(x) - \
                (1./3)*f(x-h))/h
</syntaxhighlight>
And then we add a figure too.


[[File:Wave1D.png|frame|400px|alt=Wave1D.png|<span title=""></span>]] <!-- not yet uploaded to common.wikimedia.org -->
}}




==== The end ====

A bit of text before the summary, which we now call "Concluding remarks,
for the novice",
just because we can.


{{mbox
| type = Concluding remarks, for the novice.
| textstyle = font-size: 90%;
| text = '''Concluding remarks, for the novice.''' We can summarize the most important things with admons: they have
a different typesetting, and they may have a symbol.
Titles should be optional.
}}



''Remark.''
The <code>remarks</code> and <code>hint</code> environments are not allowed outside
exercises (and problems and projects too).


************** File: admon.rst *****************
.. Automatically generated Sphinx-extended reStructuredText file from DocOnce source
   (https://github.com/hplgit/doconce/)

.. Document title:

Testing admons
%%%%%%%%%%%%%%

:Authors: H. P. Langtangen
:Date: Jan 32, 2100

.. !split

Introduction
============
First some ordinary text to compare font sizes in admonitions
and the surrounding text.

Note that ``automake_sphinx.py`` fixes the HTML file generated by Sphinx
so that all styles for admonitions have a colored background.

Code
----

Need some code outside admons for color and font comparisons:

.. code-block:: python

    def some_code(x):
        return sin(x)*exp(1-x)

And some plain text verbatim:

.. code-block:: text

    x=1.0 y=0.9 z=0.4
    x=1.1 y=0.3 z=0.1

Quotes and boxes
----------------

Here is a plain quote environment.


..

    Sayre's law states that
    "in any dispute the intensity of feeling is inversely
    proportional to the value of the issues at stake." 
    
    | By way of corollary, it adds: 
    | "That is why academic politics are so bitter." 
    | *Source*: `wikipedia <https://en.wikipedia.org/wiki/Sayre's_law>`__



Does quotes with title also work? No...cannot work in LaTeX and HTML
and then it does not make sense to support it.


.. warning::
    The boxes below are shown without any extra formatting in reST
    and Sphinx. We could use an admonition environment, but requires
    a title.




A plain *box* is sometimes useful. Let's show it here for comparison
with admons (especially the block admon has much in common with a box).
The box is more aimed at framing a law or an equation.

First a simple block with text, an equation, and a list:


.. The below box could be typeset as .. admonition: Attention
   but we have decided not to do so since the admon needs a title
   (the box formatting is therefore just ignored)

A generic equation

.. math::
         f(x) = 0 

must be solved by a numerical method, such as

 * Newton's method

 * The Bisection method

 * Fixed-point (Picard) iteration by rewriting :math:`f(x)=x - g(x)`

 * The Secant method

Now test a box with equation only (note that this line continues the
box, it is not a new paragraph):


.. The below box could be typeset as .. admonition: Attention
   but we have decided not to do so since the admon needs a title
   (the box formatting is therefore just ignored)


.. math::
   :label: _auto1

         f(x) = \sin(x)e^{1-x}


**Hint.**

Newton's method requires a good start vector to converge fast.



Let's begin a new paragraph and show a box with code only:


.. The below box could be typeset as .. admonition: Attention
   but we have decided not to do so since the admon needs a title
   (the box formatting is therefore just ignored)


.. code-block:: python

    def some_code(x):
        return sin(x)*exp(1-x)


Admonitions
-----------

Let us start with a plain warning environment.


.. warning::
    And here is a warning about something to pay attention to. We
    test how the heading behave and add quite some extra texts
    in comparison with the other admons.
    
      * and a list
    
      * with items
    
    We continue with more text to see how that affects the layout.
    And more and more text.
    And more and more text.
    And more and more text.
    And more and more text.
    And more and more text.
    And more and more text.




Test warning with title:


.. admonition:: Title ending with math :math:`\sqrt{2}\approx 1.4`

   And here comes some text with bad news in larger font.
   
   Also some code:
   
   .. code-block:: python
   
       def f(x):
           return x
   
   And a complete program
   
   .. code-block:: python
   
       print("Hello, World!")




Test warning with large title with math:
(we have no impact on the font size in the title in Sphinx)


.. admonition:: Watch out for :math:`\nabla\cdot\boldsymbol{u}=0` equations

   Divergence freedom is often problematic from a numerical point
   of view.




Then we test a block, which is guaranteed to never have any admon icon.


.. admonition:: Block with title

   Here is a block of text with title. It is typeset
   *without any icon* and is useful when you want some admons with icon
   and some without. With the small font size, as used here, one can have
   more comment-style text or text that really goes deeper or talks
   about fun facts that are not strictly necessary for the main flow
   of understanding.




Admonitions must have a title in Sphinx, otherwise they are not
shown. Here, for the following *block admon* (``!bblock``)
we have not specified any title, and DocOnce then
applies the generic title "Notice:" for the Sphinx format:


.. admonition:: Notice

   Here is a block of text with no title. As above, it is typeset without any icon
   and is useful when you want some admons with icon and some without.




.. Note that the final ! does not appear in Sphinx and reST since

.. those formats automatically add : to the admonition title.


.. admonition:: Note, eventually

   Ah, we are soon close to the end (with illegal font size specification!).
   But first a bit of math where we define :math:`\theta` and :math:`\boldsymbol{r}`:
   
   .. math::
           \begin{align*}
           \theta &= q^2,\\
           \boldsymbol{r} &= \varrho\boldsymbol{i}
           \end{align*}




.. Test one word with a number


.. admonition:: Point1

   Ah, we are soon close to the end.





.. admonition:: Question

   So, how many admonition environments does DocOnce support?





.. admonition:: Question

    1. Once more, how many admonition environments does DocOnce support?





.. admonition:: Tip

   It is of outmost important to
   
   1. stay cool
   
   2. read hints and tips carefully
   
   Because here the thing is to do
   
   .. code-block:: python
   
       import urllib
       
       def grab(url, filename):
           urllib.urlretrieve(url, filename=filename)




Next is a warning without a title ("none" implies no title).
Admonitions must have a title in Sphinx, otherwise they are not
shown. Here, we have not specified any title, and DocOnce then
applies the generic title "Notice:"


.. admonition:: Notice

   And here comes some text with bad news.




Going deeper environments
-------------------------

Here is a long notice environment with a custom title and much
text, math and code.


.. admonition:: Going deeper

   We have some equations that should be preceded by much text, so the
   task is to write and write. The number of words, and not the
   meaning, is what counts here. We need desperately to fill up the
   page in the hope that some admonitions will experience a page break,
   which the LaTeX environment should handle with ease.
   
   Let us start with some equations:
   
   .. math::
           \begin{align*}
           \frac{Du}{dt} &= 0
           \\
           \frac{1}{2} &= {1/2}\\
           \frac{1}{2}\pmb{x} &= \pmb{n}
           \end{align*}
   
   The implementation of such complicated equations in computer
   code is task that this "Going deeper" environment targets.
   
   .. code-block:: python
   
       def Dudt(u):
           r = diff(u, t) + u*grad(u)
           return r
       
       half = 0.5
       x = 2*n
   
   And some more text that can help going into the next page.
   Longer computer code requires vertical space:
   
   .. code-block:: python
   
       class Diff:
           def __init__(self, f, h=1E-5):
               self.f = f
               self.h = float(h)
       
       class Forward1(Diff):
           def __call__(self, x):
               f, h = self.f, self.h
               return (f(x+h) - f(x))/h
       
       class Backward1(Diff):
           def __call__(self, x):
               f, h = self.f, self.h
               return (f(x) - f(x-h))/h
       
       class Central2(Diff):
           def __call__(self, x):
               f, h = self.f, self.h
               return (f(x+h) - f(x-h))/(2*h)
       
       class Central4(Diff):
           def __call__(self, x):
               f, h = self.f, self.h
               return (4./3)*(f(x+h)   - f(x-h))  /(2*h) - \
                      (1./3)*(f(x+2*h) - f(x-2*h))/(4*h)
       
       class Central6(Diff):
           def __call__(self, x):
               f, h = self.f, self.h
               return (3./2) *(f(x+h)   - f(x-h))  /(2*h) - \
                      (3./5) *(f(x+2*h) - f(x-2*h))/(4*h) + \
                      (1./10)*(f(x+3*h) - f(x-3*h))/(6*h)
       
       class Forward3(Diff):
           def __call__(self, x):
               f, h = self.f, self.h
               return (-(1./6)*f(x+2*h) + f(x+h) - 0.5*f(x) - \
                       (1./3)*f(x-h))/h
   
   And then we add a figure too.
   
   .. figure:: ../doc/src/manual/fig/wave1D.png
      :width: 400




The end
-------

A bit of text before the summary, which we now call "Concluding remarks,
for the novice",
just because we can.


.. admonition:: Concluding remarks, for the novice

   We can summarize the most important things with admons: they have
   a different typesetting, and they may have a symbol.
   Titles should be optional.




**Remark.**
The ``remarks`` and ``hint`` environments are not allowed outside
exercises (and problems and projects too).

************** File: admon_paragraph.txt *****************
Testing admons
==============

H. P. Langtangen

Date: Jan 32, 2100

Copyright 2021, H. P. Langtangen. Made with DocOnce

# !split
Introduction
============
First some ordinary text to compare font sizes in admonitions
and the surrounding text.

Code
----

Need some code outside admons for color and font comparisons::

        def some_code(x):
            return sin(x)*exp(1-x)

And some plain text verbatim::

        x=1.0 y=0.9 z=0.4
        x=1.1 y=0.3 z=0.1

Quotes and boxes
----------------

Here is a plain quote environment.

        Sayre's law states that
        "in any dispute the intensity of feeling is inversely
        proportional to the value of the issues at stake." 
        By way of corollary, it adds: 
        "That is why academic politics are so bitter." 
        *Source*: wikipedia (https://en.wikipedia.org/wiki/Sayre's_law)


Does quotes with title also work? No...cannot work in LaTeX and HTML
and then it does not make sense to support it.

A plain *box* is sometimes useful. Let's show it here for comparison
with admons (especially the block admon has much in common with a box).
The box is more aimed at framing a law or an equation.

First a simple block with text, an equation, and a list:


|--------------------------------------------------------------|
| A generic equation::                                         |
|                                                              |
|         \[ f(x) = 0 \]                                       |
|                                                              |
| must be solved by a numerical method, such as                |
|                                                              |
|  * Newton's method                                           |
|                                                              |
|  * The Bisection method                                      |
|                                                              |
|  * Fixed-point (Picard) iteration by rewriting f(x)=x - g(x) |
|                                                              |
|  * The Secant method                                         |
|--------------------------------------------------------------|

Now test a box with equation only (note that this line continues the
box, it is not a new paragraph):


|---------------------------------------------------------------|
|         \begin{equation} f(x) = \sin(x)e^{1-x} \end{equation} |
|---------------------------------------------------------------|



Hint ------------------------------------------------------------|
|                                                                |
| Newton's method requires a good start vector to converge fast. |
|----------------------------------------------------------------|


Let's begin a new paragraph and show a box with code only:


|------------------------------------|
|         def some_code(x):          |
|             return sin(x)*exp(1-x) |
|------------------------------------|


Admonitions
-----------

Let us start with a plain warning environment.


Warning ---------------------------------------------------------|
|                                                                |
| And here is a warning about something to pay attention to. We  |
| test how the heading behave and add quite some extra texts     |
| in comparison with the other admons.                           |
|                                                                |
|   * and a list                                                 |
|                                                                |
|   * with items                                                 |
|                                                                |
| We continue with more text to see how that affects the layout. |
| And more and more text.                                        |
| And more and more text.                                        |
| And more and more text.                                        |
| And more and more text.                                        |
| And more and more text.                                        |
| And more and more text.                                        |
|----------------------------------------------------------------|


Test warning with title:


Title ending with math \sqrt{2}\approx 1.4 --------------|
|                                                        |
| And here comes some text with bad news in larger font. |
|                                                        |
| Also some code::                                       |
|                                                        |
|         def f(x):                                      |
|             return x                                   |
|                                                        |
| And a complete program::                               |
|                                                        |
|         print("Hello, World!")                         |
|--------------------------------------------------------|


Test warning with large title with math:


Watch out for \nabla\cdot\bm{u}=0 equations ---------------------|
|                                                                |
| Divergence freedom is often problematic from a numerical point |
| of view.                                                       |
|----------------------------------------------------------------|


Then we test a block, which is guaranteed to never have any admon icon.


Block with title --------------------------------------------------------|
|                                                                        |
| Here is a block of text with title. It is typeset                      |
| *without any icon* and is useful when you want some admons with icon   |
| and some without. With the small font size, as used here, one can have |
| more comment-style text or text that really goes deeper or talks       |
| about fun facts that are not strictly necessary for the main flow      |
| of understanding.                                                      |
|------------------------------------------------------------------------|



Block ----------------------------------------------------------------------------|
|                                                                                 |
| Here is a block of text with no title. As above, it is typeset without any icon |
| and is useful when you want some admons with icon and some without.             |
|---------------------------------------------------------------------------------|



Note, eventually! ----------------------------------------------------------|
|                                                                           |
| Ah, we are soon close to the end (with illegal font size specification!). |
| But first a bit of math where we define \theta and \bm{r}::               |
|                                                                           |
|         \begin{align*}                                                    |
|         \theta &= q^2,\\                                                  |
|         \bm{r} &= \varrho\bm{i}                                           |
|         \end{align*}                                                      |
|---------------------------------------------------------------------------|



Point1 -----------------------------|
|                                   |
| Ah, we are soon close to the end. |
|-----------------------------------|



Question ----------------------------------------------------|
|                                                            |
| So, how many admonition environments does DocOnce support? |
|------------------------------------------------------------|



Question ---------------------------------------------------------------|
|                                                                       |
|  1. Once more, how many admonition environments does DocOnce support? |
|-----------------------------------------------------------------------|



Tip -----------------------------------------------------|
|                                                        |
| It is of outmost important to                          |
|                                                        |
| 1. stay cool                                           |
|                                                        |
| 2. read hints and tips carefully                       |
|                                                        |
| Because here the thing is to do::                      |
|                                                        |
|         import urllib                                  |
|                                                        |
|         def grab(url, filename):                       |
|             urllib.urlretrieve(url, filename=filename) |
|--------------------------------------------------------|


Next is a warning without a title ("none" implies no title).


|-----------------------------------------|
| And here comes some text with bad news. |
|-----------------------------------------|


Going deeper environments
-------------------------

Here is a long notice environment with a custom title and much
text, math and code.


Going deeper. ---------------------------------------------------------|
|                                                                      |
| We have some equations that should be preceded by much text, so the  |
| task is to write and write. The number of words, and not the         |
| meaning, is what counts here. We need desperately to fill up the     |
| page in the hope that some admonitions will experience a page break, |
| which the LaTeX environment should handle with ease.                 |
|                                                                      |
| Let us start with some equations::                                   |
|                                                                      |
|         \begin{align*}                                               |
|         \frac{Du}{dt} &= 0                                           |
|         \\                                                           |
|         \frac{1}{2} &= {1/2}\\                                       |
|         \frac{1}{2}\pmb{x} &= \pmb{n}                                |
|         \end{align*}                                                 |
|                                                                      |
| The implementation of such complicated equations in computer         |
| code is task that this "Going deeper" environment targets::          |
|                                                                      |
|         def Dudt(u):                                                 |
|             r = diff(u, t) + u*grad(u)                               |
|             return r                                                 |
|                                                                      |
|         half = 0.5                                                   |
|         x = 2*n                                                      |
|                                                                      |
| And some more text that can help going into the next page.           |
| Longer computer code requires vertical space::                       |
|                                                                      |
|         class Diff:                                                  |
|             def __init__(self, f, h=1E-5):                           |
|                 self.f = f                                           |
|                 self.h = float(h)                                    |
|                                                                      |
|         class Forward1(Diff):                                        |
|             def __call__(self, x):                                   |
|                 f, h = self.f, self.h                                |
|                 return (f(x+h) - f(x))/h                             |
|                                                                      |
|         class Backward1(Diff):                                       |
|             def __call__(self, x):                                   |
|                 f, h = self.f, self.h                                |
|                 return (f(x) - f(x-h))/h                             |
|                                                                      |
|         class Central2(Diff):                                        |
|             def __call__(self, x):                                   |
|                 f, h = self.f, self.h                                |
|                 return (f(x+h) - f(x-h))/(2*h)                       |
|                                                                      |
|         class Central4(Diff):                                        |
|             def __call__(self, x):                                   |
|                 f, h = self.f, self.h                                |
|                 return (4./3)*(f(x+h)   - f(x-h))  /(2*h) - \        |
|                        (1./3)*(f(x+2*h) - f(x-2*h))/(4*h)            |
|                                                                      |
|         class Central6(Diff):                                        |
|             def __call__(self, x):                                   |
|                 f, h = self.f, self.h                                |
|                 return (3./2) *(f(x+h)   - f(x-h))  /(2*h) - \       |
|                        (3./5) *(f(x+2*h) - f(x-2*h))/(4*h) + \       |
|                        (1./10)*(f(x+3*h) - f(x-3*h))/(6*h)           |
|                                                                      |
|         class Forward3(Diff):                                        |
|             def __call__(self, x):                                   |
|                 f, h = self.f, self.h                                |
|                 return (-(1./6)*f(x+2*h) + f(x+h) - 0.5*f(x) - \     |
|                         (1./3)*f(x-h))/h                             |
|                                                                      |
| And then we add a figure too.                                        |
|                                                                      |
| FIGURE: [../doc/src/manual/fig/wave1D, width=400 frac=0.7]           |
|----------------------------------------------------------------------|


The end
-------

A bit of text before the summary, which we now call "Concluding remarks,
for the novice",
just because we can.


Concluding remarks, for the novice ---------------------------------|
|                                                                   |
| We can summarize the most important things with admons: they have |
| a different typesetting, and they may have a symbol.              |
| Titles should be optional.                                        |
|-------------------------------------------------------------------|


*Remark.*
The remarks and hint environments are not allowed outside
exercises (and problems and projects too).

************** File: locale.do.txt *****************
NOT FOUND!
************** File: locale.html *****************
NOT FOUND!
************** File: locale.tex *****************
NOT FOUND!
************** File: slides1.do.txt *****************
TITLE: Document for Testing Some Basic and Some Challenging Constructs in DocOnce Slides
AUTHOR: Hans Petter Langtangen at Simula Research Laboratory & University of Oslo
DATE: Today

!split
======= This is the first section =======
# Short title: First

!split
===== Figure and bullet list =====

!bslidecell 00  0.60
!bpop
!bblock (small) Title with comma, and brackets: $[a,b]$
  * Here is a *wave signal* $f(x-ct)$
  * It moves with velocity $c$
  * But here it is just a figure
!eblock
!epop
!eslidecell

!bslidecell 01
!bblock
FIGURE: [../doc/src/manual/fig/wave1D.png, width=300 frac=0.7]
!eblock
!eslidecell

!split
===== Slide with pop-ups in red and notes =====

[hpl: Comments are typeset as usual in DocOnce.]

!bpop highlight-red
Here we have a paragraph to pop up in red.<linebreak>
And a line more
!epop

!bnotes
One can also have ordinary notes.
Over multiple lines.
!enotes

!split
===== A LaTeX document =====

## Beamer had trouble with multiple \title{} strings, check that it works.

!bpop
!bc latex
\documentclass[11pt]{article}
\usepackage{fancyvrb}
\begin{document}

\title{Here goes the title...}
\author{John Doe \and
Jane Doe\footnote{\texttt{jane.doe@cyber.net}.}}
\date{\today}
\maketitle
!ec
!epop

!bpop
!bnotice
LaTeX has a lot of backslashes.
!enotice
!epop

!bpop
!bc latex
\section{Heading}
bla-bla
\end{document}
!ec
!epop

!split
===== An HTML document =====

!bc html
<html><head></head><body bgcolor="red">
<title>Here goes the title...<title>
<h1>Section heading</h1>
</body>
</html>
!ec

!split
======= Second section =======

!bblock
FIGURE: [../doc/src/manual/fig/wave1D.png, width=600 frac=0.8]
!eblock

!split
===== Some math and computer code =====

## Command and [] used to be problematic in blocks, check that it is ok

!bblock A simple, mathematical formula where $t\in [0,\pi]$:
!bt
\[ f(x,y,t) = e^{-xt}\sin\pi y \]
!et
!eblock

!bblock Bash demanded more of DocOnce than Python, so let's do Bash:
First, inline `$? != 0`, then comments with dollar variables (and minted
style):

!bc shcod
var=10
# $1, $2, ... are command-line args
if [ $? -eq 0 ]; then   # $? reflects success or not
  echo "Great!"
fi
!ec
!eblock

!split
===== Pop ups inside code blocks (for Beamer slides only) =====

!bc pycod
def f(x):
    return 42 + x

(*@\pause@*)
def g(x):
    return f(42)

(*@\pause@*)
print(g(13))
!ec

!split
===== Various admon blocks =====

Can use admons to simulate blocks:

!bpop
!bnotice (large) Key PDE (with large title and math font):
!bt
\[ \frac{\partial u}{\partial t} = \nabla^2 u \]
!et
!enotice
!epop

!bpop
!bsummary None
Just some block with text and a conclusion that something is important.
This one pops up after the rest of the slide.
!esummary
!epop

!bpop
!bwarning (small)
Can use, e.g., a warning admon to have my own notes, preferably
inside preprocess/mako if statements to turn notes on and off.
This one is typeset in a small font and with the default
title (Warning) since no title is specified.
!ewarning
!epop

************** File: slides1_reveal.html *****************
<!DOCTYPE html>

<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="DocOnce: https://github.com/doconce/doconce/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="description" content="Document for Testing Some Basic and Some Challenging Constructs in DocOnce Slides">

<title>Document for Testing Some Basic and Some Challenging Constructs in DocOnce Slides</title>







<!-- reveal.js: https://lab.hakim.se/reveal-js/ -->

<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">

<meta name="apple-mobile-web-app-capable" content="yes" />
<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent" />
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, minimal-ui">

<link rel="stylesheet" href="reveal.js/css/reveal.css">
<link rel="stylesheet" href="reveal.js/css/theme/beige.css" id="theme">
<!--
<link rel="stylesheet" href="reveal.js/css/reveal.css">
<link rel="stylesheet" href="reveal.js/css/theme/beige.css" id="theme">
<link rel="stylesheet" href="reveal.js/css/theme/beigesmall.css" id="theme">
<link rel="stylesheet" href="reveal.js/css/theme/solarized.css" id="theme">
<link rel="stylesheet" href="reveal.js/css/theme/serif.css" id="theme">
<link rel="stylesheet" href="reveal.js/css/theme/night.css" id="theme">
<link rel="stylesheet" href="reveal.js/css/theme/moon.css" id="theme">
<link rel="stylesheet" href="reveal.js/css/theme/simple.css" id="theme">
<link rel="stylesheet" href="reveal.js/css/theme/sky.css" id="theme">
<link rel="stylesheet" href="reveal.js/css/theme/darkgray.css" id="theme">
<link rel="stylesheet" href="reveal.js/css/theme/default.css" id="theme">
<link rel="stylesheet" href="reveal.js/css/theme/cbc.css" id="theme">
<link rel="stylesheet" href="reveal.js/css/theme/simula.css" id="theme">
<link rel="stylesheet" href="reveal.js/css/theme/black.css" id="theme">
<link rel="stylesheet" href="reveal.js/css/theme/white.css" id="theme">
<link rel="stylesheet" href="reveal.js/css/theme/league.css" id="theme">
-->

<!-- For syntax highlighting -->
<link rel="stylesheet" href="reveal.js/lib/css/zenburn.css">

<!-- Printing and PDF exports -->
<script>
var link = document.createElement( 'link' );
link.rel = 'stylesheet';
link.type = 'text/css';
link.href = window.location.search.match( /print-pdf/gi ) ? 'css/print/pdf.css' : 'css/print/paper.css';
document.getElementsByTagName( 'head' )[0].appendChild( link );
</script>

<style type="text/css">
    hr { border: 0; width: 80%; border-bottom: 1px solid #aaa}
    p.caption { width: 80%; font-size: 60%; font-style: italic; text-align: left; }
    hr.figure { border: 0; width: 80%; border-bottom: 1px solid #aaa}
    .reveal .alert-text-small   { font-size: 80%;  }
    .reveal .alert-text-large   { font-size: 130%; }
    .reveal .alert-text-normal  { font-size: 90%;  }
    .reveal .alert {
             padding:8px 35px 8px 14px; margin-bottom:18px;
             text-shadow:0 1px 0 rgba(255,255,255,0.5);
             border:5px solid #bababa;
             -webkit-border-radius: 14px; -moz-border-radius: 14px;
             border-radius:14px;
             background-position: 10px 10px;
             background-repeat: no-repeat;
             background-size: 38px;
             padding-left: 30px; /* 55px; if icon */
     }
     .reveal .alert-block {padding-top:14px; padding-bottom:14px}
     .reveal .alert-block > p, .alert-block > ul {margin-bottom:1em}
     /*.reveal .alert li {margin-top: 1em}*/
     .reveal .alert-block p+p {margin-top:5px}
     /*.reveal .alert-notice { background-image: url(https://hplgit.github.io/doconce/bundled/html_images/small_gray_notice.png); }
     .reveal .alert-summary  { background-image:url(https://hplgit.github.io/doconce/bundled/html_images/small_gray_summary.png); }
     .reveal .alert-warning { background-image: url(https://hplgit.github.io/doconce/bundled/html_images/small_gray_warning.png); }
     .reveal .alert-question {background-image:url(https://hplgit.github.io/doconce/bundled/html_images/small_gray_question.png); } */

</style>



<!-- Styles for table layout of slides -->
<style type="text/css">
td.padding {
  padding-top:20px;
  padding-bottom:20px;
  padding-right:50px;
  padding-left:50px;
}
</style>

</head>

<body>
<div class="reveal">

<!-- Any section element inside the <div class="slides"> container
     is displayed as a slide -->

<div class="slides">





<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  TeX: {
     equationNumbers: {  autoNumber: "none"  },
     extensions: ["AMSmath.js", "AMSsymbols.js", "autobold.js", "color.js"]
  }
});
</script>
<script type="text/javascript" async
 src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>



    



<section>
<!-- ------------------- main content ---------------------- -->



<center><h1 style="text-align: center;">Document for Testing Some Basic and Some Challenging Constructs in DocOnce Slides</h1></center>  <!-- document title -->

<p>
<!-- author(s): Hans Petter Langtangen -->

<center>
<b>Hans Petter Langtangen</b> [1, 2]
</center>

<p>&nbsp;<br>
<!-- institution(s) -->

<center>[1] <b>Simula Research Laboratory</b></center>
<center>[2] <b>University of Oslo</b></center>
<br>
<p>&nbsp;<br>
<center><h4>Jan 32, 2100</h4></center> <!-- date -->
<br>
</section>


<section>
<h1 id="this-is-the-first-section">This is the first section </h1>
<!-- Short title: First -->
</section>


<section>
<h2 id="figure-and-bullet-list">Figure and bullet list </h2>

<p>

<table border="0">
<tr>
<td class="padding">

<div class="fragment alert alert-block alert-block alert-text-small">
<b>Title with comma, and brackets: \( [a,b] \)</b>
<ul>

<p><li class="fragment"> Here is a <em>wave signal</em> \( f(x-ct) \)</li>

<p><li class="fragment"> It moves with velocity \( c \)</li>

<p><li class="fragment"> But here it is just a figure</li>
</ul>
</div>


</td>
<td class="padding">
<div class="alert alert-block alert-block alert-text-normal">
<b></b>
<p>
<br /><br /><center><p><img src="../doc/src/manual/fig/wave1D.png" align="bottom" width=300></p></center><br /><br />
</div>

</td>
</tr>
</table>
</section>


<section>
<h2 id="slide-with-pop-ups-in-red-and-notes">Slide with pop-ups in red and notes </h2>

<p>

<!-- begin inline comment -->
<font color="red">(<b>hpl 1</b>: Comments are typeset as usual in DocOnce.)</font>
<!-- end inline comment -->

<p>

<p class="fragment">

<span class="fragment highlight-red">

Here we have a paragraph to pop up in red.<br />
And a line more

</span>

</p>

<p>
<aside class="notes">
<!-- click "s" to activate -->

One can also have ordinary notes.
Over multiple lines.

</aside>
</section>


<section>
<h2 id="a-latex-document">A LaTeX document </h2>

<p>

<!-- code=latex (!bc latex) typeset with pygments style "perldoc" -->
<div class="fragment" class="highlight" style="background: #eeeedd"><pre style="font-size: 80%; line-height: 125%;"><span></span><span style="color: #8B008B; font-weight: bold">\documentclass</span><span style="color: #658b00">[11pt]{</span>article<span style="color: #658b00">}</span>
<span style="color: #8B008B; font-weight: bold">\usepackage</span><span style="color: #658b00">{</span>fancyvrb<span style="color: #658b00">}</span>
<span style="color: #8B008B; font-weight: bold">\begin</span><span style="color: #658b00">{</span>document<span style="color: #658b00">}</span>

<span style="color: #8B008B; font-weight: bold">\title</span><span style="color: #658b00">{</span>Here goes the title...<span style="color: #658b00">}</span>
<span style="color: #8B008B; font-weight: bold">\author</span><span style="color: #658b00">{</span>John Doe <span style="color: #8B008B; font-weight: bold">\and</span>
Jane Doe<span style="color: #8B008B; font-weight: bold">\footnote</span><span style="color: #658b00">{</span><span style="color: #8B008B; font-weight: bold">\texttt</span><span style="color: #658b00">{</span>jane.doe@cyber.net<span style="color: #658b00">}</span>.<span style="color: #658b00">}}</span>
<span style="color: #8B008B; font-weight: bold">\date</span><span style="color: #658b00">{</span><span style="color: #8B008B; font-weight: bold">\today</span><span style="color: #658b00">}</span>
<span style="color: #8B008B; font-weight: bold">\maketitle</span>
</pre></div>
<p>

<div class="fragment alert alert-block alert-notice alert-text-normal">
<b>Notice</b>
<p>
LaTeX has a lot of backslashes.
</div>

<p>

<!-- code=latex (!bc latex) typeset with pygments style "perldoc" -->
<div class="fragment" class="highlight" style="background: #eeeedd"><pre style="font-size: 80%; line-height: 125%;"><span></span><span style="color: #8B008B; font-weight: bold">\section</span><span style="color: #658b00">{</span>Heading<span style="color: #658b00">}</span>
bla-bla
<span style="color: #8B008B; font-weight: bold">\end</span><span style="color: #658b00">{</span>document<span style="color: #658b00">}</span>
</pre></div>
</section>


<section>
<h2 id="an-html-document">An HTML document </h2>

<p>

<!-- code=html (!bc html) typeset with pygments style "perldoc" -->
<div class="highlight" style="background: #eeeedd"><pre style="font-size: 80%; line-height: 125%;"><span></span>&lt;<span style="color: #8B008B; font-weight: bold">html</span>&gt;&lt;<span style="color: #8B008B; font-weight: bold">head</span>&gt;&lt;/<span style="color: #8B008B; font-weight: bold">head</span>&gt;&lt;<span style="color: #8B008B; font-weight: bold">body</span> <span style="color: #658b00">bgcolor</span>=<span style="color: #CD5555">&quot;red&quot;</span>&gt;
&lt;<span style="color: #8B008B; font-weight: bold">title</span>&gt;Here goes the title...&lt;<span style="color: #8B008B; font-weight: bold">title</span>&gt;
&lt;<span style="color: #8B008B; font-weight: bold">h1</span>&gt;Section heading&lt;/<span style="color: #8B008B; font-weight: bold">h1</span>&gt;
&lt;/<span style="color: #8B008B; font-weight: bold">body</span>&gt;
&lt;/<span style="color: #8B008B; font-weight: bold">html</span>&gt;
</pre></div>
</section>


<section>
<h1 id="second-section">Second section </h1>

<p>
<div class="alert alert-block alert-block alert-text-normal">
<b></b>
<p>
<br /><br /><center><p><img src="../doc/src/manual/fig/wave1D.png" align="bottom" width=600></p></center><br /><br />
</div>
</section>


<section>
<h2 id="some-math-and-computer-code">Some math and computer code </h2>

<p>
<div class="alert alert-block alert-block alert-text-normal">
<b>A simple, mathematical formula where \( t\in [0,\pi] \):</b>
<p>&nbsp;<br>
$$ f(x,y,t) = e^{-xt}\sin\pi y $$
<p>&nbsp;<br>
</div>

<p>
<div class="alert alert-block alert-block alert-text-normal">
<b>Bash demanded more of DocOnce than Python, so let's do Bash:</b>
<p>
First, inline <code>$? != 0</code>, then comments with dollar variables (and minted
style):

<p>

<!-- code=bash (!bc shcod) typeset with pygments style "perldoc" -->
<div class="highlight" style="background: #eeeedd"><pre style="font-size: 80%; line-height: 125%;"><span></span><span style="color: #00688B">var</span>=<span style="color: #B452CD">10</span>
<span style="color: #228B22"># $1, $2, ... are command-line args</span>
<span style="color: #8B008B; font-weight: bold">if</span> [ <span style="color: #00688B">$?</span> -eq <span style="color: #B452CD">0</span> ]; <span style="color: #8B008B; font-weight: bold">then</span>   <span style="color: #228B22"># $? reflects success or not</span>
  <span style="color: #658b00">echo</span> <span style="color: #CD5555">&quot;Great!&quot;</span>
<span style="color: #8B008B; font-weight: bold">fi</span>
</pre></div>

</div>
</section>


<section>
<h2 id="pop-ups-inside-code-blocks-for-beamer-slides-only">Pop ups inside code blocks (for Beamer slides only) </h2>

<p>

<!-- code=python (!bc pycod) typeset with pygments style "perldoc" -->
<div class="highlight" style="background: #eeeedd"><pre style="font-size: 80%; line-height: 125%;"><span></span><span style="color: #8B008B; font-weight: bold">def</span> <span style="color: #008b45">f</span>(x):
    <span style="color: #8B008B; font-weight: bold">return</span> <span style="color: #B452CD">42</span> + x

<span style="color: #8B008B; font-weight: bold">def</span> <span style="color: #008b45">g</span>(x):
    <span style="color: #8B008B; font-weight: bold">return</span> f(<span style="color: #B452CD">42</span>)

<span style="color: #658b00">print</span>(g(<span style="color: #B452CD">13</span>))
</pre></div>
</section>


<section>
<h2 id="various-admon-blocks">Various admon blocks </h2>

<p>
Can use admons to simulate blocks:

<p>

<div class="fragment alert alert-block alert-notice alert-text-large">
<b>Key PDE (with large title and math font):</b>
<p>&nbsp;<br>
$$ \frac{\partial u}{\partial t} = \nabla^2 u $$
<p>&nbsp;<br>
</div>

<p>

<div class="fragment alert alert-block alert-summary alert-text-normal">
<b></b>
<p>
Just some block with text and a conclusion that something is important.
This one pops up after the rest of the slide.
</div>

<p>

<div class="fragment alert alert-block alert-warning alert-text-small">
<b>Warning</b>
<p>
Can use, e.g., a warning admon to have my own notes, preferably
inside preprocess/mako if statements to turn notes on and off.
This one is typeset in a small font and with the default
title (Warning) since no title is specified.
</div>
</section>



</div> <!-- class="slides" -->
</div> <!-- class="reveal" -->

<script src="reveal.js/lib/js/head.min.js"></script>
<script src="reveal.js/js/reveal.js"></script>

<script>
// Full list of configuration options available here:
// https://github.com/hakimel/reveal.js#configuration
Reveal.initialize({

    // Display navigation controls in the bottom right corner
    controls: true,

    // Display progress bar (below the horiz. slider)
    progress: true,

    // Display the page number of the current slide
    slideNumber: true,

    // Push each slide change to the browser history
    history: false,

    // Enable keyboard shortcuts for navigation
    keyboard: true,

    // Enable the slide overview mode
    overview: true,

    // Vertical centering of slides
    //center: true,
    center: false,

    // Enables touch navigation on devices with touch input
    touch: true,

    // Loop the presentation
    loop: false,

    // Change the presentation direction to be RTL
    rtl: false,

    // Turns fragments on and off globally
    fragments: true,

    // Flags if the presentation is running in an embedded mode,
    // i.e. contained within a limited portion of the screen
    embedded: false,

    // Number of milliseconds between automatically proceeding to the
    // next slide, disabled when set to 0, this value can be overwritten
    // by using a data-autoslide attribute on your slides
    autoSlide: 0,

    // Stop auto-sliding after user input
    autoSlideStoppable: true,

    // Enable slide navigation via mouse wheel
    mouseWheel: false,

    // Hides the address bar on mobile devices
    hideAddressBar: true,

    // Opens links in an iframe preview overlay
    previewLinks: false,

    // Transition style
    transition: 'default', // default/cube/page/concave/zoom/linear/fade/none

    // Transition speed
    transitionSpeed: 'default', // default/fast/slow

    // Transition style for full page slide backgrounds
    backgroundTransition: 'default', // default/none/slide/concave/convex/zoom

    // Number of slides away from the current that are visible
    viewDistance: 3,

    // Parallax background image
    //parallaxBackgroundImage: '', // e.g. "'https://s3.amazonaws.com/hakim-static/reveal-js/reveal-parallax-1.jpg'"

    // Parallax background size
    //parallaxBackgroundSize: '' // CSS syntax, e.g. "2100px 900px"

    theme: Reveal.getQueryHash().theme, // available themes are in reveal.js/css/theme
    transition: Reveal.getQueryHash().transition || 'default', // default/cube/page/concave/zoom/linear/none

});

Reveal.initialize({
    dependencies: [
        // Cross-browser shim that fully implements classList - https://github.com/eligrey/classList.js/
        { src: 'reveal.js/lib/js/classList.js', condition: function() { return !document.body.classList; } },

        // Interpret Markdown in <section> elements
        { src: 'reveal.js/plugin/markdown/marked.js', condition: function() { return !!document.querySelector( '[data-markdown]' ); } },
        { src: 'reveal.js/plugin/markdown/markdown.js', condition: function() { return !!document.querySelector( '[data-markdown]' ); } },

        // Syntax highlight for <code> elements
        { src: 'reveal.js/plugin/highlight/highlight.js', async: true, callback: function() { hljs.initHighlightingOnLoad(); } },

        // Zoom in and out with Alt+click
        { src: 'reveal.js/plugin/zoom-js/zoom.js', async: true, condition: function() { return !!document.body.classList; } },

        // Speaker notes
        { src: 'reveal.js/plugin/notes/notes.js', async: true, condition: function() { return !!document.body.classList; } },

        // Remote control your reveal.js presentation using a touch device
        //{ src: 'reveal.js/plugin/remotes/remotes.js', async: true, condition: function() { return !!document.body.classList; } },

        // MathJax
        //{ src: 'reveal.js/plugin/math/math.js', async: true }
    ]
});

Reveal.initialize({

    // The "normal" size of the presentation, aspect ratio will be preserved
    // when the presentation is scaled to fit different resolutions. Can be
    // specified using percentage units.
    width: 1170,  // original: 960,
    height: 700,

    // Factor of the display size that should remain empty around the content
    margin: 0.1,

    // Bounds for smallest/largest possible scale to apply to content
    minScale: 0.2,
    maxScale: 1.0

});
</script>

<!-- begin footer logo
<div style="position: absolute; bottom: 0px; left: 0; margin-left: 0px">
<img src="somelogo.png">
</div>
     end footer logo -->



</body>
</html>
reveal.js:
bower.json
CONTRIBUTING.md
css
Gruntfile.js
index.html
js
lib
LICENSE
package.json
plugin
README.md
test

reveal.js/css:
images
print
reveal.css
reveal.scss
theme

reveal.js/css/images:
cbc_footer.png
cbc_symbol.png
simula_footer.png
simula_logo.png
simula_symbol.png
uio_footer.png
uio_symbol.png

reveal.js/css/print:
paper.css
pdf.css

reveal.js/css/theme:
beige.css
beigesmall.css
black.css
blood.css
cbc.css
darkgray.css
default.css
league.css
moon.css
night.css
README.md
serif.css
simple.css
simula.css
sky.css
solarized.css
source
template
white.css

reveal.js/css/theme/source:
beige.scss
beigesmall.scss
black.scss
blood.scss
cbc.scss
darkgray.scss
default.scss
league.scss
moon.scss
night.scss
serif.scss
simple.scss
simula.scss
sky.scss
solarized.scss
white.scss

reveal.js/css/theme/template:
mixins.scss
settings.scss
theme.scss

reveal.js/js:
reveal.js

reveal.js/lib:
css
font
js

reveal.js/lib/css:
zenburn.css

reveal.js/lib/font:
league-gothic
source-sans-pro

reveal.js/lib/font/league-gothic:
league-gothic.css
league-gothic.eot
league-gothic.ttf
league-gothic.woff
LICENSE

reveal.js/lib/font/source-sans-pro:
LICENSE
source-sans-pro.css
source-sans-pro-italic.eot
source-sans-pro-italic.ttf
source-sans-pro-italic.woff
source-sans-pro-regular.eot
source-sans-pro-regular.ttf
source-sans-pro-regular.woff
source-sans-pro-semibold.eot
source-sans-pro-semibolditalic.eot
source-sans-pro-semibolditalic.ttf
source-sans-pro-semibolditalic.woff
source-sans-pro-semibold.ttf
source-sans-pro-semibold.woff

reveal.js/lib/js:
classList.js
head.min.js
html5shiv.js

reveal.js/plugin:
highlight
leap
markdown
math
multiplex
notes
notes-server
print-pdf
remotes
search
zoom-js

reveal.js/plugin/highlight:
highlight.js

reveal.js/plugin/leap:
leap.js

reveal.js/plugin/markdown:
example.html
example.md
markdown.js
marked.js

reveal.js/plugin/math:
math.js

reveal.js/plugin/multiplex:
client.js
index.js
master.js

reveal.js/plugin/notes:
notes.html
notes.js

reveal.js/plugin/notes-server:
client.js
index.js
notes.html

reveal.js/plugin/print-pdf:
print-pdf.js

reveal.js/plugin/remotes:
remotes.js

reveal.js/plugin/search:
search.js

reveal.js/plugin/zoom-js:
zoom.js

reveal.js/test:
examples
qunit-1.12.0.css
qunit-1.12.0.js
test.html
test.js
test-markdown-element-attributes.html
test-markdown-element-attributes.js
test-markdown.html
test-markdown.js
test-markdown-slide-attributes.html
test-markdown-slide-attributes.js
test-pdf.html
test-pdf.js

reveal.js/test/examples:
assets
barebones.html
embedded-media.html
math.html
slide-backgrounds.html
slide-transitions.html

reveal.js/test/examples/assets:
image1.png
image2.png

************** File: tmp_slides_html_all.sh *****************
#!/bin/sh

doconce format html slides1 SLIDE_TYPE=dummy SLIDE_THEME=dummy
doconce slides_html slides1 doconce

doconce format html slides1 --pygments_html_style=default --keep_pygments_html_bg SLIDE_TYPE=html SLIDE_THEME=blueish --html_style=blueish --html_output=slides1_html_blueish
doconce split_html slides1_html_blueish --method=colorline  # one long file

doconce format html slides1 --pygments_html_style=default --keep_pygments_html_bg SLIDE_TYPE=html SLIDE_THEME=bloodish --html_style=bloodish --html_output=slides1_html_bloodish
doconce split_html slides1_html_bloodish --method=space8  # one long file

doconce format html slides1 SLIDE_TYPE=html SLIDE_THEME=solarized --html_style=solarized --html_output=slides1_html_solarized
doconce slides_html slides1_html_solarized doconce --nav_button=gray2,bottom --font_size=slides

doconce format html slides1 SLIDE_TYPE=html SLIDE_THEME=solarized2 --html_style=solarized2 --html_output=slides1_html_solarized2
doconce slides_html slides1_html_solarized2 doconce --nav_button=gray2,bottom --font_size=slides

doconce format html slides1 SLIDE_TYPE=html SLIDE_THEME=solarized3 --html_style=solarized3 --html_output=slides1_html_solarized3
doconce slides_html slides1_html_solarized3 doconce --nav_button=gray2,bottom --font_size=slides

doconce format html slides1 SLIDE_TYPE=html SLIDE_THEME=solarized3 --html_style=solarized3 --html_output=slides1_html_solarized3_space
doconce split_html slides1_html_solarized3_space --method=space10

doconce format html slides1 SLIDE_TYPE=html SLIDE_THEME=solarized3_dark --html_style=solarized3_dark --html_output=slides1_html_solarized3_dark
doconce slides_html slides1_html_solarized3_dark doconce --nav_button=gray2,bottom --font_size=slides

doconce format html slides1 --pygments_html_style=fruity --keep_pygments_html_bg SLIDE_TYPE=deck SLIDE_THEME=neon
doconce slides_html slides1 deck --html_slide_theme=neon
cp slides1.html slides1_deck_neon.html

doconce format html slides1 --pygments_html_style=fruity --keep_pygments_html_bg SLIDE_TYPE=deck SLIDE_THEME=sandstone.aurora
doconce slides_html slides1 deck --html_slide_theme=sandstone.aurora
cp slides1.html slides1_deck_sandstone_aurora.html

doconce format html slides1 --pygments_html_style=native --keep_pygments_html_bg SLIDE_TYPE=deck SLIDE_THEME=sandstone.dark
doconce slides_html slides1 deck --html_slide_theme=sandstone.dark
cp slides1.html slides1_deck_sandstone_dark.html

doconce format html slides1 --pygments_html_style=fruity --keep_pygments_html_bg SLIDE_TYPE=deck SLIDE_THEME=sandstone.mdn
doconce slides_html slides1 deck --html_slide_theme=sandstone.mdn
cp slides1.html slides1_deck_sandstone_mdn.html

doconce format html slides1 --pygments_html_style=default --keep_pygments_html_bg SLIDE_TYPE=deck SLIDE_THEME=sandstone.mightly
doconce slides_html slides1 deck --html_slide_theme=sandstone.mightly
cp slides1.html slides1_deck_sandstone_mightly.html

doconce format html slides1 --pygments_html_style=autumn --keep_pygments_html_bg SLIDE_TYPE=deck SLIDE_THEME=beamer
doconce slides_html slides1 deck --html_slide_theme=beamer
cp slides1.html slides1_deck_beamer.html

doconce format html slides1 --pygments_html_style=default --keep_pygments_html_bg SLIDE_TYPE=deck SLIDE_THEME=mnml
doconce slides_html slides1 deck --html_slide_theme=mnml
cp slides1.html slides1_deck_mnml.html

doconce format html slides1 --pygments_html_style=default --keep_pygments_html_bg SLIDE_TYPE=deck SLIDE_THEME=sandstone.firefox
doconce slides_html slides1 deck --html_slide_theme=sandstone.firefox
cp slides1.html slides1_deck_sandstone_firefox.html

doconce format html slides1 --pygments_html_style=perldoc --keep_pygments_html_bg SLIDE_TYPE=deck SLIDE_THEME=sandstone.default
doconce slides_html slides1 deck --html_slide_theme=sandstone.default
cp slides1.html slides1_deck_sandstone_default.html

doconce format html slides1 --pygments_html_style=emacs --keep_pygments_html_bg SLIDE_TYPE=deck SLIDE_THEME=sandstone.light
doconce slides_html slides1 deck --html_slide_theme=sandstone.light
cp slides1.html slides1_deck_sandstone_light.html

doconce format html slides1 --pygments_html_style=autumn --keep_pygments_html_bg SLIDE_TYPE=deck SLIDE_THEME=swiss
doconce slides_html slides1 deck --html_slide_theme=swiss
cp slides1.html slides1_deck_swiss.html

doconce format html slides1 --pygments_html_style=autumn --keep_pygments_html_bg SLIDE_TYPE=deck SLIDE_THEME=web-2.0
doconce slides_html slides1 deck --html_slide_theme=web-2.0
cp slides1.html slides1_deck_web-2_0.html

doconce format html slides1 --pygments_html_style=default --keep_pygments_html_bg SLIDE_TYPE=deck SLIDE_THEME=cbc
doconce slides_html slides1 deck --html_slide_theme=cbc
cp slides1.html slides1_deck_cbc.html

doconce format html slides1 --pygments_html_style=perldoc --keep_pygments_html_bg SLIDE_TYPE=reveal SLIDE_THEME=beige
doconce slides_html slides1 reveal --html_slide_theme=beige
cp slides1.html slides1_reveal_beige.html

doconce format html slides1 --pygments_html_style=perldoc --keep_pygments_html_bg SLIDE_TYPE=reveal SLIDE_THEME=beigesmall
doconce slides_html slides1 reveal --html_slide_theme=beigesmall
cp slides1.html slides1_reveal_beigesmall.html

doconce format html slides1 --pygments_html_style=perldoc --keep_pygments_html_bg SLIDE_TYPE=reveal SLIDE_THEME=solarized
doconce slides_html slides1 reveal --html_slide_theme=solarized
cp slides1.html slides1_reveal_solarized.html

doconce format html slides1 --pygments_html_style=perldoc --keep_pygments_html_bg SLIDE_TYPE=reveal SLIDE_THEME=serif
doconce slides_html slides1 reveal --html_slide_theme=serif
cp slides1.html slides1_reveal_serif.html

doconce format html slides1 --pygments_html_style=autumn --keep_pygments_html_bg SLIDE_TYPE=reveal SLIDE_THEME=simple
doconce slides_html slides1 reveal --html_slide_theme=simple
cp slides1.html slides1_reveal_simple.html

doconce format html slides1 --pygments_html_style=autumn --keep_pygments_html_bg SLIDE_TYPE=reveal SLIDE_THEME=white
doconce slides_html slides1 reveal --html_slide_theme=white
cp slides1.html slides1_reveal_white.html

doconce format html slides1 --pygments_html_style=monokai --keep_pygments_html_bg SLIDE_TYPE=reveal SLIDE_THEME=blood
doconce slides_html slides1 reveal --html_slide_theme=blood
cp slides1.html slides1_reveal_blood.html

doconce format html slides1 --pygments_html_style=monokai --keep_pygments_html_bg SLIDE_TYPE=reveal SLIDE_THEME=black
doconce slides_html slides1 reveal --html_slide_theme=black
cp slides1.html slides1_reveal_black.html

doconce format html slides1 --pygments_html_style=default --keep_pygments_html_bg SLIDE_TYPE=reveal SLIDE_THEME=sky
doconce slides_html slides1 reveal --html_slide_theme=sky
cp slides1.html slides1_reveal_sky.html

doconce format html slides1 --pygments_html_style=fruity --keep_pygments_html_bg SLIDE_TYPE=reveal SLIDE_THEME=moon
doconce slides_html slides1 reveal --html_slide_theme=moon
cp slides1.html slides1_reveal_moon.html

doconce format html slides1 --pygments_html_style=fruity --keep_pygments_html_bg SLIDE_TYPE=reveal SLIDE_THEME=night
doconce slides_html slides1 reveal --html_slide_theme=night
cp slides1.html slides1_reveal_night.html

doconce format html slides1 --pygments_html_style=native --keep_pygments_html_bg SLIDE_TYPE=reveal SLIDE_THEME=darkgray
doconce slides_html slides1 reveal --html_slide_theme=darkgray
cp slides1.html slides1_reveal_darkgray.html

doconce format html slides1 --pygments_html_style=native --keep_pygments_html_bg SLIDE_TYPE=reveal SLIDE_THEME=league
doconce slides_html slides1 reveal --html_slide_theme=league
cp slides1.html slides1_reveal_league.html

doconce format html slides1 --pygments_html_style=default --keep_pygments_html_bg SLIDE_TYPE=reveal SLIDE_THEME=cbc
doconce slides_html slides1 reveal --html_slide_theme=cbc
cp slides1.html slides1_reveal_cbc.html

doconce format html slides1 --pygments_html_style=autumn --keep_pygments_html_bg SLIDE_TYPE=reveal SLIDE_THEME=simula
doconce slides_html slides1 reveal --html_slide_theme=simula
cp slides1.html slides1_reveal_simula.html

doconce format html slides1 --pygments_html_style=monokai --keep_pygments_html_bg SLIDE_TYPE=csss SLIDE_THEME=csss_default
doconce slides_html slides1 csss --html_slide_theme=csss_default
cp slides1.html slides1_csss_csss_default.html

doconce format html slides1 --pygments_html_style=autumn --keep_pygments_html_bg SLIDE_TYPE=dzslides SLIDE_THEME=dzslides_default
doconce slides_html slides1 dzslides --html_slide_theme=dzslides_default
cp slides1.html slides1_dzslides_dzslides_default.html

doconce format html slides1 --pygments_html_style=autumn --keep_pygments_html_bg SLIDE_TYPE=html5slides SLIDE_THEME=template-default
doconce slides_html slides1 html5slides --html_slide_theme=template-default
cp slides1.html slides1_html5slides_template-default.html

doconce format html slides1 --pygments_html_style=autumn --keep_pygments_html_bg SLIDE_TYPE=html5slides SLIDE_THEME=template-io2011
doconce slides_html slides1 html5slides --html_slide_theme=template-io2011
cp slides1.html slides1_html5slides_template-io2011.html

doconce format html slides1 --pygments_html_style=autumn --keep_pygments_html_bg SLIDE_TYPE=remark SLIDE_THEME=light
doconce slides_html slides1 remark --html_slide_theme=light
cp slides1.html slides1_remark_light.html

doconce format html slides1 --pygments_html_style=native --keep_pygments_html_bg SLIDE_TYPE=remark SLIDE_THEME=dark
doconce slides_html slides1 remark --html_slide_theme=dark
cp slides1.html slides1_remark_dark.html

echo "Here are the slide shows:"
/bin/ls slides1_*_*.html

************** File: slides1_1st.html *****************
<!--
Automatically generated HTML file from DocOnce source
(https://github.com/doconce/doconce/)
-->
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="DocOnce: https://github.com/doconce/doconce/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="description" content="Document for Testing Some Basic and Some Challenging Constructs in DocOnce Slides">

<title>Document for Testing Some Basic and Some Challenging Constructs in DocOnce Slides</title>


<style type="text/css">
/* blueish style */

/* Color definitions:  https://www.december.com/html/spec/color0.html
   CSS examples:       https://www.w3schools.com/css/css_examples.asp */

body {
  margin-top: 1.0em;
  background-color: #ffffff;
  font-family: Helvetica, Arial, FreeSans, san-serif;
  color: #000000;
}
h1 { font-size: 1.8em; color: #1e36ce; }
h2 { font-size: 1.6em; color: #1e36ce; }
h3 { font-size: 1.4em; color: #1e36ce; }
a { color: #1e36ce; text-decoration:none; }
tt { font-family: "Courier New", Courier; }
/* pre style removed because it will interfer with pygments */
p { text-indent: 0px; }
hr { border: 0; width: 80%; border-bottom: 1px solid #aaa}
p.caption { width: 80%; font-style: normal; text-align: left; }
hr.figure { border: 0; width: 80%; border-bottom: 1px solid #aaa}
.alert-text-small   { font-size: 80%;  }
.alert-text-large   { font-size: 130%; }
.alert-text-normal  { font-size: 90%;  }
.alert {
  padding:8px 35px 8px 14px; margin-bottom:18px;
  text-shadow:0 1px 0 rgba(255,255,255,0.5);
  border:1px solid #bababa;
  border-radius: 4px;
  -webkit-border-radius: 4px;
  -moz-border-radius: 4px;
  color: #555;
  background-color: #f8f8f8;
  background-position: 10px 5px;
  background-repeat: no-repeat;
  background-size: 38px;
  padding-left: 55px;
  width: 75%;
 }
.alert-block {padding-top:14px; padding-bottom:14px}
.alert-block > p, .alert-block > ul {margin-bottom:1em}
.alert li {margin-top: 1em}
.alert-block p+p {margin-top:5px}
.alert-notice { background-image: url(https://raw.github.com/doconce/doconce/master/bundled/html_images/small_gray_notice.png); }
.alert-summary  { background-image:url(https://raw.github.com/doconce/doconce/master/bundled/html_images/small_gray_summary.png); }
.alert-warning { background-image: url(https://raw.github.com/doconce/doconce/master/bundled/html_images/small_gray_warning.png); }
.alert-question {background-image:url(https://raw.github.com/doconce/doconce/master/bundled/html_images/small_gray_question.png); }

div { text-align: justify; text-justify: inter-word; }
</style>


</head>

<!-- tocinfo
{'highest level': 1,
 'sections': [('This is the first section',
               1,
               None,
               'this-is-the-first-section'),
              ('Figure and bullet list', 2, None, 'figure-and-bullet-list'),
              ('Slide with pop-ups in red and notes',
               2,
               None,
               'slide-with-pop-ups-in-red-and-notes'),
              ('A LaTeX document', 2, None, 'a-latex-document'),
              ('An HTML document', 2, None, 'an-html-document'),
              ('Second section', 1, None, 'second-section'),
              ('Some math and computer code',
               2,
               None,
               'some-math-and-computer-code'),
              ('Pop ups inside code blocks (for Beamer slides only)',
               2,
               None,
               'pop-ups-inside-code-blocks-for-beamer-slides-only'),
              ('Various admon blocks', 2, None, 'various-admon-blocks')]}
end of tocinfo -->

<body>



<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  TeX: {
     equationNumbers: {  autoNumber: "AMS"  },
     extensions: ["AMSmath.js", "AMSsymbols.js", "autobold.js", "color.js"]
  }
});
</script>
<script type="text/javascript" async
 src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>



    
<!-- ------------------- main content ---------------------- -->



<center><h1>Document for Testing Some Basic and Some Challenging Constructs in DocOnce Slides</h1></center>  <!-- document title -->

<p>
<!-- author(s): Hans Petter Langtangen -->

<center>
<b>Hans Petter Langtangen</b> [1, 2]
</center>

<p>
<!-- institution(s) -->

<center>[1] <b>Simula Research Laboratory</b></center>
<center>[2] <b>University of Oslo</b></center>
<br>
<p>
<center><h4>Jan 32, 2100</h4></center> <!-- date -->
<br>
<p>
<!-- !split -->

<h1 id="this-is-the-first-section">This is the first section </h1>
<!-- Short title: First -->

<p>
<!-- !split -->

<h2 id="figure-and-bullet-list">Figure and bullet list </h2>

<p>
<!-- !bslidecell 00  0.60 -->
<!-- !bpop -->
<div class="alert alert-block alert-block alert-text-small">
<b>Title with comma, and brackets: \( [a,b] \)</b>
<p>

<ul>
  <li> Here is a <em>wave signal</em> \( f(x-ct) \)</li>
  <li> It moves with velocity \( c \)</li>
  <li> But here it is just a figure</li>
</ul>
</div>

<!-- !epop -->
<!-- !eslidecell -->

<p>
<!-- !bslidecell 01 -->
<div class="alert alert-block alert-block alert-text-normal">
<b></b>
<p>
<br /><br /><center><p><img src="../doc/src/manual/fig/wave1D.png" align="bottom" width=300></p></center><br /><br />
</div>

<!-- !eslidecell -->

<p>
<!-- !split -->

<h2 id="slide-with-pop-ups-in-red-and-notes">Slide with pop-ups in red and notes </h2>

<p>

<!-- begin inline comment -->
<font color="red">(<b>hpl 1</b>: Comments are typeset as usual in DocOnce.)</font>
<!-- end inline comment -->

<p>
<!-- !bpop highlight-red -->
Here we have a paragraph to pop up in red.<br />
And a line more
<!-- !epop -->

<p>
<!-- !bnotes -->
One can also have ordinary notes.
Over multiple lines.
<!-- !enotes -->

<p>
<!-- !split -->

<h2 id="a-latex-document">A LaTeX document </h2>

<p>
<!-- !bpop -->
<p>

<!-- code=latex (!bc latex) typeset with pygments style "perldoc" -->
<div class="highlight" style="background: #eeeedd"><pre style="line-height: 125%;"><span></span><span style="color: #8B008B; font-weight: bold">\documentclass</span><span style="color: #658b00">[11pt]{</span>article<span style="color: #658b00">}</span>
<span style="color: #8B008B; font-weight: bold">\usepackage</span><span style="color: #658b00">{</span>fancyvrb<span style="color: #658b00">}</span>
<span style="color: #8B008B; font-weight: bold">\begin</span><span style="color: #658b00">{</span>document<span style="color: #658b00">}</span>

<span style="color: #8B008B; font-weight: bold">\title</span><span style="color: #658b00">{</span>Here goes the title...<span style="color: #658b00">}</span>
<span style="color: #8B008B; font-weight: bold">\author</span><span style="color: #658b00">{</span>John Doe <span style="color: #8B008B; font-weight: bold">\and</span>
Jane Doe<span style="color: #8B008B; font-weight: bold">\footnote</span><span style="color: #658b00">{</span><span style="color: #8B008B; font-weight: bold">\texttt</span><span style="color: #658b00">{</span>jane.doe@cyber.net<span style="color: #658b00">}</span>.<span style="color: #658b00">}}</span>
<span style="color: #8B008B; font-weight: bold">\date</span><span style="color: #658b00">{</span><span style="color: #8B008B; font-weight: bold">\today</span><span style="color: #658b00">}</span>
<span style="color: #8B008B; font-weight: bold">\maketitle</span>
</pre></div>
<p>
<!-- !epop -->

<p>
<!-- !bpop -->
<div class="alert alert-block alert-notice alert-text-normal">
<b>Notice</b>
<p>
LaTeX has a lot of backslashes.
</div>

<!-- !epop -->

<p>
<!-- !bpop -->
<p>

<!-- code=latex (!bc latex) typeset with pygments style "perldoc" -->
<div class="highlight" style="background: #eeeedd"><pre style="line-height: 125%;"><span></span><span style="color: #8B008B; font-weight: bold">\section</span><span style="color: #658b00">{</span>Heading<span style="color: #658b00">}</span>
bla-bla
<span style="color: #8B008B; font-weight: bold">\end</span><span style="color: #658b00">{</span>document<span style="color: #658b00">}</span>
</pre></div>
<p>
<!-- !epop -->

<p>
<!-- !split -->

<h2 id="an-html-document">An HTML document </h2>

<p>

<!-- code=html (!bc html) typeset with pygments style "perldoc" -->
<div class="highlight" style="background: #eeeedd"><pre style="line-height: 125%;"><span></span>&lt;<span style="color: #8B008B; font-weight: bold">html</span>&gt;&lt;<span style="color: #8B008B; font-weight: bold">head</span>&gt;&lt;/<span style="color: #8B008B; font-weight: bold">head</span>&gt;&lt;<span style="color: #8B008B; font-weight: bold">body</span> <span style="color: #658b00">bgcolor</span>=<span style="color: #CD5555">&quot;red&quot;</span>&gt;
&lt;<span style="color: #8B008B; font-weight: bold">title</span>&gt;Here goes the title...&lt;<span style="color: #8B008B; font-weight: bold">title</span>&gt;
&lt;<span style="color: #8B008B; font-weight: bold">h1</span>&gt;Section heading&lt;/<span style="color: #8B008B; font-weight: bold">h1</span>&gt;
&lt;/<span style="color: #8B008B; font-weight: bold">body</span>&gt;
&lt;/<span style="color: #8B008B; font-weight: bold">html</span>&gt;
</pre></div>
<p>
<!-- !split -->

<h1 id="second-section">Second section </h1>

<p>
<div class="alert alert-block alert-block alert-text-normal">
<b></b>
<p>
<br /><br /><center><p><img src="../doc/src/manual/fig/wave1D.png" align="bottom" width=600></p></center><br /><br />
</div>


<p>
<!-- !split -->

<h2 id="some-math-and-computer-code">Some math and computer code </h2>

<p>
<div class="alert alert-block alert-block alert-text-normal">
<b>A simple, mathematical formula where \( t\in [0,\pi] \):</b>
<p>
$$ f(x,y,t) = e^{-xt}\sin\pi y $$
</div>


<p>
<div class="alert alert-block alert-block alert-text-normal">
<b>Bash demanded more of DocOnce than Python, so let's do Bash:</b>
<p>
First, inline <code>$? != 0</code>, then comments with dollar variables (and minted
style):

<p>

<!-- code=bash (!bc shcod) typeset with pygments style "perldoc" -->
<div class="highlight" style="background: #eeeedd"><pre style="line-height: 125%;"><span></span><span style="color: #00688B">var</span>=<span style="color: #B452CD">10</span>
<span style="color: #228B22"># $1, $2, ... are command-line args</span>
<span style="color: #8B008B; font-weight: bold">if</span> [ <span style="color: #00688B">$?</span> -eq <span style="color: #B452CD">0</span> ]; <span style="color: #8B008B; font-weight: bold">then</span>   <span style="color: #228B22"># $? reflects success or not</span>
  <span style="color: #658b00">echo</span> <span style="color: #CD5555">&quot;Great!&quot;</span>
<span style="color: #8B008B; font-weight: bold">fi</span>
</pre></div>

</div>


<p>
<!-- !split -->

<h2 id="pop-ups-inside-code-blocks-for-beamer-slides-only">Pop ups inside code blocks (for Beamer slides only) </h2>

<p>

<!-- code=python (!bc pycod) typeset with pygments style "perldoc" -->
<div class="highlight" style="background: #eeeedd"><pre style="line-height: 125%;"><span></span><span style="color: #8B008B; font-weight: bold">def</span> <span style="color: #008b45">f</span>(x):
    <span style="color: #8B008B; font-weight: bold">return</span> <span style="color: #B452CD">42</span> + x

<span style="color: #8B008B; font-weight: bold">def</span> <span style="color: #008b45">g</span>(x):
    <span style="color: #8B008B; font-weight: bold">return</span> f(<span style="color: #B452CD">42</span>)

<span style="color: #658b00">print</span>(g(<span style="color: #B452CD">13</span>))
</pre></div>
<p>
<!-- !split -->

<h2 id="various-admon-blocks">Various admon blocks </h2>

<p>
Can use admons to simulate blocks:

<p>
<!-- !bpop -->
<div class="alert alert-block alert-notice alert-text-large">
<b>Key PDE (with large title and math font):</b>
<p>
$$ \frac{\partial u}{\partial t} = \nabla^2 u $$
</div>

<!-- !epop -->

<p>
<!-- !bpop -->
<div class="alert alert-block alert-summary alert-text-normal">
<b></b>
<p>
Just some block with text and a conclusion that something is important.
This one pops up after the rest of the slide.
</div>

<!-- !epop -->

<p>
<!-- !bpop -->
<div class="alert alert-block alert-warning alert-text-small">
<b>Warning</b>
<p>
Can use, e.g., a warning admon to have my own notes, preferably
inside preprocess/mako if statements to turn notes on and off.
This one is typeset in a small font and with the default
title (Warning) since no title is specified.
</div>

<!-- !epop -->

<!-- ------------------- end of main content --------------- -->


</body>
</html>
    


************** File: slides1_deck.html *****************
<!DOCTYPE html>

<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="DocOnce: https://github.com/doconce/doconce/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="description" content="Document for Testing Some Basic and Some Challenging Constructs in DocOnce Slides">

<title>Document for Testing Some Basic and Some Challenging Constructs in DocOnce Slides</title>







<!-- deck.js: https://github.com/imakewebthings/deck.js -->

<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<meta name="viewport" content="width=1024, user-scalable=no">

<!-- Required stylesheet -->
<link rel="stylesheet" href="deck.js/core/deck.core.css">

<!-- Extension CSS files go here. Remove or add as needed.
deck.goto: Adds a shortcut key to jump to any slide number.
Hit g, type in the slide number, and hit enter.

deck.hash: Enables internal linking within slides, deep
linking to individual slides, and updates the address bar and
a permalink anchor with each slide change.

deck.menu: Adds a menu view, letting you see all slides in a grid.
Hit m to toggle to menu view, continue navigating your deck,
and hit m to return to normal view. Touch devices can double-tap
the deck to switch between views.

deck.navigation: Adds clickable left and right buttons for the
less keyboard inclined.

deck.status: Adds a page number indicator. (current/total).

deck.scale: Scales each slide to fit within the deck container
using CSS Transforms for those browsers that support them.

deck.pointer: Turn mouse into laser pointer (toggle with p).
(Requires https://github.com/mikeharris100/deck.pointer.js)
-->

<link rel="stylesheet" href="deck.js/extensions/menu/deck.menu.css">
<link rel="stylesheet" href="deck.js/extensions/navigation/deck.navigation.css">
<link rel="stylesheet" href="deck.js/extensions/scale/deck.scale.css">
<link rel="stylesheet" href="deck.js/extensions/pointer/deck.pointer.css">
<link rel="stylesheet" href="deck.js/extensions/notes/deck.notes.css">
<!--
<link rel="stylesheet" href="deck.js/extensions/goto/deck.goto.css">
<link rel="stylesheet" href="deck.js/extensions/hash/deck.hash.css">
<link rel="stylesheet" href="deck.js/extensions/status/deck.status.css">
-->

<!-- Style theme. More available in themes/style/ or create your own. -->
<link rel="stylesheet" href="deck.js/themes/style/web-2.0.css">

<!--
<link rel="stylesheet" href="deck.js/themes/style/neon.css">
<link rel="stylesheet" href="deck.js/themes/style/swiss.css">
<link rel="stylesheet" href="deck.js/themes/style/web-2.0.css">

git clone git://github.com/duijf/mnml.git
<link rel="stylesheet" href="deck.js/themes/style/mnml.css">

git://github.com/groovecoder/deckjs-theme-mozilla.git
<link rel="stylesheet" href="deck.js/themes/style/sandstone.css">
<link rel="stylesheet" href="deck.js/themes/style/sandstone.aurora.css">
<link rel="stylesheet" href="deck.js/themes/style/sandstone.dark.css">
<link rel="stylesheet" href="deck.js/themes/style/sandstone.default.css">
<link rel="stylesheet" href="deck.js/themes/style/sandstone.firefox.css">
<link rel="stylesheet" href="deck.js/themes/style/sandstone.light.css">
<link rel="stylesheet" href="deck.js/themes/style/sandstone.mdn.css">
<link rel="stylesheet" href="deck.js/themes/style/sandstone.nightly.css">
<link rel="stylesheet" href="deck.js/themes/style/sandstone.cbc.css">

git://github.com/barraq/deck.ext.js.git
<link rel="stylesheet" href="deck.js/themes/style/beamer.css">
-->

<!--
Transition theme. More available in /themes/transition/ or create your own. -->
<!--
<link rel="stylesheet" href="deck.js/themes/transition/horizontal-slide.css">
<link rel="stylesheet" href="deck.js/themes/transition/fade.css">
<link rel="stylesheet" href="deck.js/themes/transition/vertical-slide.css">
<link rel="stylesheet" href="deck.js/themes/transition/horizontal-slide.css">
-->

<!-- Required Modernizr file -->
<script src="deck.js/modernizr.custom.js"></script>

<style type="text/css">
/* Override h1, h2, ... styles */
h1 { font-size: 2.8em; }
h2 { font-size: 1.5em; }
h3 { font-size: 1.4em; }
h4 { font-size: 1.3em; }
h1, h2, h3, h4 { font-weight: bold; line-height: 1.2; }
body { overflow: auto; } /* vertical scrolling */

hr { border: 0; width: 80%; border-bottom: 1px solid #aaa}
p.caption { width: 80%; font-size: 60%; font-style: italic; text-align: left; }
hr.figure { border: 0; width: 80%; border-bottom: 1px solid #aaa}
.slide .alert-text-small   { font-size: 80%;  }
.slide .alert-text-large   { font-size: 130%; }
.slide .alert-text-normal  { font-size: 90%;  }
.slide .alert {
     padding:8px 35px 8px 14px; margin-bottom:18px;
     text-shadow:0 1px 0 rgba(255,255,255,0.5);
     border:5px solid #bababa;
       -webkit-border-radius:14px; -moz-border-radius:14px;
     border-radius:14px
     background-position: 10px 10px;
     background-repeat: no-repeat;
     background-size: 38px;
     padding-left: 30px; /* 55px; if icon */
 }
 .slide .alert-block {padding-top:14px; padding-bottom:14px}
 .slide .alert-block > p, .alert-block > ul {margin-bottom:0}
 /*.slide .alert li {margin-top: 1em}*/
 .deck .alert-block p+p {margin-top:5px}
 /*.slide .alert-notice { background-image: url(https://hplgit.github.io/doconce/bundled/html_images//small_gray_notice.png); }
 .slide .alert-summary  { background-image:url(https://hplgit.github.io/doconce/bundled/html_images//small_gray_summary.png); }
 .slide .alert-warning { background-image: url(https://hplgit.github.io/doconce/bundled/html_images//small_gray_warning.png); }
 .slide .alert-question {background-image:url(https://hplgit.github.io/doconce/bundled/html_images/small_gray_question.png); } */

</style>



<!-- Styles for table layout of slides -->
<style type="text/css">
td.padding {
  padding-top:20px;
  padding-bottom:20px;
  padding-right:50px;
  padding-left:50px;
}
</style>

</head>

<body class="deck-container">

<header>
<!-- Here goes a potential header -->
</header>

<!-- do not use the article tag - it gives strange sizings -->





<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  TeX: {
     equationNumbers: {  autoNumber: "none"  },
     extensions: ["AMSmath.js", "AMSsymbols.js", "autobold.js", "color.js"]
  }
});
</script>
<script type="text/javascript" async
 src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>



    



<section class="slide">
<!-- ------------------- main content ---------------------- -->

<h2 style="text-align: center;">Document for Testing Some Basic and Some Challenging Constructs in DocOnce Slides</h2>  <!-- document title -->

<p>
<!-- author(s): Hans Petter Langtangen -->

<center>
<b style="font-weight: bold">Hans Petter Langtangen</b> [1, 2]
</center>

<p>
<!-- institution(s) -->

<center>[1] <b style="font-weight: bold">Simula Research Laboratory</b></center>
<center>[2] <b style="font-weight: bold">University of Oslo</b></center>
<br>
<p>
<center><b style="font-weight: bold">Jan 32, 2100</b></center> <!-- date -->
<br>
</section>


<section class="slide">

<h1 id="this-is-the-first-section">This is the first section </h1>
<!-- Short title: First -->
</section>


<section class="slide">

<h2 id="figure-and-bullet-list">Figure and bullet list </h2>

<p>

<table border="0">
<tr>
<td class="padding">

<div class="slide alert alert-block alert-block alert-text-small">
<b style="font-weight: bold">Title with comma, and brackets: \( [a,b] \)</b>
<ul>

<p><li class="slide"> Here is a <em>wave signal</em> \( f(x-ct) \)</li>

<p><li class="slide"> It moves with velocity \( c \)</li>

<p><li class="slide"> But here it is just a figure</li>
</ul>
</div>


</td>
<td class="padding">
<div class="alert alert-block alert-block alert-text-normal">
<b style="font-weight: bold"></b>
<p>
<br /><br /><center><p><img src="../doc/src/manual/fig/wave1D.png" align="bottom" width=300></p></center><br /><br />
</div>

</td>
</tr>
</table>
</section>


<section class="slide">

<h2 id="slide-with-pop-ups-in-red-and-notes">Slide with pop-ups in red and notes </h2>

<p>

<!-- begin inline comment -->
<font color="red">(<b style="font-weight: bold">hpl 1</b>: Comments are typeset as usual in DocOnce.)</font>
<!-- end inline comment -->

<p>

<p class="slide">

Here we have a paragraph to pop up in red.<br />
And a line more

</p>

<p>
<div class="notes">
<!-- press "n" to activate -->

One can also have ordinary notes.
Over multiple lines.

</div>
</section>


<section class="slide">

<h2 id="a-latex-document">A LaTeX document </h2>

<p>

<!-- code=latex (!bc latex) typeset with pygments style "emacs" -->
<div class="slide" class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #AA22FF; font-weight: bold">\documentclass</span><span style="color: #BB4444">[11pt]</span><span style="color: #AA22FF">{</span>article<span style="color: #AA22FF">}</span>
<span style="color: #AA22FF; font-weight: bold">\usepackage</span><span style="color: #AA22FF">{</span>fancyvrb<span style="color: #AA22FF">}</span>
<span style="color: #AA22FF; font-weight: bold">\begin</span><span style="color: #AA22FF">{</span>document<span style="color: #AA22FF">}</span>

<span style="color: #AA22FF; font-weight: bold">\title</span><span style="color: #AA22FF">{</span>Here goes the title...<span style="color: #AA22FF">}</span>
<span style="color: #AA22FF; font-weight: bold">\author</span><span style="color: #AA22FF">{</span>John Doe <span style="color: #AA22FF; font-weight: bold">\and</span>
Jane Doe<span style="color: #AA22FF; font-weight: bold">\footnote</span><span style="color: #AA22FF">{</span><span style="color: #AA22FF; font-weight: bold">\texttt</span><span style="color: #AA22FF">{</span>jane.doe@cyber.net<span style="color: #AA22FF">}</span>.<span style="color: #AA22FF">}}</span>
<span style="color: #AA22FF; font-weight: bold">\date</span><span style="color: #AA22FF">{</span><span style="color: #AA22FF; font-weight: bold">\today</span><span style="color: #AA22FF">}</span>
<span style="color: #AA22FF; font-weight: bold">\maketitle</span>
</pre></div>
<p>

<div class="slide alert alert-block alert-notice alert-text-normal">
<b style="font-weight: bold">Notice</b>
<p>
LaTeX has a lot of backslashes.
</div>

<p>

<!-- code=latex (!bc latex) typeset with pygments style "emacs" -->
<div class="slide" class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #AA22FF; font-weight: bold">\section</span><span style="color: #AA22FF">{</span>Heading<span style="color: #AA22FF">}</span>
bla-bla
<span style="color: #AA22FF; font-weight: bold">\end</span><span style="color: #AA22FF">{</span>document<span style="color: #AA22FF">}</span>
</pre></div>
</section>


<section class="slide">

<h2 id="an-html-document">An HTML document </h2>

<p>

<!-- code=html (!bc html) typeset with pygments style "emacs" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>&lt;<span style="color: #008000; font-weight: bold">html</span>&gt;&lt;<span style="color: #008000; font-weight: bold">head</span>&gt;&lt;/<span style="color: #008000; font-weight: bold">head</span>&gt;&lt;<span style="color: #008000; font-weight: bold">body</span> <span style="color: #BB4444">bgcolor</span><span style="color: #666666">=</span><span style="color: #BB4444">&quot;red&quot;</span>&gt;
&lt;<span style="color: #008000; font-weight: bold">title</span>&gt;Here goes the title...&lt;<span style="color: #008000; font-weight: bold">title</span>&gt;
&lt;<span style="color: #008000; font-weight: bold">h1</span>&gt;Section heading&lt;/<span style="color: #008000; font-weight: bold">h1</span>&gt;
&lt;/<span style="color: #008000; font-weight: bold">body</span>&gt;
&lt;/<span style="color: #008000; font-weight: bold">html</span>&gt;
</pre></div>
</section>


<section class="slide">

<h1 id="second-section">Second section </h1>

<p>
<div class="alert alert-block alert-block alert-text-normal">
<b style="font-weight: bold"></b>
<p>
<br /><br /><center><p><img src="../doc/src/manual/fig/wave1D.png" align="bottom" width=600></p></center><br /><br />
</div>
</section>


<section class="slide">

<h2 id="some-math-and-computer-code">Some math and computer code </h2>

<p>
<div class="alert alert-block alert-block alert-text-normal">
<b style="font-weight: bold">A simple, mathematical formula where \( t\in [0,\pi] \):</b>
<p>&nbsp;<br>
$$ f(x,y,t) = e^{-xt}\sin\pi y $$
<p>&nbsp;<br>
</div>

<p>
<div class="alert alert-block alert-block alert-text-normal">
<b style="font-weight: bold">Bash demanded more of DocOnce than Python, so let's do Bash:</b>
<p>
First, inline <code>$? != 0</code>, then comments with dollar variables (and minted
style):

<p>

<!-- code=bash (!bc shcod) typeset with pygments style "emacs" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #B8860B">var</span><span style="color: #666666">=10</span>
<span style="color: #008800; font-style: italic"># $1, $2, ... are command-line args</span>
<span style="color: #AA22FF; font-weight: bold">if</span> <span style="color: #666666">[</span> <span style="color: #B8860B">$?</span> -eq <span style="color: #666666">0</span> <span style="color: #666666">]</span>; <span style="color: #AA22FF; font-weight: bold">then</span>   <span style="color: #008800; font-style: italic"># $? reflects success or not</span>
  <span style="color: #AA22FF">echo</span> <span style="color: #BB4444">&quot;Great!&quot;</span>
<span style="color: #AA22FF; font-weight: bold">fi</span>
</pre></div>

</div>
</section>


<section class="slide">

<h2 id="pop-ups-inside-code-blocks-for-beamer-slides-only">Pop ups inside code blocks (for Beamer slides only) </h2>

<p>

<!-- code=python (!bc pycod) typeset with pygments style "emacs" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #AA22FF; font-weight: bold">def</span> <span style="color: #00A000">f</span>(x):
    <span style="color: #AA22FF; font-weight: bold">return</span> <span style="color: #666666">42</span> <span style="color: #666666">+</span> x

<span style="color: #AA22FF; font-weight: bold">def</span> <span style="color: #00A000">g</span>(x):
    <span style="color: #AA22FF; font-weight: bold">return</span> f(<span style="color: #666666">42</span>)

<span style="color: #AA22FF">print</span>(g(<span style="color: #666666">13</span>))
</pre></div>
</section>


<section class="slide">

<h2 id="various-admon-blocks">Various admon blocks </h2>

<p>
Can use admons to simulate blocks:

<p>

<div class="slide alert alert-block alert-notice alert-text-large">
<b style="font-weight: bold">Key PDE (with large title and math font):</b>
<p>&nbsp;<br>
$$ \frac{\partial u}{\partial t} = \nabla^2 u $$
<p>&nbsp;<br>
</div>

<p>

<div class="slide alert alert-block alert-summary alert-text-normal">
<b style="font-weight: bold"></b>
<p>
Just some block with text and a conclusion that something is important.
This one pops up after the rest of the slide.
</div>

<p>

<div class="slide alert alert-block alert-warning alert-text-small">
<b style="font-weight: bold">Warning</b>
<p>
Can use, e.g., a warning admon to have my own notes, preferably
inside preprocess/mako if statements to turn notes on and off.
This one is typeset in a small font and with the default
title (Warning) since no title is specified.
</div>
</section>




<footer>
<!-- Here goes a footer -->
</footer>

<!-- Begin extension snippets. Add or remove as needed. -->

<!-- deck.navigation snippet -->
<a href="#" class="deck-prev-link" title="Previous">&#8592;</a>
<a href="#" class="deck-next-link" title="Next">&#8594;</a>

<!-- deck.status snippet
<p class="deck-status">
    <span class="deck-status-current"></span>
    /
    <span class="deck-status-total"></span>
</p>
-->

<!-- deck.goto snippet
<form action="." method="get" class="goto-form">
    <label for="goto-slide">Go to slide:</label>
    <input type="text" name="slidenum" id="goto-slide" list="goto-datalist">
    <datalist id="goto-datalist"></datalist>
    <input type="submit" value="Go">
</form>
-->

<!-- deck.hash snippet
<a href="." title="Permalink to this slide" class="deck-permalink">#</a>
-->

<!-- End extension snippets. -->


<!-- Required JS files. -->
<script src="deck.js/jquery.min.js"></script>
<script src="deck.js/core/deck.core.js"></script>

<!-- Extension JS files. Add or remove as needed. -->
<script src="deck.js/core/deck.core.js"></script>
<script src="deck.js/extensions/hash/deck.hash.js"></script>
<script src="deck.js/extensions/menu/deck.menu.js"></script>
<script src="deck.js/extensions/goto/deck.goto.js"></script>
<script src="deck.js/extensions/status/deck.status.js"></script>
<script src="deck.js/extensions/navigation/deck.navigation.js"></script>
<script src="deck.js/extensions/scale/deck.scale.js"></script>
<script src="deck.js/extensions/notes/deck.notes.js"></script>

<!-- From https://github.com/mikeharris100/deck.pointer.js -->
<script src="deck.js/extensions/pointer/deck.pointer.js"></script>

<!-- From https://github.com/stvnwrgs/presenterview
<script type="text/javascript" src="deck.js/extensions/presenterview/deck.presenterview.js"></script> -->

<!-- From https://github.com/nemec/deck.annotate.js
<script type="text/javascript" src="deck.js/extensions/deck.annotate.js/deck.annotate.js"></script>
-->


<!-- Initialize the deck. You can put this in an external file if desired. -->
<script>
    $(function() {
        $.deck('.slide');
    });
</script>


</body>
</html>
deck.js:
boilerplate.html
CHANGELOG.md
core
extensions
introduction
jquery.min.js
Makefile
MIT-license.txt
modernizr.custom.js
README.md
test
themes

deck.js/core:
deck.core.css
deck.core.js
deck.core.scss
print.css
print.scss

deck.js/extensions:
codemirror
deck.annotate.js
goto
menu
navigation
notes
pointer
presenterview
scale
status

deck.js/extensions/codemirror:
codemirror.js
CONTRIBUTORS.txt
deck.codemirror.css
deck.codemirror.js
deck.codemirror.scss
introduction
MIT-LICENSE.txt
mode
README.md
themes
VERSION.txt

deck.js/extensions/codemirror/introduction:
index.html
introduction.css
introduction.js
introduction.scss
modernizr.custom.js

deck.js/extensions/codemirror/mode:
clike
clojure
coffeescript
css
diff
haskell
htmlmixed
javascript
lua
php
plsql
python
r
rst
ruby
scheme
smalltalk
sparql
stex
velocity
xml
xmlpure
yaml

deck.js/extensions/codemirror/mode/clike:
clike.js
index.html

deck.js/extensions/codemirror/mode/clojure:
clojure.js
index.html

deck.js/extensions/codemirror/mode/coffeescript:
coffeescript.js
index.html
LICENSE

deck.js/extensions/codemirror/mode/css:
css.js
index.html

deck.js/extensions/codemirror/mode/diff:
diff.css
diff.js
index.html

deck.js/extensions/codemirror/mode/haskell:
haskell.js
index.html

deck.js/extensions/codemirror/mode/htmlmixed:
htmlmixed.js
index.html

deck.js/extensions/codemirror/mode/javascript:
index.html
javascript.js

deck.js/extensions/codemirror/mode/lua:
index.html
lua.js

deck.js/extensions/codemirror/mode/php:
index.html
php.js

deck.js/extensions/codemirror/mode/plsql:
index.html
plsql.js

deck.js/extensions/codemirror/mode/python:
index.html
LICENSE.txt
python.js

deck.js/extensions/codemirror/mode/r:
index.html
LICENSE
r.js

deck.js/extensions/codemirror/mode/rst:
index.html
rst.css
rst.js

deck.js/extensions/codemirror/mode/ruby:
index.html
LICENSE
ruby.js

deck.js/extensions/codemirror/mode/scheme:
index.html
scheme.js

deck.js/extensions/codemirror/mode/smalltalk:
index.html
smalltalk.js

deck.js/extensions/codemirror/mode/sparql:
index.html
sparql.js

deck.js/extensions/codemirror/mode/stex:
index.html
stex.js

deck.js/extensions/codemirror/mode/velocity:
index.html
velocity.js

deck.js/extensions/codemirror/mode/xml:
index.html
xml.js

deck.js/extensions/codemirror/mode/xmlpure:
index.html
xmlpure.js

deck.js/extensions/codemirror/mode/yaml:
index.html
yaml.js

deck.js/extensions/codemirror/themes:
cobalt.css
default.css
elegant.css
lesser-dark.css
neat.css
night.css

deck.js/extensions/deck.annotate.js:
bower.json
deck.annotate.css
deck.annotate.js
example.png
README.md

deck.js/extensions/goto:
deck.goto.css
deck.goto.html
deck.goto.js
deck.goto.scss

deck.js/extensions/menu:
deck.menu.css
deck.menu.js
deck.menu.scss

deck.js/extensions/navigation:
deck.navigation.css
deck.navigation.html
deck.navigation.js
deck.navigation.scss

deck.js/extensions/notes:
deck.notes.css
deck.notes.js
README.md

deck.js/extensions/pointer:
deck.pointer.css
deck.pointer.js

deck.js/extensions/presenterview:
deck.presenterview.css
deck.presenterview.html
deck.presenterview.js
iframe.html
presenterwindow.js
README.md
TODO

deck.js/extensions/scale:
deck.scale.css
deck.scale.js
deck.scale.scss

deck.js/extensions/status:
deck.status.css
deck.status.html
deck.status.js
deck.status.scss

deck.js/introduction:
index.html

deck.js/test:
fixtures
index.html
lib
settings.js
spec.core.js
spec.goto.js
spec.menu.js
spec.navigation.js
spec.scale.js
spec.status.js

deck.js/test/fixtures:
empty.html
nesteds.html
standard.html

deck.js/test/lib:
jasmine.css
jasmine-html.js
jasmine-jquery.js
jasmine.js

deck.js/themes:
images
style
transition

deck.js/themes/images:
cbc_footer.png
cbc_symbol.png
simula_footer.png
simula_logo.png
simula_symbol.png
uio_footer.png
uio_symbol.png

deck.js/themes/style:
beamer.css
beamer.scss
cbc.css
mnml.css
neon.css
neon.scss
_reset.scss
sandstone.aurora.css
sandstone.css
sandstone.dark.css
sandstone.default.css
sandstone.firefox.css
sandstone.light.css
sandstone.mdn.css
sandstone.nightly.css
sandstone.scss
swiss.css
swiss.scss
web-2.0.css
web-2.0.scss

deck.js/themes/transition:
fade.css
fade.scss
horizontal-slide.css
horizontal-slide.scss
vertical-slide.css
vertical-slide.scss

************** File: slides1_remark.html *****************

<!DOCTYPE html>
<html>
<head>
<title>Document for Testing Some Basic and Some Challenging Constructs in DocOnce Slides</title>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
<style type="text/css">
   @import url(https://fonts.googleapis.com/css?family=Yanone+Kaffeesatz);
   @import url(https://fonts.googleapis.com/css?family=Droid+Serif:400,700,400italic);
   @import url(https://fonts.googleapis.com/css?family=Ubuntu+Mono:400,700,400italic);

body { font-family: 'Droid Serif'; }
h1, h2, h3 {
  font-family: 'Yanone Kaffeesatz';
  font-weight: normal;
}
.remark-code, .remark-inline-code { font-family: 'Ubuntu Mono'; }

</style>
</head>

<body>




<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  TeX: {
     equationNumbers: {  autoNumber: "AMS"  },
     extensions: ["AMSmath.js", "AMSsymbols.js", "autobold.js", "color.js"]
  }
});
</script>
<script type="text/javascript" async
 src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>



<textarea id="source">

class: center, middle

# Document for Testing Some Basic and Some Challenging Constructs in DocOnce Slides


### **Hans Petter Langtangen** at Simula Research Laboratory and University of Oslo


### Jan 32, 2100

Made with DocOnce



---

# This is the first section
<!-- Short title: First -->

---

## Figure and bullet list

*Title with comma, and brackets: \\( [a,b] \\)* 
  * Here is a *wave signal* \\( f(x-ct) \\)
  * It moves with velocity \\( c \\)
  * But here it is just a figure


.center[<img src="../doc/src/manual/fig/wave1D.png" width=300>]


---

## Slide with pop-ups in red and notes

[hpl 1: Comments are typeset as usual in DocOnce.]

<!-- !bpop highlight-red -->
Here we have a paragraph to pop up in red.<br />
And a line more
---

## A LaTeX document


```
\documentclass[11pt]{article}
\usepackage{fancyvrb}
\begin{document}

\title{Here goes the title...}
\author{John Doe \and
Jane Doe\footnote{\texttt{jane.doe@cyber.net}.}}
\date{\today}
\maketitle
```

*Notice.* 
LaTeX has a lot of backslashes.


```
\section{Heading}
bla-bla
\end{document}
```

---

## An HTML document


```html
<html><head></head><body bgcolor="red">
<title>Here goes the title...<title>
<h1>Section heading</h1>
</body>
</html>
```

---

# Second section

.center[<img src="../doc/src/manual/fig/wave1D.png" width=600>]



---

## Some math and computer code


*A simple, mathematical formula where \\( t\in [0,\pi] \\):* 
$$
f(x,y,t) = e^{-xt}\sin\pi y
$$

*Bash demanded more of DocOnce than Python, so let's do Bash:* 
First, inline `\\( ? != 0`, then comments with dollar variables (and minted
style):


```shell
var=10
#  \\)1, \\( 2, ... are command-line args
if [  \\)? -eq 0 ]; then   # $? reflects success or not
  echo "Great!"
fi
```



---

## Pop ups inside code blocks (for Beamer slides only)


```python
def f(x):
    return 42 + x

def g(x):
    return f(42)

print(g(13))
```

---

## Various admon blocks

Can use admons to simulate blocks:

*Key PDE (with large title and math font):* 
$$
\frac{\partial u}{\partial t} = \nabla^2 u
$$

*None* 
Just some block with text and a conclusion that something is important.
This one pops up after the rest of the slide.


Can use, e.g., a warning admon to have my own notes, preferably
inside preprocess/mako if statements to turn notes on and off.
This one is typeset in a small font and with the default
title (Warning) since no title is specified.




</textarea>
<script src="https://gnab.github.io/remark/downloads/remark-latest.min.js" type="text/javascript">
</script>
<script type="text/javascript">
  var slideshow = remark.create();
</script>
</body>
</html>

************** File: slides1.tex *****************

% LaTeX Beamer file automatically generated from DocOnce
% https://github.com/hplgit/doconce

%-------------------- begin beamer-specific preamble ----------------------

\documentclass{beamer}

\usetheme{blue_shadow}
\usecolortheme{default}

% turn off the almost invisible, yet disturbing, navigation symbols:
\setbeamertemplate{navigation symbols}{}

% Examples on customization:
%\usecolortheme[named=RawSienna]{structure}
%\usetheme[height=7mm]{Rochester}
%\setbeamerfont{frametitle}{family=\rmfamily,shape=\itshape}
%\setbeamertemplate{items}[ball]
%\setbeamertemplate{blocks}[rounded][shadow=true]
%\useoutertheme{infolines}
%
%\usefonttheme{}
%\useinntertheme{}
%
%\setbeameroption{show notes}
%\setbeameroption{show notes on second screen=right}

% fine for B/W printing:
%\usecolortheme{seahorse}

\usepackage{pgf}
\usepackage{graphicx}
\usepackage{epsfig}
\usepackage{relsize}

\usepackage{fancybox}  % make sure fancybox is loaded before fancyvrb

\usepackage{fancyvrb}
%\usepackage{minted} % requires pygments and latex -shell-escape filename
%\usepackage{anslistings}
\usepackage{listingsutf8}

% Define colors
\definecolor{orange}{cmyk}{0,0.4,0.8,0.2}
\definecolor{tucorange}{rgb}{1.0,0.64,0}
\definecolor{darkorange}{rgb}{.71,0.21,0.01}
\definecolor{darkgreen}{rgb}{.12,.54,.11}
\definecolor{myteal}{rgb}{.26, .44, .56}
\definecolor{gray}{gray}{0.45}
\definecolor{mediumgray}{gray}{.8}
\definecolor{lightgray}{gray}{.95}
\definecolor{brown}{rgb}{0.54,0.27,0.07}
\definecolor{purple}{rgb}{0.5,0.0,0.5}
\definecolor{darkgray}{gray}{0.25}
\definecolor{darkblue}{rgb}{0,0.08,0.45}
\definecolor{darkblue2}{rgb}{0,0,0.8}
\definecolor{lightred}{rgb}{1.0,0.39,0.28}
\definecolor{lightgreen}{rgb}{0.48,0.99,0.0}
\definecolor{lightblue}{rgb}{0.53,0.81,0.92}
\definecolor{lightblue2}{rgb}{0.3,0.3,1.0}
\definecolor{lightpurple}{rgb}{0.87,0.63,0.87}
\definecolor{lightcyan}{rgb}{0.5,1.0,0.83}

\colorlet{comment_green}{green!50!black}
\colorlet{string_red}{red!60!black}
\colorlet{keyword_pink}{magenta!70!black}
\colorlet{indendifier_green}{green!70!white}

% Backgrounds for code
\definecolor{cbg_gray}{rgb}{.95, .95, .95}
\definecolor{bar_gray}{rgb}{.92, .92, .92}

\definecolor{cbg_yellowgray}{rgb}{.95, .95, .85}
\definecolor{bar_yellowgray}{rgb}{.95, .95, .65}

\colorlet{cbg_yellow2}{yellow!10}
\colorlet{bar_yellow2}{yellow!20}

\definecolor{cbg_yellow1}{rgb}{.98, .98, 0.8}
\definecolor{bar_yellow1}{rgb}{.98, .98, 0.4}

\definecolor{cbg_red1}{rgb}{1, 0.85, 0.85}
\definecolor{bar_red1}{rgb}{1, 0.75, 0.85}

\definecolor{cbg_blue1}{rgb}{0.87843, 0.95686, 1.0}
\definecolor{bar_blue1}{rgb}{0.7,     0.95686, 1}

\usepackage{listingsutf8}

% Common lstlisting parameters

\usepackage{calc}
\newlength{\lstboxwidth}  % width of lst box
\newlength{\framethickness}
\setlength{\framethickness}{0.5mm}
% for frame=trbl and a framerule that has significant size, set
% xleftmargin=5mm and xrightmargin=5mm.

\lstset{
  basicstyle=\small \ttfamily,
  breaklines=false,          % break/wrap lines
  breakatwhitespace=true,    % let linebreaks happen at whitespace
  breakindent=40pt,
  tab=,
  tabsize=4,                 % tab means 4 spaces
  %belowskip=\smallskipamount,  % space between code and text below
  xleftmargin=2mm,           % indentation of code frame
  xrightmargin=0mm,
  framexleftmargin=2mm,      % add frame space to the left of the code box
  %numbers=left,             % put line numbers on the left
  %stepnumber=2,             % stepnumber=1 numbers each line, =n every n lines
  framerule=\framethickness, % thickness of frame
  aboveskip=2ex,             % vertical space above code frame
  showstringspaces=false,    % show spaces in strings with an underscore
  showspaces=false,          % show spaces with an underscore
  showtabs=false,
  keepspaces=true,
  columns=fullflexible,      % tighter character kerning, like verb
  escapeinside={(*@}{@*)},   % (*@ \pause @*) in slides and math in code blocks
  extendedchars=\true,       % allows non-ascii chars, does not work with utf-8
}

% Internally defined styles for lstlisting

% Use this one without additional background color
\lstdefinestyle{yellow2_fb}{         % approx same colors as in the FEniCS book
frame=tb,                            % top+bottom frame
rulecolor=\color{black},             % frame color
framerule=0.4pt,                     % thickness of frame
backgroundcolor=\color{yellow!10},
keywordstyle=\color{blue}\bfseries,
commentstyle=\color{comment_green}\slshape,
stringstyle=\color{string_red},
identifierstyle=\color{darkorange},
}

\lstdefinestyle{simple}{
commentstyle={},
}

% end of custom lstdefinestyles

\usepackage{amsmath,amssymb,bm}
%\usepackage[latin1]{inputenc}
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage{colortbl}
\usepackage[english]{babel}
\usepackage{tikz}
\usepackage{framed}
% Use some nice templates
\beamertemplatetransparentcovereddynamic

% --- begin table of contents based on sections ---
% Delete this, if you do not want the table of contents to pop up at
% the beginning of each section:
% (Only section headings can enter the table of contents in Beamer
% slides generated from DocOnce source, while subsections are used
% for the title in ordinary slides.)
\AtBeginSection[]
{
  \begin{frame}<beamer>[plain]
  \frametitle{}
  %\frametitle{Outline}
  \tableofcontents[currentsection]
  \end{frame}
}
% --- end table of contents based on sections ---

% If you wish to uncover everything in a step-wise fashion, uncomment
% the following command:

%\beamerdefaultoverlayspecification{<+->}

\newcommand{\shortinlinecomment}[3]{\note{\textbf{#1}: #2}}
\newcommand{\longinlinecomment}[3]{\shortinlinecomment{#1}{#2}{#3}}

\definecolor{linkcolor}{rgb}{0,0,0.4}
\hypersetup{
    colorlinks=true,
    linkcolor=linkcolor,
    urlcolor=linkcolor,
    pdfmenubar=true,
    pdftoolbar=true,
    bookmarksdepth=3
    }
\setlength{\parskip}{7pt}  % {1em}

\newenvironment{doconceexercise}{}{}
\newcounter{doconceexercisecounter}
\newenvironment{doconce:movie}{}{}
\newcounter{doconce:movie:counter}

\newcommand{\subex}[1]{\noindent\textbf{#1}}  % for subexercises: a), b), etc

%-------------------- end beamer-specific preamble ----------------------

% Add user's preamble




% insert custom LaTeX commands...

\raggedbottom
\makeindex

%-------------------- end preamble ----------------------

\begin{document}

% matching end for #ifdef PREAMBLE
% #endif

\newcommand{\exercisesection}[1]{\subsection*{#1}}

\input{newcommands_bfmath}
\input{newcommands_replace}


% ------------------- main content ----------------------



% ----------------- title -------------------------

\title{Document for Testing Some Basic and Some Challenging Constructs in DocOnce Slides}

% ----------------- author(s) -------------------------

\author{Hans Petter Langtangen\inst{1,2}}
\institute{Simula Research Laboratory\inst{1}
\and
University of Oslo\inst{2}}
% ----------------- end author(s) -------------------------

\date{Jan 32, 2100
% <optional titlepage figure>
% <optional copyright>
}

\begin{frame}[plain,fragile]
\titlepage
\end{frame}

\section[First]{This is the first section}

\begin{frame}[plain,fragile]
\frametitle{Figure and bullet list}

\begin{columns}
\column{0.6\textwidth}
\pause
\begin{block}{Title with comma, and brackets: $[a,b]$ }
\footnotesize

\begin{itemize}
  \item Here is a \emph{wave signal} $f(x-ct)$

  \item It moves with velocity $c$

  \item But here it is just a figure
\end{itemize}

\noindent
\end{block}

\column{0.4\textwidth}
\begin{block}{}


\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=0.7\linewidth]{../doc/src/manual/fig/wave1D.png}}

\vspace{6mm}


\end{block}

\end{columns}
\end{frame}

\begin{frame}[plain,fragile]
\frametitle{Slide with pop-ups in red and notes}

\shortinlinecomment{hpl 1}{ Comments are typeset as usual in DocOnce. }{ Comments are typeset as }

\pause
Here we have a paragraph to pop up in red.\\
And a line more

\note{
One can also have ordinary notes.
Over multiple lines.
}
\end{frame}

\begin{frame}[plain,fragile]
\frametitle{A {\LaTeX} document}

\pause
\begin{lstlisting}[language=TeX,style=yellow2_fb]
\documentclass[11pt]{article}
\usepackage{fancyvrb}
\begin{document}

\title{Here goes the title...}
\author{John Doe \and
Jane Doe\footnote{\texttt{jane.doe@cyber.net}.}}
\date{\today}
\maketitle
\end{lstlisting}

\pause
\begin{block}{Notice}
{\LaTeX} has a lot of backslashes.
\end{block}

\pause
\begin{lstlisting}[language=TeX,style=yellow2_fb]
\section{Heading}
bla-bla
\end{document}
\end{lstlisting}
\end{frame}

\begin{frame}[plain,fragile]
\frametitle{An HTML document}

\begin{lstlisting}[language=HTML,style=yellow2_fb]
<html><head></head><body bgcolor="red">
<title>Here goes the title...<title>
<h1>Section heading</h1>
</body>
</html>
\end{lstlisting}
\end{frame}

\section{Second section}

\begin{frame}[plain,fragile]
\frametitle{Second section}


\begin{block}{}


\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=0.8\linewidth]{../doc/src/manual/fig/wave1D.png}}

\vspace{6mm}


\end{block}


\end{frame}

\begin{frame}[plain,fragile]
\frametitle{Some math and computer code}

\begin{block}{A simple, mathematical formula where $t\in [0,\pi]$: }
\[ f(x,y,t) = e^{-xt}\sin\pi y \]
\end{block}

\begin{block}{Bash demanded more of DocOnce than Python, so let's do Bash: }
First, inline \Verb@$? != 0@, then comments with dollar variables (and minted
style):

\begin{lstlisting}[language=bash,style=yellow2_fb]
var=10
# $1, $2, ... are command-line args
if [ $? -eq 0 ]; then   # $? reflects success or not
  echo "Great!"
fi
\end{lstlisting}
\end{block}
\end{frame}

\begin{frame}[plain,fragile]
\frametitle{Pop ups inside code blocks (for Beamer slides only)}

\begin{lstlisting}[language=Python,style=yellow2_fb]
def f(x):
    return 42 + x

(*@\pause@*)
def g(x):
    return f(42)

(*@\pause@*)
print(g(13))
\end{lstlisting}
\end{frame}

\begin{frame}[plain,fragile]
\frametitle{Various admon blocks}

Can use admons to simulate blocks:

\pause
\begin{block}{Key PDE (with large title and math font): }
\large

\[ \frac{\partial u}{\partial t} = \nabla^2 u \]
\end{block}

\pause
\begin{block}{}
Just some block with text and a conclusion that something is important.
This one pops up after the rest of the slide.
\end{block}

\pause
\begin{block}{Warning}
\footnotesize

Can use, e.g., a warning admon to have my own notes, preferably
inside preprocess/mako if statements to turn notes on and off.
This one is typeset in a small font and with the default
title (Warning) since no title is specified.
\end{block}
\end{frame}

\end{document}

************** File: slides1_handout.tex *****************

% LaTeX Beamer file automatically generated from DocOnce
% https://github.com/hplgit/doconce

%-------------------- begin beamer-specific preamble ----------------------

\documentclass[handout]{beamer}

\usetheme{blue_shadow}
\usecolortheme{default}

% turn off the almost invisible, yet disturbing, navigation symbols:
\setbeamertemplate{navigation symbols}{}

% Examples on customization:
%\usecolortheme[named=RawSienna]{structure}
%\usetheme[height=7mm]{Rochester}
%\setbeamerfont{frametitle}{family=\rmfamily,shape=\itshape}
%\setbeamertemplate{items}[ball]
%\setbeamertemplate{blocks}[rounded][shadow=true]
%\useoutertheme{infolines}
%
%\usefonttheme{}
%\useinntertheme{}
%
%\setbeameroption{show notes}
%\setbeameroption{show notes on second screen=right}

% fine for B/W printing:
%\usecolortheme{seahorse}

\usepackage{pgf}
\usepackage{graphicx}
\usepackage{epsfig}
\usepackage{relsize}

\usepackage{fancybox}  % make sure fancybox is loaded before fancyvrb

\usepackage{fancyvrb}
\usepackage{minted} % requires pygments and latex -shell-escape filename
%\usepackage{anslistings}
%\usepackage{listingsutf8}

\usepackage{amsmath,amssymb,bm}
%\usepackage[latin1]{inputenc}
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage{colortbl}
\usepackage[english]{babel}
\usepackage{tikz}
\usepackage{framed}
% Use some nice templates
\beamertemplatetransparentcovereddynamic

% --- begin table of contents based on sections ---
% Delete this, if you do not want the table of contents to pop up at
% the beginning of each section:
% (Only section headings can enter the table of contents in Beamer
% slides generated from DocOnce source, while subsections are used
% for the title in ordinary slides.)
\AtBeginSection[]
{
  \begin{frame}<beamer>[plain]
  \frametitle{}
  %\frametitle{Outline}
  \tableofcontents[currentsection]
  \end{frame}
}
% --- end table of contents based on sections ---

% If you wish to uncover everything in a step-wise fashion, uncomment
% the following command:

%\beamerdefaultoverlayspecification{<+->}

\newcommand{\shortinlinecomment}[3]{\note{\textbf{#1}: #2}}
\newcommand{\longinlinecomment}[3]{\shortinlinecomment{#1}{#2}{#3}}

\definecolor{linkcolor}{rgb}{0,0,0.4}
\hypersetup{
    colorlinks=true,
    linkcolor=linkcolor,
    urlcolor=linkcolor,
    pdfmenubar=true,
    pdftoolbar=true,
    bookmarksdepth=3
    }
\setlength{\parskip}{7pt}  % {1em}

\newenvironment{doconceexercise}{}{}
\newcounter{doconceexercisecounter}
\newenvironment{doconce:movie}{}{}
\newcounter{doconce:movie:counter}

\newcommand{\subex}[1]{\noindent\textbf{#1}}  % for subexercises: a), b), etc

\usepackage{pgfpages} % for handouts

\logo{{\tiny Made with \href{https://github.com/hplgit/doconce}{DocOnce}}}

%-------------------- end beamer-specific preamble ----------------------

% Add user's preamble




% insert custom LaTeX commands...

\raggedbottom
\makeindex

%-------------------- end preamble ----------------------

\begin{document}

% matching end for #ifdef PREAMBLE
% #endif

\newcommand{\exercisesection}[1]{\subsection*{#1}}

\input{newcommands_bfmath}
\input{newcommands_replace}


%\pgfpagesuselayout{4 on 1}[a4paper,landscape,border shrink=5mm]   % pdfnup is more flexible

% ------------------- main content ----------------------



% ----------------- title -------------------------

\title{Document for Testing Some Basic and Some Challenging Constructs in DocOnce Slides}

% ----------------- author(s) -------------------------

\author{Hans Petter Langtangen\inst{1,2}}
\institute{Simula Research Laboratory\inst{1}
\and
University of Oslo\inst{2}}
% ----------------- end author(s) -------------------------

\date{Jan 32, 2100
% <optional titlepage figure>
\ \\ 
{\tiny Made with \href{https://github.com/hplgit/doconce}{DocOnce}}
}

\begin{frame}[plain,fragile]
\titlepage
\end{frame}

\section[First]{This is the first section}

\begin{frame}[plain,fragile]
\frametitle{Figure and bullet list}

\begin{columns}
\column{0.6\textwidth}
\pause
\begin{block}{Title with comma, and brackets: $[a,b]$ }
\footnotesize

\begin{itemize}
  \item Here is a \emph{wave signal} $f(x-ct)$

  \item It moves with velocity $c$

  \item But here it is just a figure
\end{itemize}

\noindent
\end{block}

\column{0.4\textwidth}
\begin{block}{}


\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=0.7\linewidth]{../doc/src/manual/fig/wave1D.png}}

\vspace{6mm}


\end{block}

\end{columns}
\end{frame}

\begin{frame}[plain,fragile]
\frametitle{Slide with pop-ups in red and notes}

\shortinlinecomment{hpl 1}{ Comments are typeset as usual in DocOnce. }{ Comments are typeset as }

\pause
Here we have a paragraph to pop up in red.\\
And a line more

\note{
One can also have ordinary notes.
Over multiple lines.
}
\end{frame}

\begin{frame}[plain,fragile]
\frametitle{A {\LaTeX} document}

\pause
\begin{minted}[fontsize=\fontsize{9pt}{9pt},linenos=false,mathescape,baselinestretch=1.0,fontfamily=tt,xleftmargin=2mm]{latex}
\documentclass[11pt]{article}
\usepackage{fancyvrb}
\begin{document}

\title{Here goes the title...}
\author{John Doe \and
Jane Doe\footnote{\texttt{jane.doe@cyber.net}.}}
\date{\today}
\maketitle
\end{minted}

\pause
\begin{block}{Notice}
{\LaTeX} has a lot of backslashes.
\end{block}

\pause
\begin{minted}[fontsize=\fontsize{9pt}{9pt},linenos=false,mathescape,baselinestretch=1.0,fontfamily=tt,xleftmargin=2mm]{latex}
\section{Heading}
bla-bla
\end{document}
\end{minted}
\end{frame}

\begin{frame}[plain,fragile]
\frametitle{An HTML document}

\begin{minted}[fontsize=\fontsize{9pt}{9pt},linenos=false,mathescape,baselinestretch=1.0,fontfamily=tt,xleftmargin=2mm]{html}
<html><head></head><body bgcolor="red">
<title>Here goes the title...<title>
<h1>Section heading</h1>
</body>
</html>
\end{minted}
\end{frame}

\section{Second section}

\begin{frame}[plain,fragile]
\frametitle{Second section}


\begin{block}{}


\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=0.8\linewidth]{../doc/src/manual/fig/wave1D.png}}

\vspace{6mm}


\end{block}


\end{frame}

\begin{frame}[plain,fragile]
\frametitle{Some math and computer code}

\begin{block}{A simple, mathematical formula where $t\in [0,\pi]$: }
\[ f(x,y,t) = e^{-xt}\sin\pi y \]
\end{block}

\begin{block}{Bash demanded more of DocOnce than Python, so let's do Bash: }
First, inline \Verb@$? != 0@, then comments with dollar variables (and minted
style):

\begin{minted}[fontsize=\fontsize{9pt}{9pt},linenos=false,baselinestretch=1.0,fontfamily=tt,xleftmargin=2mm]{bash}
var=10
# $1, $2, ... are command-line args
if [ $? -eq 0 ]; then   # $? reflects success or not
  echo "Great!"
fi
\end{minted}
\end{block}
\end{frame}

\begin{frame}[plain,fragile]
\frametitle{Pop ups inside code blocks (for Beamer slides only)}

\begin{minted}[fontsize=\fontsize{9pt}{9pt},linenos=false,mathescape,baselinestretch=1.0,fontfamily=tt,xleftmargin=2mm]{python}
def f(x):
    return 42 + x

(*@\pause@*)
def g(x):
    return f(42)

(*@\pause@*)
print(g(13))
\end{minted}
\end{frame}

\begin{frame}[plain,fragile]
\frametitle{Various admon blocks}

Can use admons to simulate blocks:

\pause
\begin{block}{Key PDE (with large title and math font): }
\large

\[ \frac{\partial u}{\partial t} = \nabla^2 u \]
\end{block}

\pause
\begin{block}{}
Just some block with text and a conclusion that something is important.
This one pops up after the rest of the slide.
\end{block}

\pause
\begin{block}{Warning}
\footnotesize

Can use, e.g., a warning admon to have my own notes, preferably
inside preprocess/mako if statements to turn notes on and off.
This one is typeset in a small font and with the default
title (Warning) since no title is specified.
\end{block}
\end{frame}

\end{document}

************** File: slides2.do.txt *****************
TITLE: Test slide features
AUTHOR: Core Dump at Cyber Space Ltd
DATE: Today

FIGURE: [../doc/src/slides/fig/doconce1b, width=400 frac=0.5]

!split
TOC: on

!split
===== Scientific writing for the future needs to address many new media =====

!bslidecell 00 0.4
FIGURE: [../doc/src/slides/fig/ipad, width=400 frac=0.8]

FIGURE: [../doc/src/slides/fig/iphones, width=100 frac=0.3]

#FIGURE: [../doc/src/slides/fig/mbair, width=400]

!eslidecell

!bslidecell 01 0.6
FIGURE: [../doc/src/slides/fig/imac, width=350 frac=0.7]
!eslidecell

!split
===== The book will probably survive =====

FIGURE: [../doc/src/slides/fig/oldbooks, width=800]

!split
===== The classical report will survive =====

!bslidecell 00
FIGURE: [../doc/src/slides/fig/latex_thesis, width=400 frac=1.2]
!eslidecell

!bslidecell 01
FIGURE: [../doc/src/slides/fig/latex_paper1, width=400 frac=1.2]
!eslidecell

!split
===== Scope =====

#  * Scientific writing = lecture notes, slides, reports, thesis, books,  ...
#  * (Journal papers typeset by journals are out of scope)

!bpop
  * Scope: documents with color{red}{much} *math* and *computer code*
  * Key question: What tools should I use for writing?
  * Default answer: LaTeX
  * Alternative: MS Word w/math
  * Recent popular alternative tools: HTML w/MathJax,
    Sphinx, Markdown, MediaWiki, IPython notebook
!epop

!bslidecell 00 0.25
FIGURE: [../doc/src/slides/fig/LaTeX_logo.jpg, width=120 frac=0.3]
!eslidecell

!bslidecell 01 0.25
FIGURE: [../doc/src/slides/fig/MS_Word_logo.jpg, width=80 frac=0.2]
!eslidecell

!bslidecell 02 0.5
FIGURE: [../doc/src/slides/fig/sphinx_logo.png, width=200 frac=0.4]
!eslidecell

!bslidecell 10 0.25
FIGURE: [../doc/src/slides/fig/markdown_logo.jpg, width=80 frac=0.2]
!eslidecell

!bslidecell 11 0.25
FIGURE: [../doc/src/slides/fig/MediaWiki_logo.jpg, width=80 frac=0.2]
!eslidecell

!bslidecell 12 0.5
FIGURE: [../doc/src/slides/fig/IPython_logo.png, width=300 frac=0.6]
!eslidecell


!split
===== Scientific writing for the future needs to address many new media =====

# Insert links here to reports

!bslidecell 00
Old days (1985-2005): LaTeX for BW paper output, but now

   o BW books
   o Colorful PDF books (printed and screen)
   o Designed web pages
   o Wikis
   o Blog posts
   o Next new fancy format (iBook w/LaTeX?)
!eslidecell

!bslidecell 01
FIGURE: [../doc/src/slides/fig/jungle_with_mess.jpg, width=500]
!eslidecell

!split

===== Fundamental question =====

When I write some scientific material,

 * a LaTeX document,
 * a blog post (HTML),
 * some web pages (HTML),
 * a Sphinx document,
 * some Markdown files,

and later want to collect the pieces into a larger document, maybe
some book, or one big web document, is that at all feasible?

!bpop highlight-red
Probably not, but I have a solution :-)
!epop

!split

===== LaTeX is very rich; other tools support only some elements =====

 * LaTeX inline math: works with all (LaTeX, MathJax, Sphinx, Markdown, MediaWiki)
 * LaTeX equation math:
    * _LaTeX_: `equation*`, `equation`, `align*`, `align` +
      `eqnarray`, `split`, `alignat`, ... (numerous!)
    * _MathJax_: `equation*`, `equation`, `align*`, `align`
    * _MediaWiki_: `equation*`, `equation`, `align*`, `align`
    * _Sphinx_: `equation*`, `equation`, `align*`
    * _Markdown_: `equation*`, `equation`, `eqnarray*`, `align*` (but no labels)

!split
===== LaTeX is very rich; other tools support only some elements =====

!bpop
 * Figures: all
 * Subfigures: LaTeX (`subfigure`)
 * Movies: LaTeX (can run separately), just raw embedded HTML in others
 * Floating computer code: LaTeX
 * Fixed computer code: all
 * Floating tables: LaTeX; inline tables: all
 * Algorithms: LaTeX
 * Margin notes: LaTeX
 * Page references: LaTeX
 * Footnotes: LaTeX, Sphinx, reStructuredText, MediaWiki
 * Bibliography: LaTeX, Sphinx, reStructuredText, MediaWiki
 * Hyperlinks: all (but not on paper!)
!epop

!bpop
Conclusion: Highly non-trivial to translate a LaTeX document into something
based on HTML and vice versa.
!epop


!split
===== DocOnce demo =====

URL: "https://hplgit.github.com/teamods/writing_reports/"

 * LaTeX-based PDF "for screen": "https://hplgit.github.com/teamods/writing_reports/_static/report.pdf", "for printing": "https://hplgit.github.com/teamods/writing_reports/_static/report_4printing.pdf", "for phone": "https://hplgit.github.com/teamods/writing_reports/_static/report_4phone.pdf"
 * "Plain HTML": "https://hplgit.github.com/teamods/writing_reports/_static/report_do.html" or with a "template": "https://hplgit.github.com/teamods/writing_reports/_static/report_vagrant.html" or "another template": "https://hplgit.github.com/teamods/writing_reports/_static/report_github_minimal.html" or "solarized": "https://hplgit.github.com/teamods/writing_reports/_static/report_solarized.html"
 * Sphinx: "agni": "https://hplgit.github.com/teamods/writing_reports/_static/sphinx-agni/index.html", "pyramid": "https://hplgit.github.com/teamods/writing_reports/_static/sphinx-pyramid/report.html", "classy": "https://hplgit.github.com/teamods/writing_reports/_static/sphinx-classy/report.html", "fenics": "https://hplgit.github.com/teamods/writing_reports/_static/sphinx-fenics_minimal/report.html", "redcloud": "https://hplgit.github.com/teamods/writing_reports/_static/sphinx-fenics_minimal/report.html"
 * HTML for "Google": "https://doconce-report-demo.blogspot.no/" or "Wordpress": "https://doconcereportdemo.wordpress.com/" blog posts
 * "MediaWiki": "https://doconcedemo.shoutwiki.com/wiki/DocOnce_demo_page" (Wikipedia, Wikibooks, etc)
 * DocOnce "source code": "https://hplgit.github.com/teamods/writing_reports/_static/report.do.txt.html" and "manual": "https://hplgit.github.io/doconce/doc/src/pub/manual/html/manual.html"


!split

# #if FORMAT in ("latex", "pdflatex")
# latex interprets 9 = as chapter and then needs book style...
===== A tour of DocOnce =====
# #else
======= A tour of DocOnce =======
# #endif

!split
===== DocOnce: title, authors, date, toc =====

!bc
TITLE: Some Title
AUTHOR: name1 at institution1, with more info & institution2
AUTHOR: name2 email:name2@web.com at institution
DATE: today

# A table of contents is optional:
TOC: on
!ec

!bnotice
Title and authors must have all information *on a single line*!
!enotice

!split
===== DocOnce: abstract =====

!bc
__Abstract.__
Here goes the abstract...
!ec

Or:
!bc
__Summary.__
Here goes the summary...
!ec


!split
===== DocOnce: section headings =====

Headings are surrounded by `=` signs:
!bc
======= This is an H1/chapter heading =======

===== This is an H2/section heading =====

===== This is an H3/subsection heading =====

=== This is an H4/paragraph heading ===

__This is a paragraph heading.__
!ec

## Headings in slides don't make sense in LaTeX Beamer
# #ifndef BEAMER
Result:

======= This is an H1/chapter heading =======

===== This is an H2/section heading =====

===== This is an H3/subsection heading =====

=== This is an H4/paragraph heading ===

__This is a paragraph heading.__
# #endif

!split
===== DocOnce: markup and lists =====

!bc
 * Bullet list items start with `*`
   and may span several lines
 * *Emphasized words* are possible
 * _Boldface words_ are also possible
 * color{red}{colored words} too
 * `inline verbatim code` is featured
   o and sublists with enumerated items starting with `o`
   o items are just indented as you would do in email
!ec

This gets rendered as

 * Bullet lists start with `*`
   and may span several lines
 * *Emphasized words* are possible
 * _Boldface words_ are also possible
 * color{red}{colored words} too
 * `inline verbatim code` is featured
   o and sublists with enumerated items starting with `o`
   o items are just indented as you would do in email

!split
===== DocOnce: labels, references, index items =====

!bc do
# Insert index items in the source
idx{key word1} idx{key word2}

# Label
===== Some section =====
label{this:section}

# Make reference
As we saw in Section ref{this:section}, references, index
items and labels follow a syntax similar to LaTeX
but without backslashes.

# Make reference to equations
See (ref{eq1})-(ref{myeq}).

# Make hyperlink
"some link text": "https://github.com/hplgit/doconce"

# Hyperlink with complete URL as link text
URL: "https://github.com/hplgit/doconce"
!ec

!split
===== DocOnce: figures and movies =====

!bnotice
Figure with HTML and LaTeX info, and caption, *all on one line*:
!enotice

!bc
FIGURE: [figdir/myfig, width=300 frac=1.2] My caption. label{fig1}

# This figure will be 300 pixels wide in HTML and span 1.2 times
# the linewidth in LaTeX.
!ec

Movies are also supported:

!bc
MOVIE: [https://www.youtube.com/embed/P8VcZzgdfSc, width=420 height=315]
!ec
and rendered as

MOVIE: [https://www.youtube.com/embed/P8VcZzgdfSc, width=420 height=315]

!split
===== DocOnce: math =====

Inline math as in LaTeX:

!bc
...where $a=\int_{\Omega}fdx$ is an integral.
!ec
gets rendered as ...where $a=\int_{\Omega}fdx$ is an integral.


An equation environment is surrounded by `!bt` and `!et` tags,
the rest is plain LaTeX:

!bc
|bt
\begin{align}
\frac{\partial u}{\partial t} &= \nabla^2 u,
label{a:eq}\\
\nabla\cdot\pmb{v} & = 0
label{b:eq}
\end{align}
|et
!ec
which is rendered as

!bt
\begin{align}
\frac{\partial u}{\partial t} &= \nabla^2 u,
label{_a:eq}\\
\nabla\cdot\pmb{v} & = 0
label{_b:eq}
\end{align}
!et


!split
===== DocOnce: displaying code =====

Code is enclosed in `!bc` and `!ec` tags:

!bc
|bc pycod
def solver(I, a, T, dt, theta):
    """Solve u'=-a*u, u(0)=I, for t in (0,T] with steps of dt."""
    dt = float(dt)           # avoid integer division
    N = int(round(T/dt))     # no of time intervals
    T = N*dt                 # adjust T to fit time step dt
    u = zeros(N+1)           # array of u[n] values
    t = linspace(0, T, N+1)  # time mesh

    u[0] = I                 # assign initial condition
    for n in range(0, N):    # n=0,1,...,N-1
        u[n+1] = (1 - (1-theta)*a*dt)/(1 + theta*dt*a)*u[n]
    return u, t
|ec
!ec
This gets rendered as

!bc pycod
def solver(I, a, T, dt, theta):
    """Solve u'=-a*u, u(0)=I, for t in (0,T] with steps of dt."""
    dt = float(dt)           # avoid integer division
    N = int(round(T/dt))     # no of time intervals
    T = N*dt                 # adjust T to fit time step dt
    u = zeros(N+1)           # array of u[n] values
    t = linspace(0, T, N+1)  # time mesh

    u[0] = I                 # assign initial condition
    for n in range(0, N):    # n=0,1,...,N-1
        u[n+1] = (1 - (1-theta)*a*dt)/(1 + theta*dt*a)*u[n]
    return u, t
!ec

!bnotice Language-dependent typesetting of code:
The `!bc` command can be followed by a specification of the computer
language: `pycod` for Python code snippet, `pypro` for complete Python
program, `fcod` for Fortran snippet, `fpro` for Fortran program, and so
forth (`c` for C, `cpp` for C++, `sh` for Unix shells, `m` for Matlab).
!enotice


!split
===== DocOnce: displaying interactive demo code =====
label{slide:pot}

With `!bc pyoptpro` or a file `*.pyopt`, the code applies the
"Online Python Tutor": "https://pythontutor.com" for displaying
program flow and state of variables:

@@@CODE ../doc/src/slides/src/solver.pyopt




!split
===== DocOnce: exercises =====

DocOnce offers a special format for *exercises*, *problems*, *projects*,
and *examples*:

!bc
===== Problem: Flip a Coin =====
label{demo:ex:1}

files = flip_coin.py, flip_coin.pdf
solutions = mysol.txt, mysol_flip_coin.py
keywords = random numbers; Monte Carlo simulation

|bsubex
Make a program that simulates flipping a coin $N$ times.

|bhint
Use `r = random.random()` and define head as `r <= 0.5`.
|ehint
|esubex

|bsubex
Compute the probability of getting heads.

|bans
A short answer: 0.5.
|eans

|bsol
A full solution to this subexercise can go here.
|esol
|esubex

|bsubex
Make another program that computes the probability
of getting at least three heads out of 5 throws.
|esubex
!ec

Solutions/answers can easily be left out of the document.

## Headings in slides don't make sense in LaTeX Beamer
# #ifndef BEAMER
!split
===== DocOnce: exercises =====

Last page gets rendered as follows:

===== Problem: Flip a Coin =====
label{_demo:ex:1}
files = flip_coin.py, flip_coin.pdf
solutions = mysol.txt, mysol_flip_coin.py
keywords = random numbers; Monte Carlo simulation

!bsubex
Make a program that simulates flipping a coin $N$ times.

!bhint
Use `r = random.random()` and define head as `r <= 0.5`.
!ehint
!esubex

!bsubex
Compute the probability of getting heads.

!bans
A short answer: 0.5.
!eans

!bsol
A full solution to this subexercise can go here.
!esol
!esubex

!bsubex
Make another program that computes the probability
of getting at least three heads out of 5 throws.
!esubex
# #endif

!split
===== DocOnce: example on slide code =====

!bc
!split
===== Headline =====

 * Key point 1
 * Key point 2
 * Key point 3 takes very much more text to explain because
   this point is really comprehensive, and although long
   bullet points are not recommended in general, we need
   it here for demonstration purposes

FIGURE: [../doc/src/slides/fig/teacher1, width=100]

Key equation:

|bt
\[ -\nabla^2 u = f \quad\hbox{in }\Omega \]
|et

And maybe a final comment?

!split
===== Next slide... =====
!ec

## Headings in slides don't make sense in LaTeX Beamer
# #ifndef BEAMER
!split
===== DocOnce: example on slide code =====

Last page gets rendered to

===== Headline =====

 * Key point 1
 * Key point 2

FIGURE: [../doc/src/slides/fig/teacher1, width=100 frac=0.4]

Key equation:

!bt
\[ -\nabla^2 u = f \quad\hbox{in }\Omega \]
!et

And maybe a final comment?
# #endif

!split
===== DocOnce: example on slide code with cells =====

One can introduce a table-like layout with MxN cells and
put slide elements in various cell. A cell with position
MN is surrounded by `!bslidecell MN` and `!eslidecell`
tags. Below is an example with a bullet list to the left and
a figure to the right (two cells, numbered 00 and 01).

!bc
!split
===== Headline =====

|bslidecell 00
|bpop
 * Key point 1
 * Key point 2
 * Key point 3 takes very much more text to explain because
   this point is really comprehensive, and although long
   bullet points are not recommended in general, we need
   it here for demonstration purposes
|epop

|bpop
|bt
\[ -\nabla^2 u = f \quad\hbox{in }\Omega \]
|et
|epop

|eslidecell

|bslidecell 01
FIGURE: [../doc/src/slides/fig/broken_pen_and_paper, width=400, frac=0.8]
|eslidecell

!split
===== Next slide... =====
!ec

## Headings in slides don't make sense in LaTeX Beamer
# #ifndef BEAMER
!split
===== DocOnce: example on slide code =====

Last page gets rendered to

===== Headline =====

!bslidecell 00
!bpop
 * Key point 1
 * Key point 2
 * Key point 3 takes very much more text to explain because
   this point is really comprehensive, and although long
   bullet points are not recommended in general, we need
   it here for demonstration purposes
!epop

!bpop
!bt
\[ -\nabla^2 u = f \quad\hbox{in }\Omega \]
!et
!epop

!eslidecell

!bslidecell 01
FIGURE: [../doc/src/slides/fig/broken_pen_and_paper, width=400]
!eslidecell
# #endif

************** File: slides2_reveal.html *****************
<!DOCTYPE html>

<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="DocOnce: https://github.com/doconce/doconce/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="description" content="Test slide features">
<meta name="keywords" content="key word1,key word2">

<title>Test slide features</title>







<!-- reveal.js: https://lab.hakim.se/reveal-js/ -->

<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">

<meta name="apple-mobile-web-app-capable" content="yes" />
<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent" />
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, minimal-ui">

<link rel="stylesheet" href="reveal.js/css/reveal.css">
<link rel="stylesheet" href="reveal.js/css/theme/beigesmall.css" id="theme">
<!--
<link rel="stylesheet" href="reveal.js/css/reveal.css">
<link rel="stylesheet" href="reveal.js/css/theme/beige.css" id="theme">
<link rel="stylesheet" href="reveal.js/css/theme/beigesmall.css" id="theme">
<link rel="stylesheet" href="reveal.js/css/theme/solarized.css" id="theme">
<link rel="stylesheet" href="reveal.js/css/theme/serif.css" id="theme">
<link rel="stylesheet" href="reveal.js/css/theme/night.css" id="theme">
<link rel="stylesheet" href="reveal.js/css/theme/moon.css" id="theme">
<link rel="stylesheet" href="reveal.js/css/theme/simple.css" id="theme">
<link rel="stylesheet" href="reveal.js/css/theme/sky.css" id="theme">
<link rel="stylesheet" href="reveal.js/css/theme/darkgray.css" id="theme">
<link rel="stylesheet" href="reveal.js/css/theme/default.css" id="theme">
<link rel="stylesheet" href="reveal.js/css/theme/cbc.css" id="theme">
<link rel="stylesheet" href="reveal.js/css/theme/simula.css" id="theme">
<link rel="stylesheet" href="reveal.js/css/theme/black.css" id="theme">
<link rel="stylesheet" href="reveal.js/css/theme/white.css" id="theme">
<link rel="stylesheet" href="reveal.js/css/theme/league.css" id="theme">
-->

<!-- For syntax highlighting -->
<link rel="stylesheet" href="reveal.js/lib/css/zenburn.css">

<!-- Printing and PDF exports -->
<script>
var link = document.createElement( 'link' );
link.rel = 'stylesheet';
link.type = 'text/css';
link.href = window.location.search.match( /print-pdf/gi ) ? 'css/print/pdf.css' : 'css/print/paper.css';
document.getElementsByTagName( 'head' )[0].appendChild( link );
</script>

<style type="text/css">
    hr { border: 0; width: 80%; border-bottom: 1px solid #aaa}
    p.caption { width: 80%; font-size: 60%; font-style: italic; text-align: left; }
    hr.figure { border: 0; width: 80%; border-bottom: 1px solid #aaa}
    .reveal .alert-text-small   { font-size: 80%;  }
    .reveal .alert-text-large   { font-size: 130%; }
    .reveal .alert-text-normal  { font-size: 90%;  }
    .reveal .alert {
             padding:8px 35px 8px 14px; margin-bottom:18px;
             text-shadow:0 1px 0 rgba(255,255,255,0.5);
             border:5px solid #bababa;
             -webkit-border-radius: 14px; -moz-border-radius: 14px;
             border-radius:14px;
             background-position: 10px 10px;
             background-repeat: no-repeat;
             background-size: 38px;
             padding-left: 30px; /* 55px; if icon */
     }
     .reveal .alert-block {padding-top:14px; padding-bottom:14px}
     .reveal .alert-block > p, .alert-block > ul {margin-bottom:1em}
     /*.reveal .alert li {margin-top: 1em}*/
     .reveal .alert-block p+p {margin-top:5px}
     /*.reveal .alert-notice { background-image: url(https://hplgit.github.io/doconce/bundled/html_images/small_gray_notice.png); }
     .reveal .alert-summary  { background-image:url(https://hplgit.github.io/doconce/bundled/html_images/small_gray_summary.png); }
     .reveal .alert-warning { background-image: url(https://hplgit.github.io/doconce/bundled/html_images/small_gray_warning.png); }
     .reveal .alert-question {background-image:url(https://hplgit.github.io/doconce/bundled/html_images/small_gray_question.png); } */

</style>



<!-- Styles for table layout of slides -->
<style type="text/css">
td.padding {
  padding-top:20px;
  padding-bottom:20px;
  padding-right:50px;
  padding-left:50px;
}
</style>

</head>

<body>
<div class="reveal">

<!-- Any section element inside the <div class="slides"> container
     is displayed as a slide -->

<div class="slides">





<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  TeX: {
     equationNumbers: {  autoNumber: "none"  },
     extensions: ["AMSmath.js", "AMSsymbols.js", "autobold.js", "color.js"]
  }
});
</script>
<script type="text/javascript" async
 src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>



    



<section>
<!-- ------------------- main content ---------------------- -->



<center><h1 style="text-align: center;">Test slide features</h1></center>  <!-- document title -->

<p>
<!-- author(s): Core Dump -->

<center>
<b>Core Dump</b> 
</center>

<p>
<!-- institution -->

<center><b>Cyber Space Ltd</b></center>
<br>
<p>&nbsp;<br>
<center><h4>Jan 32, 2100</h4></center> <!-- date -->
<br>
<p>
<br /><br /><center><p><img src="../doc/src/slides/fig/doconce1b.png" align="bottom" width=400></p></center><br /><br />
</section>


<section>
<h1 id="table_of_contents">Table of contents</h2>

<p>
&nbsp; &nbsp; &nbsp; <a href="#scientific-writing-for-the-future-needs-to-address-many-new-media"> Scientific writing for the future needs to address many new media </a><br>
&nbsp; &nbsp; &nbsp; <a href="#the-book-will-probably-survive"> The book will probably survive </a><br>
&nbsp; &nbsp; &nbsp; <a href="#the-classical-report-will-survive"> The classical report will survive </a><br>
&nbsp; &nbsp; &nbsp; <a href="#scope"> Scope </a><br>
&nbsp; &nbsp; &nbsp; <a href="#scientific-writing-for-the-future-needs-to-address-many-new-media"> Scientific writing for the future needs to address many new media </a><br>
&nbsp; &nbsp; &nbsp; <a href="#fundamental-question"> Fundamental question </a><br>
&nbsp; &nbsp; &nbsp; <a href="#latex-is-very-rich-other-tools-support-only-some-elements"> LaTeX is very rich; other tools support only some elements </a><br>
&nbsp; &nbsp; &nbsp; <a href="#latex-is-very-rich-other-tools-support-only-some-elements"> LaTeX is very rich; other tools support only some elements </a><br>
&nbsp; &nbsp; &nbsp; <a href="#doconce-demo"> DocOnce demo </a><br>
<a href="#a-tour-of-doconce"> A tour of DocOnce </a><br>
&nbsp; &nbsp; &nbsp; <a href="#doconce-title-authors-date-toc"> DocOnce: title, authors, date, toc </a><br>
&nbsp; &nbsp; &nbsp; <a href="#doconce-abstract"> DocOnce: abstract </a><br>
&nbsp; &nbsp; &nbsp; <a href="#doconce-section-headings"> DocOnce: section headings </a><br>
<a href="#this-is-an-h1-chapter-heading"> This is an H1/chapter heading </a><br>
&nbsp; &nbsp; &nbsp; <a href="#this-is-an-h2-section-heading"> This is an H2/section heading </a><br>
&nbsp; &nbsp; &nbsp; <a href="#this-is-an-h3-subsection-heading"> This is an H3/subsection heading </a><br>
&nbsp; &nbsp; &nbsp; <a href="#doconce-markup-and-lists"> DocOnce: markup and lists </a><br>
&nbsp; &nbsp; &nbsp; <a href="#doconce-labels-references-index-items"> DocOnce: labels, references, index items </a><br>
&nbsp; &nbsp; &nbsp; <a href="#doconce-figures-and-movies"> DocOnce: figures and movies </a><br>
&nbsp; &nbsp; &nbsp; <a href="#doconce-math"> DocOnce: math </a><br>
&nbsp; &nbsp; &nbsp; <a href="#doconce-displaying-code"> DocOnce: displaying code </a><br>
&nbsp; &nbsp; &nbsp; <a href="#slide:pot"> DocOnce: displaying interactive demo code </a><br>
&nbsp; &nbsp; &nbsp; <a href="#doconce-exercises"> DocOnce: exercises </a><br>
&nbsp; &nbsp; &nbsp; <a href="#doconce-exercises"> DocOnce: exercises </a><br>
&nbsp; &nbsp; &nbsp; <a href="#_demo:ex:1"> Problem 1: Flip a Coin </a><br>
&nbsp; &nbsp; &nbsp; <a href="#doconce-example-on-slide-code"> DocOnce: example on slide code </a><br>
&nbsp; &nbsp; &nbsp; <a href="#doconce-example-on-slide-code"> DocOnce: example on slide code </a><br>
&nbsp; &nbsp; &nbsp; <a href="#headline"> Headline </a><br>
&nbsp; &nbsp; &nbsp; <a href="#doconce-example-on-slide-code-with-cells"> DocOnce: example on slide code with cells </a><br>
&nbsp; &nbsp; &nbsp; <a href="#doconce-example-on-slide-code"> DocOnce: example on slide code </a><br>
&nbsp; &nbsp; &nbsp; <a href="#headline"> Headline </a><br>
</p>
</section>


<section>
<h2 id="scientific-writing-for-the-future-needs-to-address-many-new-media">Scientific writing for the future needs to address many new media </h2>

<p>

<table border="0">
<tr>
<td class="padding">
<br /><br /><center><p><img src="../doc/src/slides/fig/ipad.png" align="bottom" width=400></p></center><br /><br />

<p>
<br /><br /><center><p><img src="../doc/src/slides/fig/iphones.jpg" align="bottom" width=100></p></center><br /><br />

<p>
<!-- FIGURE: [../doc/src/slides/fig/mbair, width=400] -->

<p>
</td>
<td class="padding">
<br /><br /><center><p><img src="../doc/src/slides/fig/imac.png" align="bottom" width=350></p></center><br /><br />
</td>
</tr>
</table>
</section>


<section>
<h2 id="the-book-will-probably-survive">The book will probably survive </h2>

<p>
<br /><br /><center><p><img src="../doc/src/slides/fig/oldbooks.jpg" align="bottom" width=800></p></center><br /><br />
</section>


<section>
<h2 id="the-classical-report-will-survive">The classical report will survive </h2>

<p>

<table border="0">
<tr>
<td class="padding">
<br /><br /><center><p><img src="../doc/src/slides/fig/latex_thesis.jpg" align="bottom" width=400></p></center><br /><br />
</td>
<td class="padding">
<br /><br /><center><p><img src="../doc/src/slides/fig/latex_paper1.png" align="bottom" width=400></p></center><br /><br />
</td>
</tr>
</table>
</section>


<section>
<h2 id="scope">Scope </h2>

<p>
<!-- * Scientific writing = lecture notes, slides, reports, thesis, books,  ... -->
<!-- * (Journal papers typeset by journals are out of scope) -->

<ul>

<p><li class="fragment"> Scope: documents with <font color="red">much</font> <em>math</em> and <em>computer code</em></li>

<p><li class="fragment"> Key question: What tools should I use for writing?</li>

<p><li class="fragment"> Default answer: LaTeX</li>

<p><li class="fragment"> Alternative: MS Word w/math</li>

<p><li class="fragment"> Recent popular alternative tools: HTML w/MathJax,
    Sphinx, Markdown, MediaWiki, IPython notebook</li>
</ul>
<p>

<table border="0">
<tr>
<td class="padding">
<br /><br /><center><p><img src="../doc/src/slides/fig/LaTeX_logo.jpg" align="bottom" width=120></p></center><br /><br />
</td>
<td class="padding">
<br /><br /><center><p><img src="../doc/src/slides/fig/MS_Word_logo.jpg" align="bottom" width=80></p></center><br /><br />
</td>
<td class="padding">
<br /><br /><center><p><img src="../doc/src/slides/fig/sphinx_logo.png" align="bottom" width=200></p></center><br /><br />
</td>
</tr>
<tr>
<td class="padding">
<br /><br /><center><p><img src="../doc/src/slides/fig/markdown_logo.jpg" align="bottom" width=80></p></center><br /><br />
</td>
<td class="padding">
<br /><br /><center><p><img src="../doc/src/slides/fig/MediaWiki_logo.jpg" align="bottom" width=80></p></center><br /><br />
</td>
<td class="padding">
<br /><br /><center><p><img src="../doc/src/slides/fig/IPython_logo.png" align="bottom" width=300></p></center><br /><br />
</td>
</tr>
</table>
</section>


<section>
<h2 id="scientific-writing-for-the-future-needs-to-address-many-new-media">Scientific writing for the future needs to address many new media </h2>

<p>
<!-- Insert links here to reports -->

<p>

<table border="0">
<tr>
<td class="padding">
Old days (1985-2005): LaTeX for BW paper output, but now

<ol>

<p><li> BW books</li>

<p><li> Colorful PDF books (printed and screen)</li>

<p><li> Designed web pages</li>

<p><li> Wikis</li>

<p><li> Blog posts</li>

<p><li> Next new fancy format (iBook w/LaTeX?)</li>
</ol>
<p>
</td>
<td class="padding">
<br /><br /><center><p><img src="../doc/src/slides/fig/jungle_with_mess.jpg" align="bottom" width=500></p></center><br /><br />
</td>
</tr>
</table>
</section>


<section>
<h2 id="fundamental-question">Fundamental question </h2>

<p>
When I write some scientific material,

<ul>
 <p><li> a LaTeX document,</li>
 <p><li> a blog post (HTML),</li>
 <p><li> some web pages (HTML),</li>
 <p><li> a Sphinx document,</li>
 <p><li> some Markdown files,</li>
</ul>
<p>

and later want to collect the pieces into a larger document, maybe
some book, or one big web document, is that at all feasible?

<p>

<p class="fragment">

<span class="fragment highlight-red">

Probably not, but I have a solution :-)

</span>

</p>
</section>


<section>
<h2 id="latex-is-very-rich-other-tools-support-only-some-elements">LaTeX is very rich; other tools support only some elements </h2>

<ul>
 <p><li> LaTeX inline math: works with all (LaTeX, MathJax, Sphinx, Markdown, MediaWiki)</li>
 <p><li> LaTeX equation math:</li>

<ul>

<p><li> <b>LaTeX</b>: <code>equation*</code>, <code>equation</code>, <code>align*</code>, <code>align</code> +
      <code>eqnarray</code>, <code>split</code>, <code>alignat</code>, ... (numerous!)</li>

<p><li> <b>MathJax</b>: <code>equation*</code>, <code>equation</code>, <code>align*</code>, <code>align</code></li>

<p><li> <b>MediaWiki</b>: <code>equation*</code>, <code>equation</code>, <code>align*</code>, <code>align</code></li>

<p><li> <b>Sphinx</b>: <code>equation*</code>, <code>equation</code>, <code>align*</code></li>

<p><li> <b>Markdown</b>: <code>equation*</code>, <code>equation</code>, <code>eqnarray*</code>, <code>align*</code> (but no labels)</li>
</ul>
<p>
</ul>
</section>


<section>
<h2 id="latex-is-very-rich-other-tools-support-only-some-elements">LaTeX is very rich; other tools support only some elements </h2>

<ul>
 <p><li class="fragment"> Figures: all</li>
 <p><li class="fragment"> Subfigures: LaTeX (<code>subfigure</code>)</li>
 <p><li class="fragment"> Movies: LaTeX (can run separately), just raw embedded HTML in others</li>
 <p><li class="fragment"> Floating computer code: LaTeX</li>
 <p><li class="fragment"> Fixed computer code: all</li>
 <p><li class="fragment"> Floating tables: LaTeX; inline tables: all</li>
 <p><li class="fragment"> Algorithms: LaTeX</li>
 <p><li class="fragment"> Margin notes: LaTeX</li>
 <p><li class="fragment"> Page references: LaTeX</li>
 <p><li class="fragment"> Footnotes: LaTeX, Sphinx, reStructuredText, MediaWiki</li>
 <p><li class="fragment"> Bibliography: LaTeX, Sphinx, reStructuredText, MediaWiki</li>
 <p><li class="fragment"> Hyperlinks: all (but not on paper!)</li>
</ul>
<p>

<p class="fragment">

Conclusion: Highly non-trivial to translate a LaTeX document into something
based on HTML and vice versa.

</p>
</section>


<section>
<h2 id="doconce-demo">DocOnce demo </h2>

<p>
<a href="https://hplgit.github.com/teamods/writing_reports/" target="_self"><tt>https://hplgit.github.com/teamods/writing_reports/</tt></a>

<ul>
 <p><li> LaTeX-based PDF <a href="https://hplgit.github.com/teamods/writing_reports/_static/report.pdf" target="_self">for screen</a>, <a href="https://hplgit.github.com/teamods/writing_reports/_static/report_4printing.pdf" target="_self">for printing</a>, <a href="https://hplgit.github.com/teamods/writing_reports/_static/report_4phone.pdf" target="_self">for phone</a></li>
 <p><li> <a href="https://hplgit.github.com/teamods/writing_reports/_static/report_do.html" target="_self">Plain HTML</a> or with a <a href="https://hplgit.github.com/teamods/writing_reports/_static/report_vagrant.html" target="_self">template</a> or <a href="https://hplgit.github.com/teamods/writing_reports/_static/report_github_minimal.html" target="_self">another template</a> or <a href="https://hplgit.github.com/teamods/writing_reports/_static/report_solarized.html" target="_self">solarized</a></li>
 <p><li> Sphinx: <a href="https://hplgit.github.com/teamods/writing_reports/_static/sphinx-agni/index.html" target="_self">agni</a>, <a href="https://hplgit.github.com/teamods/writing_reports/_static/sphinx-pyramid/report.html" target="_self">pyramid</a>, <a href="https://hplgit.github.com/teamods/writing_reports/_static/sphinx-classy/report.html" target="_self">classy</a>, <a href="https://hplgit.github.com/teamods/writing_reports/_static/sphinx-fenics_minimal/report.html" target="_self">fenics</a>, <a href="https://hplgit.github.com/teamods/writing_reports/_static/sphinx-fenics_minimal/report.html" target="_self">redcloud</a></li>
 <p><li> HTML for <a href="https://doconce-report-demo.blogspot.no/" target="_self">Google</a> or <a href="https://doconcereportdemo.wordpress.com/" target="_self">Wordpress</a> blog posts</li>
 <p><li> <a href="https://doconcedemo.shoutwiki.com/wiki/DocOnce_demo_page" target="_self">MediaWiki</a> (Wikipedia, Wikibooks, etc)</li>
 <p><li> DocOnce <a href="https://hplgit.github.com/teamods/writing_reports/_static/report.do.txt.html" target="_self">source code</a> and <a href="https://hplgit.github.io/doconce/doc/src/pub/manual/html/manual.html" target="_self">manual</a></li>
</ul>
</section>


<section>
<h1 id="a-tour-of-doconce">A tour of DocOnce </h1>
</section>


<section>
<h2 id="doconce-title-authors-date-toc">DocOnce: title, authors, date, toc </h2>

<p>

<!-- code=text typeset with pygments style "emacs" -->
<div class="highlight" style="background: #f8f8f8"><pre style="font-size: 80%; line-height: 125%;"><span></span>TITLE: Some Title
AUTHOR: name1 at institution1, with more info &amp; institution2
AUTHOR: name2 email:name2@web.com at institution
DATE: today

# A table of contents is optional:
TOC: on
</pre></div>
<p>
<div class="alert alert-block alert-notice alert-text-normal">
<b>Notice</b>
<p>
Title and authors must have all information <em>on a single line</em>!
</div>
</section>


<section>
<h2 id="doconce-abstract">DocOnce: abstract </h2>

<p>

<!-- code=text typeset with pygments style "emacs" -->
<div class="highlight" style="background: #f8f8f8"><pre style="font-size: 80%; line-height: 125%;"><span></span>__Abstract.__
Here goes the abstract...
</pre></div>
<p>
Or:
<p>

<!-- code=text typeset with pygments style "emacs" -->
<div class="highlight" style="background: #f8f8f8"><pre style="font-size: 80%; line-height: 125%;"><span></span>__Summary.__
Here goes the summary...
</pre></div>
</section>


<section>
<h2 id="doconce-section-headings">DocOnce: section headings </h2>

<p>
Headings are surrounded by <code>=</code> signs:
<p>

<!-- code=text typeset with pygments style "emacs" -->
<div class="highlight" style="background: #f8f8f8"><pre style="font-size: 80%; line-height: 125%;"><span></span>======= This is an H1/chapter heading =======

===== This is an H2/section heading =====

===== This is an H3/subsection heading =====

=== This is an H4/paragraph heading ===

__This is a paragraph heading.__
</pre></div>
<p>
Result:

<h1 id="this-is-an-h1-chapter-heading">This is an H1/chapter heading </h1>

<h2 id="this-is-an-h2-section-heading">This is an H2/section heading </h2>

<h2 id="this-is-an-h3-subsection-heading">This is an H3/subsection heading </h2>

<h3 id="this-is-an-h4-paragraph-heading">This is an H4/paragraph heading </h3>

<p>
<b>This is a paragraph heading.</b>
</section>


<section>
<h2 id="doconce-markup-and-lists">DocOnce: markup and lists </h2>

<p>

<!-- code=text typeset with pygments style "emacs" -->
<div class="highlight" style="background: #f8f8f8"><pre style="font-size: 80%; line-height: 125%;"><span></span> * Bullet list items start with `*`
   and may span several lines
 * *Emphasized words* are possible
 * _Boldface words_ are also possible
 * color{red}{colored words} too
 * `inline verbatim code` is featured
   o and sublists with enumerated items starting with `o`
   o items are just indented as you would do in email
</pre></div>
<p>
This gets rendered as

<ul>
 <p><li> Bullet lists start with <code>*</code>
   and may span several lines</li>
 <p><li> <em>Emphasized words</em> are possible</li>
 <p><li> <b>Boldface words</b> are also possible</li>
 <p><li> <font color="red">colored words</font> too</li>
 <p><li> <code>inline verbatim code</code> is featured

<ol type="a"></li>

<p><li> and sublists with enumerated items starting with <code>o</code></li>

<p><li> items are just indented as you would do in email</li>
</ol>
<p>
</ul>
</section>


<section>
<h2 id="doconce-labels-references-index-items">DocOnce: labels, references, index items </h2>

<p>

<!-- code=doconce (!bc do) typeset with pygments style "emacs" -->
<div class="highlight" style="background: #f8f8f8"><pre style="font-size: 80%; line-height: 125%;"><span></span><span style="color: #008800; font-style: italic"># Insert index items in the source</span>
<span style="color: #AA22FF">idx{key word1}</span> idx{key word2}

<span style="color: #008800; font-style: italic"># Label</span>
<span style="color: #000080; font-weight: bold">===== Some section =====</span>
<span style="color: #AA22FF">label{this:section}</span>

<span style="color: #008800; font-style: italic"># Make reference</span>
As we saw in Section ref{this:section}, references, index
items and labels follow a syntax similar to LaTeX
but without backslashes.

<span style="color: #008800; font-style: italic"># Make reference to equations</span>
See \eqref{eq1}-\eqref{myeq}.

<span style="color: #008800; font-style: italic"># Make hyperlink</span>
<span style="color: #BB4444">&quot;some link text&quot;</span>: &quot;https://github.com/hplgit/doconce&quot;

<span style="color: #008800; font-style: italic"># Hyperlink with complete URL as link text</span>
URL: &quot;https://github.com/hplgit/doconce&quot;
</pre></div>
</section>


<section>
<h2 id="doconce-figures-and-movies">DocOnce: figures and movies </h2>

<p>
<div class="alert alert-block alert-notice alert-text-normal">
<b>Notice</b>
<p>
Figure with HTML and LaTeX info, and caption, <em>all on one line</em>:
</div>

<p>

<!-- code=text typeset with pygments style "emacs" -->
<div class="highlight" style="background: #f8f8f8"><pre style="font-size: 80%; line-height: 125%;"><span></span>FIGURE: [figdir/myfig, width=300 frac=1.2] My caption. label{fig1}

# This figure will be 300 pixels wide in HTML and span 1.2 times
# the linewidth in LaTeX.
</pre></div>
<p>
Movies are also supported:

<p>

<!-- code=text typeset with pygments style "emacs" -->
<div class="highlight" style="background: #f8f8f8"><pre style="font-size: 80%; line-height: 125%;"><span></span>MOVIE: [https://www.youtube.com/embed/P8VcZzgdfSc, width=420 height=315]
</pre></div>
<p>
and rendered as

<p>

<iframe width="420" height="315" src="https://www.youtube.com/embed/P8VcZzgdfSc" frameborder="0" allowfullscreen></iframe>
</section>


<section>
<h2 id="doconce-math">DocOnce: math </h2>

<p>
Inline math as in LaTeX:

<p>

<!-- code=text typeset with pygments style "emacs" -->
<div class="highlight" style="background: #f8f8f8"><pre style="font-size: 80%; line-height: 125%;"><span></span>...where $a=\int_{\Omega}fdx$ is an integral.
</pre></div>
<p>
gets rendered as ...where \( a=\int_{\Omega}fdx \) is an integral.

<p>
An equation environment is surrounded by <code>!bt</code> and <code>!et</code> tags,
the rest is plain LaTeX:

<p>

<!-- code=text typeset with pygments style "emacs" -->
<div class="highlight" style="background: #f8f8f8"><pre style="font-size: 80%; line-height: 125%;"><span></span>!bt
\begin{align}
\frac{\partial u}{\partial t} &amp;= \nabla^2 u,
label{a:eq}\\
\nabla\cdot\pmb{v} &amp; = 0
label{b:eq}
\end{align}
!et
</pre></div>
<p>
which is rendered as

<p>&nbsp;<br>
$$
\begin{align}
\frac{\partial u}{\partial t} &= \nabla^2 u,
\tag{1}\\
\nabla\cdot\pmb{v} & = 0
\tag{2}
\end{align}
$$
<p>&nbsp;<br>
</section>


<section>
<h2 id="doconce-displaying-code">DocOnce: displaying code </h2>

<p>
Code is enclosed in <code>!bc</code> and <code>!ec</code> tags:

<p>

<!-- code=text typeset with pygments style "emacs" -->
<div class="highlight" style="background: #f8f8f8"><pre style="font-size: 80%; line-height: 125%;"><span></span>!bc pycod
def solver(I, a, T, dt, theta):
    &quot;&quot;&quot;Solve u&#39;=-a*u, u(0)=I, for t in (0,T] with steps of dt.&quot;&quot;&quot;
    dt = float(dt)           # avoid integer division
    N = int(round(T/dt))     # no of time intervals
    T = N*dt                 # adjust T to fit time step dt
    u = zeros(N+1)           # array of u[n] values
    t = linspace(0, T, N+1)  # time mesh

    u[0] = I                 # assign initial condition
    for n in range(0, N):    # n=0,1,...,N-1
        u[n+1] = (1 - (1-theta)*a*dt)/(1 + theta*dt*a)*u[n]
    return u, t
!ec
</pre></div>
<p>
This gets rendered as

<p>

<!-- code=python (!bc pycod) typeset with pygments style "emacs" -->
<div class="highlight" style="background: #f8f8f8"><pre style="font-size: 80%; line-height: 125%;"><span></span><span style="color: #AA22FF; font-weight: bold">def</span> <span style="color: #00A000">solver</span>(I, a, T, dt, theta):
    <span style="color: #BB4444; font-style: italic">&quot;&quot;&quot;Solve u&#39;=-a*u, u(0)=I, for t in (0,T] with steps of dt.&quot;&quot;&quot;</span>
    dt <span style="color: #666666">=</span> <span style="color: #AA22FF">float</span>(dt)           <span style="color: #008800; font-style: italic"># avoid integer division</span>
    N <span style="color: #666666">=</span> <span style="color: #AA22FF">int</span>(<span style="color: #AA22FF">round</span>(T<span style="color: #666666">/</span>dt))     <span style="color: #008800; font-style: italic"># no of time intervals</span>
    T <span style="color: #666666">=</span> N<span style="color: #666666">*</span>dt                 <span style="color: #008800; font-style: italic"># adjust T to fit time step dt</span>
    u <span style="color: #666666">=</span> zeros(N<span style="color: #666666">+1</span>)           <span style="color: #008800; font-style: italic"># array of u[n] values</span>
    t <span style="color: #666666">=</span> linspace(<span style="color: #666666">0</span>, T, N<span style="color: #666666">+1</span>)  <span style="color: #008800; font-style: italic"># time mesh</span>

    u[<span style="color: #666666">0</span>] <span style="color: #666666">=</span> I                 <span style="color: #008800; font-style: italic"># assign initial condition</span>
    <span style="color: #AA22FF; font-weight: bold">for</span> n <span style="color: #AA22FF; font-weight: bold">in</span> <span style="color: #AA22FF">range</span>(<span style="color: #666666">0</span>, N):    <span style="color: #008800; font-style: italic"># n=0,1,...,N-1</span>
        u[n<span style="color: #666666">+1</span>] <span style="color: #666666">=</span> (<span style="color: #666666">1</span> <span style="color: #666666">-</span> (<span style="color: #666666">1-</span>theta)<span style="color: #666666">*</span>a<span style="color: #666666">*</span>dt)<span style="color: #666666">/</span>(<span style="color: #666666">1</span> <span style="color: #666666">+</span> theta<span style="color: #666666">*</span>dt<span style="color: #666666">*</span>a)<span style="color: #666666">*</span>u[n]
    <span style="color: #AA22FF; font-weight: bold">return</span> u, t
</pre></div>
<p>
<div class="alert alert-block alert-notice alert-text-normal">
<b>Language-dependent typesetting of code:</b>
<p>
The <code>!bc</code> command can be followed by a specification of the computer
language: <code>pycod</code> for Python code snippet, <code>pypro</code> for complete Python
program, <code>fcod</code> for Fortran snippet, <code>fpro</code> for Fortran program, and so
forth (<code>c</code> for C, <code>cpp</code> for C++, <code>sh</code> for Unix shells, <code>m</code> for Matlab).
</div>
</section>


<section>
<h2 id="slide:pot">DocOnce: displaying interactive demo code</h2>

<p>
With <code>!bc pyoptpro</code> or a file <code>*.pyopt</code>, the code applies the
<a href="https://pythontutor.com" target="_self">Online Python Tutor</a> for displaying
program flow and state of variables:

<p>

<iframe width="950" height="500" frameborder="0"
        src="https://pythontutor.com/iframe-embed.html#code=def+solver%28I%2C+a%2C+T%2C+dt%2C+theta%29%3A%0A++++dt+%3D+float%28dt%29%0A++++N+%3D+int%28round%28T%2Fdt%29%29%0A++++T+%3D+N%2Adt%0A++++u+%3D+%5B0.0%5D%2A%28N%2B1%29%0A++++t+%3D+%5Bi%2Adt+for+i+in+range%28N%2B1%29%5D%0A%0A++++u%5B0%5D+%3D+I%0A++++for+n+in+range%280%2C+N%29%3A%0A++++++++u%5Bn%2B1%5D+%3D+%281+-+%281-theta%29%2Aa%2Adt%29%2F%281+%2B+theta%2Adt%2Aa%29%2Au%5Bn%5D%0A++++return+u%2C+t%0A%0Au%2C+t+%3D+solver%28I%3D1%2C+a%3D1%2C+T%3D3%2C+dt%3D1.%2C+theta%3D0.5%29%0Aprint+u&py=2&curInstr=0&cumulative=false">
</iframe>
</section>


<section>
<h2 id="doconce-exercises">DocOnce: exercises </h2>

<p>
DocOnce offers a special format for <em>exercises</em>, <em>problems</em>, <em>projects</em>,
and <em>examples</em>:

<p>

<!-- code=text typeset with pygments style "emacs" -->
<div class="highlight" style="background: #f8f8f8"><pre style="font-size: 80%; line-height: 125%;"><span></span>===== Problem: Flip a Coin =====
label{demo:ex:1}

files = flip_coin.py, flip_coin.pdf
solutions = mysol.txt, mysol_flip_coin.py
keywords = random numbers; Monte Carlo simulation

!bsubex
Make a program that simulates flipping a coin $N$ times.

!bhint
Use `r = random.random()` and define head as `r &lt;= 0.5`.
!ehint
!esubex

!bsubex
Compute the probability of getting heads.

!bans
A short answer: 0.5.
!eans

!bsol
A full solution to this subexercise can go here.
!esol
!esubex

!bsubex
Make another program that computes the probability
of getting at least three heads out of 5 throws.
!esubex
</pre></div>
<p>
Solutions/answers can easily be left out of the document.
</section>


<section>
<h2 id="doconce-exercises">DocOnce: exercises </h2>

<p>
Last page gets rendered as follows:

<p>
<!-- --- begin exercise --- -->

<h2 id="_demo:ex:1">Problem 1: Flip a Coin</h2>
<!-- keywords = random numbers; Monte Carlo simulation -->

<p>
<b>a)</b>
Make a program that simulates flipping a coin \( N \) times.

<p>
<!-- --- begin hint in exercise --- -->

<p>
<b>Hint.</b>
Use <code>r = random.random()</code> and define head as <code>r &lt;= 0.5</code>.

<p>
<!-- --- end hint in exercise --- -->

<p>
<b>b)</b>
Compute the probability of getting heads.

<p>
<!-- --- begin answer of exercise --- -->
<b>Answer.</b>
A short answer: 0.5.
<!-- --- end answer of exercise --- -->

<p>
<!-- --- begin solution of exercise --- -->
<b>Solution.</b>
A full solution to this subexercise can go here.
<!-- --- end solution of exercise --- -->

<p>
<b>c)</b>
Make another program that computes the probability
of getting at least three heads out of 5 throws.

<p>
Filenames: <code>flip_coin.py</code>, <code>flip_coin.pdf</code>.
<!-- solution files: mysol.txt, mysol_flip_coin.py -->

<p>
<!-- --- end exercise --- -->
</section>


<section>
<h2 id="doconce-example-on-slide-code">DocOnce: example on slide code </h2>

<p>

<!-- code=text typeset with pygments style "emacs" -->
<div class="highlight" style="background: #f8f8f8"><pre style="font-size: 80%; line-height: 125%;"><span></span>!split
===== Headline =====

 * Key point 1
 * Key point 2
 * Key point 3 takes very much more text to explain because
   this point is really comprehensive, and although long
   bullet points are not recommended in general, we need
   it here for demonstration purposes

FIGURE: [../doc/src/slides/fig/teacher1, width=100]

Key equation:

!bt
\[ -\nabla^2 u = f \quad\hbox{in }\Omega \]
!et

And maybe a final comment?

!split
===== Next slide... =====
</pre></div>
</section>


<section>
<h2 id="doconce-example-on-slide-code">DocOnce: example on slide code </h2>

<p>
Last page gets rendered to

<h2 id="headline">Headline </h2>

<ul>
 <p><li> Key point 1</li>
 <p><li> Key point 2</li>
</ul>
<p>

<br /><br /><center><p><img src="../doc/src/slides/fig/teacher1.gif" align="bottom" width=100></p></center><br /><br />

<p>
Key equation:

<p>&nbsp;<br>
$$ -\nabla^2 u = f \quad\hbox{in }\Omega $$
<p>&nbsp;<br>

<p>
And maybe a final comment?
</section>


<section>
<h2 id="doconce-example-on-slide-code-with-cells">DocOnce: example on slide code with cells </h2>

<p>
One can introduce a table-like layout with MxN cells and
put slide elements in various cell. A cell with position
MN is surrounded by <code>!bslidecell MN</code> and <code>!eslidecell</code>
tags. Below is an example with a bullet list to the left and
a figure to the right (two cells, numbered 00 and 01).

<p>

<!-- code=text typeset with pygments style "emacs" -->
<div class="highlight" style="background: #f8f8f8"><pre style="font-size: 80%; line-height: 125%;"><span></span>!split
===== Headline =====

!bslidecell 00
!bpop
 * Key point 1
 * Key point 2
 * Key point 3 takes very much more text to explain because
   this point is really comprehensive, and although long
   bullet points are not recommended in general, we need
   it here for demonstration purposes
!epop

!bpop
!bt
\[ -\nabla^2 u = f \quad\hbox{in }\Omega \]
!et
!epop

!eslidecell

!bslidecell 01
FIGURE: [../doc/src/slides/fig/broken_pen_and_paper, width=400, frac=0.8]
!eslidecell

!split
===== Next slide... =====
</pre></div>
</section>


<section>
<h2 id="doconce-example-on-slide-code">DocOnce: example on slide code </h2>

<p>
Last page gets rendered to

<h2 id="headline">Headline </h2>

<p>

<table border="0">
<tr>
<td class="padding">


<ul>
 <p><li class="fragment"> Key point 1</li>
 <p><li class="fragment"> Key point 2</li>
 <p><li class="fragment"> Key point 3 takes very much more text to explain because
   this point is really comprehensive, and although long
   bullet points are not recommended in general, we need
   it here for demonstration purposes</li>
</ul>
<p>

<p class="fragment">

&nbsp;<br>&nbsp;<br>
$$ -\nabla^2 u = f \quad\hbox{in }\Omega $$
&nbsp;<br>&nbsp;<br>


</p>

<p>
</td>
<td class="padding">
<br /><br /><center><p><img src="../doc/src/slides/fig/broken_pen_and_paper.jpg" align="bottom" width=400></p></center><br /><br />
</td>
</tr>
</table>
</section>



</div> <!-- class="slides" -->
</div> <!-- class="reveal" -->

<script src="reveal.js/lib/js/head.min.js"></script>
<script src="reveal.js/js/reveal.js"></script>

<script>
// Full list of configuration options available here:
// https://github.com/hakimel/reveal.js#configuration
Reveal.initialize({

    // Display navigation controls in the bottom right corner
    controls: true,

    // Display progress bar (below the horiz. slider)
    progress: true,

    // Display the page number of the current slide
    slideNumber: true,

    // Push each slide change to the browser history
    history: false,

    // Enable keyboard shortcuts for navigation
    keyboard: true,

    // Enable the slide overview mode
    overview: true,

    // Vertical centering of slides
    //center: true,
    center: false,

    // Enables touch navigation on devices with touch input
    touch: true,

    // Loop the presentation
    loop: false,

    // Change the presentation direction to be RTL
    rtl: false,

    // Turns fragments on and off globally
    fragments: true,

    // Flags if the presentation is running in an embedded mode,
    // i.e. contained within a limited portion of the screen
    embedded: false,

    // Number of milliseconds between automatically proceeding to the
    // next slide, disabled when set to 0, this value can be overwritten
    // by using a data-autoslide attribute on your slides
    autoSlide: 0,

    // Stop auto-sliding after user input
    autoSlideStoppable: true,

    // Enable slide navigation via mouse wheel
    mouseWheel: false,

    // Hides the address bar on mobile devices
    hideAddressBar: true,

    // Opens links in an iframe preview overlay
    previewLinks: false,

    // Transition style
    transition: 'default', // default/cube/page/concave/zoom/linear/fade/none

    // Transition speed
    transitionSpeed: 'default', // default/fast/slow

    // Transition style for full page slide backgrounds
    backgroundTransition: 'default', // default/none/slide/concave/convex/zoom

    // Number of slides away from the current that are visible
    viewDistance: 3,

    // Parallax background image
    //parallaxBackgroundImage: '', // e.g. "'https://s3.amazonaws.com/hakim-static/reveal-js/reveal-parallax-1.jpg'"

    // Parallax background size
    //parallaxBackgroundSize: '' // CSS syntax, e.g. "2100px 900px"

    theme: Reveal.getQueryHash().theme, // available themes are in reveal.js/css/theme
    transition: Reveal.getQueryHash().transition || 'default', // default/cube/page/concave/zoom/linear/none

});

Reveal.initialize({
    dependencies: [
        // Cross-browser shim that fully implements classList - https://github.com/eligrey/classList.js/
        { src: 'reveal.js/lib/js/classList.js', condition: function() { return !document.body.classList; } },

        // Interpret Markdown in <section> elements
        { src: 'reveal.js/plugin/markdown/marked.js', condition: function() { return !!document.querySelector( '[data-markdown]' ); } },
        { src: 'reveal.js/plugin/markdown/markdown.js', condition: function() { return !!document.querySelector( '[data-markdown]' ); } },

        // Syntax highlight for <code> elements
        { src: 'reveal.js/plugin/highlight/highlight.js', async: true, callback: function() { hljs.initHighlightingOnLoad(); } },

        // Zoom in and out with Alt+click
        { src: 'reveal.js/plugin/zoom-js/zoom.js', async: true, condition: function() { return !!document.body.classList; } },

        // Speaker notes
        { src: 'reveal.js/plugin/notes/notes.js', async: true, condition: function() { return !!document.body.classList; } },

        // Remote control your reveal.js presentation using a touch device
        //{ src: 'reveal.js/plugin/remotes/remotes.js', async: true, condition: function() { return !!document.body.classList; } },

        // MathJax
        //{ src: 'reveal.js/plugin/math/math.js', async: true }
    ]
});

Reveal.initialize({

    // The "normal" size of the presentation, aspect ratio will be preserved
    // when the presentation is scaled to fit different resolutions. Can be
    // specified using percentage units.
    width: 1170,  // original: 960,
    height: 700,

    // Factor of the display size that should remain empty around the content
    margin: 0.1,

    // Bounds for smallest/largest possible scale to apply to content
    minScale: 0.2,
    maxScale: 1.0

});
</script>

<!-- begin footer logo
<div style="position: absolute; bottom: 0px; left: 0; margin-left: 0px">
<img src="somelogo.png">
</div>
     end footer logo -->



</body>
</html>

************** File: slides2.p.tex *****************
%%
%% Automatically generated file from DocOnce source
%% (https://github.com/hplgit/doconce/)
%%
%%
% #ifdef PTEX2TEX_EXPLANATION
%%
%% The file follows the ptex2tex extended LaTeX format, see
%% ptex2tex: https://code.google.com/p/ptex2tex/
%%
%% Run
%%      ptex2tex myfile
%% or
%%      doconce ptex2tex myfile
%%
%% to turn myfile.p.tex into an ordinary LaTeX file myfile.tex.
%% (The ptex2tex program: https://code.google.com/p/ptex2tex)
%% Many preprocess options can be added to ptex2tex or doconce ptex2tex
%%
%%      ptex2tex -DMINTED myfile
%%      doconce ptex2tex myfile envir=minted
%%
%% ptex2tex will typeset code environments according to a global or local
%% .ptex2tex.cfg configure file. doconce ptex2tex will typeset code
%% according to options on the command line (just type doconce ptex2tex to
%% see examples). If doconce ptex2tex has envir=minted, it enables the
%% minted style without needing -DMINTED.
% #endif

% #define PREAMBLE

% #ifdef PREAMBLE
%-------------------- begin preamble ----------------------

\documentclass[%
oneside,                 % oneside: electronic viewing, twoside: printing
final,                   % draft: marks overfull hboxes, figures with paths
10pt]{article}

\listfiles               %  print all files needed to compile this document

\usepackage{relsize,makeidx,color,setspace,amsmath,amsfonts,amssymb}
\usepackage[table]{xcolor}
\usepackage{bm,ltablex,microtype}

\usepackage[pdftex]{graphicx}

% Movies are handled by the href package
\newenvironment{doconce:movie}{}{}
\newcounter{doconce:movie:counter}


\usepackage{ptex2tex}
% #ifdef MINTED
\usepackage{minted}
\usemintedstyle{default}
% #endif
\usepackage{fancyvrb}

\usepackage[T1]{fontenc}
%\usepackage[latin1]{inputenc}
\usepackage{ucs}
\usepackage[utf8x]{inputenc}

\usepackage{lmodern}         % Latin Modern fonts derived from Computer Modern

% Hyperlinks in PDF:
\definecolor{linkcolor}{rgb}{0,0,0.4}
\usepackage{hyperref}
\hypersetup{
    breaklinks=true,
    colorlinks=true,
    linkcolor=linkcolor,
    urlcolor=linkcolor,
    citecolor=black,
    filecolor=black,
    %filecolor=blue,
    pdfmenubar=true,
    pdftoolbar=true,
    bookmarksdepth=3   % Uncomment (and tweak) for PDF bookmarks with more levels than the TOC
    }
%\hyperbaseurl{}   % hyperlinks are relative to this root

\setcounter{tocdepth}{2}  % levels in table of contents

% Tricks for having figures close to where they are defined:
% 1. define less restrictive rules for where to put figures
\setcounter{topnumber}{2}
\setcounter{bottomnumber}{2}
\setcounter{totalnumber}{4}
\renewcommand{\topfraction}{0.95}
\renewcommand{\bottomfraction}{0.95}
\renewcommand{\textfraction}{0}
\renewcommand{\floatpagefraction}{0.75}
% floatpagefraction must always be less than topfraction!
% 2. ensure all figures are flushed before next section
\usepackage[section]{placeins}
% 3. enable begin{figure}[H] (often leads to ugly pagebreaks)
%\usepackage{float}\restylefloat{figure}

\usepackage[framemethod=TikZ]{mdframed}

% --- begin definitions of admonition environments ---

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "notice" admon
\colorlet{mdfbox_notice_background}{gray!5}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_notice_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=mdfbox_notice_background,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{notice_mdfboxmdframed}

\newenvironment{notice_mdfboxadmon}[1][]{
\begin{notice_mdfboxmdframed}[frametitle=#1]
}
{
\end{notice_mdfboxmdframed}
}

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "summary" admon
\colorlet{mdfbox_summary_background}{gray!5}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_summary_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=mdfbox_summary_background,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{summary_mdfboxmdframed}

\newenvironment{summary_mdfboxadmon}[1][]{
\begin{summary_mdfboxmdframed}[frametitle=#1]
}
{
\end{summary_mdfboxmdframed}
}

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "warning" admon
\colorlet{mdfbox_warning_background}{gray!5}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_warning_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=mdfbox_warning_background,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{warning_mdfboxmdframed}

\newenvironment{warning_mdfboxadmon}[1][]{
\begin{warning_mdfboxmdframed}[frametitle=#1]
}
{
\end{warning_mdfboxmdframed}
}

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "question" admon
\colorlet{mdfbox_question_background}{gray!5}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_question_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=mdfbox_question_background,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{question_mdfboxmdframed}

\newenvironment{question_mdfboxadmon}[1][]{
\begin{question_mdfboxmdframed}[frametitle=#1]
}
{
\end{question_mdfboxmdframed}
}

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "block" admon
\colorlet{mdfbox_block_background}{gray!5}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_block_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=mdfbox_block_background,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{block_mdfboxmdframed}

\newenvironment{block_mdfboxadmon}[1][]{
\begin{block_mdfboxmdframed}[frametitle=#1]
}
{
\end{block_mdfboxmdframed}
}

% --- end of definitions of admonition environments ---

% prevent orhpans and widows
\clubpenalty = 10000
\widowpenalty = 10000

\newenvironment{doconceexercise}{}{}
\newcounter{doconceexercisecounter}


% ------ header in subexercises ------
%\newcommand{\subex}[1]{\paragraph{#1}}
%\newcommand{\subex}[1]{\par\vspace{1.7mm}\noindent{\bf #1}\ \ }
\makeatletter
% 1.5ex is the spacing above the header, 0.5em the spacing after subex title
\newcommand\subex{\@startsection{paragraph}{4}{\z@}%
                  {1.5ex\@plus1ex \@minus.2ex}%
                  {-0.5em}%
                  {\normalfont\normalsize\bfseries}}
\makeatother


% --- end of standard preamble for documents ---


% insert custom LaTeX commands...

\raggedbottom
\makeindex

%-------------------- end preamble ----------------------

\begin{document}

% matching end for #ifdef PREAMBLE
% #endif

\newcommand{\exercisesection}[1]{\subsection*{#1}}

\input{newcommands_bfmath}
\input{newcommands_replace}

% ------------------- main content ----------------------



% ----------------- title -------------------------

\title{Test slide features}

% ----------------- author(s) -------------------------

\author{Core Dump\inst{1}}
\institute{Cyber Space Ltd\inst{1}}
% ----------------- end author(s) -------------------------

\date{Jan 32, 2100
% <optional titlepage figure>
% <optional copyright>
}

\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=0.5\linewidth]{../doc/src/slides/fig/doconce1b.png}}

\vspace{6mm}



% !split





% !split
\subsection{Scientific writing for the future needs to address many new media}

% !bslidecell 00 0.4


\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=0.8\linewidth]{../doc/src/slides/fig/ipad.png}}

\vspace{6mm}





\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=0.3\linewidth]{../doc/src/slides/fig/iphones.jpg}}

\vspace{6mm}



% FIGURE: [../doc/src/slides/fig/mbair, width=400]

% !eslidecell

% !bslidecell 01 0.6


\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=0.7\linewidth]{../doc/src/slides/fig/imac.png}}

\vspace{6mm}


% !eslidecell

% !split
\subsection{The book will probably survive}



\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=0.9\linewidth]{../doc/src/slides/fig/oldbooks.jpg}}

\vspace{6mm}



% !split
\subsection{The classical report will survive}

% !bslidecell 00


\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=1.2\linewidth]{../doc/src/slides/fig/latex_thesis.jpg}}

\vspace{6mm}


% !eslidecell

% !bslidecell 01


\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=1.2\linewidth]{../doc/src/slides/fig/latex_paper1.png}}

\vspace{6mm}


% !eslidecell

% !split
\subsection{Scope}

% * Scientific writing = lecture notes, slides, reports, thesis, books,  ...
% * (Journal papers typeset by journals are out of scope)

% !bpop
\begin{itemize}
  \item Scope: documents with \textcolor{red}{much} \emph{math} and \emph{computer code}

  \item Key question: What tools should I use for writing?

  \item Default answer: {\LaTeX}

  \item Alternative: MS Word w/math

  \item Recent popular alternative tools: HTML w/MathJax,
    Sphinx, Markdown, MediaWiki, IPython notebook
\end{itemize}

\noindent
% !epop

% !bslidecell 00 0.25


\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=0.3\linewidth]{../doc/src/slides/fig/LaTeX_logo.jpg}}

\vspace{6mm}


% !eslidecell

% !bslidecell 01 0.25


\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=0.2\linewidth]{../doc/src/slides/fig/MS_Word_logo.jpg}}

\vspace{6mm}


% !eslidecell

% !bslidecell 02 0.5


\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=0.4\linewidth]{../doc/src/slides/fig/sphinx_logo.png}}

\vspace{6mm}


% !eslidecell

% !bslidecell 10 0.25


\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=0.2\linewidth]{../doc/src/slides/fig/markdown_logo.jpg}}

\vspace{6mm}


% !eslidecell

% !bslidecell 11 0.25


\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=0.2\linewidth]{../doc/src/slides/fig/MediaWiki_logo.jpg}}

\vspace{6mm}


% !eslidecell

% !bslidecell 12 0.5


\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=0.6\linewidth]{../doc/src/slides/fig/IPython_logo.png}}

\vspace{6mm}


% !eslidecell


% !split
\subsection{Scientific writing for the future needs to address many new media}

% Insert links here to reports

% !bslidecell 00
Old days (1985-2005): {\LaTeX} for BW paper output, but now

\begin{enumerate}
  \item BW books

  \item Colorful PDF books (printed and screen)

  \item Designed web pages

  \item Wikis

  \item Blog posts

  \item Next new fancy format (iBook w/LaTeX?)
\end{enumerate}

\noindent
% !eslidecell

% !bslidecell 01


\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=0.9\linewidth]{../doc/src/slides/fig/jungle_with_mess.jpg}}

\vspace{6mm}


% !eslidecell

% !split

\subsection{Fundamental question}

When I write some scientific material,

\begin{itemize}
 \item a {\LaTeX} document,

 \item a blog post (HTML),

 \item some web pages (HTML),

 \item a Sphinx document,

 \item some Markdown files,
\end{itemize}

\noindent
and later want to collect the pieces into a larger document, maybe
some book, or one big web document, is that at all feasible?

% !bpop highlight-red
Probably not, but I have a solution :-)
% !epop

% !split

\subsection{{\LaTeX} is very rich; other tools support only some elements}

\begin{itemize}
 \item {\LaTeX} inline math: works with all ({\LaTeX}, MathJax, Sphinx, Markdown, MediaWiki)

 \item {\LaTeX} equation math:
\begin{itemize}

    \item \textbf{LaTeX}: \texttt{equation*}, \texttt{equation}, \texttt{align*}, \texttt{align} +
      \texttt{eqnarray}, \texttt{split}, \texttt{alignat}, ... (numerous!)

    \item \textbf{MathJax}: \texttt{equation*}, \texttt{equation}, \texttt{align*}, \texttt{align}

    \item \textbf{MediaWiki}: \texttt{equation*}, \texttt{equation}, \texttt{align*}, \texttt{align}

    \item \textbf{Sphinx}: \texttt{equation*}, \texttt{equation}, \texttt{align*}

    \item \textbf{Markdown}: \texttt{equation*}, \texttt{equation}, \texttt{eqnarray*}, \texttt{align*} (but no labels)
\end{itemize}

\noindent
\end{itemize}

\noindent
% !split
\subsection{{\LaTeX} is very rich; other tools support only some elements}

% !bpop
\begin{itemize}
 \item Figures: all

 \item Subfigures: {\LaTeX} (\texttt{subfigure})

 \item Movies: {\LaTeX} (can run separately), just raw embedded HTML in others

 \item Floating computer code: {\LaTeX}

 \item Fixed computer code: all

 \item Floating tables: {\LaTeX}; inline tables: all

 \item Algorithms: {\LaTeX}

 \item Margin notes: {\LaTeX}

 \item Page references: {\LaTeX}

 \item Footnotes: {\LaTeX}, Sphinx, reStructuredText, MediaWiki

 \item Bibliography: {\LaTeX}, Sphinx, reStructuredText, MediaWiki

 \item Hyperlinks: all (but not on paper!)
\end{itemize}

\noindent
% !epop

% !bpop
Conclusion: Highly non-trivial to translate a {\LaTeX} document into something
based on HTML and vice versa.
% !epop


% !split
\subsection{DocOnce demo}

\href{{https://hplgit.github.com/teamods/writing_reports/}}{\nolinkurl{https://hplgit.github.com/teamods/writing_reports/}}

\begin{itemize}
 \item LaTeX-based PDF \href{{https://hplgit.github.com/teamods/writing_reports/_static/report.pdf}}{for screen}, \href{{https://hplgit.github.com/teamods/writing_reports/_static/report_4printing.pdf}}{for printing}, \href{{https://hplgit.github.com/teamods/writing_reports/_static/report_4phone.pdf}}{for phone}

 \item \href{{https://hplgit.github.com/teamods/writing_reports/_static/report_do.html}}{Plain HTML} or with a \href{{https://hplgit.github.com/teamods/writing_reports/_static/report_vagrant.html}}{template} or \href{{https://hplgit.github.com/teamods/writing_reports/_static/report_github_minimal.html}}{another template} or \href{{https://hplgit.github.com/teamods/writing_reports/_static/report_solarized.html}}{solarized}

 \item Sphinx: \href{{https://hplgit.github.com/teamods/writing_reports/_static/sphinx-agni/index.html}}{agni}, \href{{https://hplgit.github.com/teamods/writing_reports/_static/sphinx-pyramid/report.html}}{pyramid}, \href{{https://hplgit.github.com/teamods/writing_reports/_static/sphinx-classy/report.html}}{classy}, \href{{https://hplgit.github.com/teamods/writing_reports/_static/sphinx-fenics_minimal/report.html}}{fenics}, \href{{https://hplgit.github.com/teamods/writing_reports/_static/sphinx-fenics_minimal/report.html}}{redcloud}

 \item HTML for \href{{https://doconce-report-demo.blogspot.no/}}{Google} or \href{{https://doconcereportdemo.wordpress.com/}}{Wordpress} blog posts

 \item \href{{https://doconcedemo.shoutwiki.com/wiki/DocOnce_demo_page}}{MediaWiki} (Wikipedia, Wikibooks, etc)

 \item DocOnce \href{{https://hplgit.github.com/teamods/writing_reports/_static/report.do.txt.html}}{source code} and \href{{https://hplgit.github.io/doconce/doc/src/pub/manual/html/manual.html}}{manual}
\end{itemize}

\noindent
% !split

% latex interprets 9 = as chapter and then needs book style...
\subsection{A tour of DocOnce}

% !split
\subsection{DocOnce: title, authors, date, toc}

\bccq
TITLE: Some Title
AUTHOR: name1 at institution1, with more info & institution2
AUTHOR: name2 email:name2@web.com at institution
DATE: today

# A table of contents is optional:
TOC: on
\eccq

\begin{block}{Notice}
Title and authors must have all information \emph{on a single line}!
\end{block}

% !split
\subsection{DocOnce: abstract}

\bccq
__Abstract.__
Here goes the abstract...
\eccq

Or:
\bccq
__Summary.__
Here goes the summary...
\eccq


% !split
\subsection{DocOnce: section headings}

Headings are surrounded by \texttt{=} signs:
\bccq
======= This is an H1/chapter heading =======

===== This is an H2/section heading =====

===== This is an H3/subsection heading =====

=== This is an H4/paragraph heading ===

__This is a paragraph heading.__
\eccq


% !split
\subsection{DocOnce: markup and lists}

\bccq
 * Bullet list items start with `*`
   and may span several lines
 * *Emphasized words* are possible
 * _Boldface words_ are also possible
 * color{red}{colored words} too
 * `inline verbatim code` is featured
   o and sublists with enumerated items starting with `o`
   o items are just indented as you would do in email
\eccq

This gets rendered as

\begin{itemize}
 \item Bullet lists start with \texttt{*}
   and may span several lines

 \item \emph{Emphasized words} are possible

 \item \textbf{Boldface words} are also possible

 \item \textcolor{red}{colored words} too

 \item \texttt{inline verbatim code} is featured
\begin{enumerate}

  \item and sublists with enumerated items starting with \texttt{o}

  \item items are just indented as you would do in email
\end{enumerate}

\noindent
\end{itemize}

\noindent
% !split
\subsection{DocOnce: labels, references, index items}

\bdo
# Insert index items in the source
idx{key word1} idx{key word2}

# Label
===== Some section =====
label{this:section}

# Make reference
As we saw in Section ref{this:section}, references, index
items and labels follow a syntax similar to LaTeX
but without backslashes.

# Make reference to equations
See (ref{eq1})-(ref{myeq}).

# Make hyperlink
"some link text": "https://github.com/hplgit/doconce"

# Hyperlink with complete URL as link text
URL: "https://github.com/hplgit/doconce"
\edo

% !split
\subsection{DocOnce: figures and movies}

\begin{block}{Notice}
Figure with HTML and {\LaTeX} info, and caption, \emph{all on one line}:
\end{block}

\bccq
FIGURE: [figdir/myfig, width=300 frac=1.2] My caption. label{fig1}

# This figure will be 300 pixels wide in HTML and span 1.2 times
# the linewidth in LaTeX.
\eccq

Movies are also supported:

\bccq
MOVIE: [https://www.youtube.com/embed/P8VcZzgdfSc, width=420 height=315]
\eccq
and rendered as


\begin{doconce:movie}
\refstepcounter{doconce:movie:counter}
\begin{center}
\href{{https://www.youtube.com/embed/P8VcZzgdfSc}}{\nolinkurl{https://www.youtube.com/embed/P8VcZzgdfSc}}
\end{center}
\end{doconce:movie}


% !split
\subsection{DocOnce: math}

Inline math as in {\LaTeX}:

\bccq
...where $a=\int_{\Omega}fdx$ is an integral.
\eccq
gets rendered as ...where $a=\int_{\Omega}fdx$ is an integral.


An equation environment is surrounded by \Verb?!bt? and \Verb?!et? tags,
the rest is plain {\LaTeX}:

\bccq
!bt
\begin{align}
\frac{\partial u}{\partial t} &= \nabla^2 u,
label{a:eq}\\
\nabla\cdot\pmb{v} & = 0
label{b:eq}
\end{align}
!et
\eccq
which is rendered as

\begin{align}
\frac{\partial u}{\partial t} &= \nabla^2 u,
\label{_a:eq}\\
\nabla\cdot\pmb{v} & = 0
\label{_b:eq}
\end{align}


% !split
\subsection{DocOnce: displaying code}

Code is enclosed in \Verb?!bc? and \Verb?!ec? tags:

\bccq
!bc pycod
def solver(I, a, T, dt, theta):
    """Solve u'=-a*u, u(0)=I, for t in (0,T] with steps of dt."""
    dt = float(dt)           # avoid integer division
    N = int(round(T/dt))     # no of time intervals
    T = N*dt                 # adjust T to fit time step dt
    u = zeros(N+1)           # array of u[n] values
    t = linspace(0, T, N+1)  # time mesh

    u[0] = I                 # assign initial condition
    for n in range(0, N):    # n=0,1,...,N-1
        u[n+1] = (1 - (1-theta)*a*dt)/(1 + theta*dt*a)*u[n]
    return u, t
!ec
\eccq
This gets rendered as

\bpycod
def solver(I, a, T, dt, theta):
    """Solve u'=-a*u, u(0)=I, for t in (0,T] with steps of dt."""
    dt = float(dt)           # avoid integer division
    N = int(round(T/dt))     # no of time intervals
    T = N*dt                 # adjust T to fit time step dt
    u = zeros(N+1)           # array of u[n] values
    t = linspace(0, T, N+1)  # time mesh

    u[0] = I                 # assign initial condition
    for n in range(0, N):    # n=0,1,...,N-1
        u[n+1] = (1 - (1-theta)*a*dt)/(1 + theta*dt*a)*u[n]
    return u, t
\epycod

\begin{block}{Language-dependent typesetting of code: }
The \Verb?!bc? command can be followed by a specification of the computer
language: \texttt{pycod} for Python code snippet, \texttt{pypro} for complete Python
program, \texttt{fcod} for Fortran snippet, \texttt{fpro} for Fortran program, and so
forth (\texttt{c} for C, \texttt{cpp} for C++, \texttt{sh} for Unix shells, \texttt{m} for Matlab).
\end{block}


% !split
\subsection{DocOnce: displaying interactive demo code}
\label{slide:pot}

With \Verb?!bc pyoptpro? or a file \texttt{*.pyopt}, the code applies the
\href{{https://pythontutor.com}}{Online Python Tutor} for displaying
program flow and state of variables:

\bpypro
def solver(I, a, T, dt, theta):
    dt = float(dt)
    N = int(round(T/dt))
    T = N*dt
    u = [0.0]*(N+1)
    t = [i*dt for i in range(N+1)]

    u[0] = I
    for n in range(0, N):
        u[n+1] = (1 - (1-theta)*a*dt)/(1 + theta*dt*a)*u[n]
    return u, t

u, t = solver(I=1, a=1, T=3, dt=1., theta=0.5)
print u
\epypro
\noindent
(\href{{https://pythontutor.com/visualize.html\#code=def+solver\%28I\%2C+a\%2C+T\%2C+dt\%2C+theta\%29\%3A\%0A++++dt+\%3D+float\%28dt\%29\%0A++++N+\%3D+int\%28round\%28T\%2Fdt\%29\%29\%0A++++T+\%3D+N\%2Adt\%0A++++u+\%3D+\%5B0.0\%5D\%2A\%28N\%2B1\%29\%0A++++t+\%3D+\%5Bi\%2Adt+for+i+in+range\%28N\%2B1\%29\%5D\%0A\%0A++++u\%5B0\%5D+\%3D+I\%0A++++for+n+in+range\%280\%2C+N\%29\%3A\%0A++++++++u\%5Bn\%2B1\%5D+\%3D+\%281+-+\%281-theta\%29\%2Aa\%2Adt\%29\%2F\%281+\%2B+theta\%2Adt\%2Aa\%29\%2Au\%5Bn\%5D\%0A++++return+u\%2C+t\%0A\%0Au\%2C+t+\%3D+solver\%28I\%3D1\%2C+a\%3D1\%2C+T\%3D3\%2C+dt\%3D1.\%2C+theta\%3D0.5\%29\%0Aprint+u&mode=display&cumulative=false&heapPrimitives=false&drawParentPointers=false&textReferences=false&py=2&curInstr=0}}{Visualize execution}) 





% !split
\subsection{DocOnce: exercises}

DocOnce offers a special format for \emph{exercises}, \emph{problems}, \emph{projects},
and \emph{examples}:

\bccq
===== Problem: Flip a Coin =====
label{demo:ex:1}

files = flip_coin.py, flip_coin.pdf
solutions = mysol.txt, mysol_flip_coin.py
keywords = random numbers; Monte Carlo simulation

!bsubex
Make a program that simulates flipping a coin $N$ times.

!bhint
Use `r = random.random()` and define head as `r <= 0.5`.
!ehint
!esubex

!bsubex
Compute the probability of getting heads.

!bans
A short answer: 0.5.
!eans

!bsol
A full solution to this subexercise can go here.
!esol
!esubex

!bsubex
Make another program that computes the probability
of getting at least three heads out of 5 throws.
!esubex
\eccq

Solutions/answers can easily be left out of the document.


% !split
\subsection{DocOnce: example on slide code}

\bccq
!split
===== Headline =====

 * Key point 1
 * Key point 2
 * Key point 3 takes very much more text to explain because
   this point is really comprehensive, and although long
   bullet points are not recommended in general, we need
   it here for demonstration purposes

FIGURE: [../doc/src/slides/fig/teacher1, width=100]

Key equation:

!bt
\[ -\nabla^2 u = f \quad\hbox{in }\Omega \]
!et

And maybe a final comment?

!split
===== Next slide... =====
\eccq


% !split
\subsection{DocOnce: example on slide code with cells}

One can introduce a table-like layout with MxN cells and
put slide elements in various cell. A cell with position
MN is surrounded by \Verb?!bslidecell MN? and \Verb?!eslidecell?
tags. Below is an example with a bullet list to the left and
a figure to the right (two cells, numbered 00 and 01).

\bccq
!split
===== Headline =====

!bslidecell 00
!bpop
 * Key point 1
 * Key point 2
 * Key point 3 takes very much more text to explain because
   this point is really comprehensive, and although long
   bullet points are not recommended in general, we need
   it here for demonstration purposes
!epop

!bpop
!bt
\[ -\nabla^2 u = f \quad\hbox{in }\Omega \]
!et
!epop

!eslidecell

!bslidecell 01
FIGURE: [../doc/src/slides/fig/broken_pen_and_paper, width=400, frac=0.8]
!eslidecell

!split
===== Next slide... =====
\eccq


% ------------------- end of main content ---------------

% #ifdef PREAMBLE
\cleardoublepage\phantomsection  % trick to get correct link to Index
\printindex

\end{document}
% #endif


************** File: slides2.tex *****************

% LaTeX Beamer file automatically generated from DocOnce
% https://github.com/hplgit/doconce

%-------------------- begin beamer-specific preamble ----------------------

\documentclass{beamer}

\usetheme{default}
\usecolortheme{default}

% turn off the almost invisible, yet disturbing, navigation symbols:
\setbeamertemplate{navigation symbols}{}

% Examples on customization:
%\usecolortheme[named=RawSienna]{structure}
%\usetheme[height=7mm]{Rochester}
%\setbeamerfont{frametitle}{family=\rmfamily,shape=\itshape}
%\setbeamertemplate{items}[ball]
%\setbeamertemplate{blocks}[rounded][shadow=true]
%\useoutertheme{infolines}
%
%\usefonttheme{}
%\useinntertheme{}
%
%\setbeameroption{show notes}
%\setbeameroption{show notes on second screen=right}

% fine for B/W printing:
%\usecolortheme{seahorse}

\usepackage{pgf}
\usepackage{graphicx}
\usepackage{epsfig}
\usepackage{relsize}

\usepackage{fancybox}  % make sure fancybox is loaded before fancyvrb

\usepackage{fancyvrb}
\usepackage{minted} % requires pygments and latex -shell-escape filename
%\usepackage{anslistings}
%\usepackage{listingsutf8}

\usepackage{amsmath,amssymb,bm}
%\usepackage[latin1]{inputenc}
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage{colortbl}
\usepackage[english]{babel}
\usepackage{tikz}
\usepackage{framed}
% Use some nice templates
\beamertemplatetransparentcovereddynamic

% --- begin table of contents based on sections ---
% Delete this, if you do not want the table of contents to pop up at
% the beginning of each section:
% (Only section headings can enter the table of contents in Beamer
% slides generated from DocOnce source, while subsections are used
% for the title in ordinary slides.)
\AtBeginSection[]
{
  \begin{frame}<beamer>[plain]
  \frametitle{}
  %\frametitle{Outline}
  \tableofcontents[currentsection]
  \end{frame}
}
% --- end table of contents based on sections ---

% If you wish to uncover everything in a step-wise fashion, uncomment
% the following command:

%\beamerdefaultoverlayspecification{<+->}

\newcommand{\shortinlinecomment}[3]{\note{\textbf{#1}: #2}}
\newcommand{\longinlinecomment}[3]{\shortinlinecomment{#1}{#2}{#3}}

\definecolor{linkcolor}{rgb}{0,0,0.4}
\hypersetup{
    colorlinks=true,
    linkcolor=linkcolor,
    urlcolor=linkcolor,
    pdfmenubar=true,
    pdftoolbar=true,
    bookmarksdepth=3
    }
\setlength{\parskip}{7pt}  % {1em}

\newenvironment{doconceexercise}{}{}
\newcounter{doconceexercisecounter}
\newenvironment{doconce:movie}{}{}
\newcounter{doconce:movie:counter}

\newcommand{\subex}[1]{\noindent\textbf{#1}}  % for subexercises: a), b), etc

%-------------------- end beamer-specific preamble ----------------------

% Add user's preamble




% insert custom LaTeX commands...

\raggedbottom
\makeindex

%-------------------- end preamble ----------------------

\begin{document}

% matching end for #ifdef PREAMBLE

\newcommand{\exercisesection}[1]{\subsection*{#1}}

\input{newcommands_bfmath}
\input{newcommands_replace}


% ------------------- main content ----------------------



% ----------------- title -------------------------

\title{Test slide features}

% ----------------- author(s) -------------------------

\author{Core Dump\inst{1}}
\institute{Cyber Space Ltd\inst{1}}
% ----------------- end author(s) -------------------------

\date{Jan 32, 2100
\\ \ \\ 
\centerline{\includegraphics[width=0.5\linewidth]{../doc/src/slides/fig/doconce1b.png}}
% <optional copyright>
}

\vspace{6mm}



\vspace{6mm}

\begin{frame}[plain,fragile]
\titlepage
\end{frame}

\begin{frame}[plain,fragile]
\frametitle{Scientific writing for the future needs to address many new media}

\begin{columns}
\column{0.4\textwidth}
\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=0.8\linewidth]{../doc/src/slides/fig/ipad.png}}

\vspace{6mm}





\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=0.3\linewidth]{../doc/src/slides/fig/iphones.jpg}}

\vspace{6mm}



% FIGURE: [../doc/src/slides/fig/mbair, width=400]


\column{0.6\textwidth}
\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=0.7\linewidth]{../doc/src/slides/fig/imac.png}}

\vspace{6mm}



\end{columns}
\end{frame}

\begin{frame}[plain,fragile]
\frametitle{The book will probably survive}

\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=0.9\linewidth]{../doc/src/slides/fig/oldbooks.jpg}}

\vspace{6mm}
\end{frame}

\begin{frame}[plain,fragile]
\frametitle{The classical report will survive}

\begin{columns}
\column{0.5\textwidth}
\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=1.2\linewidth]{../doc/src/slides/fig/latex_thesis.jpg}}

\vspace{6mm}



\column{0.5\textwidth}
\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=1.2\linewidth]{../doc/src/slides/fig/latex_paper1.png}}

\vspace{6mm}



\end{columns}
\end{frame}

\begin{frame}[plain,fragile]
\frametitle{Scope}

% * Scientific writing = lecture notes, slides, reports, thesis, books,  ...
% * (Journal papers typeset by journals are out of scope)

\begin{itemize}
\pause
  \item Scope: documents with \textcolor{red}{much} \emph{math} and \emph{computer code}

\pause
  \item Key question: What tools should I use for writing?

\pause
  \item Default answer: {\LaTeX}

\pause
  \item Alternative: MS Word w/math

\pause
  \item Recent popular alternative tools: HTML w/MathJax,
    Sphinx, Markdown, MediaWiki, IPython notebook
\end{itemize}

\noindent

\begin{columns}
\column{0.25\textwidth}
\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=0.3\linewidth]{../doc/src/slides/fig/LaTeX_logo.jpg}}

\vspace{6mm}



\column{0.25\textwidth}
\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=0.2\linewidth]{../doc/src/slides/fig/MS_Word_logo.jpg}}

\vspace{6mm}



\column{0.5\textwidth}
\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=0.4\linewidth]{../doc/src/slides/fig/sphinx_logo.png}}

\vspace{6mm}



\end{columns}
\begin{columns}
\column{0.25\textwidth}
\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=0.2\linewidth]{../doc/src/slides/fig/markdown_logo.jpg}}

\vspace{6mm}



\column{0.25\textwidth}
\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=0.2\linewidth]{../doc/src/slides/fig/MediaWiki_logo.jpg}}

\vspace{6mm}



\column{0.5\textwidth}
\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=0.6\linewidth]{../doc/src/slides/fig/IPython_logo.png}}

\vspace{6mm}



\end{columns}
\end{frame}

\begin{frame}[plain,fragile]
\frametitle{Scientific writing for the future needs to address many new media}

% Insert links here to reports

\begin{columns}
\column{0.5\textwidth}
Old days (1985-2005): {\LaTeX} for BW paper output, but now

\begin{enumerate}
  \item BW books

  \item Colorful PDF books (printed and screen)

  \item Designed web pages

  \item Wikis

  \item Blog posts

  \item Next new fancy format (iBook w/LaTeX?)
\end{enumerate}

\noindent

\column{0.5\textwidth}
\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=0.9\linewidth]{../doc/src/slides/fig/jungle_with_mess.jpg}}

\vspace{6mm}



\end{columns}
\end{frame}

\begin{frame}[plain,fragile]
\frametitle{Fundamental question}

When I write some scientific material,

\begin{itemize}
 \item a {\LaTeX} document,

 \item a blog post (HTML),

 \item some web pages (HTML),

 \item a Sphinx document,

 \item some Markdown files,
\end{itemize}

\noindent
and later want to collect the pieces into a larger document, maybe
some book, or one big web document, is that at all feasible?

\pause
Probably not, but I have a solution :-)
\end{frame}

\begin{frame}[plain,fragile]
\frametitle{{\LaTeX} is very rich; other tools support only some elements}

\begin{itemize}
 \item {\LaTeX} inline math: works with all ({\LaTeX}, MathJax, Sphinx, Markdown, MediaWiki)

 \item {\LaTeX} equation math:
\begin{itemize}

    \item \textbf{LaTeX}: \texttt{equation*}, \texttt{equation}, \texttt{align*}, \texttt{align} +
      \texttt{eqnarray}, \texttt{split}, \texttt{alignat}, ... (numerous!)

    \item \textbf{MathJax}: \texttt{equation*}, \texttt{equation}, \texttt{align*}, \texttt{align}

    \item \textbf{MediaWiki}: \texttt{equation*}, \texttt{equation}, \texttt{align*}, \texttt{align}

    \item \textbf{Sphinx}: \texttt{equation*}, \texttt{equation}, \texttt{align*}

    \item \textbf{Markdown}: \texttt{equation*}, \texttt{equation}, \texttt{eqnarray*}, \texttt{align*} (but no labels)
\end{itemize}

\noindent
\end{itemize}

\noindent
\end{frame}

\begin{frame}[plain,fragile]
\frametitle{{\LaTeX} is very rich; other tools support only some elements}

\begin{itemize}
\pause
 \item Figures: all

\pause
 \item Subfigures: {\LaTeX} (\texttt{subfigure})

\pause
 \item Movies: {\LaTeX} (can run separately), just raw embedded HTML in others

\pause
 \item Floating computer code: {\LaTeX}

\pause
 \item Fixed computer code: all

\pause
 \item Floating tables: {\LaTeX}; inline tables: all

\pause
 \item Algorithms: {\LaTeX}

\pause
 \item Margin notes: {\LaTeX}

\pause
 \item Page references: {\LaTeX}

\pause
 \item Footnotes: {\LaTeX}, Sphinx, reStructuredText, MediaWiki

\pause
 \item Bibliography: {\LaTeX}, Sphinx, reStructuredText, MediaWiki

\pause
 \item Hyperlinks: all (but not on paper!)
\end{itemize}

\noindent

\pause
Conclusion: Highly non-trivial to translate a {\LaTeX} document into something
based on HTML and vice versa.
\end{frame}

\begin{frame}[plain,fragile]
\frametitle{DocOnce demo}

\href{{https://hplgit.github.com/teamods/writing_reports/}}{\nolinkurl{https://hplgit.github.com/teamods/writing_reports/}}

\begin{itemize}
 \item LaTeX-based PDF \href{{https://hplgit.github.com/teamods/writing_reports/_static/report.pdf}}{for screen}, \href{{https://hplgit.github.com/teamods/writing_reports/_static/report_4printing.pdf}}{for printing}, \href{{https://hplgit.github.com/teamods/writing_reports/_static/report_4phone.pdf}}{for phone}

 \item \href{{https://hplgit.github.com/teamods/writing_reports/_static/report_do.html}}{Plain HTML} or with a \href{{https://hplgit.github.com/teamods/writing_reports/_static/report_vagrant.html}}{template} or \href{{https://hplgit.github.com/teamods/writing_reports/_static/report_github_minimal.html}}{another template} or \href{{https://hplgit.github.com/teamods/writing_reports/_static/report_solarized.html}}{solarized}

 \item Sphinx: \href{{https://hplgit.github.com/teamods/writing_reports/_static/sphinx-agni/index.html}}{agni}, \href{{https://hplgit.github.com/teamods/writing_reports/_static/sphinx-pyramid/report.html}}{pyramid}, \href{{https://hplgit.github.com/teamods/writing_reports/_static/sphinx-classy/report.html}}{classy}, \href{{https://hplgit.github.com/teamods/writing_reports/_static/sphinx-fenics_minimal/report.html}}{fenics}, \href{{https://hplgit.github.com/teamods/writing_reports/_static/sphinx-fenics_minimal/report.html}}{redcloud}

 \item HTML for \href{{https://doconce-report-demo.blogspot.no/}}{Google} or \href{{https://doconcereportdemo.wordpress.com/}}{Wordpress} blog posts

 \item \href{{https://doconcedemo.shoutwiki.com/wiki/DocOnce_demo_page}}{MediaWiki} (Wikipedia, Wikibooks, etc)

 \item DocOnce \href{{https://hplgit.github.com/teamods/writing_reports/_static/report.do.txt.html}}{source code} and \href{{https://hplgit.github.io/doconce/doc/src/pub/manual/html/manual.html}}{manual}
\end{itemize}

\noindent
\end{frame}

\begin{frame}[plain,fragile]
\frametitle{DocOnce: title, authors, date, toc}

\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95]
TITLE: Some Title
AUTHOR: name1 at institution1, with more info & institution2
AUTHOR: name2 email:name2@web.com at institution
DATE: today

# A table of contents is optional:
TOC: on
\end{Verbatim}

\begin{block}{Notice}
Title and authors must have all information \emph{on a single line}!
\end{block}
\end{frame}

\begin{frame}[plain,fragile]
\frametitle{DocOnce: abstract}

\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95]
__Abstract.__
Here goes the abstract...
\end{Verbatim}

Or:
\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95]
__Summary.__
Here goes the summary...
\end{Verbatim}
\end{frame}

\begin{frame}[plain,fragile]
\frametitle{DocOnce: section headings}

Headings are surrounded by \texttt{=} signs:
\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95]
======= This is an H1/chapter heading =======

===== This is an H2/section heading =====

===== This is an H3/subsection heading =====

=== This is an H4/paragraph heading ===

__This is a paragraph heading.__
\end{Verbatim}
\end{frame}

\begin{frame}[plain,fragile]
\frametitle{DocOnce: markup and lists}

\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95]
 * Bullet list items start with `*`
   and may span several lines
 * *Emphasized words* are possible
 * _Boldface words_ are also possible
 * color{red}{colored words} too
 * `inline verbatim code` is featured
   o and sublists with enumerated items starting with `o`
   o items are just indented as you would do in email
\end{Verbatim}

This gets rendered as

\begin{itemize}
 \item Bullet lists start with \texttt{*}
   and may span several lines

 \item \emph{Emphasized words} are possible

 \item \textbf{Boldface words} are also possible

 \item \textcolor{red}{colored words} too

 \item \texttt{inline verbatim code} is featured
\begin{enumerate}

  \item and sublists with enumerated items starting with \texttt{o}

  \item items are just indented as you would do in email
\end{enumerate}

\noindent
\end{itemize}

\noindent
\end{frame}

\begin{frame}[plain,fragile]
\frametitle{DocOnce: labels, references, index items}

\begin{minted}[fontsize=\fontsize{9pt}{9pt},linenos=false,mathescape,baselinestretch=1.0,fontfamily=tt,xleftmargin=2mm]{doconce}
# Insert index items in the source
idx{key word1} idx{key word2}

# Label
===== Some section =====
label{this:section}

# Make reference
As we saw in Section ref{this:section}, references, index
items and labels follow a syntax similar to LaTeX
but without backslashes.

# Make reference to equations
See (ref{eq1})-(ref{myeq}).

# Make hyperlink
"some link text": "https://github.com/hplgit/doconce"

# Hyperlink with complete URL as link text
URL: "https://github.com/hplgit/doconce"
\end{minted}
\end{frame}

\begin{frame}[plain,fragile]
\frametitle{DocOnce: figures and movies}

\begin{block}{Notice}
Figure with HTML and {\LaTeX} info, and caption, \emph{all on one line}:
\end{block}

\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95]
FIGURE: [figdir/myfig, width=300 frac=1.2] My caption. label{fig1}

# This figure will be 300 pixels wide in HTML and span 1.2 times
# the linewidth in LaTeX.
\end{Verbatim}

Movies are also supported:

\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95]
MOVIE: [https://www.youtube.com/embed/P8VcZzgdfSc, width=420 height=315]
\end{Verbatim}
and rendered as


\begin{doconce:movie}
\refstepcounter{doconce:movie:counter}
\begin{center}
\href{{https://www.youtube.com/embed/P8VcZzgdfSc}}{\nolinkurl{https://www.youtube.com/embed/P8VcZzgdfSc}}
\end{center}
\end{doconce:movie}
\end{frame}

\begin{frame}[plain,fragile]
\frametitle{DocOnce: math}

Inline math as in {\LaTeX}:

\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95]
...where $a=\int_{\Omega}fdx$ is an integral.
\end{Verbatim}
gets rendered as ...where $a=\int_{\Omega}fdx$ is an integral.


An equation environment is surrounded by \Verb?!bt? and \Verb?!et? tags,
the rest is plain {\LaTeX}:

\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95]
!bt
\begin{align}
\frac{\partial u}{\partial t} &= \nabla^2 u,
label{a:eq}\\
\nabla\cdot\pmb{v} & = 0
label{b:eq}
\end{align}
!et
\end{Verbatim}
which is rendered as

\begin{align}
\frac{\partial u}{\partial t} &= \nabla^2 u,
\label{_a:eq}\\
\nabla\cdot\pmb{v} & = 0
\label{_b:eq}
\end{align}
\end{frame}

\begin{frame}[plain,fragile]
\frametitle{DocOnce: displaying code}

Code is enclosed in \Verb?!bc? and \Verb?!ec? tags:

\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95]
!bc pycod
def solver(I, a, T, dt, theta):
    """Solve u'=-a*u, u(0)=I, for t in (0,T] with steps of dt."""
    dt = float(dt)           # avoid integer division
    N = int(round(T/dt))     # no of time intervals
    T = N*dt                 # adjust T to fit time step dt
    u = zeros(N+1)           # array of u[n] values
    t = linspace(0, T, N+1)  # time mesh

    u[0] = I                 # assign initial condition
    for n in range(0, N):    # n=0,1,...,N-1
        u[n+1] = (1 - (1-theta)*a*dt)/(1 + theta*dt*a)*u[n]
    return u, t
!ec
\end{Verbatim}
This gets rendered as

\begin{minted}[fontsize=\fontsize{9pt}{9pt},linenos=false,mathescape,baselinestretch=1.0,fontfamily=tt,xleftmargin=2mm]{python}
def solver(I, a, T, dt, theta):
    """Solve u'=-a*u, u(0)=I, for t in (0,T] with steps of dt."""
    dt = float(dt)           # avoid integer division
    N = int(round(T/dt))     # no of time intervals
    T = N*dt                 # adjust T to fit time step dt
    u = zeros(N+1)           # array of u[n] values
    t = linspace(0, T, N+1)  # time mesh

    u[0] = I                 # assign initial condition
    for n in range(0, N):    # n=0,1,...,N-1
        u[n+1] = (1 - (1-theta)*a*dt)/(1 + theta*dt*a)*u[n]
    return u, t
\end{minted}

\begin{block}{Language-dependent typesetting of code: }
The \Verb?!bc? command can be followed by a specification of the computer
language: \texttt{pycod} for Python code snippet, \texttt{pypro} for complete Python
program, \texttt{fcod} for Fortran snippet, \texttt{fpro} for Fortran program, and so
forth (\texttt{c} for C, \texttt{cpp} for C++, \texttt{sh} for Unix shells, \texttt{m} for Matlab).
\end{block}
\end{frame}

\begin{frame}[plain,fragile]
\frametitle{DocOnce: displaying interactive demo code}

\label{slide:pot}

With \Verb?!bc pyoptpro? or a file \texttt{*.pyopt}, the code applies the
\href{{https://pythontutor.com}}{Online Python Tutor} for displaying
program flow and state of variables:

\begin{minted}[fontsize=\fontsize{9pt}{9pt},linenos=false,mathescape,baselinestretch=1.0,fontfamily=tt,xleftmargin=2mm]{python}
def solver(I, a, T, dt, theta):
    dt = float(dt)
    N = int(round(T/dt))
    T = N*dt
    u = [0.0]*(N+1)
    t = [i*dt for i in range(N+1)]

    u[0] = I
    for n in range(0, N):
        u[n+1] = (1 - (1-theta)*a*dt)/(1 + theta*dt*a)*u[n]
    return u, t

u, t = solver(I=1, a=1, T=3, dt=1., theta=0.5)
print u
\end{minted}
\noindent
(\href{{https://pythontutor.com/visualize.html\#code=def+solver\%28I\%2C+a\%2C+T\%2C+dt\%2C+theta\%29\%3A\%0A++++dt+\%3D+float\%28dt\%29\%0A++++N+\%3D+int\%28round\%28T\%2Fdt\%29\%29\%0A++++T+\%3D+N\%2Adt\%0A++++u+\%3D+\%5B0.0\%5D\%2A\%28N\%2B1\%29\%0A++++t+\%3D+\%5Bi\%2Adt+for+i+in+range\%28N\%2B1\%29\%5D\%0A\%0A++++u\%5B0\%5D+\%3D+I\%0A++++for+n+in+range\%280\%2C+N\%29\%3A\%0A++++++++u\%5Bn\%2B1\%5D+\%3D+\%281+-+\%281-theta\%29\%2Aa\%2Adt\%29\%2F\%281+\%2B+theta\%2Adt\%2Aa\%29\%2Au\%5Bn\%5D\%0A++++return+u\%2C+t\%0A\%0Au\%2C+t+\%3D+solver\%28I\%3D1\%2C+a\%3D1\%2C+T\%3D3\%2C+dt\%3D1.\%2C+theta\%3D0.5\%29\%0Aprint+u&mode=display&cumulative=false&heapPrimitives=false&drawParentPointers=false&textReferences=false&py=2&curInstr=0}}{Visualize execution})
\end{frame}

\begin{frame}[plain,fragile]
\frametitle{DocOnce: exercises}

DocOnce offers a special format for \emph{exercises}, \emph{problems}, \emph{projects},
and \emph{examples}:

\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95]
===== Problem: Flip a Coin =====
label{demo:ex:1}

files = flip_coin.py, flip_coin.pdf
solutions = mysol.txt, mysol_flip_coin.py
keywords = random numbers; Monte Carlo simulation

!bsubex
Make a program that simulates flipping a coin $N$ times.

!bhint
Use `r = random.random()` and define head as `r <= 0.5`.
!ehint
!esubex

!bsubex
Compute the probability of getting heads.

!bans
A short answer: 0.5.
!eans

!bsol
A full solution to this subexercise can go here.
!esol
!esubex

!bsubex
Make another program that computes the probability
of getting at least three heads out of 5 throws.
!esubex
\end{Verbatim}

Solutions/answers can easily be left out of the document.
\end{frame}

\begin{frame}[plain,fragile]
\frametitle{DocOnce: example on slide code}

\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95]
!split
===== Headline =====

 * Key point 1
 * Key point 2
 * Key point 3 takes very much more text to explain because
   this point is really comprehensive, and although long
   bullet points are not recommended in general, we need
   it here for demonstration purposes

FIGURE: [../doc/src/slides/fig/teacher1, width=100]

Key equation:

!bt
\[ -\nabla^2 u = f \quad\hbox{in }\Omega \]
!et

And maybe a final comment?

!split
===== Next slide... =====
\end{Verbatim}
\end{frame}

\begin{frame}[plain,fragile]
\frametitle{DocOnce: example on slide code with cells}

One can introduce a table-like layout with MxN cells and
put slide elements in various cell. A cell with position
MN is surrounded by \Verb?!bslidecell MN? and \Verb?!eslidecell?
tags. Below is an example with a bullet list to the left and
a figure to the right (two cells, numbered 00 and 01).

\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95]
!split
===== Headline =====

!bslidecell 00
!bpop
 * Key point 1
 * Key point 2
 * Key point 3 takes very much more text to explain because
   this point is really comprehensive, and although long
   bullet points are not recommended in general, we need
   it here for demonstration purposes
!epop

!bpop
!bt
\[ -\nabla^2 u = f \quad\hbox{in }\Omega \]
!et
!epop

!eslidecell

!bslidecell 01
FIGURE: [../doc/src/slides/fig/broken_pen_and_paper, width=400, frac=0.8]
!eslidecell

!split
===== Next slide... =====
\end{Verbatim}
\end{frame}

\end{document}

************** File: slides3.do.txt *****************
TITLE: On Schemes for Exponential Decay
AUTHOR: Hans Petter Langtangen at Center for Biomedical Computing, Simula Research Laboratory & Department of Informatics, University of Oslo
DATE: today

FIGURE: [../doc/src/slides/fig/CN_logo, width=300 frac=0.4]

## Comments start with a # and are visible as comments in the
## output. Lines starting with ## are also comments, but not visible
## in the output.

!split
===== Goal =====

The primary goal of this demo talk is to demonstrate how to write
talks with "DocOnce": "https://github.com/doconce/doconce"
and get them rendered in numerous HTML formats.
# #if FORMAT in ("html", "pdflatex", "latex")
!bnotice Layout
This version
utilizes ${SLIDE_TYPE} slides with the theme ${SLIDE_THEME}.
!enotice
# #endif

## Demonstrate use of Mako variables set on the command line
## (see last sentence too). We use Preprocess (run before Mako)
## to leave out the Mako test on SLIDE_THEME and SLIDE_TYPE.
## In that way, we do not need to specify these variables on
## the command line when compiling for LaTeX or other formats
## (e.g. for handouts).

# #if FORMAT == "html"
!bnotice
Speaker notes show up by
% if SLIDE_TYPE == 'reveal':
pressing "s".
% elif SLIDE_TYPE == 'deck':
pressing "n".
% elif SLIDE_TYPE == 'csss':
pressing "Ctrl-P".
% elif SLIDE_TYPE == 'html5slides':
pressing "p".
% elif SLIDE_TYPE == 'csss':
using the "onstage.html": "https://raw.github.com/doconce/doconce/master/bundled/dzslides/shells/onstage.html" embedding page.
% endif
!enotice
# #endif

## Add speaker notes (can also use preprocess or mako for this)

!bnotes
The talk investigates the accuracy of three finite difference
schemes for the ordinary differential equation $u'=-au$ with the
aid of numerical experiments. Numerical artifacts are in particular
demonstrated.
!enotes

!split
======= Methods =======

## New slide is indicated by !split at the beginning of a line:

!split
===== Mathematical problem =====

## Use !bslidecell XY and !eslidecell as begin and end for
## defining a cell XY in a table layout of the slide.
## X=0,1,..., Y=0,1,... XY=00 is the upper left cell.
## Here we define cell 00 and 01 (bullet list to the left
## and figure to the right).

!bslidecell 00

## latex blocks are surrounded by !bt and !et

!bt
\begin{align}
u'(t) &= -au(t),
label{ode}\\
u(0)  &= I,
label{initial:value}
\end{align}
!et

 * $t\in (0,T]$
 * $a$, $I$, and $T$ are prescribed parameters
 * $u(t)$ is the unknown function

!eslidecell

## Figures can have a width parameter specifying the pixel
## width in HTML. A caption can be added (after [...]).

!bslidecell 01
FIGURE: [../doc/src/slides/fig/teacher2, width=250 frac=0.5]
!eslidecell

!split
===== Numerical solution method =====

## !bpop and !epop surround elements that are to pop up
## as we progress in the slide show.
## They will often not work if there is code inside.

!bpop
 * Mesh in time: $0= t_0< t_1 \cdots < t_N=T$
 * Assume constant $\Delta t = t_{n}-t_{n-1}$
 * $u^n$: numerical approx to the exact solution at $t_n$
!epop

!bpop
Numerical scheme:
!bt
   \[
   u^{n+1} = \frac{1 - (1-\theta) a\Delta t}{1 + \theta a\Delta t}u^n,
   \quad n=0,1,\ldots,N-1
   \]
!et
!epop

# #if FORMAT == "html"

!split
## Next: embed YouTube video

===== Forward Euler explained =====

MOVIE: [https://youtu.be/PtJrPEIHNJw, width=640 height=480]

# #endif

!split
## Next: exemplify copying code directly from file (start
## with the line matching "def solver" and ending with
## "def verify_three", but not including this last line).

===== Implementation =====

The numerical method is implemented in a Python function:

@@@CODE ../doc/src/slides/src/solver.py  fromto: def solver@def exact_sol

!split
======= Selected results =======
# Short title: Results


!split
===== The Crank-Nicolson method =====

## Figure filenames do not need extension - the right version is picked

FIGURE: [../doc/src/slides/fig/CN, width=600]

!split
===== The artifacts can be explained by some theory =====

!bpop
Exact solution of the scheme:

!bt
\[ u^n = A^n,\quad A = \frac{1 - (1-\theta) a\Delta t}{1 + \theta a\Delta t}\thinspace .\]
!et
!epop

!bpop
 * Stability: $|A| < 1$
 * No oscillations: $A>0$
 * Always for Backward Euler ($\theta=1$)
 * $\Delta t < 1/a$ for Forward Euler ($\theta=0$)
 * $\Delta t < 2/a$ for Crank-Nicolson ($\theta=1/2$)
!epop

## The summary environment appears in a box in most formats
## (warning, notice, hint, question are other environments)
!bpop
!bsummary Concluding remarks:
Only the Backward Euler scheme is guaranteed to always give
qualitatively correct results.
!esummary
!epop

************** File: slides3_reveal.html *****************
<!DOCTYPE html>

<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="DocOnce: https://github.com/doconce/doconce/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="description" content="On Schemes for Exponential Decay">

<title>On Schemes for Exponential Decay</title>







<!-- reveal.js: https://lab.hakim.se/reveal-js/ -->

<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">

<meta name="apple-mobile-web-app-capable" content="yes" />
<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent" />
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, minimal-ui">

<link rel="stylesheet" href="reveal.js/css/reveal.css">
<link rel="stylesheet" href="reveal.js/css/theme/beige.css" id="theme">
<!--
<link rel="stylesheet" href="reveal.js/css/reveal.css">
<link rel="stylesheet" href="reveal.js/css/theme/beige.css" id="theme">
<link rel="stylesheet" href="reveal.js/css/theme/beigesmall.css" id="theme">
<link rel="stylesheet" href="reveal.js/css/theme/solarized.css" id="theme">
<link rel="stylesheet" href="reveal.js/css/theme/serif.css" id="theme">
<link rel="stylesheet" href="reveal.js/css/theme/night.css" id="theme">
<link rel="stylesheet" href="reveal.js/css/theme/moon.css" id="theme">
<link rel="stylesheet" href="reveal.js/css/theme/simple.css" id="theme">
<link rel="stylesheet" href="reveal.js/css/theme/sky.css" id="theme">
<link rel="stylesheet" href="reveal.js/css/theme/darkgray.css" id="theme">
<link rel="stylesheet" href="reveal.js/css/theme/default.css" id="theme">
<link rel="stylesheet" href="reveal.js/css/theme/cbc.css" id="theme">
<link rel="stylesheet" href="reveal.js/css/theme/simula.css" id="theme">
<link rel="stylesheet" href="reveal.js/css/theme/black.css" id="theme">
<link rel="stylesheet" href="reveal.js/css/theme/white.css" id="theme">
<link rel="stylesheet" href="reveal.js/css/theme/league.css" id="theme">
-->

<!-- For syntax highlighting -->
<link rel="stylesheet" href="reveal.js/lib/css/zenburn.css">

<!-- Printing and PDF exports -->
<script>
var link = document.createElement( 'link' );
link.rel = 'stylesheet';
link.type = 'text/css';
link.href = window.location.search.match( /print-pdf/gi ) ? 'css/print/pdf.css' : 'css/print/paper.css';
document.getElementsByTagName( 'head' )[0].appendChild( link );
</script>

<style type="text/css">
    hr { border: 0; width: 80%; border-bottom: 1px solid #aaa}
    p.caption { width: 80%; font-size: 60%; font-style: italic; text-align: left; }
    hr.figure { border: 0; width: 80%; border-bottom: 1px solid #aaa}
    .reveal .alert-text-small   { font-size: 80%;  }
    .reveal .alert-text-large   { font-size: 130%; }
    .reveal .alert-text-normal  { font-size: 90%;  }
    .reveal .alert {
             padding:8px 35px 8px 14px; margin-bottom:18px;
             text-shadow:0 1px 0 rgba(255,255,255,0.5);
             border:5px solid #bababa;
             -webkit-border-radius: 14px; -moz-border-radius: 14px;
             border-radius:14px;
             background-position: 10px 10px;
             background-repeat: no-repeat;
             background-size: 38px;
             padding-left: 30px; /* 55px; if icon */
     }
     .reveal .alert-block {padding-top:14px; padding-bottom:14px}
     .reveal .alert-block > p, .alert-block > ul {margin-bottom:1em}
     /*.reveal .alert li {margin-top: 1em}*/
     .reveal .alert-block p+p {margin-top:5px}
     /*.reveal .alert-notice { background-image: url(https://hplgit.github.io/doconce/bundled/html_images/small_gray_notice.png); }
     .reveal .alert-summary  { background-image:url(https://hplgit.github.io/doconce/bundled/html_images/small_gray_summary.png); }
     .reveal .alert-warning { background-image: url(https://hplgit.github.io/doconce/bundled/html_images/small_gray_warning.png); }
     .reveal .alert-question {background-image:url(https://hplgit.github.io/doconce/bundled/html_images/small_gray_question.png); } */

</style>



<!-- Styles for table layout of slides -->
<style type="text/css">
td.padding {
  padding-top:20px;
  padding-bottom:20px;
  padding-right:50px;
  padding-left:50px;
}
</style>

</head>

<body>
<div class="reveal">

<!-- Any section element inside the <div class="slides"> container
     is displayed as a slide -->

<div class="slides">





<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  TeX: {
     equationNumbers: {  autoNumber: "none"  },
     extensions: ["AMSmath.js", "AMSsymbols.js", "autobold.js", "color.js"]
  }
});
</script>
<script type="text/javascript" async
 src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>



    



<section>
<!-- ------------------- main content ---------------------- -->



<center><h1 style="text-align: center;">On Schemes for Exponential Decay</h1></center>  <!-- document title -->

<p>
<!-- author(s): Hans Petter Langtangen -->

<center>
<b>Hans Petter Langtangen</b> [1, 2]
</center>

<p>&nbsp;<br>
<!-- institution(s) -->

<center>[1] <b>Center for Biomedical Computing, Simula Research Laboratory</b></center>
<center>[2] <b>Department of Informatics, University of Oslo</b></center>
<br>
<p>&nbsp;<br>
<center><h4>Jan 32, 2100</h4></center> <!-- date -->
<br>
<p>
<br /><br /><center><p><img src="../doc/src/slides/fig/CN_logo.png" align="bottom" width=300></p></center><br /><br />
</section>


<section>
<h2 id="goal">Goal </h2>

<p>
The primary goal of this demo talk is to demonstrate how to write
talks with <a href="https://github.com/doconce/doconce" target="_self">DocOnce</a>
and get them rendered in numerous HTML formats.
<div class="alert alert-block alert-notice alert-text-normal">
<b>Layout</b>
<p>
This version
utilizes reveal slides with the theme beigesmall.
</div>

<p>
<div class="alert alert-block alert-notice alert-text-normal">
<b>Notice</b>
<p>
Speaker notes show up by
pressing "s".
</div>

<p>
<aside class="notes">
<!-- click "s" to activate -->

The talk investigates the accuracy of three finite difference
schemes for the ordinary differential equation \( u'=-au \) with the
aid of numerical experiments. Numerical artifacts are in particular
demonstrated.

</aside>
</section>


<section>
<h1 id="methods">Methods </h1>
</section>


<section>
<h2 id="mathematical-problem">Mathematical problem </h2>

<p>

<table border="0">
<tr>
<td class="padding">
<p>&nbsp;<br>
$$
\begin{align}
u'(t) &= -au(t),
\tag{1}\\ 
u(0)  &= I,
\tag{2}
\end{align}
$$
<p>&nbsp;<br>


<ul>
 <p><li> \( t\in (0,T] \)</li>
 <p><li> \( a \), \( I \), and \( T \) are prescribed parameters</li>
 <p><li> \( u(t) \) is the unknown function</li>
</ul>
<p>
</td>
<td class="padding">
<br /><br /><center><p><img src="../doc/src/slides/fig/teacher2.jpg" align="bottom" width=250></p></center><br /><br />
</td>
</tr>
</table>
</section>


<section>
<h2 id="numerical-solution-method">Numerical solution method </h2>

<ul>
 <p><li class="fragment"> Mesh in time: \( 0= t_0 < t_1 \cdots < t_N=T \)</li>
 <p><li class="fragment"> Assume constant \( \Delta t = t_{n}-t_{n-1} \)</li>
 <p><li class="fragment"> \( u^n \): numerical approx to the exact solution at \( t_n \)</li>
</ul>
<p>

<p class="fragment">

Numerical scheme:
&nbsp;<br>&nbsp;<br>
$$
   u^{n+1} = \frac{1 - (1-\theta) a\Delta t}{1 + \theta a\Delta t}u^n,
   \quad n=0,1,\ldots,N-1
   $$
&nbsp;<br>&nbsp;<br>


</p>
</section>


<section>
<h2 id="forward-euler-explained">Forward Euler explained </h2>

<p>

<iframe width="640" height="480" src="https://www.youtube.com/embed/PtJrPEIHNJw" frameborder="0" allowfullscreen></iframe>
</section>


<section>
<h2 id="implementation">Implementation </h2>

<p>
The numerical method is implemented in a Python function:

<p>

<!-- code=python (!bc pycod) typeset with pygments style "emacs" -->
<div class="highlight" style="background: #f8f8f8"><pre style="font-size: 80%; line-height: 125%;"><span></span><span style="color: #AA22FF; font-weight: bold">def</span> <span style="color: #00A000">solver</span>(I, a, T, dt, theta):
    <span style="color: #BB4444; font-style: italic">&quot;&quot;&quot;Solve u&#39;=-a*u, u(0)=I, for t in (0,T]; step: dt.&quot;&quot;&quot;</span>
    dt <span style="color: #666666">=</span> <span style="color: #AA22FF">float</span>(dt)           <span style="color: #008800; font-style: italic"># avoid integer division</span>
    N <span style="color: #666666">=</span> <span style="color: #AA22FF">int</span>(<span style="color: #AA22FF">round</span>(old_div(T,dt)))     <span style="color: #008800; font-style: italic"># no of time intervals</span>
    T <span style="color: #666666">=</span> N<span style="color: #666666">*</span>dt                 <span style="color: #008800; font-style: italic"># adjust T to fit time step dt</span>
    u <span style="color: #666666">=</span> zeros(N<span style="color: #666666">+1</span>)           <span style="color: #008800; font-style: italic"># array of u[n] values</span>
    t <span style="color: #666666">=</span> linspace(<span style="color: #666666">0</span>, T, N<span style="color: #666666">+1</span>)  <span style="color: #008800; font-style: italic"># time mesh</span>

    u[<span style="color: #666666">0</span>] <span style="color: #666666">=</span> I                 <span style="color: #008800; font-style: italic"># assign initial condition</span>
    <span style="color: #AA22FF; font-weight: bold">for</span> n <span style="color: #AA22FF; font-weight: bold">in</span> <span style="color: #AA22FF">range</span>(<span style="color: #666666">0</span>, N):    <span style="color: #008800; font-style: italic"># n=0,1,...,N-1</span>
        u[n<span style="color: #666666">+1</span>] <span style="color: #666666">=</span> (<span style="color: #666666">1</span> <span style="color: #666666">-</span> (<span style="color: #666666">1-</span>theta)<span style="color: #666666">*</span>a<span style="color: #666666">*</span>dt)<span style="color: #666666">/</span>(<span style="color: #666666">1</span> <span style="color: #666666">+</span> theta<span style="color: #666666">*</span>dt<span style="color: #666666">*</span>a)<span style="color: #666666">*</span>u[n]
    <span style="color: #AA22FF; font-weight: bold">return</span> u, t
</pre></div>
</section>


<section>
<h1 id="selected-results">Selected results </h1>
<!-- Short title: Results -->
</section>


<section>
<h2 id="the-crank-nicolson-method">The Crank-Nicolson method </h2>

<p>
<br /><br /><center><p><img src="../doc/src/slides/fig/CN.png" align="bottom" width=600></p></center><br /><br />
</section>


<section>
<h2 id="the-artifacts-can-be-explained-by-some-theory">The artifacts can be explained by some theory </h2>

<p>

<p class="fragment">

Exact solution of the scheme:

&nbsp;<br>&nbsp;<br>
$$ u^n = A^n,\quad A = \frac{1 - (1-\theta) a\Delta t}{1 + \theta a\Delta t}\thinspace .$$
&nbsp;<br>&nbsp;<br>


</p>


<ul>
 <p><li class="fragment"> Stability: \( |A| < 1 \)</li>
 <p><li class="fragment"> No oscillations: \( A>0 \)</li>
 <p><li class="fragment"> Always for Backward Euler (\( \theta=1 \))</li>
 <p><li class="fragment"> \( \Delta t < 1/a \) for Forward Euler (\( \theta=0 \))</li>
 <p><li class="fragment"> \( \Delta t < 2/a \) for Crank-Nicolson (\( \theta=1/2 \))</li>
</ul>
<p>

<div class="fragment alert alert-block alert-summary alert-text-normal">
<b>Concluding remarks:</b>
<p>
Only the Backward Euler scheme is guaranteed to always give
qualitatively correct results.
</div>
</section>



</div> <!-- class="slides" -->
</div> <!-- class="reveal" -->

<script src="reveal.js/lib/js/head.min.js"></script>
<script src="reveal.js/js/reveal.js"></script>

<script>
// Full list of configuration options available here:
// https://github.com/hakimel/reveal.js#configuration
Reveal.initialize({

    // Display navigation controls in the bottom right corner
    controls: true,

    // Display progress bar (below the horiz. slider)
    progress: true,

    // Display the page number of the current slide
    slideNumber: true,

    // Push each slide change to the browser history
    history: false,

    // Enable keyboard shortcuts for navigation
    keyboard: true,

    // Enable the slide overview mode
    overview: true,

    // Vertical centering of slides
    //center: true,
    center: false,

    // Enables touch navigation on devices with touch input
    touch: true,

    // Loop the presentation
    loop: false,

    // Change the presentation direction to be RTL
    rtl: false,

    // Turns fragments on and off globally
    fragments: true,

    // Flags if the presentation is running in an embedded mode,
    // i.e. contained within a limited portion of the screen
    embedded: false,

    // Number of milliseconds between automatically proceeding to the
    // next slide, disabled when set to 0, this value can be overwritten
    // by using a data-autoslide attribute on your slides
    autoSlide: 0,

    // Stop auto-sliding after user input
    autoSlideStoppable: true,

    // Enable slide navigation via mouse wheel
    mouseWheel: false,

    // Hides the address bar on mobile devices
    hideAddressBar: true,

    // Opens links in an iframe preview overlay
    previewLinks: false,

    // Transition style
    transition: 'default', // default/cube/page/concave/zoom/linear/fade/none

    // Transition speed
    transitionSpeed: 'default', // default/fast/slow

    // Transition style for full page slide backgrounds
    backgroundTransition: 'default', // default/none/slide/concave/convex/zoom

    // Number of slides away from the current that are visible
    viewDistance: 3,

    // Parallax background image
    //parallaxBackgroundImage: '', // e.g. "'https://s3.amazonaws.com/hakim-static/reveal-js/reveal-parallax-1.jpg'"

    // Parallax background size
    //parallaxBackgroundSize: '' // CSS syntax, e.g. "2100px 900px"

    theme: Reveal.getQueryHash().theme, // available themes are in reveal.js/css/theme
    transition: Reveal.getQueryHash().transition || 'default', // default/cube/page/concave/zoom/linear/none

});

Reveal.initialize({
    dependencies: [
        // Cross-browser shim that fully implements classList - https://github.com/eligrey/classList.js/
        { src: 'reveal.js/lib/js/classList.js', condition: function() { return !document.body.classList; } },

        // Interpret Markdown in <section> elements
        { src: 'reveal.js/plugin/markdown/marked.js', condition: function() { return !!document.querySelector( '[data-markdown]' ); } },
        { src: 'reveal.js/plugin/markdown/markdown.js', condition: function() { return !!document.querySelector( '[data-markdown]' ); } },

        // Syntax highlight for <code> elements
        { src: 'reveal.js/plugin/highlight/highlight.js', async: true, callback: function() { hljs.initHighlightingOnLoad(); } },

        // Zoom in and out with Alt+click
        { src: 'reveal.js/plugin/zoom-js/zoom.js', async: true, condition: function() { return !!document.body.classList; } },

        // Speaker notes
        { src: 'reveal.js/plugin/notes/notes.js', async: true, condition: function() { return !!document.body.classList; } },

        // Remote control your reveal.js presentation using a touch device
        //{ src: 'reveal.js/plugin/remotes/remotes.js', async: true, condition: function() { return !!document.body.classList; } },

        // MathJax
        //{ src: 'reveal.js/plugin/math/math.js', async: true }
    ]
});

Reveal.initialize({

    // The "normal" size of the presentation, aspect ratio will be preserved
    // when the presentation is scaled to fit different resolutions. Can be
    // specified using percentage units.
    width: 1170,  // original: 960,
    height: 700,

    // Factor of the display size that should remain empty around the content
    margin: 0.1,

    // Bounds for smallest/largest possible scale to apply to content
    minScale: 0.2,
    maxScale: 1.0

});
</script>

<!-- begin footer logo
<div style="position: absolute; bottom: 0px; left: 0; margin-left: 0px">
<img src="somelogo.png">
</div>
     end footer logo -->



</body>
</html>

************** File: ._slides3-solarized3001.html *****************
<!--
Automatically generated HTML file from DocOnce source
(https://github.com/doconce/doconce/)
-->
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="DocOnce: https://github.com/doconce/doconce/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="description" content="On Schemes for Exponential Decay">

<title>On Schemes for Exponential Decay</title>


<link href="https://raw.github.com/doconce/doconce/master/bundled/html_styles/style_solarized_box/css/solarized_light_code.css" rel="stylesheet" type="text/css" title="light"/>
<script src="https://raw.github.com/doconce/doconce/master/bundled/html_styles/style_solarized_box/js/highlight.pack.js"></script>
<script>hljs.initHighlightingOnLoad();</script>

<link href="https://thomasf.github.io/solarized-css/solarized-light.min.css" rel="stylesheet">
<style type="text/css">
body, td {font-size: 140%;}
h1 {font-size: 200%;}
h2 {font-size: 180%;}

h1 {color: #b58900;}  /* yellow */
/* h1 {color: #cb4b16;}  orange */
/* h1 {color: #d33682;}  magenta, the original choice of thomasf */
code { padding: 0px; background-color: inherit; }
pre {
  border: 0pt solid #93a1a1;
  box-shadow: none;
}
.alert-text-small   { font-size: 80%;  }
.alert-text-large   { font-size: 130%; }
.alert-text-normal  { font-size: 90%;  }
.alert {
  padding:8px 35px 8px 14px; margin-bottom:18px;
  text-shadow:0 1px 0 rgba(255,255,255,0.5);
  border:1px solid #93a1a1;
  border-radius: 4px;
  -webkit-border-radius: 4px;
  -moz-border-radius: 4px;
  color: #555;
  background-color: #eee8d5;
  background-position: 10px 5px;
  background-repeat: no-repeat;
  background-size: 38px;
  padding-left: 55px;
  width: 75%;
 }
.alert-block {padding-top:14px; padding-bottom:14px}
.alert-block > p, .alert-block > ul {margin-bottom:1em}
.alert li {margin-top: 1em}
.alert-block p+p {margin-top:5px}
.alert-notice { background-image: url(https://raw.github.com/doconce/doconce/master/bundled/html_images/small_yellow_notice.png); }
.alert-summary  { background-image:url(https://raw.github.com/doconce/doconce/master/bundled/html_images/small_yellow_summary.png); }
.alert-warning { background-image: url(https://raw.github.com/doconce/doconce/master/bundled/html_images/small_yellow_warning.png); }
.alert-question {background-image:url(https://raw.github.com/doconce/doconce/master/bundled/html_images/small_yellow_question.png); }

div { text-align: justify; text-justify: inter-word; }
</style>


</head>

<!-- tocinfo
{'highest level': 1,
 'sections': [('Goal', 2, None, 'goal'),
              ('Methods', 1, None, 'methods'),
              ('Mathematical problem', 2, None, 'mathematical-problem'),
              ('Numerical solution method',
               2,
               None,
               'numerical-solution-method'),
              ('Forward Euler explained', 2, None, 'forward-euler-explained'),
              ('Implementation', 2, None, 'implementation'),
              ('Selected results', 1, None, 'selected-results'),
              ('The Crank-Nicolson method',
               2,
               None,
               'the-crank-nicolson-method'),
              ('The artifacts can be explained by some theory',
               2,
               None,
               'the-artifacts-can-be-explained-by-some-theory')]}
end of tocinfo -->

<body>



<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  TeX: {
     equationNumbers: {  autoNumber: "none"  },
     extensions: ["AMSmath.js", "AMSsymbols.js", "autobold.js", "color.js"]
  }
});
</script>
<script type="text/javascript" async
 src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>



    
<a name="part0001"></a>
<!-- !split -->

<h2 id="goal">Goal </h2>

<p>
The primary goal of this demo talk is to demonstrate how to write
talks with <a href="https://github.com/doconce/doconce" target="_self">DocOnce</a>
and get them rendered in numerous HTML formats.
<div class="alert alert-block alert-notice alert-text-normal">
<b>Layout</b>
<p>
This version
utilizes doconce slides with the theme solarized3.
</div>


<p>
<div class="alert alert-block alert-notice alert-text-normal">
<b>Notice</b>
<p>
Speaker notes show up by
</div>


<p>


<p>
<p>
<!-- begin bottom navigation -->
<table style="width: 100%"><tr><td>
\
<div style="text-align: left;"><a href="._slides3-solarized3000.html"><img src="https://hplgit.github.io/doconce/bundled/html_images/prev3.png" border=0 alt="&laquo; Previous"></a></div>
</td><td>
\
<div style="text-align: right;"><a href="._slides3-solarized3002.html"><img src="https://hplgit.github.io/doconce/bundled/html_images/next3.png" border=0 alt="Next &raquo;"></a></div>
</td></tr></table>
<!-- end bottom navigation -->
</p>

<!-- ------------------- end of main content --------------- -->


</body>
</html>
    


************** File: slides3.p.tex *****************
%%
%% Automatically generated file from DocOnce source
%% (https://github.com/hplgit/doconce/)
%%
%%
% #ifdef PTEX2TEX_EXPLANATION
%%
%% The file follows the ptex2tex extended LaTeX format, see
%% ptex2tex: https://code.google.com/p/ptex2tex/
%%
%% Run
%%      ptex2tex myfile
%% or
%%      doconce ptex2tex myfile
%%
%% to turn myfile.p.tex into an ordinary LaTeX file myfile.tex.
%% (The ptex2tex program: https://code.google.com/p/ptex2tex)
%% Many preprocess options can be added to ptex2tex or doconce ptex2tex
%%
%%      ptex2tex -DMINTED myfile
%%      doconce ptex2tex myfile envir=minted
%%
%% ptex2tex will typeset code environments according to a global or local
%% .ptex2tex.cfg configure file. doconce ptex2tex will typeset code
%% according to options on the command line (just type doconce ptex2tex to
%% see examples). If doconce ptex2tex has envir=minted, it enables the
%% minted style without needing -DMINTED.
% #endif

% #define PREAMBLE

% #ifdef PREAMBLE
%-------------------- begin preamble ----------------------

\documentclass[%
oneside,                 % oneside: electronic viewing, twoside: printing
final,                   % draft: marks overfull hboxes, figures with paths
10pt]{article}

\listfiles               %  print all files needed to compile this document

\usepackage{relsize,makeidx,color,setspace,amsmath,amsfonts,amssymb}
\usepackage[table]{xcolor}
\usepackage{bm,ltablex,microtype}

\usepackage[pdftex]{graphicx}

\usepackage{ptex2tex}
% #ifdef MINTED
\usepackage{minted}
\usemintedstyle{default}
% #endif

\usepackage[T1]{fontenc}
%\usepackage[latin1]{inputenc}
\usepackage{ucs}
\usepackage[utf8x]{inputenc}

\usepackage{lmodern}         % Latin Modern fonts derived from Computer Modern

% Hyperlinks in PDF:
\definecolor{linkcolor}{rgb}{0,0,0.4}
\usepackage{hyperref}
\hypersetup{
    breaklinks=true,
    colorlinks=true,
    linkcolor=linkcolor,
    urlcolor=linkcolor,
    citecolor=black,
    filecolor=black,
    %filecolor=blue,
    pdfmenubar=true,
    pdftoolbar=true,
    bookmarksdepth=3   % Uncomment (and tweak) for PDF bookmarks with more levels than the TOC
    }
%\hyperbaseurl{}   % hyperlinks are relative to this root

\setcounter{tocdepth}{2}  % levels in table of contents

% Tricks for having figures close to where they are defined:
% 1. define less restrictive rules for where to put figures
\setcounter{topnumber}{2}
\setcounter{bottomnumber}{2}
\setcounter{totalnumber}{4}
\renewcommand{\topfraction}{0.95}
\renewcommand{\bottomfraction}{0.95}
\renewcommand{\textfraction}{0}
\renewcommand{\floatpagefraction}{0.75}
% floatpagefraction must always be less than topfraction!
% 2. ensure all figures are flushed before next section
\usepackage[section]{placeins}
% 3. enable begin{figure}[H] (often leads to ugly pagebreaks)
%\usepackage{float}\restylefloat{figure}

\usepackage[framemethod=TikZ]{mdframed}

% --- begin definitions of admonition environments ---

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "notice" admon
\colorlet{mdfbox_notice_background}{gray!5}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_notice_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=mdfbox_notice_background,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{notice_mdfboxmdframed}

\newenvironment{notice_mdfboxadmon}[1][]{
\begin{notice_mdfboxmdframed}[frametitle=#1]
}
{
\end{notice_mdfboxmdframed}
}

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "summary" admon
\colorlet{mdfbox_summary_background}{gray!5}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_summary_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=mdfbox_summary_background,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{summary_mdfboxmdframed}

\newenvironment{summary_mdfboxadmon}[1][]{
\begin{summary_mdfboxmdframed}[frametitle=#1]
}
{
\end{summary_mdfboxmdframed}
}

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "warning" admon
\colorlet{mdfbox_warning_background}{gray!5}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_warning_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=mdfbox_warning_background,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{warning_mdfboxmdframed}

\newenvironment{warning_mdfboxadmon}[1][]{
\begin{warning_mdfboxmdframed}[frametitle=#1]
}
{
\end{warning_mdfboxmdframed}
}

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "question" admon
\colorlet{mdfbox_question_background}{gray!5}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_question_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=mdfbox_question_background,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{question_mdfboxmdframed}

\newenvironment{question_mdfboxadmon}[1][]{
\begin{question_mdfboxmdframed}[frametitle=#1]
}
{
\end{question_mdfboxmdframed}
}

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "block" admon
\colorlet{mdfbox_block_background}{gray!5}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_block_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=mdfbox_block_background,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{block_mdfboxmdframed}

\newenvironment{block_mdfboxadmon}[1][]{
\begin{block_mdfboxmdframed}[frametitle=#1]
}
{
\end{block_mdfboxmdframed}
}

% --- end of definitions of admonition environments ---

% prevent orhpans and widows
\clubpenalty = 10000
\widowpenalty = 10000

% --- end of standard preamble for documents ---


% insert custom LaTeX commands...

\raggedbottom
\makeindex

%-------------------- end preamble ----------------------

\begin{document}

% matching end for #ifdef PREAMBLE
% #endif

\newcommand{\exercisesection}[1]{\subsection*{#1}}

\input{newcommands_bfmath}
\input{newcommands_replace}

% ------------------- main content ----------------------



% ----------------- title -------------------------

\title{On Schemes for Exponential Decay}

% ----------------- author(s) -------------------------

\author{Hans Petter Langtangen\inst{1,2}}
\institute{Center for Biomedical Computing, Simula Research Laboratory\inst{1}
\and
Department of Informatics, University of Oslo\inst{2}}
% ----------------- end author(s) -------------------------

\date{Jan 32, 2100
% <optional titlepage figure>
% <optional copyright>
}

\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=0.4\linewidth]{../doc/src/slides/fig/CN_logo.pdf}}

\vspace{6mm}




% !split
\subsection{Goal}

The primary goal of this demo talk is to demonstrate how to write
talks with \href{{https://github.com/doconce/doconce}}{DocOnce}
and get them rendered in numerous HTML formats.
\begin{block}{Layout }
This version
utilizes beamer slides with the theme red_plain.
\end{block}




% !bnotes
The talk investigates the accuracy of three finite difference
schemes for the ordinary differential equation $u'=-au$ with the
aid of numerical experiments. Numerical artifacts are in particular
demonstrated.
% !enotes

% !split
\section{Methods}


% !split
\subsection{Mathematical problem}


% !bslidecell 00


\begin{align}
u'(t) &= -au(t),
\label{ode}\\ 
u(0)  &= I,
\label{initial:value}
\end{align}

\begin{itemize}
 \item $t\in (0,T]$

 \item $a$, $I$, and $T$ are prescribed parameters

 \item $u(t)$ is the unknown function
\end{itemize}

\noindent
% !eslidecell


% !bslidecell 01


\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=0.5\linewidth]{../doc/src/slides/fig/teacher2.jpg}}

\vspace{6mm}


% !eslidecell

% !split
\subsection{Numerical solution method}


% !bpop
\begin{itemize}
 \item Mesh in time: $0= t_0< t_1 \cdots < t_N=T$

 \item Assume constant $\Delta t = t_{n}-t_{n-1}$

 \item $u^n$: numerical approx to the exact solution at $t_n$
\end{itemize}

\noindent
% !epop

% !bpop
Numerical scheme:
   \[
   u^{n+1} = \frac{1 - (1-\theta) a\Delta t}{1 + \theta a\Delta t}u^n,
   \quad n=0,1,\ldots,N-1
   \]
% !epop


% !split

\subsection{Implementation}

The numerical method is implemented in a Python function:

\bpycod
def solver(I, a, T, dt, theta):
    """Solve u'=-a*u, u(0)=I, for t in (0,T]; step: dt."""
    dt = float(dt)           # avoid integer division
    N = int(round(old_div(T,dt)))     # no of time intervals
    T = N*dt                 # adjust T to fit time step dt
    u = zeros(N+1)           # array of u[n] values
    t = linspace(0, T, N+1)  # time mesh

    u[0] = I                 # assign initial condition
    for n in range(0, N):    # n=0,1,...,N-1
        u[n+1] = (1 - (1-theta)*a*dt)/(1 + theta*dt*a)*u[n]
    return u, t
\epycod

% !split
\section{Selected results}
% Short title: Results


% !split
\subsection{The Crank-Nicolson method}




\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=0.9\linewidth]{../doc/src/slides/fig/CN.pdf}}

\vspace{6mm}



% !split
\subsection{The artifacts can be explained by some theory}

% !bpop
Exact solution of the scheme:

\[ u^n = A^n,\quad A = \frac{1 - (1-\theta) a\Delta t}{1 + \theta a\Delta t}\thinspace .\]
% !epop

% !bpop
\begin{itemize}
 \item Stability: $|A| < 1$

 \item No oscillations: $A>0$

 \item Always for Backward Euler ($\theta=1$)

 \item $\Delta t < 1/a$ for Forward Euler ($\theta=0$)

 \item $\Delta t < 2/a$ for Crank-Nicolson ($\theta=1/2$)
\end{itemize}

\noindent
% !epop

% !bpop
\begin{block}{Concluding remarks: }
Only the Backward Euler scheme is guaranteed to always give
qualitatively correct results.
\end{block}
% !epop

% ------------------- end of main content ---------------

% #ifdef PREAMBLE
\end{document}
% #endif


************** File: slides3.tex *****************

% LaTeX Beamer file automatically generated from DocOnce
% https://github.com/hplgit/doconce

%-------------------- begin beamer-specific preamble ----------------------

\documentclass{beamer}

\usetheme{red_plain}
\usecolortheme{default}

% turn off the almost invisible, yet disturbing, navigation symbols:
\setbeamertemplate{navigation symbols}{}

% Examples on customization:
%\usecolortheme[named=RawSienna]{structure}
%\usetheme[height=7mm]{Rochester}
%\setbeamerfont{frametitle}{family=\rmfamily,shape=\itshape}
%\setbeamertemplate{items}[ball]
%\setbeamertemplate{blocks}[rounded][shadow=true]
%\useoutertheme{infolines}
%
%\usefonttheme{}
%\useinntertheme{}
%
%\setbeameroption{show notes}
%\setbeameroption{show notes on second screen=right}

% fine for B/W printing:
%\usecolortheme{seahorse}

\usepackage{pgf}
\usepackage{graphicx}
\usepackage{epsfig}
\usepackage{relsize}

\usepackage{fancybox}  % make sure fancybox is loaded before fancyvrb

\usepackage{fancyvrb}
\usepackage{minted} % requires pygments and latex -shell-escape filename
%\usepackage{anslistings}
%\usepackage{listingsutf8}

\usepackage{amsmath,amssymb,bm}
%\usepackage[latin1]{inputenc}
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage{colortbl}
\usepackage[english]{babel}
\usepackage{tikz}
\usepackage{framed}
% Use some nice templates
\beamertemplatetransparentcovereddynamic

% --- begin table of contents based on sections ---
% Delete this, if you do not want the table of contents to pop up at
% the beginning of each section:
% (Only section headings can enter the table of contents in Beamer
% slides generated from DocOnce source, while subsections are used
% for the title in ordinary slides.)
\AtBeginSection[]
{
  \begin{frame}<beamer>[plain]
  \frametitle{}
  %\frametitle{Outline}
  \tableofcontents[currentsection]
  \end{frame}
}
% --- end table of contents based on sections ---

% If you wish to uncover everything in a step-wise fashion, uncomment
% the following command:

%\beamerdefaultoverlayspecification{<+->}

\newcommand{\shortinlinecomment}[3]{\note{\textbf{#1}: #2}}
\newcommand{\longinlinecomment}[3]{\shortinlinecomment{#1}{#2}{#3}}

\definecolor{linkcolor}{rgb}{0,0,0.4}
\hypersetup{
    colorlinks=true,
    linkcolor=linkcolor,
    urlcolor=linkcolor,
    pdfmenubar=true,
    pdftoolbar=true,
    bookmarksdepth=3
    }
\setlength{\parskip}{0pt}  % {1em}

\newenvironment{doconceexercise}{}{}
\newcounter{doconceexercisecounter}
\newenvironment{doconce:movie}{}{}
\newcounter{doconce:movie:counter}

\newcommand{\subex}[1]{\noindent\textbf{#1}}  % for subexercises: a), b), etc

%-------------------- end beamer-specific preamble ----------------------

% Add user's preamble




% insert custom LaTeX commands...

\raggedbottom
\makeindex

%-------------------- end preamble ----------------------

\begin{document}

% matching end for #ifdef PREAMBLE

\newcommand{\exercisesection}[1]{\subsection*{#1}}

\input{newcommands_bfmath}
\input{newcommands_replace}


% ------------------- main content ----------------------



% ----------------- title -------------------------

\title{On Schemes for Exponential Decay}

% ----------------- author(s) -------------------------

\author{Hans Petter Langtangen\inst{1,2}}
\institute{Center for Biomedical Computing, Simula Research Laboratory\inst{1}
\and
Department of Informatics, University of Oslo\inst{2}}
% ----------------- end author(s) -------------------------

\date{Jan 32, 2100
\\ \ \\ 
\centerline{\includegraphics[width=0.4\linewidth]{../doc/src/slides/fig/CN_logo.pdf}}
% <optional copyright>
}

\vspace{6mm}



\vspace{6mm}

\begin{frame}[plain,fragile]
\titlepage
\end{frame}

\begin{frame}[plain,fragile]
\frametitle{Goal}

The primary goal of this demo talk is to demonstrate how to write
talks with \href{{https://github.com/doconce/doconce}}{DocOnce}
and get them rendered in numerous HTML formats.
\begin{block}{Layout }
This version
utilizes beamer slides with the theme red_plain.
\end{block}




\note{
The talk investigates the accuracy of three finite difference
schemes for the ordinary differential equation $u'=-au$ with the
aid of numerical experiments. Numerical artifacts are in particular
demonstrated.
}
\end{frame}

\section{Methods}

\begin{frame}[plain,fragile]
\frametitle{Mathematical problem}

\begin{columns}
\column{0.5\textwidth}
\begin{align}
u'(t) &= -au(t),
\label{ode}\\ 
u(0)  &= I,
\label{initial:value}
\end{align}

\begin{itemize}
 \item $t\in (0,T]$

 \item $a$, $I$, and $T$ are prescribed parameters

 \item $u(t)$ is the unknown function
\end{itemize}

\noindent

\column{0.5\textwidth}
\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=0.5\linewidth]{../doc/src/slides/fig/teacher2.jpg}}

\vspace{6mm}



\end{columns}
\end{frame}

\begin{frame}[plain,fragile]
\frametitle{Numerical solution method}

\begin{itemize}
\pause
 \item Mesh in time: $0= t_0< t_1 \cdots < t_N=T$

\pause
 \item Assume constant $\Delta t = t_{n}-t_{n-1}$

\pause
 \item $u^n$: numerical approx to the exact solution at $t_n$
\end{itemize}

\noindent

\pause
Numerical scheme:
   \[
   u^{n+1} = \frac{1 - (1-\theta) a\Delta t}{1 + \theta a\Delta t}u^n,
   \quad n=0,1,\ldots,N-1
   \]
\end{frame}

\begin{frame}[plain,fragile]
\frametitle{Implementation}

The numerical method is implemented in a Python function:

\begin{minted}[fontsize=\fontsize{9pt}{9pt},linenos=false,mathescape,baselinestretch=1.0,fontfamily=tt,xleftmargin=2mm]{python}
def solver(I, a, T, dt, theta):
    """Solve u'=-a*u, u(0)=I, for t in (0,T]; step: dt."""
    dt = float(dt)           # avoid integer division
    N = int(round(old_div(T,dt)))     # no of time intervals
    T = N*dt                 # adjust T to fit time step dt
    u = zeros(N+1)           # array of u[n] values
    t = linspace(0, T, N+1)  # time mesh

    u[0] = I                 # assign initial condition
    for n in range(0, N):    # n=0,1,...,N-1
        u[n+1] = (1 - (1-theta)*a*dt)/(1 + theta*dt*a)*u[n]
    return u, t
\end{minted}
\end{frame}

\section[Results]{Selected results}

\begin{frame}[plain,fragile]
\frametitle{The Crank-Nicolson method}

\vspace{6mm}

% inline figure
\centerline{\includegraphics[width=0.9\linewidth]{../doc/src/slides/fig/CN.pdf}}

\vspace{6mm}
\end{frame}

\begin{frame}[plain,fragile]
\frametitle{The artifacts can be explained by some theory}

\pause
Exact solution of the scheme:

\[ u^n = A^n,\quad A = \frac{1 - (1-\theta) a\Delta t}{1 + \theta a\Delta t}\thinspace .\]

\begin{itemize}
\pause
 \item Stability: $|A| < 1$

\pause
 \item No oscillations: $A>0$

\pause
 \item Always for Backward Euler ($\theta=1$)

\pause
 \item $\Delta t < 1/a$ for Forward Euler ($\theta=0$)

\pause
 \item $\Delta t < 2/a$ for Crank-Nicolson ($\theta=1/2$)
\end{itemize}

\noindent

\pause
\begin{block}{Concluding remarks: }
Only the Backward Euler scheme is guaranteed to always give
qualitatively correct results.
\end{block}
\end{frame}

\end{document}

************** File: table_1.csv *****************
time,velocity,acceleration
0.0,1.4186,-5.01
2.0,1.376512,11.919
4.0,1.1E+1,14.717624

************** File: table_2.csv *****************
time,velocity,acceleration
0.0,1.4186,-5.01
1.0,1.376512,11.919
3.0,1.1E+1,14.717624

************** File: table_3.csv *****************
i,h_i,\bar T_i,L_i
0,0,288,-0.0065
1,"11,000",216,0.0
2,"20,000",216,0.001
3,"32,000",228,0.0028
4,"47,000",270,0.0
5,"51,000",270,-0.0028
6,"71,000",214,NaN

************** File: table_4.csv *****************
exact,v_1,a_i + v_2,verb_3_
9,9.62,5.57,8.98
-20,-23.39,-7.65,-19.93
10,17.74,-4.50,9.96
0,-9.19,4.13,-0.26

************** File: testtable.csv *****************
i,h_i,\bar T_i,L_i
0,0,288,-0.0065
1,"11,000",216,0.0, 1, 2, 3
2,"20,000",216,   0.001
3,"32,000",228, 0.0028
4,"47,000",   270,0.0
5,"51,000",270,-0.0028
6,"71,000",214, NaN

************** File: testtable.do.txt *****************


|----c----------c----------c----------c----------c----------c----------c-----|
| i        | h_i      | \bar T_i | L_i      |          |          |          |
|----c----------c----------c----------c----------c----------c----------c-----|
| 0        | 0        | 288      | -0.0065  |          |          |          |
| 1        | 11,000   | 216      | 0.0      | 1        | 2        | 3        |
| 2        | 20,000   | 216      | 0.001    |          |          |          |
| 3        | 32,000   | 228      | 0.0028   |          |          |          |
| 4        | 47,000   | 270      | 0.0      |          |          |          |
| 5        | 51,000   | 270      | -0.0028  |          |          |          |
| 6        | 71,000   | 214      | NaN      |          |          |          |
|----------------------------------------------------------------------------|



************** File: github_md.md *****************
<!-- Test of GitHub Flavored Markdown -->

<!-- Write in doconce -->
<!-- Translate with doconce format pandoc githu_md --github_md -->

> ### Problems with a function
> 
> There is a problem with the `f(x)` function
> 
> 
> ```python
> def f(x):
>     return 1 + x
> ```
> 
> This function should be quadratic.



OK, this is fixed:


```python
def f(x, a=1, b=1, c=1):
    return a*x**2 + b*x + c
```

### Updated task list

   - [x] Offer an `f(x)` function
   - [ ] Extension to cubic functions
   - [x] Allowing general coefficient in the quadratic function

#### Remaining functionality

<table border="1">
<thead>
<tr><th align="center">function</th> <th align="center">           purpose            </th> <th align="center">      state      </th> </tr>
</thead>
<tbody>
<tr><td align="left">   <code>g(x)</code>      </td> <td align="left">   Compute the Gaussian function.    </td> <td align="left">   Formula ready.       </td> </tr>
<tr><td align="left">   <code>h(x)</code>      </td> <td align="left">   Heaviside function.               </td> <td align="left">   Formula ready.       </td> </tr>
<tr><td align="left">   <code>I(x)</code>      </td> <td align="left">   Indicator function.               </td> <td align="left">   Nothing done yet.    </td> </tr>
</tbody>
</table>


************** File: movies.do.txt *****************
TITLE: This is a demo of movies in DocOnce
AUTHOR: HPL
DATE: today


Here is a movie in WebM format.
# #if FORMAT == "html"
Note that in HTML format a WebM movie
may actually be the MP4 version of this movie
three alternative sources (MP4, WebM, OGG)
are inserted in the HTML code by default. The command-line
option `--no_mp4_webm_ogg_alternatives` makes the HTML
code use exactly the specified movie file.
# #endif

MOVIE: [../doc/src/manual/mov/wave.webm, width=700 height=400] 1D wave in WebM.

Here is the same movie in Ogg format:

MOVIE: [../doc/src/manual/mov/wave.ogg, width=700 height=400] 1D wave in Ogg.

Here is the same movie in MP4 format:

MOVIE: [../doc/src/manual/mov/wave.mp4, width=700 height=400] 1D wave in MP4.

Here is the same movie in Flash format:

MOVIE: [../doc/src/manual/mov/wave.flv, width=700 height=400] 1D wave in Flash.

And here is a collection of images shown as an animation
(`frame_*.png`):

MOVIE: [../doc/src/manual/mov/wave_frames/frame_*.png, width=700 height=400] Animated collection of images.

Here is the same collection, but with images in cyberspace, given as URLs:

!bc
https://hplgit.github.io/animate/..../frame_%04d.png:80->129
!ec

MOVIE: [https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_%04d.png:80->129] Taking images to animate from cyberspace.

The movie above in MPEG format, typeset in a box:

!bbox
MOVIE: [../doc/src/manual/mov/wave.mpeg, width=700 height=400] 1D wave in MPEG. label{mov:wave}
!ebox

Here is the same movie in AVI format:

MOVIE: [../doc/src/manual/mov/wave.avi, width=700 height=400] 1D wave in AVI.

Here is the same movie, but with a URL to GitHub:

MOVIE: [https://hplgit.github.io/animate/doc/pub/mov-animate/demo.ogg]

Here is a YouTube video:

MOVIE: [https://www.youtube.com/watch?v=_O7iUiftbKU, width=420 height=315] YouTube movie.

And a vimeo video:

MOVIE: [https://vimeo.com/55562330, width=500 height=278] Vimeo movie.


Finally, let us demonstrate referencing the movie ref{mov:wave}.
************** File: movies_3choices.html *****************
<!--
Automatically generated HTML file from DocOnce source
(https://github.com/doconce/doconce/)
-->
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="DocOnce: https://github.com/doconce/doconce/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="description" content="This is a demo of movies in DocOnce">

<title>This is a demo of movies in DocOnce</title>


<style type="text/css">
/* blueish style */

/* Color definitions:  https://www.december.com/html/spec/color0.html
   CSS examples:       https://www.w3schools.com/css/css_examples.asp */

body {
  margin-top: 1.0em;
  background-color: #ffffff;
  font-family: Helvetica, Arial, FreeSans, san-serif;
  color: #000000;
}
h1 { font-size: 1.8em; color: #1e36ce; }
h2 { font-size: 1.6em; color: #1e36ce; }
h3 { font-size: 1.4em; color: #1e36ce; }
a { color: #1e36ce; text-decoration:none; }
tt { font-family: "Courier New", Courier; }
/* pre style removed because it will interfer with pygments */
p { text-indent: 0px; }
hr { border: 0; width: 80%; border-bottom: 1px solid #aaa}
p.caption { width: 80%; font-style: normal; text-align: left; }
hr.figure { border: 0; width: 80%; border-bottom: 1px solid #aaa}

div { text-align: justify; text-justify: inter-word; }
</style>


</head>

<!-- tocinfo
{'highest level': 4, 'sections': []}
end of tocinfo -->

<body>

    
<!-- ------------------- main content ---------------------- -->



<center><h1>This is a demo of movies in DocOnce</h1></center>  <!-- document title -->

<p>
<!-- author(s): HPL -->

<center>
<b>HPL</b> 
</center>

<p>
<!-- institution(s) -->

<br>
<p>
<center><h4>Jan 32, 2100</h4></center> <!-- date -->
<br>
<p>
Here is a movie in WebM format.
Note that in HTML format a WebM movie
may actually be the MP4 version of this movie
three alternative sources (MP4, WebM, OGG)
are inserted in the HTML code by default. The command-line
option <code>--no_mp4_webm_ogg_alternatives</code> makes the HTML
code use exactly the specified movie file.

<p>

<div>
<video  loop controls width='700' height='400' preload='none'>
    <source src='../doc/src/manual/mov/wave.mp4'  type='video/mp4;  codecs="avc1.42E01E, mp4a.40.2"'>
    <source src='../doc/src/manual/mov/wave.webm' type='video/webm; codecs="vp8, vorbis"'>
    <source src='../doc/src/manual/mov/wave.ogg'  type='video/ogg;  codecs="theora, vorbis"'>
</video>
</div>
<p><em>1D wave in WebM.</em></p>

<!-- Issue warning if in a Safari browser -->
<script language="javascript">
if (!!(window.safari)) {
  document.write("<div style=\"width: 95%%; padding: 10px; border: 1px solid #100; border-radius: 4px;\"><p><font color=\"red\">The above movie will not play in Safari - use Chrome, Firefox, or Opera.</font></p></div>")}
</script>

<p>
Here is the same movie in Ogg format:

<p>

<div>
<video  loop controls width='700' height='400' preload='none'>
    <source src='../doc/src/manual/mov/wave.mp4'  type='video/mp4;  codecs="avc1.42E01E, mp4a.40.2"'>
    <source src='../doc/src/manual/mov/wave.webm' type='video/webm; codecs="vp8, vorbis"'>
    <source src='../doc/src/manual/mov/wave.ogg'  type='video/ogg;  codecs="theora, vorbis"'>
</video>
</div>
<p><em>1D wave in Ogg.</em></p>

<!-- Issue warning if in a Safari browser -->
<script language="javascript">
if (!!(window.safari)) {
  document.write("<div style=\"width: 95%%; padding: 10px; border: 1px solid #100; border-radius: 4px;\"><p><font color=\"red\">The above movie will not play in Safari - use Chrome, Firefox, or Opera.</font></p></div>")}
</script>

<p>
Here is the same movie in MP4 format:

<p>

<div>
<video  loop controls width='700' height='400' preload='none'>
    <source src='../doc/src/manual/mov/wave.mp4'  type='video/mp4;  codecs="avc1.42E01E, mp4a.40.2"'>
    <source src='../doc/src/manual/mov/wave.webm' type='video/webm; codecs="vp8, vorbis"'>
    <source src='../doc/src/manual/mov/wave.ogg'  type='video/ogg;  codecs="theora, vorbis"'>
</video>
</div>
<p><em>1D wave in MP4.</em></p>

<!-- Issue warning if in a Safari browser -->
<script language="javascript">
if (!!(window.safari)) {
  document.write("<div style=\"width: 95%%; padding: 10px; border: 1px solid #100; border-radius: 4px;\"><p><font color=\"red\">The above movie will not play in Safari - use Chrome, Firefox, or Opera.</font></p></div>")}
</script>

<p>
Here is the same movie in Flash format:

<p>

<embed src="../doc/src/manual/mov/wave.flv" width=700 height=400 autoplay="false" loop="true"></embed>
<p><em>1D wave in Flash.</em></p>

<p>
And here is a collection of images shown as an animation
(<code>frame_*.png</code>):

<p>

<script language="Javascript">
<!---
var num_images____doc_src_manual_mov_wave_frames_frame_0080 = 50;
var img_width____doc_src_manual_mov_wave_frames_frame_0080 = 700;
var img_height____doc_src_manual_mov_wave_frames_frame_0080 = 400;
var interval____doc_src_manual_mov_wave_frames_frame_0080 = 300;
var images____doc_src_manual_mov_wave_frames_frame_0080 = new Array();

function preload_images____doc_src_manual_mov_wave_frames_frame_0080()
{
   t = document.getElementById("progress");

   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[0] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[0].src = "../doc/src/manual/mov/wave_frames/frame_0080.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[1] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[1].src = "../doc/src/manual/mov/wave_frames/frame_0081.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[2] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[2].src = "../doc/src/manual/mov/wave_frames/frame_0082.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[3] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[3].src = "../doc/src/manual/mov/wave_frames/frame_0083.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[4] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[4].src = "../doc/src/manual/mov/wave_frames/frame_0084.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[5] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[5].src = "../doc/src/manual/mov/wave_frames/frame_0085.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[6] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[6].src = "../doc/src/manual/mov/wave_frames/frame_0086.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[7] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[7].src = "../doc/src/manual/mov/wave_frames/frame_0087.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[8] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[8].src = "../doc/src/manual/mov/wave_frames/frame_0088.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[9] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[9].src = "../doc/src/manual/mov/wave_frames/frame_0089.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[10] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[10].src = "../doc/src/manual/mov/wave_frames/frame_0090.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[11] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[11].src = "../doc/src/manual/mov/wave_frames/frame_0091.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[12] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[12].src = "../doc/src/manual/mov/wave_frames/frame_0092.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[13] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[13].src = "../doc/src/manual/mov/wave_frames/frame_0093.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[14] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[14].src = "../doc/src/manual/mov/wave_frames/frame_0094.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[15] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[15].src = "../doc/src/manual/mov/wave_frames/frame_0095.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[16] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[16].src = "../doc/src/manual/mov/wave_frames/frame_0096.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[17] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[17].src = "../doc/src/manual/mov/wave_frames/frame_0097.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[18] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[18].src = "../doc/src/manual/mov/wave_frames/frame_0098.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[19] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[19].src = "../doc/src/manual/mov/wave_frames/frame_0099.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[20] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[20].src = "../doc/src/manual/mov/wave_frames/frame_0100.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[21] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[21].src = "../doc/src/manual/mov/wave_frames/frame_0101.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[22] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[22].src = "../doc/src/manual/mov/wave_frames/frame_0102.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[23] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[23].src = "../doc/src/manual/mov/wave_frames/frame_0103.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[24] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[24].src = "../doc/src/manual/mov/wave_frames/frame_0104.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[25] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[25].src = "../doc/src/manual/mov/wave_frames/frame_0105.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[26] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[26].src = "../doc/src/manual/mov/wave_frames/frame_0106.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[27] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[27].src = "../doc/src/manual/mov/wave_frames/frame_0107.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[28] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[28].src = "../doc/src/manual/mov/wave_frames/frame_0108.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[29] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[29].src = "../doc/src/manual/mov/wave_frames/frame_0109.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[30] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[30].src = "../doc/src/manual/mov/wave_frames/frame_0110.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[31] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[31].src = "../doc/src/manual/mov/wave_frames/frame_0111.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[32] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[32].src = "../doc/src/manual/mov/wave_frames/frame_0112.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[33] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[33].src = "../doc/src/manual/mov/wave_frames/frame_0113.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[34] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[34].src = "../doc/src/manual/mov/wave_frames/frame_0114.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[35] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[35].src = "../doc/src/manual/mov/wave_frames/frame_0115.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[36] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[36].src = "../doc/src/manual/mov/wave_frames/frame_0116.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[37] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[37].src = "../doc/src/manual/mov/wave_frames/frame_0117.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[38] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[38].src = "../doc/src/manual/mov/wave_frames/frame_0118.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[39] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[39].src = "../doc/src/manual/mov/wave_frames/frame_0119.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[40] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[40].src = "../doc/src/manual/mov/wave_frames/frame_0120.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[41] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[41].src = "../doc/src/manual/mov/wave_frames/frame_0121.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[42] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[42].src = "../doc/src/manual/mov/wave_frames/frame_0122.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[43] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[43].src = "../doc/src/manual/mov/wave_frames/frame_0123.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[44] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[44].src = "../doc/src/manual/mov/wave_frames/frame_0124.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[45] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[45].src = "../doc/src/manual/mov/wave_frames/frame_0125.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[46] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[46].src = "../doc/src/manual/mov/wave_frames/frame_0126.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[47] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[47].src = "../doc/src/manual/mov/wave_frames/frame_0127.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[48] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[48].src = "../doc/src/manual/mov/wave_frames/frame_0128.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[49] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[49].src = "../doc/src/manual/mov/wave_frames/frame_0129.png";
        
   t.innerHTML = "";
}

function tick____doc_src_manual_mov_wave_frames_frame_0080()
{
   if (frame____doc_src_manual_mov_wave_frames_frame_0080 > num_images____doc_src_manual_mov_wave_frames_frame_0080 - 1)
       frame____doc_src_manual_mov_wave_frames_frame_0080 = 0;

   document.name____doc_src_manual_mov_wave_frames_frame_0080.src = images____doc_src_manual_mov_wave_frames_frame_0080[frame____doc_src_manual_mov_wave_frames_frame_0080].src;
   frame____doc_src_manual_mov_wave_frames_frame_0080 += 1;
   tt = setTimeout("tick____doc_src_manual_mov_wave_frames_frame_0080()", interval____doc_src_manual_mov_wave_frames_frame_0080);
}

function startup____doc_src_manual_mov_wave_frames_frame_0080()
{
   preload_images____doc_src_manual_mov_wave_frames_frame_0080();
   frame____doc_src_manual_mov_wave_frames_frame_0080 = 0;
   setTimeout("tick____doc_src_manual_mov_wave_frames_frame_0080()", interval____doc_src_manual_mov_wave_frames_frame_0080);
}

function stopit____doc_src_manual_mov_wave_frames_frame_0080()
{ clearTimeout(tt); }

function restart____doc_src_manual_mov_wave_frames_frame_0080()
{ tt = setTimeout("tick____doc_src_manual_mov_wave_frames_frame_0080()", interval____doc_src_manual_mov_wave_frames_frame_0080); }

function slower____doc_src_manual_mov_wave_frames_frame_0080()
{ interval____doc_src_manual_mov_wave_frames_frame_0080 = interval____doc_src_manual_mov_wave_frames_frame_0080/0.7; }

function faster____doc_src_manual_mov_wave_frames_frame_0080()
{ interval____doc_src_manual_mov_wave_frames_frame_0080 = interval____doc_src_manual_mov_wave_frames_frame_0080*0.7; }

// --->
</script>

<form>
&nbsp;
<input type="button" value="Start movie" onClick="startup____doc_src_manual_mov_wave_frames_frame_0080()">
<input type="button" value="Pause movie" onClick="stopit____doc_src_manual_mov_wave_frames_frame_0080()">
<input type="button" value="Restart movie" onClick="restart____doc_src_manual_mov_wave_frames_frame_0080()">
&nbsp;
<input type="button" value="Slower" onClick="slower____doc_src_manual_mov_wave_frames_frame_0080()">
<input type="button" value="Faster" onClick="faster____doc_src_manual_mov_wave_frames_frame_0080()">
</form>

<p><div ID="progress"></div></p>
<img src="../doc/src/manual/mov/wave_frames/frame_0080.png" name="name____doc_src_manual_mov_wave_frames_frame_0080" border=2/>

<br><em>Animated collection of images.</em><br>

<p>
Here is the same collection, but with images in cyberspace, given as URLs:

<p>

<!-- code=text typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>https://hplgit.github.io/animate/..../frame_%04d.png:80-&gt;129
</pre></div>
<p>

<script language="Javascript">
<!---
var num_images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080 = 50;
var img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080 = 800;
var img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080 = 600;
var interval_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080 = 300;
var images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080 = new Array();

function preload_images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080()
{
   t = document.getElementById("progress");

   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[0] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[0].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0080.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[1] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[1].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0081.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[2] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[2].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0082.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[3] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[3].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0083.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[4] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[4].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0084.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[5] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[5].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0085.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[6] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[6].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0086.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[7] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[7].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0087.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[8] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[8].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0088.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[9] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[9].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0089.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[10] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[10].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0090.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[11] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[11].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0091.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[12] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[12].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0092.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[13] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[13].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0093.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[14] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[14].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0094.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[15] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[15].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0095.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[16] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[16].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0096.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[17] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[17].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0097.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[18] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[18].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0098.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[19] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[19].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0099.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[20] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[20].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0100.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[21] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[21].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0101.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[22] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[22].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0102.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[23] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[23].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0103.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[24] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[24].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0104.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[25] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[25].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0105.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[26] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[26].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0106.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[27] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[27].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0107.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[28] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[28].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0108.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[29] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[29].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0109.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[30] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[30].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0110.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[31] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[31].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0111.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[32] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[32].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0112.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[33] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[33].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0113.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[34] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[34].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0114.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[35] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[35].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0115.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[36] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[36].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0116.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[37] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[37].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0117.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[38] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[38].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0118.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[39] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[39].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0119.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[40] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[40].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0120.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[41] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[41].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0121.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[42] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[42].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0122.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[43] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[43].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0123.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[44] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[44].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0124.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[45] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[45].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0125.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[46] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[46].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0126.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[47] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[47].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0127.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[48] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[48].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0128.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[49] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[49].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0129.png";
        
   t.innerHTML = "";
}

function tick_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080()
{
   if (frame_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080 > num_images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080 - 1)
       frame_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080 = 0;

   document.name_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080.src = images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[frame_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080].src;
   frame_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080 += 1;
   tt = setTimeout("tick_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080()", interval_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
}

function startup_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080()
{
   preload_images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080();
   frame_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080 = 0;
   setTimeout("tick_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080()", interval_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
}

function stopit_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080()
{ clearTimeout(tt); }

function restart_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080()
{ tt = setTimeout("tick_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080()", interval_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080); }

function slower_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080()
{ interval_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080 = interval_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080/0.7; }

function faster_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080()
{ interval_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080 = interval_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080*0.7; }

// --->
</script>

<form>
&nbsp;
<input type="button" value="Start movie" onClick="startup_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080()">
<input type="button" value="Pause movie" onClick="stopit_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080()">
<input type="button" value="Restart movie" onClick="restart_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080()">
&nbsp;
<input type="button" value="Slower" onClick="slower_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080()">
<input type="button" value="Faster" onClick="faster_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080()">
</form>

<p><div ID="progress"></div></p>
<img src="https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0080.png" name="name_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080" border=2/>

<br><em>Taking images to animate from cyberspace.</em><br>

<p>
The movie above in MPEG format, typeset in a box:

<p>

<!-- begin box -->
<div style="width: 95%; padding: 10px; border: 1px solid #000; border-radius: 4px;">

<embed src="../doc/src/manual/mov/wave.mpeg" width=700 height=400 autoplay="false" loop="true"></embed>
<p><em>1D wave in MPEG. <div id="mov:wave"></div></em></p>
</div>
<!-- end box -->


<p>
Here is the same movie in AVI format:

<p>

<embed src="../doc/src/manual/mov/wave.avi" width=700 height=400 autoplay="false" loop="true"></embed>
<p><em>1D wave in AVI.</em></p>

<p>
Here is the same movie, but with a URL to GitHub:

<p>

<div>
<video  loop controls width='640' height='365' preload='none'>
    <source src='https://hplgit.github.io/animate/doc/pub/mov-animate/demo.mp4'  type='video/mp4;  codecs="avc1.42E01E, mp4a.40.2"'>
    <source src='https://hplgit.github.io/animate/doc/pub/mov-animate/demo.webm' type='video/webm; codecs="vp8, vorbis"'>
    <source src='https://hplgit.github.io/animate/doc/pub/mov-animate/demo.ogg'  type='video/ogg;  codecs="theora, vorbis"'>
</video>
</div>
<p><em></em></p>

<!-- Issue warning if in a Safari browser -->
<script language="javascript">
if (!!(window.safari)) {
  document.write("<div style=\"width: 95%%; padding: 10px; border: 1px solid #100; border-radius: 4px;\"><p><font color=\"red\">The above movie will not play in Safari - use Chrome, Firefox, or Opera.</font></p></div>")}
</script>

<p>
Here is a YouTube video:

<p>

<iframe width="420" height="315" src="https://www.youtube.com/embed/_O7iUiftbKU" frameborder="0" allowfullscreen></iframe>

<p><em>YouTube movie.</em></p>

<p>
And a vimeo video:

<p>

<iframe width="500" height="278" src="https://player.vimeo.com/video/55562330" frameborder="0" allowfullscreen></iframe>

<em>Vimeo movie.</em>

<p>
Finally, let us demonstrate referencing the movie <a href="#mov:wave">mov:wave</a>.

<!-- ------------------- end of main content --------------- -->


</body>
</html>
    


************** File: movies.html *****************
<!--
Automatically generated HTML file from DocOnce source
(https://github.com/doconce/doconce/)
-->
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="DocOnce: https://github.com/doconce/doconce/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="description" content="This is a demo of movies in DocOnce">

<title>This is a demo of movies in DocOnce</title>


<style type="text/css">
/* blueish style */

/* Color definitions:  https://www.december.com/html/spec/color0.html
   CSS examples:       https://www.w3schools.com/css/css_examples.asp */

body {
  margin-top: 1.0em;
  background-color: #ffffff;
  font-family: Helvetica, Arial, FreeSans, san-serif;
  color: #000000;
}
h1 { font-size: 1.8em; color: #1e36ce; }
h2 { font-size: 1.6em; color: #1e36ce; }
h3 { font-size: 1.4em; color: #1e36ce; }
a { color: #1e36ce; text-decoration:none; }
tt { font-family: "Courier New", Courier; }
/* pre style removed because it will interfer with pygments */
p { text-indent: 0px; }
hr { border: 0; width: 80%; border-bottom: 1px solid #aaa}
p.caption { width: 80%; font-style: normal; text-align: left; }
hr.figure { border: 0; width: 80%; border-bottom: 1px solid #aaa}

div { text-align: justify; text-justify: inter-word; }
</style>


</head>

<!-- tocinfo
{'highest level': 4, 'sections': []}
end of tocinfo -->

<body>

    
<!-- ------------------- main content ---------------------- -->



<center><h1>This is a demo of movies in DocOnce</h1></center>  <!-- document title -->

<p>
<!-- author(s): HPL -->

<center>
<b>HPL</b> 
</center>

<p>
<!-- institution(s) -->

<br>
<p>
<center><h4>Jan 32, 2100</h4></center> <!-- date -->
<br>
<p>
Here is a movie in WebM format.
Note that in HTML format a WebM movie
may actually be the MP4 version of this movie
three alternative sources (MP4, WebM, OGG)
are inserted in the HTML code by default. The command-line
option <code>--no_mp4_webm_ogg_alternatives</code> makes the HTML
code use exactly the specified movie file.

<p>

<div>
<video  loop controls width='700' height='400' preload='none'>
    <source src='../doc/src/manual/mov/wave.mp4'  type='video/mp4;  codecs="avc1.42E01E, mp4a.40.2"'>
    <source src='../doc/src/manual/mov/wave.webm' type='video/webm; codecs="vp8, vorbis"'>
    <source src='../doc/src/manual/mov/wave.ogg'  type='video/ogg;  codecs="theora, vorbis"'>
</video>
</div>
<p><em>1D wave in WebM.</em></p>

<!-- Issue warning if in a Safari browser -->
<script language="javascript">
if (!!(window.safari)) {
  document.write("<div style=\"width: 95%%; padding: 10px; border: 1px solid #100; border-radius: 4px;\"><p><font color=\"red\">The above movie will not play in Safari - use Chrome, Firefox, or Opera.</font></p></div>")}
</script>

<p>
Here is the same movie in Ogg format:

<p>

<div>
<video  loop controls width='700' height='400' preload='none'>
    <source src='../doc/src/manual/mov/wave.mp4'  type='video/mp4;  codecs="avc1.42E01E, mp4a.40.2"'>
    <source src='../doc/src/manual/mov/wave.webm' type='video/webm; codecs="vp8, vorbis"'>
    <source src='../doc/src/manual/mov/wave.ogg'  type='video/ogg;  codecs="theora, vorbis"'>
</video>
</div>
<p><em>1D wave in Ogg.</em></p>

<!-- Issue warning if in a Safari browser -->
<script language="javascript">
if (!!(window.safari)) {
  document.write("<div style=\"width: 95%%; padding: 10px; border: 1px solid #100; border-radius: 4px;\"><p><font color=\"red\">The above movie will not play in Safari - use Chrome, Firefox, or Opera.</font></p></div>")}
</script>

<p>
Here is the same movie in MP4 format:

<p>

<div>
<video  loop controls width='700' height='400' preload='none'>
    <source src='../doc/src/manual/mov/wave.mp4'  type='video/mp4;  codecs="avc1.42E01E, mp4a.40.2"'>
    <source src='../doc/src/manual/mov/wave.webm' type='video/webm; codecs="vp8, vorbis"'>
    <source src='../doc/src/manual/mov/wave.ogg'  type='video/ogg;  codecs="theora, vorbis"'>
</video>
</div>
<p><em>1D wave in MP4.</em></p>

<!-- Issue warning if in a Safari browser -->
<script language="javascript">
if (!!(window.safari)) {
  document.write("<div style=\"width: 95%%; padding: 10px; border: 1px solid #100; border-radius: 4px;\"><p><font color=\"red\">The above movie will not play in Safari - use Chrome, Firefox, or Opera.</font></p></div>")}
</script>

<p>
Here is the same movie in Flash format:

<p>

<embed src="../doc/src/manual/mov/wave.flv" width=700 height=400 autoplay="false" loop="true"></embed>
<p><em>1D wave in Flash.</em></p>

<p>
And here is a collection of images shown as an animation
(<code>frame_*.png</code>):

<p>

<script language="Javascript">
<!---
var num_images____doc_src_manual_mov_wave_frames_frame_0080 = 50;
var img_width____doc_src_manual_mov_wave_frames_frame_0080 = 700;
var img_height____doc_src_manual_mov_wave_frames_frame_0080 = 400;
var interval____doc_src_manual_mov_wave_frames_frame_0080 = 300;
var images____doc_src_manual_mov_wave_frames_frame_0080 = new Array();

function preload_images____doc_src_manual_mov_wave_frames_frame_0080()
{
   t = document.getElementById("progress");

   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[0] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[0].src = "../doc/src/manual/mov/wave_frames/frame_0080.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[1] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[1].src = "../doc/src/manual/mov/wave_frames/frame_0081.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[2] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[2].src = "../doc/src/manual/mov/wave_frames/frame_0082.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[3] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[3].src = "../doc/src/manual/mov/wave_frames/frame_0083.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[4] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[4].src = "../doc/src/manual/mov/wave_frames/frame_0084.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[5] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[5].src = "../doc/src/manual/mov/wave_frames/frame_0085.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[6] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[6].src = "../doc/src/manual/mov/wave_frames/frame_0086.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[7] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[7].src = "../doc/src/manual/mov/wave_frames/frame_0087.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[8] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[8].src = "../doc/src/manual/mov/wave_frames/frame_0088.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[9] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[9].src = "../doc/src/manual/mov/wave_frames/frame_0089.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[10] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[10].src = "../doc/src/manual/mov/wave_frames/frame_0090.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[11] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[11].src = "../doc/src/manual/mov/wave_frames/frame_0091.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[12] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[12].src = "../doc/src/manual/mov/wave_frames/frame_0092.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[13] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[13].src = "../doc/src/manual/mov/wave_frames/frame_0093.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[14] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[14].src = "../doc/src/manual/mov/wave_frames/frame_0094.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[15] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[15].src = "../doc/src/manual/mov/wave_frames/frame_0095.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[16] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[16].src = "../doc/src/manual/mov/wave_frames/frame_0096.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[17] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[17].src = "../doc/src/manual/mov/wave_frames/frame_0097.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[18] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[18].src = "../doc/src/manual/mov/wave_frames/frame_0098.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[19] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[19].src = "../doc/src/manual/mov/wave_frames/frame_0099.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[20] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[20].src = "../doc/src/manual/mov/wave_frames/frame_0100.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[21] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[21].src = "../doc/src/manual/mov/wave_frames/frame_0101.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[22] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[22].src = "../doc/src/manual/mov/wave_frames/frame_0102.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[23] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[23].src = "../doc/src/manual/mov/wave_frames/frame_0103.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[24] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[24].src = "../doc/src/manual/mov/wave_frames/frame_0104.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[25] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[25].src = "../doc/src/manual/mov/wave_frames/frame_0105.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[26] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[26].src = "../doc/src/manual/mov/wave_frames/frame_0106.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[27] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[27].src = "../doc/src/manual/mov/wave_frames/frame_0107.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[28] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[28].src = "../doc/src/manual/mov/wave_frames/frame_0108.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[29] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[29].src = "../doc/src/manual/mov/wave_frames/frame_0109.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[30] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[30].src = "../doc/src/manual/mov/wave_frames/frame_0110.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[31] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[31].src = "../doc/src/manual/mov/wave_frames/frame_0111.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[32] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[32].src = "../doc/src/manual/mov/wave_frames/frame_0112.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[33] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[33].src = "../doc/src/manual/mov/wave_frames/frame_0113.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[34] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[34].src = "../doc/src/manual/mov/wave_frames/frame_0114.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[35] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[35].src = "../doc/src/manual/mov/wave_frames/frame_0115.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[36] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[36].src = "../doc/src/manual/mov/wave_frames/frame_0116.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[37] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[37].src = "../doc/src/manual/mov/wave_frames/frame_0117.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[38] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[38].src = "../doc/src/manual/mov/wave_frames/frame_0118.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[39] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[39].src = "../doc/src/manual/mov/wave_frames/frame_0119.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[40] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[40].src = "../doc/src/manual/mov/wave_frames/frame_0120.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[41] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[41].src = "../doc/src/manual/mov/wave_frames/frame_0121.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[42] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[42].src = "../doc/src/manual/mov/wave_frames/frame_0122.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[43] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[43].src = "../doc/src/manual/mov/wave_frames/frame_0123.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[44] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[44].src = "../doc/src/manual/mov/wave_frames/frame_0124.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[45] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[45].src = "../doc/src/manual/mov/wave_frames/frame_0125.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[46] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[46].src = "../doc/src/manual/mov/wave_frames/frame_0126.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[47] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[47].src = "../doc/src/manual/mov/wave_frames/frame_0127.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[48] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[48].src = "../doc/src/manual/mov/wave_frames/frame_0128.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[49] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[49].src = "../doc/src/manual/mov/wave_frames/frame_0129.png";
        
   t.innerHTML = "";
}

function tick____doc_src_manual_mov_wave_frames_frame_0080()
{
   if (frame____doc_src_manual_mov_wave_frames_frame_0080 > num_images____doc_src_manual_mov_wave_frames_frame_0080 - 1)
       frame____doc_src_manual_mov_wave_frames_frame_0080 = 0;

   document.name____doc_src_manual_mov_wave_frames_frame_0080.src = images____doc_src_manual_mov_wave_frames_frame_0080[frame____doc_src_manual_mov_wave_frames_frame_0080].src;
   frame____doc_src_manual_mov_wave_frames_frame_0080 += 1;
   tt = setTimeout("tick____doc_src_manual_mov_wave_frames_frame_0080()", interval____doc_src_manual_mov_wave_frames_frame_0080);
}

function startup____doc_src_manual_mov_wave_frames_frame_0080()
{
   preload_images____doc_src_manual_mov_wave_frames_frame_0080();
   frame____doc_src_manual_mov_wave_frames_frame_0080 = 0;
   setTimeout("tick____doc_src_manual_mov_wave_frames_frame_0080()", interval____doc_src_manual_mov_wave_frames_frame_0080);
}

function stopit____doc_src_manual_mov_wave_frames_frame_0080()
{ clearTimeout(tt); }

function restart____doc_src_manual_mov_wave_frames_frame_0080()
{ tt = setTimeout("tick____doc_src_manual_mov_wave_frames_frame_0080()", interval____doc_src_manual_mov_wave_frames_frame_0080); }

function slower____doc_src_manual_mov_wave_frames_frame_0080()
{ interval____doc_src_manual_mov_wave_frames_frame_0080 = interval____doc_src_manual_mov_wave_frames_frame_0080/0.7; }

function faster____doc_src_manual_mov_wave_frames_frame_0080()
{ interval____doc_src_manual_mov_wave_frames_frame_0080 = interval____doc_src_manual_mov_wave_frames_frame_0080*0.7; }

// --->
</script>

<form>
&nbsp;
<input type="button" value="Start movie" onClick="startup____doc_src_manual_mov_wave_frames_frame_0080()">
<input type="button" value="Pause movie" onClick="stopit____doc_src_manual_mov_wave_frames_frame_0080()">
<input type="button" value="Restart movie" onClick="restart____doc_src_manual_mov_wave_frames_frame_0080()">
&nbsp;
<input type="button" value="Slower" onClick="slower____doc_src_manual_mov_wave_frames_frame_0080()">
<input type="button" value="Faster" onClick="faster____doc_src_manual_mov_wave_frames_frame_0080()">
</form>

<p><div ID="progress"></div></p>
<img src="../doc/src/manual/mov/wave_frames/frame_0080.png" name="name____doc_src_manual_mov_wave_frames_frame_0080" border=2/>

<br><em>Animated collection of images.</em><br>

<p>
Here is the same collection, but with images in cyberspace, given as URLs:

<p>

<!-- code=text typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>https://hplgit.github.io/animate/..../frame_%04d.png:80-&gt;129
</pre></div>
<p>

<script language="Javascript">
<!---
var num_images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080 = 50;
var img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080 = 800;
var img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080 = 600;
var interval_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080 = 300;
var images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080 = new Array();

function preload_images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080()
{
   t = document.getElementById("progress");

   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[0] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[0].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0080.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[1] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[1].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0081.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[2] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[2].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0082.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[3] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[3].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0083.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[4] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[4].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0084.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[5] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[5].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0085.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[6] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[6].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0086.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[7] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[7].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0087.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[8] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[8].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0088.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[9] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[9].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0089.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[10] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[10].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0090.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[11] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[11].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0091.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[12] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[12].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0092.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[13] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[13].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0093.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[14] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[14].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0094.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[15] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[15].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0095.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[16] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[16].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0096.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[17] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[17].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0097.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[18] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[18].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0098.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[19] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[19].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0099.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[20] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[20].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0100.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[21] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[21].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0101.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[22] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[22].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0102.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[23] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[23].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0103.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[24] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[24].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0104.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[25] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[25].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0105.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[26] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[26].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0106.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[27] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[27].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0107.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[28] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[28].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0108.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[29] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[29].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0109.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[30] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[30].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0110.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[31] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[31].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0111.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[32] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[32].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0112.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[33] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[33].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0113.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[34] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[34].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0114.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[35] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[35].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0115.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[36] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[36].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0116.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[37] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[37].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0117.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[38] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[38].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0118.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[39] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[39].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0119.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[40] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[40].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0120.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[41] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[41].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0121.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[42] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[42].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0122.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[43] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[43].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0123.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[44] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[44].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0124.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[45] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[45].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0125.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[46] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[46].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0126.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[47] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[47].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0127.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[48] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[48].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0128.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[49] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[49].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0129.png";
        
   t.innerHTML = "";
}

function tick_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080()
{
   if (frame_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080 > num_images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080 - 1)
       frame_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080 = 0;

   document.name_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080.src = images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[frame_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080].src;
   frame_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080 += 1;
   tt = setTimeout("tick_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080()", interval_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
}

function startup_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080()
{
   preload_images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080();
   frame_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080 = 0;
   setTimeout("tick_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080()", interval_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
}

function stopit_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080()
{ clearTimeout(tt); }

function restart_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080()
{ tt = setTimeout("tick_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080()", interval_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080); }

function slower_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080()
{ interval_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080 = interval_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080/0.7; }

function faster_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080()
{ interval_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080 = interval_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080*0.7; }

// --->
</script>

<form>
&nbsp;
<input type="button" value="Start movie" onClick="startup_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080()">
<input type="button" value="Pause movie" onClick="stopit_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080()">
<input type="button" value="Restart movie" onClick="restart_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080()">
&nbsp;
<input type="button" value="Slower" onClick="slower_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080()">
<input type="button" value="Faster" onClick="faster_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080()">
</form>

<p><div ID="progress"></div></p>
<img src="https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0080.png" name="name_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080" border=2/>

<br><em>Taking images to animate from cyberspace.</em><br>

<p>
The movie above in MPEG format, typeset in a box:

<p>

<!-- begin box -->
<div style="width: 95%; padding: 10px; border: 1px solid #000; border-radius: 4px;">

<embed src="../doc/src/manual/mov/wave.mpeg" width=700 height=400 autoplay="false" loop="true"></embed>
<p><em>1D wave in MPEG. <div id="mov:wave"></div></em></p>
</div>
<!-- end box -->


<p>
Here is the same movie in AVI format:

<p>

<embed src="../doc/src/manual/mov/wave.avi" width=700 height=400 autoplay="false" loop="true"></embed>
<p><em>1D wave in AVI.</em></p>

<p>
Here is the same movie, but with a URL to GitHub:

<p>

<div>
<video  loop controls width='640' height='365' preload='none'>
    <source src='https://hplgit.github.io/animate/doc/pub/mov-animate/demo.mp4'  type='video/mp4;  codecs="avc1.42E01E, mp4a.40.2"'>
    <source src='https://hplgit.github.io/animate/doc/pub/mov-animate/demo.webm' type='video/webm; codecs="vp8, vorbis"'>
    <source src='https://hplgit.github.io/animate/doc/pub/mov-animate/demo.ogg'  type='video/ogg;  codecs="theora, vorbis"'>
</video>
</div>
<p><em></em></p>

<!-- Issue warning if in a Safari browser -->
<script language="javascript">
if (!!(window.safari)) {
  document.write("<div style=\"width: 95%%; padding: 10px; border: 1px solid #100; border-radius: 4px;\"><p><font color=\"red\">The above movie will not play in Safari - use Chrome, Firefox, or Opera.</font></p></div>")}
</script>

<p>
Here is a YouTube video:

<p>

<iframe width="420" height="315" src="https://www.youtube.com/embed/_O7iUiftbKU" frameborder="0" allowfullscreen></iframe>

<p><em>YouTube movie.</em></p>

<p>
And a vimeo video:

<p>

<iframe width="500" height="278" src="https://player.vimeo.com/video/55562330" frameborder="0" allowfullscreen></iframe>

<em>Vimeo movie.</em>

<p>
Finally, let us demonstrate referencing the movie <a href="#mov:wave">mov:wave</a>.

<!-- ------------------- end of main content --------------- -->


</body>
</html>
    


************** File: movies.p.tex *****************
%%
%% Automatically generated file from DocOnce source
%% (https://github.com/hplgit/doconce/)
%%
%%
% #ifdef PTEX2TEX_EXPLANATION
%%
%% The file follows the ptex2tex extended LaTeX format, see
%% ptex2tex: https://code.google.com/p/ptex2tex/
%%
%% Run
%%      ptex2tex myfile
%% or
%%      doconce ptex2tex myfile
%%
%% to turn myfile.p.tex into an ordinary LaTeX file myfile.tex.
%% (The ptex2tex program: https://code.google.com/p/ptex2tex)
%% Many preprocess options can be added to ptex2tex or doconce ptex2tex
%%
%%      ptex2tex -DMINTED myfile
%%      doconce ptex2tex myfile envir=minted
%%
%% ptex2tex will typeset code environments according to a global or local
%% .ptex2tex.cfg configure file. doconce ptex2tex will typeset code
%% according to options on the command line (just type doconce ptex2tex to
%% see examples). If doconce ptex2tex has envir=minted, it enables the
%% minted style without needing -DMINTED.
% #endif

% #define PREAMBLE

% #ifdef PREAMBLE
%-------------------- begin preamble ----------------------

\documentclass[%
oneside,                 % oneside: electronic viewing, twoside: printing
final,                   % draft: marks overfull hboxes, figures with paths
10pt]{article}

\listfiles               %  print all files needed to compile this document

\usepackage{relsize,makeidx,color,setspace,amsmath,amsfonts,amssymb}
\usepackage[table]{xcolor}
\usepackage{bm,ltablex,microtype}

\usepackage[pdftex]{graphicx}

\usepackage{fancybox}  % make sure fancybox is loaded before fancyvrb
%\setlength{\fboxsep}{8pt}  % may clash with need in pre/cod envirs

% Movies are handled by the href package
\newenvironment{doconce:movie}{}{}
\newcounter{doconce:movie:counter}

\usepackage{animate}


\usepackage{ptex2tex}
% #ifdef MINTED
\usepackage{minted}
\usemintedstyle{default}
% #endif
\usepackage{fancyvrb}

\usepackage[T1]{fontenc}
%\usepackage[latin1]{inputenc}
\usepackage{ucs}
\usepackage[utf8x]{inputenc}

\usepackage{lmodern}         % Latin Modern fonts derived from Computer Modern

% Hyperlinks in PDF:
\definecolor{linkcolor}{rgb}{0,0,0.4}
\usepackage{hyperref}
\hypersetup{
    breaklinks=true,
    colorlinks=true,
    linkcolor=linkcolor,
    urlcolor=linkcolor,
    citecolor=black,
    filecolor=black,
    %filecolor=blue,
    pdfmenubar=true,
    pdftoolbar=true,
    bookmarksdepth=3   % Uncomment (and tweak) for PDF bookmarks with more levels than the TOC
    }
%\hyperbaseurl{}   % hyperlinks are relative to this root

\setcounter{tocdepth}{2}  % levels in table of contents

% prevent orhpans and widows
\clubpenalty = 10000
\widowpenalty = 10000

% --- end of standard preamble for documents ---


% insert custom LaTeX commands...

\raggedbottom
\makeindex
\usepackage[totoc]{idxlayout}   % for index in the toc
\usepackage[nottoc]{tocbibind}  % for references/bibliography in the toc

%-------------------- end preamble ----------------------

\begin{document}

% matching end for #ifdef PREAMBLE
% #endif

\newcommand{\exercisesection}[1]{\subsection*{#1}}

\input{newcommands_bfmath}
\input{newcommands_replace}

% ------------------- main content ----------------------



% ----------------- title -------------------------

\thispagestyle{empty}

\begin{center}
{\LARGE\bf
\begin{spacing}{1.25}
This is a demo of movies in DocOnce
\end{spacing}
}
\end{center}

% ----------------- author(s) -------------------------

\begin{center}
{\bf HPL${}^{}$} \\ [0mm]
\end{center}

\begin{center}
% List of all institutions:
\end{center}
    
% ----------------- end author(s) -------------------------

% --- begin date ---
\begin{center}
Jan 32, 2100
\end{center}
% --- end date ---

\vspace{1cm}


Here is a movie in WebM format.


\begin{doconce:movie}
\refstepcounter{doconce:movie:counter}
\begin{quote}
% link to external viewer
Movie \arabic{doconce:movie:counter}: 1D wave in WebM. \href{run:../doc/src/manual/mov/wave.webm}{\nolinkurl{../doc/src/manual/mov/wave.webm}}
\end{quote}
\end{doconce:movie}


Here is the same movie in Ogg format:


\begin{doconce:movie}
\refstepcounter{doconce:movie:counter}
\begin{quote}
% link to external viewer
Movie \arabic{doconce:movie:counter}: 1D wave in Ogg. \href{run:../doc/src/manual/mov/wave.ogg}{\nolinkurl{../doc/src/manual/mov/wave.ogg}}
\end{quote}
\end{doconce:movie}


Here is the same movie in MP4 format:


\begin{doconce:movie}
\refstepcounter{doconce:movie:counter}
\begin{quote}
% link to external viewer
Movie \arabic{doconce:movie:counter}: 1D wave in MP4. \href{run:../doc/src/manual/mov/wave.mp4}{\nolinkurl{../doc/src/manual/mov/wave.mp4}}
\end{quote}
\end{doconce:movie}


Here is the same movie in Flash format:


\begin{doconce:movie}
\refstepcounter{doconce:movie:counter}
\begin{quote}
% link to external viewer
Movie \arabic{doconce:movie:counter}: 1D wave in Flash. \href{run:../doc/src/manual/mov/wave.flv}{\nolinkurl{../doc/src/manual/mov/wave.flv}}
\end{quote}
\end{doconce:movie}


And here is a collection of images shown as an animation
(\Verb!frame_*.png!):


\begin{doconce:movie}
\refstepcounter{doconce:movie:counter}
\begin{center}
\begin{animateinline}[controls,loop]{1} % frames: ../doc/src/manual/mov/wave_frames/frame_0080.png -> ../doc/src/manual/mov/wave_frames/frame_0129.png
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0080.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0081.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0082.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0083.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0084.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0085.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0086.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0087.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0088.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0089.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0090.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0091.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0092.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0093.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0094.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0095.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0096.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0097.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0098.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0099.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0100.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0101.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0102.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0103.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0104.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0105.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0106.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0107.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0108.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0109.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0110.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0111.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0112.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0113.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0114.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0115.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0116.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0117.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0118.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0119.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0120.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0121.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0122.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0123.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0124.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0125.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0126.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0127.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0128.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0129.png}
\end{animateinline}
\end{center}

\begin{center}  % movie caption
Movie \arabic{doconce:movie:counter}: Animated collection of images.
\end{center}
\end{doconce:movie}


Here is the same collection, but with images in cyberspace, given as URLs:

\bccq
https://hplgit.github.io/animate/..../frame_%04d.png:80->129
\eccq


\begin{doconce:movie}
\refstepcounter{doconce:movie:counter}
\begin{center}
Taking images to animate from cyberspace. \Verb!https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_%04d.png:80->129!: load \href{{file:///home/amarin/doconce/test/movie_player1.html}}{\nolinkurl{movie_player1.html}} into a browser
\end{center}

\begin{center}  % movie caption
Movie \arabic{doconce:movie:counter}: Taking images to animate from cyberspace.
\end{center}
\end{doconce:movie}


The movie above in MPEG format, typeset in a box:


\begin{center}
\begin{Sbox}
\begin{minipage}{0.85\linewidth}

\begin{doconce:movie}
\refstepcounter{doconce:movie:counter}
\begin{quote}
% link to external viewer
Movie \arabic{doconce:movie:counter}: 1D wave in MPEG. \label{mov:wave} \href{run:../doc/src/manual/mov/wave.mpeg}{\nolinkurl{../doc/src/manual/mov/wave.mpeg}}
\end{quote}
\end{doconce:movie}
\end{minipage}
\end{Sbox}
\fbox{\TheSbox}
\end{center}

Here is the same movie in AVI format:


\begin{doconce:movie}
\refstepcounter{doconce:movie:counter}
\begin{quote}
% link to external viewer
Movie \arabic{doconce:movie:counter}: 1D wave in AVI. \href{run:../doc/src/manual/mov/wave.avi}{\nolinkurl{../doc/src/manual/mov/wave.avi}}
\end{quote}
\end{doconce:movie}


Here is the same movie, but with a URL to GitHub:


\begin{doconce:movie}
\refstepcounter{doconce:movie:counter}
\begin{quote}
% link to web movie
Movie \arabic{doconce:movie:counter}:  \href{https://hplgit.github.io/animate/doc/pub/mov-animate/demo.ogg}{\nolinkurl{https://hplgit.github.io/animate/doc/pub/mov-animate/demo.ogg}}
\end{quote}
\end{doconce:movie}


Here is a YouTube video:


\begin{doconce:movie}
\refstepcounter{doconce:movie:counter}
\begin{center}
\href{{https://www.youtube.com/watch?v=_O7iUiftbKU}}{\nolinkurl{https://www.youtube.com/watch?v=_O7iUiftbKU}}
\end{center}

\begin{center}  % movie caption
Movie \arabic{doconce:movie:counter}: YouTube movie.
\end{center}
\end{doconce:movie}


And a vimeo video:


\begin{doconce:movie}
\refstepcounter{doconce:movie:counter}
\begin{center}\href{{https://vimeo.com/55562330}}{\nolinkurl{https://vimeo.com/55562330}}\end{center}

\begin{center}  % movie caption
Movie \arabic{doconce:movie:counter}: Vimeo movie.
\end{center}
\end{doconce:movie}



Finally, let us demonstrate referencing the movie~\ref{mov:wave}.

% ------------------- end of main content ---------------

% #ifdef PREAMBLE
\end{document}
% #endif


************** File: movies.tex *****************
%%
%% Automatically generated file from DocOnce source
%% (https://github.com/hplgit/doconce/)
%%
%%


%-------------------- begin preamble ----------------------

\documentclass[%
oneside,                 % oneside: electronic viewing, twoside: printing
final,                   % draft: marks overfull hboxes, figures with paths
10pt]{article}

\listfiles               %  print all files needed to compile this document

\usepackage{relsize,makeidx,color,setspace,amsmath,amsfonts,amssymb}
\usepackage[table]{xcolor}
\usepackage{bm,ltablex,microtype}

\usepackage[pdftex]{graphicx}

\usepackage{fancybox}  % make sure fancybox is loaded before fancyvrb
%\setlength{\fboxsep}{8pt}  % may clash with need in pre/cod envirs

% Movies are handled by the href package
\newenvironment{doconce:movie}{}{}
\newcounter{doconce:movie:counter}

\usepackage{animate}


\usepackage{fancyvrb} % packages needed for verbatim environments
\usepackage{fancyvrb}

\usepackage[T1]{fontenc}
%\usepackage[latin1]{inputenc}
\usepackage{ucs}
\usepackage[utf8x]{inputenc}

\usepackage{lmodern}         % Latin Modern fonts derived from Computer Modern

% Hyperlinks in PDF:
\definecolor{linkcolor}{rgb}{0,0,0.4}
\usepackage{hyperref}
\hypersetup{
    breaklinks=true,
    colorlinks=true,
    linkcolor=linkcolor,
    urlcolor=linkcolor,
    citecolor=black,
    filecolor=black,
    %filecolor=blue,
    pdfmenubar=true,
    pdftoolbar=true,
    bookmarksdepth=3   % Uncomment (and tweak) for PDF bookmarks with more levels than the TOC
    }
%\hyperbaseurl{}   % hyperlinks are relative to this root

\setcounter{tocdepth}{2}  % levels in table of contents

% prevent orhpans and widows
\clubpenalty = 10000
\widowpenalty = 10000

% --- end of standard preamble for documents ---


% insert custom LaTeX commands...

\raggedbottom
\makeindex
\usepackage[totoc]{idxlayout}   % for index in the toc
\usepackage[nottoc]{tocbibind}  % for references/bibliography in the toc

%-------------------- end preamble ----------------------

\begin{document}

% matching end for #ifdef PREAMBLE

\newcommand{\exercisesection}[1]{\subsection*{#1}}

\input{newcommands_bfmath}
\input{newcommands_replace}

% ------------------- main content ----------------------



% ----------------- title -------------------------

\thispagestyle{empty}

\begin{center}
{\LARGE\bf
\begin{spacing}{1.25}
This is a demo of movies in DocOnce
\end{spacing}
}
\end{center}

% ----------------- author(s) -------------------------

\begin{center}
{\bf HPL${}^{}$} \\ [0mm]
\end{center}

\begin{center}
% List of all institutions:
\end{center}
    
% ----------------- end author(s) -------------------------

% --- begin date ---
\begin{center}
Jan 32, 2100
\end{center}
% --- end date ---

\vspace{1cm}


Here is a movie in WebM format.


\begin{doconce:movie}
\refstepcounter{doconce:movie:counter}
\begin{quote}
% link to external viewer
Movie \arabic{doconce:movie:counter}: 1D wave in WebM. \href{run:../doc/src/manual/mov/wave.webm}{\nolinkurl{../doc/src/manual/mov/wave.webm}}
\end{quote}
\end{doconce:movie}


Here is the same movie in Ogg format:


\begin{doconce:movie}
\refstepcounter{doconce:movie:counter}
\begin{quote}
% link to external viewer
Movie \arabic{doconce:movie:counter}: 1D wave in Ogg. \href{run:../doc/src/manual/mov/wave.ogg}{\nolinkurl{../doc/src/manual/mov/wave.ogg}}
\end{quote}
\end{doconce:movie}


Here is the same movie in MP4 format:


\begin{doconce:movie}
\refstepcounter{doconce:movie:counter}
\begin{quote}
% link to external viewer
Movie \arabic{doconce:movie:counter}: 1D wave in MP4. \href{run:../doc/src/manual/mov/wave.mp4}{\nolinkurl{../doc/src/manual/mov/wave.mp4}}
\end{quote}
\end{doconce:movie}


Here is the same movie in Flash format:


\begin{doconce:movie}
\refstepcounter{doconce:movie:counter}
\begin{quote}
% link to external viewer
Movie \arabic{doconce:movie:counter}: 1D wave in Flash. \href{run:../doc/src/manual/mov/wave.flv}{\nolinkurl{../doc/src/manual/mov/wave.flv}}
\end{quote}
\end{doconce:movie}


And here is a collection of images shown as an animation
(\Verb!frame_*.png!):


\begin{doconce:movie}
\refstepcounter{doconce:movie:counter}
\begin{center}
\begin{animateinline}[controls,loop]{1} % frames: ../doc/src/manual/mov/wave_frames/frame_0080.png -> ../doc/src/manual/mov/wave_frames/frame_0129.png
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0080.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0081.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0082.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0083.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0084.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0085.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0086.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0087.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0088.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0089.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0090.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0091.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0092.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0093.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0094.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0095.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0096.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0097.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0098.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0099.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0100.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0101.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0102.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0103.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0104.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0105.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0106.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0107.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0108.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0109.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0110.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0111.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0112.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0113.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0114.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0115.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0116.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0117.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0118.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0119.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0120.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0121.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0122.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0123.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0124.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0125.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0126.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0127.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0128.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0129.png}
\end{animateinline}
\end{center}

\begin{center}  % movie caption
Movie \arabic{doconce:movie:counter}: Animated collection of images.
\end{center}
\end{doconce:movie}


Here is the same collection, but with images in cyberspace, given as URLs:

\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95]
https://hplgit.github.io/animate/..../frame_%04d.png:80->129
\end{Verbatim}


\begin{doconce:movie}
\refstepcounter{doconce:movie:counter}
\begin{center}
Taking images to animate from cyberspace. \Verb!https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_%04d.png:80->129!: load \href{{file:///home/amarin/doconce/test/movie_player1.html}}{\nolinkurl{movie_player1.html}} into a browser
\end{center}

\begin{center}  % movie caption
Movie \arabic{doconce:movie:counter}: Taking images to animate from cyberspace.
\end{center}
\end{doconce:movie}


The movie above in MPEG format, typeset in a box:


\begin{center}
\begin{Sbox}
\begin{minipage}{0.85\linewidth}

\begin{doconce:movie}
\refstepcounter{doconce:movie:counter}
\begin{quote}
% link to external viewer
Movie \arabic{doconce:movie:counter}: 1D wave in MPEG. \label{mov:wave} \href{run:../doc/src/manual/mov/wave.mpeg}{\nolinkurl{../doc/src/manual/mov/wave.mpeg}}
\end{quote}
\end{doconce:movie}
\end{minipage}
\end{Sbox}
\fbox{\TheSbox}
\end{center}

Here is the same movie in AVI format:


\begin{doconce:movie}
\refstepcounter{doconce:movie:counter}
\begin{quote}
% link to external viewer
Movie \arabic{doconce:movie:counter}: 1D wave in AVI. \href{run:../doc/src/manual/mov/wave.avi}{\nolinkurl{../doc/src/manual/mov/wave.avi}}
\end{quote}
\end{doconce:movie}


Here is the same movie, but with a URL to GitHub:


\begin{doconce:movie}
\refstepcounter{doconce:movie:counter}
\begin{quote}
% link to web movie
Movie \arabic{doconce:movie:counter}:  \href{https://hplgit.github.io/animate/doc/pub/mov-animate/demo.ogg}{\nolinkurl{https://hplgit.github.io/animate/doc/pub/mov-animate/demo.ogg}}
\end{quote}
\end{doconce:movie}


Here is a YouTube video:


\begin{doconce:movie}
\refstepcounter{doconce:movie:counter}
\begin{center}
\href{{https://www.youtube.com/watch?v=_O7iUiftbKU}}{\nolinkurl{https://www.youtube.com/watch?v=_O7iUiftbKU}}
\end{center}

\begin{center}  % movie caption
Movie \arabic{doconce:movie:counter}: YouTube movie.
\end{center}
\end{doconce:movie}


And a vimeo video:


\begin{doconce:movie}
\refstepcounter{doconce:movie:counter}
\begin{center}\href{{https://vimeo.com/55562330}}{\nolinkurl{https://vimeo.com/55562330}}\end{center}

\begin{center}  % movie caption
Movie \arabic{doconce:movie:counter}: Vimeo movie.
\end{center}
\end{doconce:movie}



Finally, let us demonstrate referencing the movie~\ref{mov:wave}.

% ------------------- end of main content ---------------

\end{document}


************** File: movies_media9.tex *****************
%%
%% Automatically generated file from DocOnce source
%% (https://github.com/hplgit/doconce/)
%%
%%


%-------------------- begin preamble ----------------------

\documentclass[%
oneside,                 % oneside: electronic viewing, twoside: printing
final,                   % draft: marks overfull hboxes, figures with paths
10pt]{article}

\listfiles               %  print all files needed to compile this document

\usepackage{relsize,makeidx,color,setspace,amsmath,amsfonts,amssymb}
\usepackage[table]{xcolor}
\usepackage{bm,ltablex,microtype}

\usepackage[pdftex]{graphicx}

\usepackage{fancybox}  % make sure fancybox is loaded before fancyvrb
%\setlength{\fboxsep}{8pt}  % may clash with need in pre/cod envirs

% Movies are handled by the media9 package
\newenvironment{doconce:movie}{}{}
\newcounter{doconce:movie:counter}
\usepackage{media9}
\usepackage{movie15}
\usepackage{animate}


\usepackage{fancyvrb} % packages needed for verbatim environments
\usepackage{fancyvrb}

\usepackage[T1]{fontenc}
%\usepackage[latin1]{inputenc}
\usepackage{ucs}
\usepackage[utf8x]{inputenc}

\usepackage{lmodern}         % Latin Modern fonts derived from Computer Modern

% Hyperlinks in PDF:
\definecolor{linkcolor}{rgb}{0,0,0.4}
\usepackage{hyperref}
\hypersetup{
    breaklinks=true,
    colorlinks=true,
    linkcolor=linkcolor,
    urlcolor=linkcolor,
    citecolor=black,
    filecolor=black,
    %filecolor=blue,
    pdfmenubar=true,
    pdftoolbar=true,
    bookmarksdepth=3   % Uncomment (and tweak) for PDF bookmarks with more levels than the TOC
    }
%\hyperbaseurl{}   % hyperlinks are relative to this root

\setcounter{tocdepth}{2}  % levels in table of contents

% prevent orhpans and widows
\clubpenalty = 10000
\widowpenalty = 10000

% --- end of standard preamble for documents ---


% insert custom LaTeX commands...

\raggedbottom
\makeindex
\usepackage[totoc]{idxlayout}   % for index in the toc
\usepackage[nottoc]{tocbibind}  % for references/bibliography in the toc

%-------------------- end preamble ----------------------

\begin{document}

% matching end for #ifdef PREAMBLE

\newcommand{\exercisesection}[1]{\subsection*{#1}}

\input{newcommands_bfmath}
\input{newcommands_replace}

% ------------------- main content ----------------------



% ----------------- title -------------------------

\thispagestyle{empty}

\begin{center}
{\LARGE\bf
\begin{spacing}{1.25}
This is a demo of movies in DocOnce
\end{spacing}
}
\end{center}

% ----------------- author(s) -------------------------

\begin{center}
{\bf HPL${}^{}$} \\ [0mm]
\end{center}

\begin{center}
% List of all institutions:
\end{center}
    
% ----------------- end author(s) -------------------------

% --- begin date ---
\begin{center}
Jan 32, 2100
\end{center}
% --- end date ---

\vspace{1cm}


Here is a movie in WebM format.


\begin{doconce:movie}
\refstepcounter{doconce:movie:counter}
\begin{quote}
% link to external viewer
Movie \arabic{doconce:movie:counter}: 1D wave in WebM. \href{run:../doc/src/manual/mov/wave.webm}{\nolinkurl{../doc/src/manual/mov/wave.webm}}
\end{quote}
\end{doconce:movie}


Here is the same movie in Ogg format:


\begin{doconce:movie}
\refstepcounter{doconce:movie:counter}
\begin{quote}
% link to external viewer
Movie \arabic{doconce:movie:counter}: 1D wave in Ogg. \href{run:../doc/src/manual/mov/wave.ogg}{\nolinkurl{../doc/src/manual/mov/wave.ogg}}
\end{quote}
\end{doconce:movie}


Here is the same movie in MP4 format:


\begin{doconce:movie}
\refstepcounter{doconce:movie:counter}
\begin{center}
% media9 package
\includemedia[
label=docsrcmanualmovwavemp4,
width=0.8\linewidth,
activate=pageopen,         % or onclick or pagevisible
addresource=../doc/src/manual/mov/wave.mp4,  % embed the video in the PDF
flashvars={
source=../doc/src/manual/mov/wave.mp4
&autoPlay=true
&loop=true
&scaleMode=letterbox       % preserve aspect ratio while scaling this video
}]{}{VPlayer.swf}
%\mediabutton[mediacommand=docsrcmanualmovwavemp4:playPause]{\fbox{\strut Play/Pause}}
\end{center}

\begin{center}  % movie caption
Movie \arabic{doconce:movie:counter}: 1D wave in MP4.
\end{center}
\end{doconce:movie}


Here is the same movie in Flash format:


\begin{doconce:movie}
\refstepcounter{doconce:movie:counter}
\begin{center}
% media9 package
\includemedia[
label=docsrcmanualmovwaveflv,
width=0.8\linewidth,
activate=pageopen,         % or onclick or pagevisible
addresource=../doc/src/manual/mov/wave.flv,  % embed the video in the PDF
flashvars={
source=../doc/src/manual/mov/wave.flv
&autoPlay=true
&loop=true
&scaleMode=letterbox       % preserve aspect ratio while scaling this video
}]{}{VPlayer.swf}
%\mediabutton[mediacommand=docsrcmanualmovwaveflv:playPause]{\fbox{\strut Play/Pause}}
\end{center}

\begin{center}  % movie caption
Movie \arabic{doconce:movie:counter}: 1D wave in Flash.
\end{center}
\end{doconce:movie}


And here is a collection of images shown as an animation
(\Verb!frame_*.png!):


\begin{doconce:movie}
\refstepcounter{doconce:movie:counter}
\begin{center}
\begin{animateinline}[controls,loop]{1} % frames: ../doc/src/manual/mov/wave_frames/frame_0080.png -> ../doc/src/manual/mov/wave_frames/frame_0129.png
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0080.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0081.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0082.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0083.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0084.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0085.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0086.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0087.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0088.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0089.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0090.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0091.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0092.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0093.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0094.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0095.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0096.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0097.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0098.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0099.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0100.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0101.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0102.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0103.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0104.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0105.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0106.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0107.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0108.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0109.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0110.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0111.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0112.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0113.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0114.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0115.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0116.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0117.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0118.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0119.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0120.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0121.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0122.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0123.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0124.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0125.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0126.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0127.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0128.png}
\newframe
\includegraphics[width=0.9\textwidth]{../doc/src/manual/mov/wave_frames/frame_0129.png}
\end{animateinline}
\end{center}

\begin{center}  % movie caption
Movie \arabic{doconce:movie:counter}: Animated collection of images.
\end{center}
\end{doconce:movie}


Here is the same collection, but with images in cyberspace, given as URLs:

\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95]
https://hplgit.github.io/animate/..../frame_%04d.png:80->129
\end{Verbatim}


\begin{doconce:movie}
\refstepcounter{doconce:movie:counter}
\begin{center}
Taking images to animate from cyberspace. \Verb!https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_%04d.png:80->129!: load \href{{file:///home/amarin/doconce/test/movie_player1.html}}{\nolinkurl{movie_player1.html}} into a browser
\end{center}

\begin{center}  % movie caption
Movie \arabic{doconce:movie:counter}: Taking images to animate from cyberspace.
\end{center}
\end{doconce:movie}


The movie above in MPEG format, typeset in a box:


\begin{center}
\begin{Sbox}
\begin{minipage}{0.85\linewidth}

\begin{doconce:movie}
\refstepcounter{doconce:movie:counter}
\begin{center}
% movie15 package
\includemovie[poster,
label=docsrcmanualmovwavempeg,
autoplay,
controls,
toolbar,
text={\small (Loading ../doc/src/manual/mov/wave.mpeg)},
repeat,
]{0.9\linewidth}{0.9\linewidth}{../doc/src/manual/mov/wave.mpeg}

\movieref[rate=0.5]{docsrcmanualmovwavempeg}{Slower}
\movieref[rate=2]{docsrcmanualmovwavempeg}{Faster}
\movieref[default]{docsrcmanualmovwavempeg}{Normal}
\movieref[pause]{docsrcmanualmovwavempeg}{Play/Pause}
\movieref[stop]{docsrcmanualmovwavempeg}{Stop}
\end{center}

\begin{center}  % movie caption
Movie \arabic{doconce:movie:counter}: 1D wave in MPEG. \label{mov:wave}
\end{center}
\end{doconce:movie}
\end{minipage}
\end{Sbox}
\fbox{\TheSbox}
\end{center}

Here is the same movie in AVI format:


\begin{doconce:movie}
\refstepcounter{doconce:movie:counter}
\begin{center}
% movie15 package
\includemovie[poster,
label=docsrcmanualmovwaveavi,
autoplay,
controls,
toolbar,
text={\small (Loading ../doc/src/manual/mov/wave.avi)},
repeat,
]{0.9\linewidth}{0.9\linewidth}{../doc/src/manual/mov/wave.avi}

\movieref[rate=0.5]{docsrcmanualmovwaveavi}{Slower}
\movieref[rate=2]{docsrcmanualmovwaveavi}{Faster}
\movieref[default]{docsrcmanualmovwaveavi}{Normal}
\movieref[pause]{docsrcmanualmovwaveavi}{Play/Pause}
\movieref[stop]{docsrcmanualmovwaveavi}{Stop}
\end{center}

\begin{center}  % movie caption
Movie \arabic{doconce:movie:counter}: 1D wave in AVI.
\end{center}
\end{doconce:movie}


Here is the same movie, but with a URL to GitHub:


\begin{doconce:movie}
\refstepcounter{doconce:movie:counter}
\begin{quote}
% link to web movie
Movie \arabic{doconce:movie:counter}:  \href{https://hplgit.github.io/animate/doc/pub/mov-animate/demo.ogg}{\nolinkurl{https://hplgit.github.io/animate/doc/pub/mov-animate/demo.ogg}}
\end{quote}
\end{doconce:movie}


Here is a YouTube video:


\begin{doconce:movie}
\refstepcounter{doconce:movie:counter}
\begin{center}
\includemedia[
width=0.6\linewidth,height=0.45\linewidth,
activate=pageopen,
flashvars={
modestbranding=1   % no YouTube logo in control bar
&autohide=1        % controlbar autohide
&showinfo=0        % no title and other info before start
&rel=0             % no related videos after end
},
]{}{https://www.youtube.com/watch?v=_O7iUiftbKU}
\end{center}

\begin{center}  % movie caption
Movie \arabic{doconce:movie:counter}: YouTube movie.
\end{center}
\end{doconce:movie}


And a vimeo video:


\begin{doconce:movie}
\refstepcounter{doconce:movie:counter}
\begin{center}\href{{https://vimeo.com/55562330}}{\nolinkurl{https://vimeo.com/55562330}}\end{center}

\begin{center}  % movie caption
Movie \arabic{doconce:movie:counter}: Vimeo movie.
\end{center}
\end{doconce:movie}



Finally, let us demonstrate referencing the movie~\ref{mov:wave}.

% ------------------- end of main content ---------------

\end{document}


************** File: movies.txt *****************
This is a demo of movies in DocOnce
===================================

HPL

Date: Jan 32, 2100

Here is a movie in WebM format.

1D wave in WebM. ../doc/src/manual/mov/wave.webm: load movie_player1.html (movie_player1.html) into a browser

Here is the same movie in Ogg format:

1D wave in Ogg. ../doc/src/manual/mov/wave.ogg: load movie_player2.html (movie_player2.html) into a browser

Here is the same movie in MP4 format:

1D wave in MP4. ../doc/src/manual/mov/wave.mp4: load movie_player3.html (movie_player3.html) into a browser

Here is the same movie in Flash format:

1D wave in Flash. ../doc/src/manual/mov/wave.flv: load movie_player4.html (movie_player4.html) into a browser

And here is a collection of images shown as an animation
(frame_*.png):

Animated collection of images. ../doc/src/manual/mov/wave_frames/frame_*.png: load movie_player5.html (movie_player5.html) into a browser

Here is the same collection, but with images in cyberspace, given as URLs::

        https://hplgit.github.io/animate/..../frame_%04d.png:80->129

Taking images to animate from cyberspace. https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_%04d.png:80->129: load movie_player6.html (movie_player6.html) into a browser

The movie above in MPEG format, typeset in a box:


|---------------------------------------------------------------------------------------------------------------|
| 1D wave in MPEG. ../doc/src/manual/mov/wave.mpeg: load movie_player7.html (movie_player7.html) into a browser |
|---------------------------------------------------------------------------------------------------------------|


Here is the same movie in AVI format:

1D wave in AVI. ../doc/src/manual/mov/wave.avi: load movie_player8.html (movie_player8.html) into a browser

Here is the same movie, but with a URL to GitHub:

 https://hplgit.github.io/animate/doc/pub/mov-animate/demo.ogg: load movie_player9.html (movie_player9.html) into a browser

Here is a YouTube video:

YouTube movie. https://www.youtube.com/watch?v=_O7iUiftbKU: load movie_player10.html (movie_player10.html) into a browser

And a vimeo video:

Vimeo movie. https://vimeo.com/55562330: load movie_player11.html (movie_player11.html) into a browser

Finally, let us demonstrate referencing the movie ref{mov:wave}.

************** File: movie_player4.html *****************

<html>
<head>
</head>
<body>
<title>Embedding media in HTML</title>

<embed src="../doc/src/manual/mov/wave.flv" width=700 height=400 autoplay="false" loop="true"></embed>
<p><em>1D wave in Flash.</em></p>

</body>
</html>

************** File: movie_player5.html *****************

<html>
<head>
</head>
<body>
<title>Embedding media in HTML</title>

<script language="Javascript">
<!---
var num_images____doc_src_manual_mov_wave_frames_frame_0080 = 50;
var img_width____doc_src_manual_mov_wave_frames_frame_0080 = 700;
var img_height____doc_src_manual_mov_wave_frames_frame_0080 = 400;
var interval____doc_src_manual_mov_wave_frames_frame_0080 = 300;
var images____doc_src_manual_mov_wave_frames_frame_0080 = new Array();

function preload_images____doc_src_manual_mov_wave_frames_frame_0080()
{
   t = document.getElementById("progress");

   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[0] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[0].src = "../doc/src/manual/mov/wave_frames/frame_0080.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[1] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[1].src = "../doc/src/manual/mov/wave_frames/frame_0081.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[2] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[2].src = "../doc/src/manual/mov/wave_frames/frame_0082.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[3] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[3].src = "../doc/src/manual/mov/wave_frames/frame_0083.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[4] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[4].src = "../doc/src/manual/mov/wave_frames/frame_0084.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[5] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[5].src = "../doc/src/manual/mov/wave_frames/frame_0085.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[6] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[6].src = "../doc/src/manual/mov/wave_frames/frame_0086.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[7] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[7].src = "../doc/src/manual/mov/wave_frames/frame_0087.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[8] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[8].src = "../doc/src/manual/mov/wave_frames/frame_0088.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[9] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[9].src = "../doc/src/manual/mov/wave_frames/frame_0089.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[10] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[10].src = "../doc/src/manual/mov/wave_frames/frame_0090.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[11] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[11].src = "../doc/src/manual/mov/wave_frames/frame_0091.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[12] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[12].src = "../doc/src/manual/mov/wave_frames/frame_0092.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[13] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[13].src = "../doc/src/manual/mov/wave_frames/frame_0093.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[14] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[14].src = "../doc/src/manual/mov/wave_frames/frame_0094.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[15] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[15].src = "../doc/src/manual/mov/wave_frames/frame_0095.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[16] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[16].src = "../doc/src/manual/mov/wave_frames/frame_0096.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[17] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[17].src = "../doc/src/manual/mov/wave_frames/frame_0097.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[18] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[18].src = "../doc/src/manual/mov/wave_frames/frame_0098.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[19] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[19].src = "../doc/src/manual/mov/wave_frames/frame_0099.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[20] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[20].src = "../doc/src/manual/mov/wave_frames/frame_0100.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[21] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[21].src = "../doc/src/manual/mov/wave_frames/frame_0101.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[22] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[22].src = "../doc/src/manual/mov/wave_frames/frame_0102.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[23] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[23].src = "../doc/src/manual/mov/wave_frames/frame_0103.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[24] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[24].src = "../doc/src/manual/mov/wave_frames/frame_0104.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[25] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[25].src = "../doc/src/manual/mov/wave_frames/frame_0105.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[26] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[26].src = "../doc/src/manual/mov/wave_frames/frame_0106.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[27] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[27].src = "../doc/src/manual/mov/wave_frames/frame_0107.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[28] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[28].src = "../doc/src/manual/mov/wave_frames/frame_0108.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[29] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[29].src = "../doc/src/manual/mov/wave_frames/frame_0109.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[30] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[30].src = "../doc/src/manual/mov/wave_frames/frame_0110.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[31] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[31].src = "../doc/src/manual/mov/wave_frames/frame_0111.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[32] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[32].src = "../doc/src/manual/mov/wave_frames/frame_0112.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[33] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[33].src = "../doc/src/manual/mov/wave_frames/frame_0113.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[34] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[34].src = "../doc/src/manual/mov/wave_frames/frame_0114.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[35] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[35].src = "../doc/src/manual/mov/wave_frames/frame_0115.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[36] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[36].src = "../doc/src/manual/mov/wave_frames/frame_0116.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[37] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[37].src = "../doc/src/manual/mov/wave_frames/frame_0117.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[38] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[38].src = "../doc/src/manual/mov/wave_frames/frame_0118.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[39] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[39].src = "../doc/src/manual/mov/wave_frames/frame_0119.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[40] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[40].src = "../doc/src/manual/mov/wave_frames/frame_0120.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[41] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[41].src = "../doc/src/manual/mov/wave_frames/frame_0121.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[42] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[42].src = "../doc/src/manual/mov/wave_frames/frame_0122.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[43] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[43].src = "../doc/src/manual/mov/wave_frames/frame_0123.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[44] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[44].src = "../doc/src/manual/mov/wave_frames/frame_0124.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[45] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[45].src = "../doc/src/manual/mov/wave_frames/frame_0125.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[46] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[46].src = "../doc/src/manual/mov/wave_frames/frame_0126.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[47] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[47].src = "../doc/src/manual/mov/wave_frames/frame_0127.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[48] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[48].src = "../doc/src/manual/mov/wave_frames/frame_0128.png";
        
   t.innerHTML = "Preloading image ";
   images____doc_src_manual_mov_wave_frames_frame_0080[49] = new Image(img_width____doc_src_manual_mov_wave_frames_frame_0080, img_height____doc_src_manual_mov_wave_frames_frame_0080);
   images____doc_src_manual_mov_wave_frames_frame_0080[49].src = "../doc/src/manual/mov/wave_frames/frame_0129.png";
        
   t.innerHTML = "";
}

function tick____doc_src_manual_mov_wave_frames_frame_0080()
{
   if (frame____doc_src_manual_mov_wave_frames_frame_0080 > num_images____doc_src_manual_mov_wave_frames_frame_0080 - 1)
       frame____doc_src_manual_mov_wave_frames_frame_0080 = 0;

   document.name____doc_src_manual_mov_wave_frames_frame_0080.src = images____doc_src_manual_mov_wave_frames_frame_0080[frame____doc_src_manual_mov_wave_frames_frame_0080].src;
   frame____doc_src_manual_mov_wave_frames_frame_0080 += 1;
   tt = setTimeout("tick____doc_src_manual_mov_wave_frames_frame_0080()", interval____doc_src_manual_mov_wave_frames_frame_0080);
}

function startup____doc_src_manual_mov_wave_frames_frame_0080()
{
   preload_images____doc_src_manual_mov_wave_frames_frame_0080();
   frame____doc_src_manual_mov_wave_frames_frame_0080 = 0;
   setTimeout("tick____doc_src_manual_mov_wave_frames_frame_0080()", interval____doc_src_manual_mov_wave_frames_frame_0080);
}

function stopit____doc_src_manual_mov_wave_frames_frame_0080()
{ clearTimeout(tt); }

function restart____doc_src_manual_mov_wave_frames_frame_0080()
{ tt = setTimeout("tick____doc_src_manual_mov_wave_frames_frame_0080()", interval____doc_src_manual_mov_wave_frames_frame_0080); }

function slower____doc_src_manual_mov_wave_frames_frame_0080()
{ interval____doc_src_manual_mov_wave_frames_frame_0080 = interval____doc_src_manual_mov_wave_frames_frame_0080/0.7; }

function faster____doc_src_manual_mov_wave_frames_frame_0080()
{ interval____doc_src_manual_mov_wave_frames_frame_0080 = interval____doc_src_manual_mov_wave_frames_frame_0080*0.7; }

// --->
</script>

<form>
&nbsp;
<input type="button" value="Start movie" onClick="startup____doc_src_manual_mov_wave_frames_frame_0080()">
<input type="button" value="Pause movie" onClick="stopit____doc_src_manual_mov_wave_frames_frame_0080()">
<input type="button" value="Restart movie" onClick="restart____doc_src_manual_mov_wave_frames_frame_0080()">
&nbsp;
<input type="button" value="Slower" onClick="slower____doc_src_manual_mov_wave_frames_frame_0080()">
<input type="button" value="Faster" onClick="faster____doc_src_manual_mov_wave_frames_frame_0080()">
</form>

<p><div ID="progress"></div></p>
<img src="../doc/src/manual/mov/wave_frames/frame_0080.png" name="name____doc_src_manual_mov_wave_frames_frame_0080" border=2/>

<br><em>Animated collection of images.</em><br>


</body>
</html>

************** File: movie_player6.html *****************

<html>
<head>
</head>
<body>
<title>Embedding media in HTML</title>

<script language="Javascript">
<!---
var num_images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080 = 50;
var img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080 = 800;
var img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080 = 600;
var interval_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080 = 300;
var images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080 = new Array();

function preload_images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080()
{
   t = document.getElementById("progress");

   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[0] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[0].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0080.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[1] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[1].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0081.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[2] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[2].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0082.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[3] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[3].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0083.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[4] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[4].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0084.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[5] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[5].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0085.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[6] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[6].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0086.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[7] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[7].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0087.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[8] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[8].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0088.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[9] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[9].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0089.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[10] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[10].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0090.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[11] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[11].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0091.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[12] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[12].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0092.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[13] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[13].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0093.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[14] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[14].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0094.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[15] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[15].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0095.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[16] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[16].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0096.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[17] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[17].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0097.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[18] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[18].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0098.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[19] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[19].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0099.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[20] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[20].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0100.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[21] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[21].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0101.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[22] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[22].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0102.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[23] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[23].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0103.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[24] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[24].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0104.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[25] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[25].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0105.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[26] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[26].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0106.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[27] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[27].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0107.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[28] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[28].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0108.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[29] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[29].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0109.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[30] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[30].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0110.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[31] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[31].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0111.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[32] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[32].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0112.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[33] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[33].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0113.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[34] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[34].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0114.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[35] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[35].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0115.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[36] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[36].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0116.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[37] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[37].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0117.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[38] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[38].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0118.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[39] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[39].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0119.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[40] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[40].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0120.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[41] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[41].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0121.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[42] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[42].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0122.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[43] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[43].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0123.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[44] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[44].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0124.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[45] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[45].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0125.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[46] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[46].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0126.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[47] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[47].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0127.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[48] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[48].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0128.png";
        
   t.innerHTML = "Preloading image ";
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[49] = new Image(img_width_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080, img_height_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
   images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[49].src = "https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0129.png";
        
   t.innerHTML = "";
}

function tick_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080()
{
   if (frame_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080 > num_images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080 - 1)
       frame_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080 = 0;

   document.name_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080.src = images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080[frame_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080].src;
   frame_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080 += 1;
   tt = setTimeout("tick_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080()", interval_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
}

function startup_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080()
{
   preload_images_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080();
   frame_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080 = 0;
   setTimeout("tick_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080()", interval_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080);
}

function stopit_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080()
{ clearTimeout(tt); }

function restart_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080()
{ tt = setTimeout("tick_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080()", interval_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080); }

function slower_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080()
{ interval_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080 = interval_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080/0.7; }

function faster_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080()
{ interval_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080 = interval_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080*0.7; }

// --->
</script>

<form>
&nbsp;
<input type="button" value="Start movie" onClick="startup_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080()">
<input type="button" value="Pause movie" onClick="stopit_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080()">
<input type="button" value="Restart movie" onClick="restart_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080()">
&nbsp;
<input type="button" value="Slower" onClick="slower_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080()">
<input type="button" value="Faster" onClick="faster_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080()">
</form>

<p><div ID="progress"></div></p>
<img src="https://hplgit.github.io/animate/doc/pub/mov-animate/frames/frame_0080.png" name="name_https___hplgit_github_io_animate_doc_pub_mov_animate_frames_frame_0080" border=2/>

<br><em>Taking images to animate from cyberspace.</em><br>


</body>
</html>

************** File: encoding3.do.txt *****************
## Test of handling non-ASCII characters in DocOnce
Text with a name like Åsmund Ødegård works in general.
# #ifdef PREPROCESS
Verbatim blocks with non-ASCII text does not work for HTML, but it works
for LaTeX. The remedy for HTML is to read the file with UTF-8 encoding.

!bc
a = 1  # Value suggested by Åsmund Ødegård.
!ec
# #endif

# #ifdef MAKO
## trigger Mako through the FORMAT variable...
This block (in format ${FORMAT})
triggers use of `mako`. For all formats, `mako` has
problem with non-ASCII characters anywhere in the text. The remedy
for all formats is to read the file with UTF-8 encoding. With --debug
one can see the internal str/unicode representation of the text
through the various stages of the text transformation process.

## Mako fails whether plain text or verbatim block:
$b = 1$ is a value suggested by Åsmund Ødegård.
# #endif


************** File: encoding3.p.tex-ascii *****************

% ------------------- main content ----------------------

Text with a name like Åsmund Ødegård works in general.



% ------------------- end of main content ---------------


************** File: encoding3.html-ascii *****************

<!-- tocinfo
{'highest level': 4, 'sections': []}
end of tocinfo -->


<!-- ------------------- main content ---------------------- -->

Text with a name like &#197;smund &#216;deg&#229;rd works in general.

<p>

<!-- ------------------- end of main content --------------- -->


    This is a log file for the doconce script.
    Debugging is turned on by the command-line argument '--debug'
    to doconce format. Without that command-line argument,
    this file is not produced.

    

******* output format: html *******




Found use of 2 preprocess directives # #if|define|include in file encoding3.do.txt



************************************************************
str>>> The file after running preprocess and/or mako:

## Test of handling non-ASCII characters in DocOnce
Text with a name like Åsmund Ødegård works in general.




************************************************************
str>>> The file after running @@@OSCMD (from file):

## Test of handling non-ASCII characters in DocOnce
Text with a name like Åsmund Ødegård works in general.




************************************************************
str>>> The file after inserting @@@CODE (from file):

## Test of handling non-ASCII characters in DocOnce
Text with a name like Åsmund Ødegård works in general.




************************************************************
str>>> The file after removal of code/tex blocks:

## Test of handling non-ASCII characters in DocOnce
Text with a name like Åsmund Ødegård works in general.



The code blocks:


The code block types:


The tex blocks:



************************************************************
str>>> The file after handling exercises:

Text with a name like Åsmund Ødegård works in general.




************************************************************
str>>> The file after handling figures:

Text with a name like Åsmund Ødegård works in general.




************************************************************
str>>> The file after handling ref and label cross referencing:

Text with a name like &#197;smund &#216;deg&#229;rd works in general.



************************************************************
str>>> The file after handling index and bibliography:

Text with a name like &#197;smund &#216;deg&#229;rd works in general.


*** List typesetting phase + comments and blank lines ***


[Text with a name like &#197;smund &#216;deg&#229;rd works in general.] (ordinary line)



************************************************************
str>>> The file after typesetting of lists:

Text with a name like &#197;smund &#216;deg&#229;rd works in general.

<p>


*** Dealing with authors and institutions ***



*** Inline tags substitution phase ***



*************** Working with tag "horizontal-rule"



*************** Working with tag "title"



*************** Working with tag "date"



*************** Working with tag "movie"



*************** Working with tag "inlinecomment"



*************** Working with tag "abstract"



*************** Working with tag "keywords"



*************** Working with tag "emphasize"



*************** Working with tag "math2"



*************** Working with tag "math"



*************** Working with tag "bold"



*************** Working with tag "ampersand2"



*************** Working with tag "ampersand1"



*************** Working with tag "colortext"



*************** Working with tag "verbatim"



*************** Working with tag "emoji"



*************** Working with tag "paragraph"



*************** Working with tag "plainURL"



*************** Working with tag "linkURL2v"



*************** Working with tag "linkURL3v"



*************** Working with tag "linkURL2"



*************** Working with tag "linkURL3"



*************** Working with tag "linkURL"



*************** Working with tag "chapter"



*************** Working with tag "section"



*************** Working with tag "subsection"



*************** Working with tag "subsubsection"



*************** Working with tag "linebreak"



*************** Working with tag "non-breaking-space"



************************************************************
str>>> The file after all inline substitutions:

Text with a name like &#197;smund &#216;deg&#229;rd works in general.

<p>


************************************************************
str>>> The file after typesetting of tables:

Text with a name like &#197;smund &#216;deg&#229;rd works in general.

<p>


************************************************************
str>>> The file after commenting out !split, !bpop, !epop, !bslidecell, !eslidecell, !bnotes, !enotes:

Text with a name like &#197;smund &#216;deg&#229;rd works in general.

<p>


************************************************************
str>>> File before call to insert_code_and_tex (format html):


<!-- ------------------- main content ---------------------- -->

Text with a name like &#197;smund &#216;deg&#229;rd works in general.

<p>

<!-- ------------------- end of main content --------------- -->


************************************************************
str>>> File after call to insert_code_and tex (format html):


<!-- ------------------- main content ---------------------- -->

Text with a name like &#197;smund &#216;deg&#229;rd works in general.

<p>

<!-- ------------------- end of main content --------------- -->


************************************************************
str>>> The file after inserting intro/outro and tex/code blocks, and fixing last format-specific issues:


<!-- tocinfo
{'highest level': 4, 'sections': []}
end of tocinfo -->


<!-- ------------------- main content ---------------------- -->

Text with a name like &#197;smund &#216;deg&#229;rd works in general.

<p>

<!-- ------------------- end of main content --------------- -->



************************************************************
str>>> The file after typesetting of admons and the rest of the !b/!e environments:


<!-- tocinfo
{'highest level': 4, 'sections': []}
end of tocinfo -->


<!-- ------------------- main content ---------------------- -->

Text with a name like &#197;smund &#216;deg&#229;rd works in general.

<p>

<!-- ------------------- end of main content --------------- -->



************************************************************
str>>> The file after potential removal of solutions, answers, hints, etc.:


<!-- tocinfo
{'highest level': 4, 'sections': []}
end of tocinfo -->


<!-- ------------------- main content ---------------------- -->

Text with a name like &#197;smund &#216;deg&#229;rd works in general.

<p>

<!-- ------------------- end of main content --------------- -->



************** File: encoding3.p.tex-ascii-verb *****************

% ------------------- main content ----------------------

Text with a name like Åsmund Ødegård works in general.
Verbatim blocks with non-ASCII text does not work for HTML, but it works
for {\LaTeX}. The remedy for HTML is to read the file with UTF-8 encoding.

\bccq
a = 1  # Value suggested by Åsmund Ødegård.
\eccq



% ------------------- end of main content ---------------


************** File: encoding3.html-ascii-verb *****************

<!-- tocinfo
{'highest level': 4, 'sections': []}
end of tocinfo -->


<!-- ------------------- main content ---------------------- -->

Text with a name like &#197;smund &#216;deg&#229;rd works in general.
Verbatim blocks with non-ASCII text does not work for HTML, but it works
for LaTeX. The remedy for HTML is to read the file with UTF-8 encoding.

<p>
<!-- begin verbatim block -->
<pre><code>a = 1  # Value suggested by Åsmund Ødegård.
</code></pre>
<!-- end verbatim block -->

<p>

<!-- ------------------- end of main content --------------- -->


    This is a log file for the doconce script.
    Debugging is turned on by the command-line argument '--debug'
    to doconce format. Without that command-line argument,
    this file is not produced.

    

******* output format: html *******




Found use of 2 preprocess directives # #if|define|include in file encoding3.do.txt



************************************************************
str>>> The file after running preprocess and/or mako:

## Test of handling non-ASCII characters in DocOnce
Text with a name like Åsmund Ødegård works in general.
Verbatim blocks with non-ASCII text does not work for HTML, but it works
for LaTeX. The remedy for HTML is to read the file with UTF-8 encoding.

!bc
a = 1  # Value suggested by Åsmund Ødegård.
!ec




************************************************************
str>>> The file after running @@@OSCMD (from file):

## Test of handling non-ASCII characters in DocOnce
Text with a name like Åsmund Ødegård works in general.
Verbatim blocks with non-ASCII text does not work for HTML, but it works
for LaTeX. The remedy for HTML is to read the file with UTF-8 encoding.

!bc
a = 1  # Value suggested by Åsmund Ødegård.
!ec




************************************************************
str>>> The file after inserting @@@CODE (from file):

## Test of handling non-ASCII characters in DocOnce
Text with a name like Åsmund Ødegård works in general.
Verbatim blocks with non-ASCII text does not work for HTML, but it works
for LaTeX. The remedy for HTML is to read the file with UTF-8 encoding.

!bc
a = 1  # Value suggested by Åsmund Ødegård.
!ec




************************************************************
str>>> The file after removal of code/tex blocks:

## Test of handling non-ASCII characters in DocOnce
Text with a name like Åsmund Ødegård works in general.
Verbatim blocks with non-ASCII text does not work for HTML, but it works
for LaTeX. The remedy for HTML is to read the file with UTF-8 encoding.

0 <<<!!CODE_BLOCK 




************************************************************
str>>> The code blocks:

0:
a = 1  # Value suggested by Åsmund Ødegård.

------------


************************************************************
str>>> The code block types:

0

The tex blocks:



************************************************************
str>>> The file after handling exercises:

Text with a name like Åsmund Ødegård works in general.
Verbatim blocks with non-ASCII text does not work for HTML, but it works
for LaTeX. The remedy for HTML is to read the file with UTF-8 encoding.

0 <<<!!CODE_BLOCK 




************************************************************
str>>> The file after handling figures:

Text with a name like Åsmund Ødegård works in general.
Verbatim blocks with non-ASCII text does not work for HTML, but it works
for LaTeX. The remedy for HTML is to read the file with UTF-8 encoding.

0 <<<!!CODE_BLOCK 




************************************************************
str>>> The file after handling ref and label cross referencing:

Text with a name like &#197;smund &#216;deg&#229;rd works in general.
Verbatim blocks with non-ASCII text does not work for HTML, but it works
for LaTeX. The remedy for HTML is to read the file with UTF-8 encoding.

0 <<<!!CODE_BLOCK 



************************************************************
str>>> The file after handling index and bibliography:

Text with a name like &#197;smund &#216;deg&#229;rd works in general.
Verbatim blocks with non-ASCII text does not work for HTML, but it works
for LaTeX. The remedy for HTML is to read the file with UTF-8 encoding.

0 <<<!!CODE_BLOCK 


*** List typesetting phase + comments and blank lines ***


[Text with a name like &#197;smund &#216;deg&#229;rd works in general.] (ordinary line)


[Verbatim blocks with non-ASCII text does not work for HTML, but it works] (ordinary line)


[for LaTeX. The remedy for HTML is to read the file with UTF-8 encoding.] (ordinary line)


[0 <<<!!CODE_BLOCK ] (ordinary line)



************************************************************
str>>> The file after typesetting of lists:

Text with a name like &#197;smund &#216;deg&#229;rd works in general.
Verbatim blocks with non-ASCII text does not work for HTML, but it works
for LaTeX. The remedy for HTML is to read the file with UTF-8 encoding.

<p>
0 <<<!!CODE_BLOCK 

<p>


*** Dealing with authors and institutions ***



*** Inline tags substitution phase ***



*************** Working with tag "horizontal-rule"



*************** Working with tag "title"



*************** Working with tag "date"



*************** Working with tag "movie"



*************** Working with tag "inlinecomment"



*************** Working with tag "abstract"



*************** Working with tag "keywords"



*************** Working with tag "emphasize"



*************** Working with tag "math2"



*************** Working with tag "math"



*************** Working with tag "bold"



*************** Working with tag "ampersand2"



*************** Working with tag "ampersand1"



*************** Working with tag "colortext"



*************** Working with tag "verbatim"



*************** Working with tag "emoji"



*************** Working with tag "paragraph"



*************** Working with tag "plainURL"



*************** Working with tag "linkURL2v"



*************** Working with tag "linkURL3v"



*************** Working with tag "linkURL2"



*************** Working with tag "linkURL3"



*************** Working with tag "linkURL"



*************** Working with tag "chapter"



*************** Working with tag "section"



*************** Working with tag "subsection"



*************** Working with tag "subsubsection"



*************** Working with tag "linebreak"



*************** Working with tag "non-breaking-space"



************************************************************
str>>> The file after all inline substitutions:

Text with a name like &#197;smund &#216;deg&#229;rd works in general.
Verbatim blocks with non-ASCII text does not work for HTML, but it works
for LaTeX. The remedy for HTML is to read the file with UTF-8 encoding.

<p>
0 <<<!!CODE_BLOCK 

<p>


************************************************************
str>>> The file after typesetting of tables:

Text with a name like &#197;smund &#216;deg&#229;rd works in general.
Verbatim blocks with non-ASCII text does not work for HTML, but it works
for LaTeX. The remedy for HTML is to read the file with UTF-8 encoding.

<p>
0 <<<!!CODE_BLOCK 

<p>


************************************************************
str>>> The file after commenting out !split, !bpop, !epop, !bslidecell, !eslidecell, !bnotes, !enotes:

Text with a name like &#197;smund &#216;deg&#229;rd works in general.
Verbatim blocks with non-ASCII text does not work for HTML, but it works
for LaTeX. The remedy for HTML is to read the file with UTF-8 encoding.

<p>
0 <<<!!CODE_BLOCK 

<p>


************************************************************
str>>> File before call to insert_code_and_tex (format html):


<!-- ------------------- main content ---------------------- -->

Text with a name like &#197;smund &#216;deg&#229;rd works in general.
Verbatim blocks with non-ASCII text does not work for HTML, but it works
for LaTeX. The remedy for HTML is to read the file with UTF-8 encoding.

<p>
0 <<<!!CODE_BLOCK 

<p>

<!-- ------------------- end of main content --------------- -->


************************************************************
str>>> File after call to insert_code_and tex (format html):


<!-- ------------------- main content ---------------------- -->

Text with a name like &#197;smund &#216;deg&#229;rd works in general.
Verbatim blocks with non-ASCII text does not work for HTML, but it works
for LaTeX. The remedy for HTML is to read the file with UTF-8 encoding.

<p>
!bc
a = 1  # Value suggested by Åsmund Ødegård.
!ec

<p>

<!-- ------------------- end of main content --------------- -->


************************************************************
str>>> The file after inserting intro/outro and tex/code blocks, and fixing last format-specific issues:


<!-- tocinfo
{'highest level': 4, 'sections': []}
end of tocinfo -->


<!-- ------------------- main content ---------------------- -->

Text with a name like &#197;smund &#216;deg&#229;rd works in general.
Verbatim blocks with non-ASCII text does not work for HTML, but it works
for LaTeX. The remedy for HTML is to read the file with UTF-8 encoding.

<p>
<!-- begin verbatim block -->
<pre><code>a = 1  # Value suggested by Åsmund Ødegård.
</code></pre>
<!-- end verbatim block -->

<p>

<!-- ------------------- end of main content --------------- -->



************************************************************
str>>> The file after typesetting of admons and the rest of the !b/!e environments:


<!-- tocinfo
{'highest level': 4, 'sections': []}
end of tocinfo -->


<!-- ------------------- main content ---------------------- -->

Text with a name like &#197;smund &#216;deg&#229;rd works in general.
Verbatim blocks with non-ASCII text does not work for HTML, but it works
for LaTeX. The remedy for HTML is to read the file with UTF-8 encoding.

<p>
<!-- begin verbatim block -->
<pre><code>a = 1  # Value suggested by Åsmund Ødegård.
</code></pre>
<!-- end verbatim block -->

<p>

<!-- ------------------- end of main content --------------- -->



************************************************************
str>>> The file after potential removal of solutions, answers, hints, etc.:


<!-- tocinfo
{'highest level': 4, 'sections': []}
end of tocinfo -->


<!-- ------------------- main content ---------------------- -->

Text with a name like &#197;smund &#216;deg&#229;rd works in general.
Verbatim blocks with non-ASCII text does not work for HTML, but it works
for LaTeX. The remedy for HTML is to read the file with UTF-8 encoding.

<p>
<!-- begin verbatim block -->
<pre><code>a = 1  # Value suggested by Åsmund Ødegård.
</code></pre>
<!-- end verbatim block -->

<p>

<!-- ------------------- end of main content --------------- -->



************** File: encoding3.p.tex-utf8 *****************

% ------------------- main content ----------------------

Text with a name like Åsmund Ødegård works in general.

This block (in format latex)
triggers use of \texttt{mako}. For all formats, \texttt{mako} has
problem with non-ASCII characters anywhere in the text. The remedy
for all formats is to read the file with UTF-8 encoding. With --debug
one can see the internal str/unicode representation of the text
through the various stages of the text transformation process.

$b = 1$ is a value suggested by Åsmund Ødegård.


% ------------------- end of main content ---------------


************** File: encoding3.html-utf8 *****************

<!-- tocinfo
{'highest level': 4, 'sections': []}
end of tocinfo -->





<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  TeX: {
     equationNumbers: {  autoNumber: "AMS"  },
     extensions: ["AMSmath.js", "AMSsymbols.js", "autobold.js", "color.js"]
  }
});
</script>
<script type="text/javascript" async
 src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>



<!-- ------------------- main content ---------------------- -->

Text with a name like &#197;smund &#216;deg&#229;rd works in general.

<p>
This block (in format html)
triggers use of <code>mako</code>. For all formats, <code>mako</code> has
problem with non-ASCII characters anywhere in the text. The remedy
for all formats is to read the file with UTF-8 encoding. With --debug
one can see the internal str/unicode representation of the text
through the various stages of the text transformation process.

<p>
\( b = 1 \) is a value suggested by &#197;smund &#216;deg&#229;rd.

<!-- ------------------- end of main content --------------- -->


    This is a log file for the doconce script.
    Debugging is turned on by the command-line argument '--debug'
    to doconce format. Without that command-line argument,
    this file is not produced.

    

******* output format: html *******




Found use of 2 preprocess directives # #if|define|include in file encoding3.do.txt


Found use of mako variable(s) in tmp_preprocess__encoding3.do.txt: ${FORMAT}


Keyword arguments to be sent to mako: {'DEVICE': 'screen', 'FORMAT': 'html', 'MAKO': True}



************************************************************
str>>> The file after running preprocess and/or mako:

Text with a name like Åsmund Ødegård works in general.

This block (in format html)
triggers use of `mako`. For all formats, `mako` has
problem with non-ASCII characters anywhere in the text. The remedy
for all formats is to read the file with UTF-8 encoding. With --debug
one can see the internal str/unicode representation of the text
through the various stages of the text transformation process.

$b = 1$ is a value suggested by Åsmund Ødegård.



************************************************************
str>>> The file after running @@@OSCMD (from file):

Text with a name like Åsmund Ødegård works in general.

This block (in format html)
triggers use of `mako`. For all formats, `mako` has
problem with non-ASCII characters anywhere in the text. The remedy
for all formats is to read the file with UTF-8 encoding. With --debug
one can see the internal str/unicode representation of the text
through the various stages of the text transformation process.

$b = 1$ is a value suggested by Åsmund Ødegård.



************************************************************
str>>> The file after inserting @@@CODE (from file):

Text with a name like Åsmund Ødegård works in general.

This block (in format html)
triggers use of `mako`. For all formats, `mako` has
problem with non-ASCII characters anywhere in the text. The remedy
for all formats is to read the file with UTF-8 encoding. With --debug
one can see the internal str/unicode representation of the text
through the various stages of the text transformation process.

$b = 1$ is a value suggested by Åsmund Ødegård.



************************************************************
str>>> The file after removal of code/tex blocks:

Text with a name like Åsmund Ødegård works in general.

This block (in format html)
triggers use of `mako`. For all formats, `mako` has
problem with non-ASCII characters anywhere in the text. The remedy
for all formats is to read the file with UTF-8 encoding. With --debug
one can see the internal str/unicode representation of the text
through the various stages of the text transformation process.

$b = 1$ is a value suggested by Åsmund Ødegård.


The code blocks:


The code block types:


The tex blocks:



************************************************************
str>>> The file after handling exercises:

Text with a name like Åsmund Ødegård works in general.

This block (in format html)
triggers use of `mako`. For all formats, `mako` has
problem with non-ASCII characters anywhere in the text. The remedy
for all formats is to read the file with UTF-8 encoding. With --debug
one can see the internal str/unicode representation of the text
through the various stages of the text transformation process.

$b = 1$ is a value suggested by Åsmund Ødegård.



************************************************************
str>>> The file after handling figures:

Text with a name like Åsmund Ødegård works in general.

This block (in format html)
triggers use of `mako`. For all formats, `mako` has
problem with non-ASCII characters anywhere in the text. The remedy
for all formats is to read the file with UTF-8 encoding. With --debug
one can see the internal str/unicode representation of the text
through the various stages of the text transformation process.

$b = 1$ is a value suggested by Åsmund Ødegård.



************************************************************
str>>> The file after handling ref and label cross referencing:

Text with a name like &#197;smund &#216;deg&#229;rd works in general.

This block (in format html)
triggers use of `mako`. For all formats, `mako` has
problem with non-ASCII characters anywhere in the text. The remedy
for all formats is to read the file with UTF-8 encoding. With --debug
one can see the internal str/unicode representation of the text
through the various stages of the text transformation process.

$b = 1$ is a value suggested by &#197;smund &#216;deg&#229;rd.


************************************************************
str>>> The file after handling index and bibliography:

Text with a name like &#197;smund &#216;deg&#229;rd works in general.

This block (in format html)
triggers use of `mako`. For all formats, `mako` has
problem with non-ASCII characters anywhere in the text. The remedy
for all formats is to read the file with UTF-8 encoding. With --debug
one can see the internal str/unicode representation of the text
through the various stages of the text transformation process.

$b = 1$ is a value suggested by &#197;smund &#216;deg&#229;rd.

*** List typesetting phase + comments and blank lines ***


[Text with a name like &#197;smund &#216;deg&#229;rd works in general.] (ordinary line)


[This block (in format html)] (ordinary line)


[triggers use of `mako`. For all formats, `mako` has] (ordinary line)


[problem with non-ASCII characters anywhere in the text. The remedy] (ordinary line)


[for all formats is to read the file with UTF-8 encoding. With --debug] (ordinary line)


[one can see the internal str/unicode representation of the text] (ordinary line)


[through the various stages of the text transformation process.] (ordinary line)


[$b = 1$ is a value suggested by &#197;smund &#216;deg&#229;rd.] (ordinary line)



************************************************************
str>>> The file after typesetting of lists:

Text with a name like &#197;smund &#216;deg&#229;rd works in general.

<p>
This block (in format html)
triggers use of `mako`. For all formats, `mako` has
problem with non-ASCII characters anywhere in the text. The remedy
for all formats is to read the file with UTF-8 encoding. With --debug
one can see the internal str/unicode representation of the text
through the various stages of the text transformation process.

<p>
$b = 1$ is a value suggested by &#197;smund &#216;deg&#229;rd.


*** Dealing with authors and institutions ***



*** Inline tags substitution phase ***



*************** Working with tag "horizontal-rule"



*************** Working with tag "title"



*************** Working with tag "date"



*************** Working with tag "movie"



*************** Working with tag "inlinecomment"



*************** Working with tag "abstract"



*************** Working with tag "keywords"



*************** Working with tag "emphasize"



*************** Working with tag "math2"



*************** Working with tag "math"


Found 1 occurences of "math":
findall list: [('\n', '\n', 'b = 1', ' ', ' ')]


math is to be replaced using \g<begin>\( \g<subst> \)\g<end>


First occurence: "
$b = 1$ "
groups: ('\n', '\n', 'b = 1', ' ', ' ')
named groups: {'begin': '\n', 'subst': 'b = 1', 'end': ' '}



**** The file after 1 "math" substitutions ***
Text with a name like &#197;smund &#216;deg&#229;rd works in general.

<p>
This block (in format html)
triggers use of `mako`. For all formats, `mako` has
problem with non-ASCII characters anywhere in the text. The remedy
for all formats is to read the file with UTF-8 encoding. With --debug
one can see the internal str/unicode representation of the text
through the various stages of the text transformation process.

<p>
\( b = 1 \) is a value suggested by &#197;smund &#216;deg&#229;rd.

--------------------------------------------------------------------------------





*************** Working with tag "bold"



*************** Working with tag "ampersand2"



*************** Working with tag "ampersand1"



*************** Working with tag "colortext"



*************** Working with tag "verbatim"


Found 2 occurences of "verbatim":
findall list: [(' ', ' ', 'mako', '.', '.'), (' ', ' ', 'mako', ' ', ' ')]


verbatim is to be replaced using <function html_verbatim at XXX>


First occurence: " `mako`."
groups: (' ', ' ', 'mako', '.', '.')
named groups: {'begin': ' ', 'subst': 'mako', 'end': '.'}



**** The file after 2 "verbatim" substitutions ***
Text with a name like &#197;smund &#216;deg&#229;rd works in general.

<p>
This block (in format html)
triggers use of <code>mako</code>. For all formats, <code>mako</code> has
problem with non-ASCII characters anywhere in the text. The remedy
for all formats is to read the file with UTF-8 encoding. With --debug
one can see the internal str/unicode representation of the text
through the various stages of the text transformation process.

<p>
\( b = 1 \) is a value suggested by &#197;smund &#216;deg&#229;rd.

--------------------------------------------------------------------------------





*************** Working with tag "emoji"



*************** Working with tag "paragraph"



*************** Working with tag "plainURL"



*************** Working with tag "linkURL2v"



*************** Working with tag "linkURL3v"



*************** Working with tag "linkURL2"



*************** Working with tag "linkURL3"



*************** Working with tag "linkURL"



*************** Working with tag "chapter"



*************** Working with tag "section"



*************** Working with tag "subsection"



*************** Working with tag "subsubsection"



*************** Working with tag "linebreak"



*************** Working with tag "non-breaking-space"



************************************************************
str>>> The file after all inline substitutions:

Text with a name like &#197;smund &#216;deg&#229;rd works in general.

<p>
This block (in format html)
triggers use of <code>mako</code>. For all formats, <code>mako</code> has
problem with non-ASCII characters anywhere in the text. The remedy
for all formats is to read the file with UTF-8 encoding. With --debug
one can see the internal str/unicode representation of the text
through the various stages of the text transformation process.

<p>
\( b = 1 \) is a value suggested by &#197;smund &#216;deg&#229;rd.


************************************************************
str>>> The file after typesetting of tables:

Text with a name like &#197;smund &#216;deg&#229;rd works in general.

<p>
This block (in format html)
triggers use of <code>mako</code>. For all formats, <code>mako</code> has
problem with non-ASCII characters anywhere in the text. The remedy
for all formats is to read the file with UTF-8 encoding. With --debug
one can see the internal str/unicode representation of the text
through the various stages of the text transformation process.

<p>
\( b = 1 \) is a value suggested by &#197;smund &#216;deg&#229;rd.


************************************************************
str>>> The file after commenting out !split, !bpop, !epop, !bslidecell, !eslidecell, !bnotes, !enotes:

Text with a name like &#197;smund &#216;deg&#229;rd works in general.

<p>
This block (in format html)
triggers use of <code>mako</code>. For all formats, <code>mako</code> has
problem with non-ASCII characters anywhere in the text. The remedy
for all formats is to read the file with UTF-8 encoding. With --debug
one can see the internal str/unicode representation of the text
through the various stages of the text transformation process.

<p>
\( b = 1 \) is a value suggested by &#197;smund &#216;deg&#229;rd.


************************************************************
str>>> File before call to insert_code_and_tex (format html):


<!-- ------------------- main content ---------------------- -->

Text with a name like &#197;smund &#216;deg&#229;rd works in general.

<p>
This block (in format html)
triggers use of <code>mako</code>. For all formats, <code>mako</code> has
problem with non-ASCII characters anywhere in the text. The remedy
for all formats is to read the file with UTF-8 encoding. With --debug
one can see the internal str/unicode representation of the text
through the various stages of the text transformation process.

<p>
\( b = 1 \) is a value suggested by &#197;smund &#216;deg&#229;rd.

<!-- ------------------- end of main content --------------- -->


************************************************************
str>>> File after call to insert_code_and tex (format html):


<!-- ------------------- main content ---------------------- -->

Text with a name like &#197;smund &#216;deg&#229;rd works in general.

<p>
This block (in format html)
triggers use of <code>mako</code>. For all formats, <code>mako</code> has
problem with non-ASCII characters anywhere in the text. The remedy
for all formats is to read the file with UTF-8 encoding. With --debug
one can see the internal str/unicode representation of the text
through the various stages of the text transformation process.

<p>
\( b = 1 \) is a value suggested by &#197;smund &#216;deg&#229;rd.

<!-- ------------------- end of main content --------------- -->


************************************************************
str>>> The file after inserting intro/outro and tex/code blocks, and fixing last format-specific issues:


<!-- tocinfo
{'highest level': 4, 'sections': []}
end of tocinfo -->





<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  TeX: {
     equationNumbers: {  autoNumber: "AMS"  },
     extensions: ["AMSmath.js", "AMSsymbols.js", "autobold.js", "color.js"]
  }
});
</script>
<script type="text/javascript" async
 src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>



<!-- ------------------- main content ---------------------- -->

Text with a name like &#197;smund &#216;deg&#229;rd works in general.

<p>
This block (in format html)
triggers use of <code>mako</code>. For all formats, <code>mako</code> has
problem with non-ASCII characters anywhere in the text. The remedy
for all formats is to read the file with UTF-8 encoding. With --debug
one can see the internal str/unicode representation of the text
through the various stages of the text transformation process.

<p>
\( b = 1 \) is a value suggested by &#197;smund &#216;deg&#229;rd.

<!-- ------------------- end of main content --------------- -->



************************************************************
str>>> The file after typesetting of admons and the rest of the !b/!e environments:


<!-- tocinfo
{'highest level': 4, 'sections': []}
end of tocinfo -->





<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  TeX: {
     equationNumbers: {  autoNumber: "AMS"  },
     extensions: ["AMSmath.js", "AMSsymbols.js", "autobold.js", "color.js"]
  }
});
</script>
<script type="text/javascript" async
 src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>



<!-- ------------------- main content ---------------------- -->

Text with a name like &#197;smund &#216;deg&#229;rd works in general.

<p>
This block (in format html)
triggers use of <code>mako</code>. For all formats, <code>mako</code> has
problem with non-ASCII characters anywhere in the text. The remedy
for all formats is to read the file with UTF-8 encoding. With --debug
one can see the internal str/unicode representation of the text
through the various stages of the text transformation process.

<p>
\( b = 1 \) is a value suggested by &#197;smund &#216;deg&#229;rd.

<!-- ------------------- end of main content --------------- -->



************************************************************
str>>> The file after potential removal of solutions, answers, hints, etc.:


<!-- tocinfo
{'highest level': 4, 'sections': []}
end of tocinfo -->





<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  TeX: {
     equationNumbers: {  autoNumber: "AMS"  },
     extensions: ["AMSmath.js", "AMSsymbols.js", "autobold.js", "color.js"]
  }
});
</script>
<script type="text/javascript" async
 src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>



<!-- ------------------- main content ---------------------- -->

Text with a name like &#197;smund &#216;deg&#229;rd works in general.

<p>
This block (in format html)
triggers use of <code>mako</code>. For all formats, <code>mako</code> has
problem with non-ASCII characters anywhere in the text. The remedy
for all formats is to read the file with UTF-8 encoding. With --debug
one can see the internal str/unicode representation of the text
through the various stages of the text transformation process.

<p>
\( b = 1 \) is a value suggested by &#197;smund &#216;deg&#229;rd.

<!-- ------------------- end of main content --------------- -->



************** File: _genref1.do.txt *****************
NOT FOUND!
************** File: _genref2.do.txt *****************
NOT FOUND!
************** File: _tmp_genref2.do.txt *****************
NOT FOUND!
************** File: tmp_subst_references.sh *****************
files="genref2.do.txt"  # files to which substitutions apply


************** File: Springer_T2/Springer_T2_book.do.txt *****************
# Note on the Springer T2 style: used the modifications in t2do.sty
# and svmonodo.cls (come bundled with DocOnce).

TITLE:  Test of DocOnce-Based Book with Springer's T2/T4 Styles
AUTHOR: Hans Petter Langtangen at Center for Biomedical Computing, Simula Research Laboratory & Department of Informatics, University of Oslo
DATE: today

<%
src_path = 'https://some.where.net/doconce/test/software'
%>


========= Preface =========

The aim of this book is to teach computer programming using examples
from mathematics and the natural sciences.  We have chosen to use the
Python programming language because it combines remarkable expressive
power with very clean, simple, and compact syntax.  Python is easy to
learn and very well suited for an introduction to computer
programming. Python is also quite similar to MATLAB and a good
language for doing mathematical computing.  It is easy to combine
Python with compiled languages, like Fortran, C, and C++, which are
widely used languages for scientific computations.  A seamless
integration of Python with Java is offered by a special version of
Python called Jython.

The examples in this book integrate programming with applications to
mathematics, physics, biology, and finance.  The reader is expected to
have knowledge of basic one-variable calculus as taught in
mathematics-intensive programs in high schools. It is certainly an
advantage to take a university calculus course in parallel, preferably
containing both classical and numerical aspects of calculus.  Although
not strictly required, a background in high school physics makes many
of the examples more meaningful.

Many introductory programming books are quite compact and focus on
listing functionality of a programming language. However, learning to
program is learning how to *think* as a programmer.  This book
has its main focus on the thinking process, or equivalently:
programming as a problem solving technique. That is why most of the
pages are devoted to case studies in programming, where we define a
problem and explain how to create the corresponding program.  New
constructions and programming styles (what we could call theory) is also usually
introduced via examples.  Special attention is paid to verification of
programs and to finding errors. These topics are very demanding for
mathematical software, because the unavoidable numerical
approximation errors are possibly mixed with programming mistakes.

By studying the many examples in the
book, I hope readers will learn how to think right and thereby
write programs in a quicker and more reliable way. Remember, nobody can learn
programming by just reading - one has to solve a large amount of
exercises hands on.  The book is therefore full of exercises of
various types: modifications of existing examples, completely new
problems, or debugging of given programs.

=== Python version 2 or 3? ===

A common problem among Python programmers is to choose between version
2 or 3, which at the time of this writing means choosing
between version 2.7 and 3.3.
The general recommendation is to go for version 3, but programs are
then not compatible with version 2 and vice versa. There is still
a problem that much useful mathematical software in Python
has not yet been ported to version 3. Therefore, scientific computing
with Python still goes mostly with version 2.
A widely used strategy for software
developers who want to write Python code that works with both versions,
is to develop for v2.7, which is very close to what is accepted
in version 3, and then
use the ranslation tool *2to3* to automatically translate the code
to version 3.

When using v2.7, one should employ the newest syntax
and modules that make the differences beween version 2 and 3 very small.
This strategy is adopted in the present book. Only two
differences between versions 2 and 3 are expected to be significant for
the programs in the book:
`a/b` implies float division in version 3 if `a` and `b`
are integers,
and `print('Hello')` in version 2 must be turned into a function call
`print('Hello')` in version 3. None of these differences should lead
to any annoying problems when future readers study the book's v2.7
examples, but program in version 3. Anyway, running 2to3 on the
example files generates the corresponding version 3 code.

=== Acknowledgments ===

Several people have helped to make substantial improvements of the
text. Here I list only the names with Norwgian characters to
test the handling of those: Ståle Zerener Haugnæss,
Tobias Vidarssønn Langhoff, and Håkon Møller.

# #if FORMAT in ("latex", "pdflatex")
\vspace{1cm}

\noindent
*Oslo, May 2015*  \hfill  *Hans Petter Langtangen*
# #endif


TOC: on


========= Basic array computing and plotting =========

This ${CHAPTER} gives an introduction to arrays: how they are created
and what they can be used for.  Array computing usually ends up with a
lot of numbers. It may be very hard to understand what these numbers
mean by just looking at them. Since the human is a visual animal, a
good way to understand numbers is to visualize them. In this
${CHAPTER} we concentrate on visualizing curves that reflect functions
of one variable; i.e., curves of the form $y=f(x)$.  A synonym for
curve is graph, and the image of curves on the screen is often called
a plot.  We will use arrays to store the information about points
along the curve. In a nutshell, array computing demands visualization
and visualization demands arrays.

All program examples in this ${CHAPTER} can be found as files in the
folder "`src/plot`": "${src_path}/plot".

======= Arrays in Python programs =======
label{sec:plot:arraycomp}

This section introduces array programming in Python, but first we
create some lists and show how arrays differ from lists.

===== Using lists for collecting function data =====
label{sec:plot:listdata}

Suppose we have a function $f(x)$ and want to evaluate this function
at a number of $x$ points $x_0,x_1,\ldots,x_{n-1}$.  We could collect
the $n$ pairs $(x_i,f(x_i))$ in a list, or we could collect all the
$x_i$ values, for $i=0,\ldots,n-1$, in a list and all the associated
$f(x_i)$ values in another list.  The following interactive session
demonstrates how to create these three types of lists:

!bc py
>>> def f(x):
...     return x**3       # sample function
...
>>> n = 5                 # no of points along the x axis
>>> dx = 1.0/(n-1)        # spacing between x points in [0,1]
>>> xlist = [i*dx for i in range(n)]
>>> ylist = [f(x) for x in xlist]
>>> pairs = [[x, y] for x, y in zip(xlist, ylist)]
!ec
Here we have used list comprehensions for achieving compact code. Make
sure that you understand what is going on in these list comprehensions
(if not, try to write the same code using standard `for` loops and
appending new list elements in each pass of the loops).

idx{heterogeneous lists}

The list elements consist of objects of the same type: any element in
`pairs` is a list of two `float` objects, while any element in `xlist`
or `ylist` is a `float`. Lists are more flexible than that, because an
element can be an object of any type, e.g.,

!bc pycod
mylist = [2, 6.0, 'tmp.ps', [0,1]]
!ec
Here `mylist` holds an `int`, a `float`, a string, and a list. This
combination of diverse object types makes up what is known as
*heterogeneous* lists.  We can also easily remove elements from a list
or add new elements anywhere in the list.  This flexibility of lists
is in general convenient to have as a programmer, but in cases where
the elements are of the same type and the number of elements is fixed,
arrays can be used instead. The benefits of arrays are faster
computations, less memory demands, and extensive support for
mathematical operations on the data.  Because of greater efficiency
and mathematical convenience, arrays will be used to a large extent in
this ${BOOK}.  The great use of arrays is also prominent in other
programming environments such as MATLAB, Octave, and R, for instance.
Lists will be our choice instead of arrays when we need the
flexibility of adding or removing elements or when the elements may be
of different object types.

!bquote
*People only become computer programmers if they're
obsessive about details, crave power over machines, and can bear
to be told day after day exactly how
stupid they are.* <linebreak>
Gregory J. E. Rawlins cite{Rawlins_1998}, computer scientist.
!equote

===== Basics of numerical Python arrays =====
label{sec:plot:array:basics}

idx{Numerical Python} idx{NumPy} idx{`numpy`}
idx{array (datatype)} idx{array computing}
idx{vectorization}

An *array* object can be viewed as a variant of a list, but with the
following assumptions and features:

  * All elements must be of the same type, preferably integer, real, or complex numbers, for efficient numerical computing and storage.
  * The number of elements must be known when the array is created.
  * Arrays are not part of standard Python - one needs an additional package called *Numerical Python*, often abbreviated as NumPy. The Python name of the package, to be used in `import` statements, is `numpy`.
  * With `numpy`, a wide range of mathematical operations can be done directly on complete arrays, thereby removing the need for loops over array elements. This is commonly called *vectorization* %or *array computing* and may cause a dramatic speed-up of Python programs. Vectorization makes use of the vector computing concepts from Section ref{sec:plot:arraycomp}.
  * Arrays with one index are often called vectors. Arrays with two indices are used as an efficient data structure for tables, instead of lists of lists. Arrays can also have three or more indices.

!bnotice Remarks

 o There is actually an
   object type called `array` in standard Python, but this data type is
   not so efficient for mathematical computations, and we will not use it
   in this ${BOOK}.
 o The number of elements in an array *can* be
   changed, but at a substantial computational cost.
!enotice

The following text lists some important functionality of NumPy arrays.
A more comprehensive treatment is found in the excellent *NumPy
Tutorial*, *NumPy User Guide*, *NumPy Reference*, *Guide to NumPy*,
and *NumPy for MATLAB Users*, all accessible at "scipy.org":
"https://scipy.org".


idx{`zeros` (from `numpy`)} idx{`np.zeros` function}
idx{`array` (from `numpy`)} idx{`np.array` function}
idx{`np` prefix (`numpy`)}
idx{`zeros_like` (from `numpy`)}idx{`np.zeros_like` function}


!bnotice Remarks on importing NumPy
The statement

!bc pycod
import numpy as np
!ec
with subsequent prefixing of all NumPy functions and variables by `np.`,
has evolved as a standard syntax in the Python scientific computing
community. However, to make Python programs look closer to MATLAB
and ease the transition to and from that language, one can do

!bc pycod
from numpy import *
!ec
to get rid of the prefix (this is evolved as the standard in
*interactive* Python shells). This author prefers mathematical
functions from `numpy` to be written without the prefix to
make the formulas as close as possible to the mathematics.
So, $f(x)=\sinh(x-1)\sin(w t)$ would be coded as

!bc pycod
from numpy import sinh, sin

def f(x):
    return sinh(x-1)*sin(w*t)
!ec
or one may take the less recommended
lazy approach `from numpy import *` and fill up
the program with *a lot* of functions and variables from `numpy`.
!enotice

To convert a list `r` to an array,
we use the `array` function
from `numpy`:

!bc pycod
a = np.array(r)
!ec
To create a new array of length `n`, filled with zeros, we write

!bc pycod
a = np.zeros(n)
!ec
The array elements are of a type that corresponds to Python's
`float` type. A second argument to `np.zeros` can be used to
specify other element types, e.g., `int`.
A similar function,

!bc pycod
a = np.zeros_like(c)
!ec
generates an array of zeros where the length is that of the array `c`
and the element type is the same as those in `c`.

idx{`linspace` (from `numpy`)}idx{`np.linspace` function}

Often one wants an array to have $n$ elements with uniformly
distributed values in an interval $[p,q]$. The `numpy` function
`linspace` creates such arrays:

!bc pycod
a = np.linspace(p, q, n)
!ec

|-------------c-----------------------------------------c-------------------------------|
| Construction              | Meaning                                                   |
|-------------l-----------------------------------------l-------------------------------|
| `array(ld)`               | copy list data `ld` to a `numpy` array                    |
| `asarray(d)`              | make array of data `d` (no data copy if already array)    |
| `zeros(n)`                | make a `float` vector/array of length `n`, with zeros     |
| `zeros(n, int)`           | make an `int` vector/array of length `n` with zeros       |
| `zeros((m,n))`            | make a two-dimensional `float` array with shape (`m`,`n`) |
| `zeros_like(x)`           | make array of same shape and element type as `x`          |
| `linspace(a,b,m)`         | uniform sequence of `m` numbers in $[a,b]$                |
| `a.shape`                 | tuple containing `a`'s shape                              |
| `a.size`                  | total no of elements in `a`                               |
| `len(a)`                  | length of a one-dim. array `a` (same as `a.shape[0]`)     |
| `a.dtype`                 | the type of elements in `a`                               |
| `a.reshape(3,2)`          | return `a` reshaped as $3\times 2$ array                  |
| `a[i]`                    | vector indexing                                           |
| `a[i,j]`                  | two-dim. array indexing                                   |
| `a[1:k]`                  | slice: reference data with indices `1`,\ldots,`k-1`       |
| `a[1:8:3]`                | slice: reference data with indices `1`, `4`,\ldots,`7`    |
| `b = a.copy()`            | copy an array                                             |
|---------------------------------------------------------------------------------------|

========= Storing results in data files and adding more words here to get a very long chapter heading =========

We need to test spaces around footnotes for 2-digit footnotes, which
means we need a lot of URLs, e.g., to files:
"`ball2_cml.py`": "${src_path}/input/ball2_cml.py",
"`bisection_ex.py`": "${src_path}/input/bisection_ex.py",
"`bisection_movie.py`": "${src_path}/input/bisection_movie.py",
"`bisection_plot.py`": "${src_path}/input/bisection_plot.py",
"`bisection.py`": "${src_path}/input/bisection.py",
"`bisection_v1.py`": "${src_path}/input/bisection_v1.py",
"`bisection_v2.py`": "${src_path}/input/bisection_v2.py",
"`c2f_cml.py`": "${src_path}/input/c2f_cml.py",
"`data.txt`": "${src_path}/input/data.txt",
"`Fdeg.dat`": "${src_path}/input/Fdeg.dat",
"`integrate.py`": "${src_path}/input/integrate.py", and
"`interest.py`": "${src_path}/input/interest.py".

======= Writing data to file =======
label{sec:files:writing}

Writing data to file is easy.
There is basically one function to pay attention to: `outfile.write(s)`,
which writes a string `s` to
a file handled by the file object `outfile`. Unlike `print`,
`outfile.write(s)`
does not append a newline character to the written string.
It will therefore
often be necessary to add a newline character,

!bc pycod
outfile.write(s + '\n')
!ec
if the string `s` is meant to appear on a single line in the file
and `s` does not already contain a trailing newline character.
File writing is then a matter of constructing strings containing the
text we want to have in the file and for each such string call
`outfile.write`.

Writing to a file demands
the file object `f`
to be opened for writing:

!bc pycod
# write to new file, or overwrite file:
outfile = open(filename, 'w')

# append to the end of an existing file:
outfile = open(filename, 'a')
!ec

===== Example: Writing a table to file =====

=== Problem ===

As a worked example of file writing,
we shall write out a nested list with tabular data to file.
A sample list may take look as

!bc ccq
[[ 0.75,        0.29619813, -0.29619813, -0.75      ],
 [ 0.29619813,  0.11697778, -0.11697778, -0.29619813],
 [-0.29619813, -0.11697778,  0.11697778,  0.29619813],
 [-0.75,       -0.29619813,  0.29619813,  0.75      ]]
!ec

=== Solution ===

We iterate through the rows (first index) in the list, and for each row,
we iterate through the column values (second index)
and write each value to the file.
At the end of each row, we must insert a newline character in the file to get
a linebreak. The code resides in the file "`write1.py`": "${src_path}/input/write1.py".

The resulting data file becomes

!bc dat
    0.75000000    0.29619813   -0.29619813   -0.75000000
    0.29619813    0.11697778   -0.11697778   -0.29619813
   -0.29619813   -0.11697778    0.11697778    0.29619813
   -0.75000000   -0.29619813    0.29619813    0.75000000
!ec

An extension of this program consists in adding column and row headings:

!bc dat
           column  1     column  2     column  3     column  4
row  1    0.75000000    0.29619813   -0.29619813   -0.75000000
row  2    0.29619813    0.11697778   -0.11697778   -0.29619813
row  3   -0.29619813   -0.11697778    0.11697778    0.29619813
row  4   -0.75000000   -0.29619813    0.29619813    0.75000000
!ec
To obtain this end result, we need to the add some statements to
the program `write1.py`. For the column headings we need
to know the number of columns, i.e., the length of the rows,
and loop from 1 to this length:

!bc pycod
ncolumns = len(data[0])
outfile.write('          ')
for i in range(1, ncolumns+1):
    outfile.write('%10s    ' % ('column %2d' % i))
outfile.write('\n')
!ec
Note the use of a nested printf construction: The text we want to
insert is itself a printf string. We could also have written the
text as `'column  ' + str(i)`, but then the length of the
resulting string would depend on the number of digits in `i`.
It is recommended to always use printf constructions for
a tabular output format, because this gives automatic padding of
blanks so that the width of the output strings remain the same.
As always, the tuning of the widths is done in a trial-and-error
process.

To add the row headings, we need a counter over the row numbers:

!bc pycod
row_counter = 1
for row in data:
    outfile.write('row %2d' % row_counter)
    for column in row:
        outfile.write('%14.8f' % column)
    outfile.write('\n')
    row_counter += 1
!ec
The complete code is found in the file "`write2.py`": "${src_path}/input/write2.py".
We could, alternatively, iterate over the indices in the list:

!bc pycod
for i in range(len(data)):
    outfile.write('row %2d' % (i+1))
    for j in range(len(data[i])):
        outfile.write('%14.8f' % data[i][j])
    outfile.write('\n')
!ec
Some other files and URLs we can mention, just to test a 2-digit footnote,
are

 * "`addall.py`": "${src_path}/input/addall.py"
 * "`addall_v1.py`": "${src_path}/input/addall_v1.py"
 * "`add_cml.py`": "${src_path}/input/add_cml.py"
 * "`add_input.py`": "${src_path}/input/add_input.py"



===== Standard input and output as file objects =====

idx{standard input} idx{standard output}

idx{`sys.stdin`}idx{`sys.stdout`}

Reading user input from the keyboard applies the function
# #ifdef PRIMER_BOOK
`raw_input` as explained in another section.
# #else
`raw_input`.
# #endif
The keyboard is a medium that the computer in fact
treats as a file, referred to
as *standard input*.

The `print` command prints text in the terminal window. This medium
is also viewed as a file from the computer's point of view and called
*standard output*. All general-purpose programming languages
allow reading from standard input and
writing to standard output. This reading and writing can be done with
two types of tools, either file-like objects or special tools like
`raw_input`
and `print` in Python.
We will here describe the file-line objects:
`sys.stdin` for standard input
and `sys.stdout` for standard output. These objects
behave as file objects, except that they do not need to be opened or
closed. The statement

!bc pycod
s = raw_input('Give s:')
!ec
is equivalent to

!bc pycod
print('Give s: '),
s = sys.stdin.readline()
!ec
Recall that the trailing comma in the `print` statement avoids the
newline that `print` by default adds to the output string.
Similarly,

!bc pycod
s = eval(raw_input('Give s:'))
!ec
is equivalent to

!bc pycod
print('Give s: '),
s = eval(sys.stdin.readline())
!ec
For output to the terminal window, the statement

!bc pycod
print(s)
!ec
is equivalent to

!bc pycod
sys.stdout.write(s + '\n')
!ec

Why it is handy to have access to standard input and output
as file objects can be illustrated by an example. Suppose you have a
function that reads data from a file object `infile`
and writes data to a file object `outfile`.
A sample function may take the form

!bc pycod
def x2f(infile, outfile, f):
    for line in infile:
        x = float(line)
        y = f(x)
        outfile.write('%g\n' % y)
!ec
This function works with all types of files, including
web pages as `infile`.
With `sys.stdin` as `infile` and/or `sys.stdout`
as `outfile`, the `x2f` function also works with standard input
and/or standard output. Without `sys.stdin` and `sys.stdout`,
we would need different code, employing `raw_input`
and `print`,
to deal with standard input and output. Now we can write a single
function that deals with all file media in a unified way.

idx{standard error}
idx{`sys.stderr`}

There is also something called *standard error*.
Usually this is the terminal window, just as standard output, but
programs can distinguish between writing ordinary output to standard
output and error messages to standard error, and these output media
can be redirected to, e.g., files such that one can separate
error messages from ordinary output.
In Python, standard error is the file-like object `sys.stderr`.
A typical application of `sys.stderr` is to report errors:

!bc pycod
if x < 0:
    sys.stderr.write('Illegal value of x'); sys.exit(1)
!ec
This message to `sys.stderr` is an alternative to
`print` or raising an exception.

=== Redirecting standard input, output, and error ===

Standard output from a program `prog`
can be redirected to a file
`output` instead of the screen, by
using the greater than sign:

!bc sys
Terminal> prog > output
!ec
Here, `prog` can be any
program, including a Python program run as `python myprog.py`.
Similarly, output to the medium called *standard error*
can be redirected by

!bc sys
Terminal> prog &> output
!ec
For example, error messages are normally written to standard error, which
is exemplified in this little terminal session on a Unix machine:

!bc sys
Terminal> ls bla-bla1 bla-bla2
ls: cannot access bla-bla1: No such file or directory
ls: cannot access bla-bla2: No such file or directory
Terminal> ls bla-bla1 bla-bla2 &> errors
Terminal> cat errors  # print the file errors
ls: cannot access bla-bla1: No such file or directory
ls: cannot access bla-bla2: No such file or directory
!ec
When the program reads from standard input (the keyboard),
we can equally well redirect
standard input to a file, say with name `raw_input`, such that
the program reads from this file rather than from the keyboard:

!bc sys
Terminal> prog < input
!ec
Combinations are also possible:

!bc sys
Terminal> prog < input > output
!ec

=== Note ===

The redirection of standard output, input, and error
does not work for Python programs executed with the `run`
command inside IPython, only when executed directly
in the operating system in a terminal window, or with the same
command prefixed with an exclamation mark in IPython.

=== References ===

To check the bibliography, we need to make citations to a book{TCSE3},
Matplotlib cite{Matplotlib:paper}, and more books cite{Mertz,PythonQt}
as well as Python itself cite{Python}, and of course NumPy
cite{NumPy}.

======= Exercises =======

===== Problem: Add numbers =====
label{exer:add}
file=add

Compute

!bt
\[ 1 + 1 \]
!et

!bans
2
!eans

!bsol
Python shell as calculator:

!bc pyshell
>>> 1 + 1
2
!ec
!esol

===== Problem: Multiply numbers =====
label{exer:mul}
file=multiply

!bsubex
Compute $1\cdot 3$.

!bans
3.
!eans
!esubex

!bsubex
Compute $2\cdot 3$.

!bhint
Use a Python shell.
!ehint

!bsol
!bc pyshell
>>> 2*3
6
!ec
!esol
!esubex



========= Appendix: Styles for Springer T2/T4 =========

The T2/T4 style for DocOnce-generated LaTeX should make use of
slightly modified `svmono.cls` and `t2.sty` files:

 * `svmonodo.cls`
 * `t2do.sty` or `t4do.sty`


========= References =========

BIBFILE: papers.pub

************** File: Springer_T2/Springer_T2_book.p.tex *****************
NOT FOUND!
************** File: Springer_T2/Springer_T2_book.tex *****************
%%
%% Automatically generated file from DocOnce source
%% (https://github.com/hplgit/doconce/)
%%

% #define PREAMBLE

% #ifdef PREAMBLE
%-------------------- begin preamble ----------------------

% Style: T4 (Springer)
% Use svmono.cls with doconce modifications for bibliography (svmonodo.cls)
\documentclass[graybox,sectrefs,envcountresetchap,open=right,final]{svmonodo}

% Use t4.sty with doconce modifications (t4do.sty)
\usepackage{t4do}
\special{papersize=178mm,254mm}

\listfiles               %  print all files needed to compile this document

\usepackage{relsize,makeidx,color,setspace,amsmath,amsfonts,amssymb}
\usepackage[table]{xcolor}
\usepackage{bm,ltablex,microtype}

\usepackage{graphicx}

% Packages for typesetting blocks of computer code
\usepackage{fancyvrb,framed,moreverb}

% Define colors
\definecolor{orange}{cmyk}{0,0.4,0.8,0.2}
\definecolor{tucorange}{rgb}{1.0,0.64,0}
\definecolor{darkorange}{rgb}{.71,0.21,0.01}
\definecolor{darkgreen}{rgb}{.12,.54,.11}
\definecolor{myteal}{rgb}{.26, .44, .56}
\definecolor{gray}{gray}{0.45}
\definecolor{mediumgray}{gray}{.8}
\definecolor{lightgray}{gray}{.95}
\definecolor{brown}{rgb}{0.54,0.27,0.07}
\definecolor{purple}{rgb}{0.5,0.0,0.5}
\definecolor{darkgray}{gray}{0.25}
\definecolor{darkblue}{rgb}{0,0.08,0.45}
\definecolor{darkblue2}{rgb}{0,0,0.8}
\definecolor{lightred}{rgb}{1.0,0.39,0.28}
\definecolor{lightgreen}{rgb}{0.48,0.99,0.0}
\definecolor{lightblue}{rgb}{0.53,0.81,0.92}
\definecolor{lightblue2}{rgb}{0.3,0.3,1.0}
\definecolor{lightpurple}{rgb}{0.87,0.63,0.87}
\definecolor{lightcyan}{rgb}{0.5,1.0,0.83}

\colorlet{comment_green}{green!50!black}
\colorlet{string_red}{red!60!black}
\colorlet{keyword_pink}{magenta!70!black}
\colorlet{indendifier_green}{green!70!white}

% Backgrounds for code
\definecolor{cbg_gray}{rgb}{.95, .95, .95}
\definecolor{bar_gray}{rgb}{.92, .92, .92}

\definecolor{cbg_yellowgray}{rgb}{.95, .95, .85}
\definecolor{bar_yellowgray}{rgb}{.95, .95, .65}

\colorlet{cbg_yellow2}{yellow!10}
\colorlet{bar_yellow2}{yellow!20}

\definecolor{cbg_yellow1}{rgb}{.98, .98, 0.8}
\definecolor{bar_yellow1}{rgb}{.98, .98, 0.4}

\definecolor{cbg_red1}{rgb}{1, 0.85, 0.85}
\definecolor{bar_red1}{rgb}{1, 0.75, 0.85}

\definecolor{cbg_blue1}{rgb}{0.87843, 0.95686, 1.0}
\definecolor{bar_blue1}{rgb}{0.7,     0.95686, 1}

\usepackage{listingsutf8}

% Common lstlisting parameters

\usepackage{calc}
\newlength{\lstboxwidth}  % width of lst box
\newlength{\framethickness}
\setlength{\framethickness}{0.5mm}
% for frame=trbl and a framerule that has significant size, set
% xleftmargin=5mm and xrightmargin=5mm.

\lstset{
  basicstyle=\small \ttfamily,
  breaklines=false,          % break/wrap lines
  breakatwhitespace=true,    % let linebreaks happen at whitespace
  breakindent=40pt,
  tab=,
  tabsize=4,                 % tab means 4 spaces
  %belowskip=\smallskipamount,  % space between code and text below
  xleftmargin=2mm,           % indentation of code frame
  xrightmargin=0mm,
  framexleftmargin=2mm,      % add frame space to the left of the code box
  %numbers=left,             % put line numbers on the left
  %stepnumber=2,             % stepnumber=1 numbers each line, =n every n lines
  framerule=\framethickness, % thickness of frame
  aboveskip=2ex,             % vertical space above code frame
  showstringspaces=false,    % show spaces in strings with an underscore
  showspaces=false,          % show spaces with an underscore
  showtabs=false,
  keepspaces=true,
  columns=fullflexible,      % tighter character kerning, like verb
  escapeinside={(*@}{@*)},   % (*@ \pause @*) in slides and math in code blocks
  extendedchars=\true,       % allows non-ascii chars, does not work with utf-8
}

% Internally defined styles for lstlisting

\lstdefinestyle{simple}{
commentstyle={},
}

% end of custom lstdefinestyles

\usepackage[T1]{fontenc}
%\usepackage[latin1]{inputenc}
\usepackage{ucs}
\usepackage[utf8x]{inputenc}

\usepackage{lmodern}         % Latin Modern fonts derived from Computer Modern

% Hyperlinks in PDF:

\usepackage{hyperref}
\hypersetup{
    breaklinks=true,
    colorlinks=true,
    linkcolor=black,
    urlcolor=black,
    citecolor=black,
    filecolor=black,
    %filecolor=blue,
    pdfmenubar=true,
    pdftoolbar=true,
    bookmarksdepth=3   % Uncomment (and tweak) for PDF bookmarks with more levels than the TOC
    }
%\hyperbaseurl{}   % hyperlinks are relative to this root

\setcounter{tocdepth}{3}  % levels in table of contents

\usepackage[framemethod=TikZ]{mdframed}

% --- begin definitions of admonition environments ---

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "notice" admon
\definecolor{mdfbox_notice_background}{rgb}{1,1,1}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_notice_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=mdfbox_notice_background,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{notice_mdfboxmdframed}

\newenvironment{notice_mdfboxadmon}[1][]{
\begin{notice_mdfboxmdframed}[frametitle=#1]
}
{
\end{notice_mdfboxmdframed}
}

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "summary" admon
\definecolor{mdfbox_summary_background}{rgb}{1,1,1}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_summary_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=mdfbox_summary_background,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{summary_mdfboxmdframed}

\newenvironment{summary_mdfboxadmon}[1][]{
\begin{summary_mdfboxmdframed}[frametitle=#1]
}
{
\end{summary_mdfboxmdframed}
}

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "warning" admon
\definecolor{mdfbox_warning_background}{rgb}{1,1,1}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_warning_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=mdfbox_warning_background,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{warning_mdfboxmdframed}

\newenvironment{warning_mdfboxadmon}[1][]{
\begin{warning_mdfboxmdframed}[frametitle=#1]
}
{
\end{warning_mdfboxmdframed}
}

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "question" admon
\definecolor{mdfbox_question_background}{rgb}{1,1,1}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_question_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=mdfbox_question_background,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{question_mdfboxmdframed}

\newenvironment{question_mdfboxadmon}[1][]{
\begin{question_mdfboxmdframed}[frametitle=#1]
}
{
\end{question_mdfboxmdframed}
}

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "block" admon
\definecolor{mdfbox_block_background}{rgb}{1,1,1}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_block_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=mdfbox_block_background,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{block_mdfboxmdframed}

\newenvironment{block_mdfboxadmon}[1][]{
\begin{block_mdfboxmdframed}[frametitle=#1]
}
{
\end{block_mdfboxmdframed}
}

% --- end of definitions of admonition environments ---

% prevent orhpans and widows
\clubpenalty = 10000
\widowpenalty = 10000

\newenvironment{doconceexercise}{}{}
\newcounter{doconceexercisecounter}
% --- begin definition of \listofexercises command ---
\makeatletter
\newcommand\listofexercises{
\chapter*{List of Problems
          \@mkboth{List of Problems}{List of Problems}}
\markboth{List of Problems}{List of Problems}
\@starttoc{loe}
}
\newcommand*{\l@doconceexercise}{\@dottedtocline{0}{0pt}{6.5em}}
\makeatother
% --- end definition of \listofexercises command ---


% Let exercises, problems, and projects be numbered per chapter:
\usepackage{chngcntr}
\counterwithin{doconceexercisecounter}{chapter}

% \subex{} is defined in t2do.sty or t4do.sty

% Redefine double page clear to make it a blank page without headers
% (from BYUTextbook)
\makeatletter
\def\cleardoublepage{\clearpage\if@twoside \ifodd\c@page\else
\hbox{}
\thispagestyle{empty}
\newpage
\if@twocolumn\hbox{}\newpage\fi\fi\fi}
\makeatother
% These commands fiddle with the space left for page numbers in the TOC
% (from BYUTextbook)
\makeatletter
%\renewcommand{\@pnumwidth}{2em}
%\renewcommand{\@tocrmarg}{2.85em}
\makeatother

% --- end of standard preamble for documents ---


% insert custom LaTeX commands...

\raggedbottom
\makeindex
\usepackage[totoc]{idxlayout}   % for index in the toc
\usepackage[nottoc]{tocbibind}  % for references/bibliography in the toc

%-------------------- end preamble ----------------------

\begin{document}

% matching end for #ifdef PREAMBLE
% #endif

\newcommand{\exercisesection}[1]{\subsection*{#1}}

\input{newcommands_keep}

% ------------------- main content ----------------------

% Note on the Springer T2 style: used the modifications in t2do.sty
% and svmonodo.cls (come bundled with DocOnce).


\frontmatter
\setcounter{page}{3}
\pagestyle{headings}


% ----------------- title -------------------------

\thispagestyle{empty}
\hbox{\ \ }
\vfill
\begin{center}
{\huge{\bfseries{
\begin{spacing}{1.25}
{\rule{\linewidth}{0.5mm}} \\[0.4cm]
{Test of DocOnce-Based Book with Springer's T2/T4 Styles}
\\[0.4cm] {\rule{\linewidth}{0.5mm}} \\[1.5cm]
\end{spacing}
}}}

% ----------------- author(s) -------------------------

\vspace{0.5cm}

{\Large\textsf{Hans Petter Langtangen${}^{1, 2}$}}\\ [3mm]

\ \\ [2mm]

{\large\textsf{${}^1$Center for Biomedical Computing, Simula Research Laboratory} \\ [1.5mm]}
{\large\textsf{${}^2$Department of Informatics, University of Oslo} \\ [1.5mm]}
% ----------------- end author(s) -------------------------

% --- begin date ---
\ \\ [10mm]
{\large\textsf{Jan 32, 2100}}
\end{center}
% --- end date ---
\vfill
\clearpage

\setpagesize

\chapter*{Preface}
\addcontentsline{toc}{chapter}{Preface}

The aim of this book is to teach computer programming using examples
from mathematics and the natural sciences.  We have chosen to use the
Python programming language because it combines remarkable expressive
power with very clean, simple, and compact syntax.  Python is easy to
learn and very well suited for an introduction to computer
programming. Python is also quite similar to MATLAB and a good
language for doing mathematical computing.  It is easy to combine
Python with compiled languages, like Fortran, C, and C++, which are
widely used languages for scientific computations.  A seamless
integration of Python with Java is offered by a special version of
Python called Jython.

The examples in this book integrate programming with applications to
mathematics, physics, biology, and finance.  The reader is expected to
have knowledge of basic one-variable calculus as taught in
mathematics-intensive programs in high schools. It is certainly an
advantage to take a university calculus course in parallel, preferably
containing both classical and numerical aspects of calculus.  Although
not strictly required, a background in high school physics makes many
of the examples more meaningful.

Many introductory programming books are quite compact and focus on
listing functionality of a programming language. However, learning to
program is learning how to \emph{think} as a programmer.  This book
has its main focus on the thinking process, or equivalently:
programming as a problem solving technique. That is why most of the
pages are devoted to case studies in programming, where we define a
problem and explain how to create the corresponding program.  New
constructions and programming styles (what we could call theory) is also usually
introduced via examples.  Special attention is paid to verification of
programs and to finding errors. These topics are very demanding for
mathematical software, because the unavoidable numerical
approximation errors are possibly mixed with programming mistakes.

By studying the many examples in the
book, I hope readers will learn how to think right and thereby
write programs in a quicker and more reliable way. Remember, nobody can learn
programming by just reading - one has to solve a large amount of
exercises hands on.  The book is therefore full of exercises of
various types: modifications of existing examples, completely new
problems, or debugging of given programs.

\paragraph{Python version 2 or 3?}
A common problem among Python programmers is to choose between version
2 or 3, which at the time of this writing means choosing
between version 2.7 and 3.3.
The general recommendation is to go for version 3, but programs are
then not compatible with version 2 and vice versa. There is still
a problem that much useful mathematical software in Python
has not yet been ported to version 3. Therefore, scientific computing
with Python still goes mostly with version 2.
A widely used strategy for software
developers who want to write Python code that works with both versions,
is to develop for v2.7, which is very close to what is accepted
in version 3, and then
use the ranslation tool \emph{2to3} to automatically translate the code
to version 3.

When using v2.7, one should employ the newest syntax
and modules that make the differences beween version 2 and 3 very small.
This strategy is adopted in the present book. Only two
differences between versions 2 and 3 are expected to be significant for
the programs in the book:
\texttt{a/b} implies float division in version 3 if \texttt{a} and \texttt{b}
are integers,
and \texttt{print('Hello')} in version 2 must be turned into a function call
\texttt{print('Hello')} in version 3. None of these differences should lead
to any annoying problems when future readers study the book's v2.7
examples, but program in version 3. Anyway, running 2to3 on the
example files generates the corresponding version 3 code.

\paragraph{Acknowledgments.}
Several people have helped to make substantial improvements of the
text. Here I list only the names with Norwgian characters to
test the handling of those: Ståle Zerener Haugnæss,
Tobias Vidarssønn Langhoff, and Håkon Møller.

\vspace{1cm}

\noindent
\emph{Oslo, May 2015}  \hfill  \emph{Hans Petter Langtangen}




\tableofcontents
\clearemptydoublepage
\listofexercises
\clearemptydoublepage



\vspace{1cm} % after toc

\mainmatter





\chapter{Basic array computing and plotting}

This chapter gives an introduction to arrays: how they are created
and what they can be used for.  Array computing usually ends up with a
lot of numbers. It may be very hard to understand what these numbers
mean by just looking at them. Since the human is a visual animal, a
good way to understand numbers is to visualize them. In this
chapter we concentrate on visualizing curves that reflect functions
of one variable; i.e., curves of the form $y=f(x)$.  A synonym for
curve is graph, and the image of curves on the screen is often called
a plot.  We will use arrays to store the information about points
along the curve. In a nutshell, array computing demands visualization
and visualization demands arrays.

All program examples in this chapter can be found as files in the
folder \href{{https://some.where.net/doconce/test/software/plot}}{\nolinkurl{src/plot}\footnote{\texttt{https://some.where.net/doconce/test/software/plot}}}.

\section{Arrays in Python programs}
\label{sec:plot:arraycomp}

This section introduces array programming in Python, but first we
create some lists and show how arrays differ from lists.

\subsection{Using lists for collecting function data}
\label{sec:plot:listdata}

Suppose we have a function $f(x)$ and want to evaluate this function
at a number of $x$ points $x_0,x_1,\ldots,x_{n-1}$.  We could collect
the $n$ pairs $(x_i,f(x_i))$ in a list, or we could collect all the
$x_i$ values, for $i=0,\ldots,n-1$, in a list and all the associated
$f(x_i)$ values in another list.  The following interactive session
demonstrates how to create these three types of lists:

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
>>> def f(x):
...     return x**3       # sample function
...
>>> n = 5                 # no of points along the x axis
>>> dx = 1.0/(n-1)        # spacing between x points in [0,1]
>>> xlist = [i*dx for i in range(n)]
>>> ylist = [f(x) for x in xlist]
>>> pairs = [[x, y] for x, y in zip(xlist, ylist)]
\end{lstlisting}
Here we have used list comprehensions for achieving compact code. Make
sure that you understand what is going on in these list comprehensions
(if not, try to write the same code using standard \texttt{for} loops and
appending new list elements in each pass of the loops).

\index{heterogeneous lists}

The list elements consist of objects of the same type: any element in
\texttt{pairs} is a list of two \texttt{float} objects, while any element in \texttt{xlist}
or \texttt{ylist} is a \texttt{float}. Lists are more flexible than that, because an
element can be an object of any type, e.g.,

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
mylist = [2, 6.0, 'tmp.ps', [0,1]]
\end{lstlisting}
Here \texttt{mylist} holds an \texttt{int}, a \texttt{float}, a string, and a list. This
combination of diverse object types makes up what is known as
\emph{heterogeneous} lists.  We can also easily remove elements from a list
or add new elements anywhere in the list.  This flexibility of lists
is in general convenient to have as a programmer, but in cases where
the elements are of the same type and the number of elements is fixed,
arrays can be used instead. The benefits of arrays are faster
computations, less memory demands, and extensive support for
mathematical operations on the data.  Because of greater efficiency
and mathematical convenience, arrays will be used to a large extent in
this book.  The great use of arrays is also prominent in other
programming environments such as MATLAB, Octave, and R, for instance.
Lists will be our choice instead of arrays when we need the
flexibility of adding or removing elements or when the elements may be
of different object types.


\begin{quote}
\emph{People only become computer programmers if they're
obsessive about details, crave power over machines, and can bear
to be told day after day exactly how
stupid they are.} \\
Gregory J. E. Rawlins \cite{Rawlins_1998}, computer scientist.
\end{quote}


\subsection{Basics of numerical Python arrays}
\label{sec:plot:array:basics}

\index{Numerical Python} \index{NumPy} \index{numpy@{\rm\texttt{numpy}}}
\index{array (datatype)} \index{array computing}
\index{vectorization}

An \emph{array} object can be viewed as a variant of a list, but with the
following assumptions and features:

\begin{itemize}
  \item All elements must be of the same type, preferably integer, real, or complex numbers, for efficient numerical computing and storage.

  \item The number of elements must be known when the array is created.

  \item Arrays are not part of standard Python - one needs an additional package called \emph{Numerical Python}, often abbreviated as NumPy. The Python name of the package, to be used in \texttt{import} statements, is \texttt{numpy}.

  \item With \texttt{numpy}, a wide range of mathematical operations can be done directly on complete arrays, thereby removing the need for loops over array elements. This is commonly called \emph{vectorization} %or \emph{array computing} and may cause a dramatic speed-up of Python programs. Vectorization makes use of the vector computing concepts from Section~\ref{sec:plot:arraycomp}.

  \item Arrays with one index are often called vectors. Arrays with two indices are used as an efficient data structure for tables, instead of lists of lists. Arrays can also have three or more indices.
\end{itemize}

\noindent

\begin{notice_mdfboxadmon}[Remarks]

\begin{enumerate}
\item There is actually an
   object type called \texttt{array} in standard Python, but this data type is
   not so efficient for mathematical computations, and we will not use it
   in this book.

\item The number of elements in an array \emph{can} be
   changed, but at a substantial computational cost.
\end{enumerate}

\noindent
\end{notice_mdfboxadmon} % title: Remarks



The following text lists some important functionality of NumPy arrays.
A more comprehensive treatment is found in the excellent \emph{NumPy
Tutorial}, \emph{NumPy User Guide}, \emph{NumPy Reference}, \emph{Guide to NumPy},
and \emph{NumPy for MATLAB Users}, all accessible at \href{{https://scipy.org}}{scipy.org}\footnote{\texttt{https://scipy.org}}.


\index{zeros@{\rm\texttt{zeros}} (from {\rm\texttt{numpy}})} \index{np.zeros@{\rm\texttt{np.zeros}} function}
\index{array@{\rm\texttt{array}} (from {\rm\texttt{numpy}})} \index{np.array@{\rm\texttt{np.array}} function}
\index{np@{\rm\texttt{np}} prefix ({\rm\texttt{numpy}})}
\index{zeros\_like@{\rm\texttt{zeros\_like}} (from {\rm\texttt{numpy}})}\index{np.zeros\_like@{\rm\texttt{np.zeros\_like}} function}



\begin{notice_mdfboxadmon}[Remarks on importing NumPy]
The statement

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
import numpy as np
\end{lstlisting}
with subsequent prefixing of all NumPy functions and variables by \texttt{np.},
has evolved as a standard syntax in the Python scientific computing
community. However, to make Python programs look closer to MATLAB
and ease the transition to and from that language, one can do

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
from numpy import *
\end{lstlisting}
to get rid of the prefix (this is evolved as the standard in
\emph{interactive} Python shells). This author prefers mathematical
functions from \texttt{numpy} to be written without the prefix to
make the formulas as close as possible to the mathematics.
So, $f(x)=\sinh(x-1)\sin(w t)$ would be coded as

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
from numpy import sinh, sin

def f(x):
    return sinh(x-1)*sin(w*t)
\end{lstlisting}
or one may take the less recommended
lazy approach \texttt{from numpy import *} and fill up
the program with \emph{a lot} of functions and variables from \texttt{numpy}.
\end{notice_mdfboxadmon} % title: Remarks on importing NumPy



To convert a list \texttt{r} to an array,
we use the \texttt{array} function
from \texttt{numpy}:

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
a = np.array(r)
\end{lstlisting}
To create a new array of length \texttt{n}, filled with zeros, we write

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
a = np.zeros(n)
\end{lstlisting}
The array elements are of a type that corresponds to Python's
\texttt{float} type. A second argument to \texttt{np.zeros} can be used to
specify other element types, e.g., \texttt{int}.
A similar function,

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
a = np.zeros_like(c)
\end{lstlisting}
generates an array of zeros where the length is that of the array \texttt{c}
and the element type is the same as those in \texttt{c}.

\index{linspace@{\rm\texttt{linspace}} (from {\rm\texttt{numpy}})}\index{np.linspace@{\rm\texttt{np.linspace}} function}

Often one wants an array to have $n$ elements with uniformly
distributed values in an interval $[p,q]$. The \texttt{numpy} function
\texttt{linspace} creates such arrays:

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
a = np.linspace(p, q, n)
\end{lstlisting}


\begin{center}
{\small   % for Springer style: small table font and more vspace

\vspace{4mm}

\begin{tabular}{ll}
\hline
\multicolumn{1}{c}{ Construction } & \multicolumn{1}{c}{ Meaning } \\
\hline
\texttt{array(ld)}       & copy list data \texttt{ld} to a \texttt{numpy} array                    \\
\texttt{asarray(d)}      & make array of data \texttt{d} (no data copy if already array)         \\
\texttt{zeros(n)}        & make a \texttt{float} vector/array of length \texttt{n}, with zeros     \\
\texttt{zeros(n, int)}   & make an \texttt{int} vector/array of length \texttt{n} with zeros       \\
\texttt{zeros((m,n))}    & make a two-dimensional \texttt{float} array with shape (\texttt{m},`n`) \\
\Verb!zeros_like(x)!   & make array of same shape and element type as \texttt{x}               \\
\texttt{linspace(a,b,m)} & uniform sequence of \texttt{m} numbers in $[a,b]$                     \\
\texttt{a.shape}         & tuple containing \texttt{a}'s shape                                   \\
\texttt{a.size}          & total no of elements in \texttt{a}                                    \\
\texttt{len(a)}          & length of a one-dim. array \texttt{a} (same as \texttt{a.shape[0]})     \\
\texttt{a.dtype}         & the type of elements in \texttt{a}                                    \\
\texttt{a.reshape(3,2)}  & return \texttt{a} reshaped as $3\times 2$ array                       \\
\texttt{a[i]}            & vector indexing                                                     \\
\texttt{a[i,j]}          & two-dim. array indexing                                             \\
\texttt{a[1:k]}          & slice: reference data with indices \texttt{1},\ldots,`k-1`            \\
\texttt{a[1:8:3]}        & slice: reference data with indices \texttt{1}, \texttt{4},\ldots,`7`    \\
\texttt{b = a.copy()}    & copy an array                                                       \\
\hline
\end{tabular}

\vspace{4mm}

}
\end{center}

\noindent
\chapter{Storing results in data files and adding more words here to get a very long chapter heading}

We need to test spaces around footnotes for 2-digit footnotes, which
means we need a lot of URLs, e.g., to files:
\href{{https://some.where.net/doconce/test/software/input/ball2_cml.py}}{\nolinkurl{ball2_cml.py}\footnote{\texttt{https://some.where.net/doconce/test/software/input/ball2\_cml.py}}},
\href{{https://some.where.net/doconce/test/software/input/bisection_ex.py}}{\nolinkurl{bisection_ex.py}\footnote{\texttt{https://some.where.net/doconce/test/software/input/bisection\_ex.py}}},
\href{{https://some.where.net/doconce/test/software/input/bisection_movie.py}}{\nolinkurl{bisection_movie.py}\footnote{\texttt{https://some.where.net/doconce/test/software/input/bisection\_movie.py}}},
\href{{https://some.where.net/doconce/test/software/input/bisection_plot.py}}{\nolinkurl{bisection_plot.py}\footnote{\texttt{https://some.where.net/doconce/test/software/input/bisection\_plot.py}}},
\href{{https://some.where.net/doconce/test/software/input/bisection.py}}{\nolinkurl{bisection.py}\footnote{\texttt{https://some.where.net/doconce/test/software/input/bisection.py}}},
\href{{https://some.where.net/doconce/test/software/input/bisection_v1.py}}{\nolinkurl{bisection_v1.py}\footnote{\texttt{https://some.where.net/doconce/test/software/input/bisection\_v1.py}}},
\href{{https://some.where.net/doconce/test/software/input/bisection_v2.py}}{\nolinkurl{bisection_v2.py}\footnote{\texttt{https://some.where.net/doconce/test/software/input/bisection\_v2.py}}},
\href{{https://some.where.net/doconce/test/software/input/c2f_cml.py}}{\nolinkurl{c2f_cml.py}\footnote{\texttt{https://some.where.net/doconce/test/software/input/c2f\_cml.py}}},
\href{{https://some.where.net/doconce/test/software/input/data.txt}}{\nolinkurl{data.txt}\footnote{\texttt{https://some.where.net/doconce/test/software/input/data.txt}}},
\href{{https://some.where.net/doconce/test/software/input/Fdeg.dat}}{\nolinkurl{Fdeg.dat}\footnote{\texttt{https://some.where.net/doconce/test/software/input/Fdeg.dat}}},
\href{{https://some.where.net/doconce/test/software/input/integrate.py}}{\nolinkurl{integrate.py}\footnote{\texttt{https://some.where.net/doconce/test/software/input/integrate.py}}}, and
\href{{https://some.where.net/doconce/test/software/input/interest.py}}{\nolinkurl{interest.py}\footnote{\texttt{https://some.where.net/doconce/test/software/input/interest.py}}}.

\section{Writing data to file}
\label{sec:files:writing}

Writing data to file is easy.
There is basically one function to pay attention to: \texttt{outfile.write(s)},
which writes a string \texttt{s} to
a file handled by the file object \texttt{outfile}. Unlike \texttt{print},
\texttt{outfile.write(s)}
does not append a newline character to the written string.
It will therefore
often be necessary to add a newline character,

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
outfile.write(s + '\n')
\end{lstlisting}
if the string \texttt{s} is meant to appear on a single line in the file
and \texttt{s} does not already contain a trailing newline character.
File writing is then a matter of constructing strings containing the
text we want to have in the file and for each such string call
\texttt{outfile.write}.

Writing to a file demands
the file object \texttt{f}
to be opened for writing:

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
# write to new file, or overwrite file:
outfile = open(filename, 'w')

# append to the end of an existing file:
outfile = open(filename, 'a')
\end{lstlisting}

\subsection{Example: Writing a table to file}

\paragraph{Problem.}
As a worked example of file writing,
we shall write out a nested list with tabular data to file.
A sample list may take look as

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
[[ 0.75,        0.29619813, -0.29619813, -0.75      ],
 [ 0.29619813,  0.11697778, -0.11697778, -0.29619813],
 [-0.29619813, -0.11697778,  0.11697778,  0.29619813],
 [-0.75,       -0.29619813,  0.29619813,  0.75      ]]
\end{lstlisting}

\paragraph{Solution.}
We iterate through the rows (first index) in the list, and for each row,
we iterate through the column values (second index)
and write each value to the file.
At the end of each row, we must insert a newline character in the file to get
a linebreak. The code resides in the file \href{{https://some.where.net/doconce/test/software/input/write1.py}}{\nolinkurl{write1.py}\footnote{\texttt{https://some.where.net/doconce/test/software/input/write1.py}}}.

The resulting data file becomes

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
    0.75000000    0.29619813   -0.29619813   -0.75000000
    0.29619813    0.11697778   -0.11697778   -0.29619813
   -0.29619813   -0.11697778    0.11697778    0.29619813
   -0.75000000   -0.29619813    0.29619813    0.75000000
\end{lstlisting}

An extension of this program consists in adding column and row headings:

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
           column  1     column  2     column  3     column  4
row  1    0.75000000    0.29619813   -0.29619813   -0.75000000
row  2    0.29619813    0.11697778   -0.11697778   -0.29619813
row  3   -0.29619813   -0.11697778    0.11697778    0.29619813
row  4   -0.75000000   -0.29619813    0.29619813    0.75000000
\end{lstlisting}
To obtain this end result, we need to the add some statements to
the program \texttt{write1.py}. For the column headings we need
to know the number of columns, i.e., the length of the rows,
and loop from 1 to this length:

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
ncolumns = len(data[0])
outfile.write('          ')
for i in range(1, ncolumns+1):
    outfile.write('%10s    ' % ('column %2d' % i))
outfile.write('\n')
\end{lstlisting}
Note the use of a nested printf construction: The text we want to
insert is itself a printf string. We could also have written the
text as \texttt{'column  ' + str(i)}, but then the length of the
resulting string would depend on the number of digits in \texttt{i}.
It is recommended to always use printf constructions for
a tabular output format, because this gives automatic padding of
blanks so that the width of the output strings remain the same.
As always, the tuning of the widths is done in a trial-and-error
process.

To add the row headings, we need a counter over the row numbers:

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
row_counter = 1
for row in data:
    outfile.write('row %2d' % row_counter)
    for column in row:
        outfile.write('%14.8f' % column)
    outfile.write('\n')
    row_counter += 1
\end{lstlisting}
The complete code is found in the file \href{{https://some.where.net/doconce/test/software/input/write2.py}}{\nolinkurl{write2.py}\footnote{\texttt{https://some.where.net/doconce/test/software/input/write2.py}}}.
We could, alternatively, iterate over the indices in the list:

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
for i in range(len(data)):
    outfile.write('row %2d' % (i+1))
    for j in range(len(data[i])):
        outfile.write('%14.8f' % data[i][j])
    outfile.write('\n')
\end{lstlisting}
Some other files and URLs we can mention, just to test a 2-digit footnote,
are

\begin{itemize}
 \item \href{{https://some.where.net/doconce/test/software/input/addall.py}}{\nolinkurl{addall.py}\footnote{\texttt{https://some.where.net/doconce/test/software/input/addall.py}}}

 \item \href{{https://some.where.net/doconce/test/software/input/addall_v1.py}}{\nolinkurl{addall_v1.py}\footnote{\texttt{https://some.where.net/doconce/test/software/input/addall\_v1.py}}}

 \item \href{{https://some.where.net/doconce/test/software/input/add_cml.py}}{\nolinkurl{add_cml.py}\footnote{\texttt{https://some.where.net/doconce/test/software/input/add\_cml.py}}}

 \item \href{{https://some.where.net/doconce/test/software/input/add_input.py}}{\nolinkurl{add_input.py}\footnote{\texttt{https://some.where.net/doconce/test/software/input/add\_input.py}}}
\end{itemize}

\noindent
\subsection{Standard input and output as file objects}

\index{standard input} \index{standard output}

\index{sys.stdin@{\rm\texttt{sys.stdin}}}\index{sys.stdout@{\rm\texttt{sys.stdout}}}

Reading user input from the keyboard applies the function
\Verb!raw_input! as explained in another section.
The keyboard is a medium that the computer in fact
treats as a file, referred to
as \emph{standard input}.

The \texttt{print} command prints text in the terminal window. This medium
is also viewed as a file from the computer's point of view and called
\emph{standard output}. All general-purpose programming languages
allow reading from standard input and
writing to standard output. This reading and writing can be done with
two types of tools, either file-like objects or special tools like
\Verb!raw_input!
and \texttt{print} in Python.
We will here describe the file-line objects:
\texttt{sys.stdin} for standard input
and \texttt{sys.stdout} for standard output. These objects
behave as file objects, except that they do not need to be opened or
closed. The statement

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
s = raw_input('Give s:')
\end{lstlisting}
is equivalent to

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
print('Give s: '),
s = sys.stdin.readline()
\end{lstlisting}
Recall that the trailing comma in the \texttt{print} statement avoids the
newline that \texttt{print} by default adds to the output string.
Similarly,

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
s = eval(raw_input('Give s:'))
\end{lstlisting}
is equivalent to

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
print('Give s: '),
s = eval(sys.stdin.readline())
\end{lstlisting}
For output to the terminal window, the statement

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
print(s)
\end{lstlisting}
is equivalent to

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
sys.stdout.write(s + '\n')
\end{lstlisting}

Why it is handy to have access to standard input and output
as file objects can be illustrated by an example. Suppose you have a
function that reads data from a file object \texttt{infile}
and writes data to a file object \texttt{outfile}.
A sample function may take the form

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
def x2f(infile, outfile, f):
    for line in infile:
        x = float(line)
        y = f(x)
        outfile.write('%g\n' % y)
\end{lstlisting}
This function works with all types of files, including
web pages as \texttt{infile}.
With \texttt{sys.stdin} as \texttt{infile} and/or \texttt{sys.stdout}
as \texttt{outfile}, the \texttt{x2f} function also works with standard input
and/or standard output. Without \texttt{sys.stdin} and \texttt{sys.stdout},
we would need different code, employing \Verb!raw_input!
and \texttt{print},
to deal with standard input and output. Now we can write a single
function that deals with all file media in a unified way.

\index{standard error}
\index{sys.stderr@{\rm\texttt{sys.stderr}}}

There is also something called \emph{standard error}.
Usually this is the terminal window, just as standard output, but
programs can distinguish between writing ordinary output to standard
output and error messages to standard error, and these output media
can be redirected to, e.g., files such that one can separate
error messages from ordinary output.
In Python, standard error is the file-like object \texttt{sys.stderr}.
A typical application of \texttt{sys.stderr} is to report errors:

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
if x < 0:
    sys.stderr.write('Illegal value of x'); sys.exit(1)
\end{lstlisting}
This message to \texttt{sys.stderr} is an alternative to
\texttt{print} or raising an exception.

\paragraph{Redirecting standard input, output, and error.}
Standard output from a program \texttt{prog}
can be redirected to a file
\texttt{output} instead of the screen, by
using the greater than sign:

\begin{lstlisting}[language=bash,style=simple,xleftmargin=2mm]
Terminal> prog > output
\end{lstlisting}
Here, \texttt{prog} can be any
program, including a Python program run as \texttt{python myprog.py}.
Similarly, output to the medium called \emph{standard error}
can be redirected by

\begin{lstlisting}[language=bash,style=simple,xleftmargin=2mm]
Terminal> prog &> output
\end{lstlisting}
For example, error messages are normally written to standard error, which
is exemplified in this little terminal session on a Unix machine:

\begin{lstlisting}[language=bash,style=simple,xleftmargin=2mm]
Terminal> ls bla-bla1 bla-bla2
ls: cannot access bla-bla1: No such file or directory
ls: cannot access bla-bla2: No such file or directory
Terminal> ls bla-bla1 bla-bla2 &> errors
Terminal> cat errors  # print the file errors
ls: cannot access bla-bla1: No such file or directory
ls: cannot access bla-bla2: No such file or directory
\end{lstlisting}
When the program reads from standard input (the keyboard),
we can equally well redirect
standard input to a file, say with name \Verb!raw_input!, such that
the program reads from this file rather than from the keyboard:

\begin{lstlisting}[language=bash,style=simple,xleftmargin=2mm]
Terminal> prog < input
\end{lstlisting}
Combinations are also possible:

\begin{lstlisting}[language=bash,style=simple,xleftmargin=2mm]
Terminal> prog < input > output
\end{lstlisting}

\paragraph{Note.}
The redirection of standard output, input, and error
does not work for Python programs executed with the \texttt{run}
command inside IPython, only when executed directly
in the operating system in a terminal window, or with the same
command prefixed with an exclamation mark in IPython.

\paragraph{References.}
To check the bibliography, we need to make citations to a book{TCSE3},
Matplotlib \cite{Matplotlib:paper}, and more books \cite{Mertz,PythonQt}
as well as Python itself \cite{Python}, and of course NumPy
\cite{NumPy}.

\section{Exercises}



% --- begin exercise ---
\begin{doconceexercise}
\refstepcounter{doconceexercisecounter}

\exercisesection{Problem \thedoconceexercisecounter: Add numbers}
                \addcontentsline{loe}{doconceexercise}{Problem \thedoconceexercisecounter: Add numbers}
                
\label{exer:add}

Compute

\[ 1 + 1 \]


% --- begin answer of exercise ---
\paragraph{Answer.}
2

% --- end answer of exercise ---


% --- begin solution of exercise ---
\paragraph{Solution.}
Python shell as calculator:

\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
>>> 1 + 1
2
\end{lstlisting}

% --- end solution of exercise ---
\noindent Filename: \texttt{add}.

\end{doconceexercise}
% --- end exercise ---




% --- begin exercise ---
\begin{doconceexercise}
\refstepcounter{doconceexercisecounter}

\exercisesection{Problem \thedoconceexercisecounter: Multiply numbers}
                \addcontentsline{loe}{doconceexercise}{Problem \thedoconceexercisecounter: Multiply numbers}
                
\label{exer:mul}


\subex{a)}
Compute $1\cdot 3$.


% --- begin answer of exercise ---
\paragraph{Answer.}
3.
% --- end answer of exercise ---

\subex{b)}
Compute $2\cdot 3$.

% --- begin hint in exercise ---

\paragraph{Hint.}
Use a Python shell.

% --- end hint in exercise ---


% --- begin solution of exercise ---
\paragraph{Solution.}
\begin{lstlisting}[language=Python,style=simple,xleftmargin=2mm]
>>> 2*3
6
\end{lstlisting}
% --- end solution of exercise ---



\noindent Filename: \texttt{multiply}.

\end{doconceexercise}
% --- end exercise ---




\appendix

\chapter{Styles for Springer T2/T4}

The T2/T4 style for DocOnce-generated {\LaTeX} should make use of
slightly modified \texttt{svmono.cls} and \texttt{t2.sty} files:

\begin{itemize}
 \item \texttt{svmonodo.cls}

 \item \texttt{t2do.sty} or \texttt{t4do.sty}
\end{itemize}

\noindent
\clearemptydoublepage
\markboth{Bibliography}{Bibliography}
\thispagestyle{empty}

\bibliographystyle{plain}
\bibliography{papers}

% ------------------- end of main content ---------------

% #ifdef PREAMBLE
\cleardoublepage\phantomsection  % trick to get correct link to Index
\printindex

\end{document}
% #endif


************** File: test_boots.do.txt *****************
TITLE: Test of the Bootstrap style

DocOnce can work with Bootstrap HTML styles this way:

!bc sys
Terminal> doconce format html mydoc --html_style=bootswatch --html_admon=bootstrap_panel
!ec

Here goes optional text.

# A split before the first section will enable a button in the jumbotron
# for going to the first real page

!split
========= More details on writing DocOnce documents with Bootstrap layout =========


======= Demonstrations of admons =======

The Bootstrap/Bootswatch styles support two kinds of admons:

 * alert admons (`bootstrap_alert`) with colored background (default)
 * panel admon (`bootstrap_panel`) where only the title has colored background


Below are some examples on admons.

!bwarning Warning: recall to prefix module functions

!bc ipy

In [1]: import numpy as np

In [2]: x = np.linspace(0, 4*np.pi, 11)

In [3]: y = exp(-0.1*x)*sin(x)
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-3-c1040545fa6c> in <module>()
----> 1 y = exp(-0.1*x)*sin(x)

NameError: name 'exp' is not defined

In [4]: y = np.exp(-0.1*x)*np.sin(x)

In [5]: y
Out[5]:
array([  0.00000000e+00,   8.38747563e-01,   4.57160372e-01,
        -4.03174933e-01,  -5.75315545e-01,  -1.30666897e-16,
         4.47461836e-01,   2.43889614e-01,  -2.15089026e-01,
        -3.06923992e-01,  -1.39418467e-16])
!ec


This is the admon for warnings or paying attention.
!ewarning

!bnotice Information
This is the notice admon with nice-to-have information.
!enotice

!bquestion Testing the understanding
How many admon styles are supported by the DocOnce Boostrap and Bootswatch
styles?
!equestion

!bsummary
DocOnce supports the following elements of Bootstrap elements:

 * Admons
 * Panels (via admons)
 * Jumbotron for title and intro
 * Columns of content (grid structure via the `slidecell` environment)
 * Tooltips via footnotes
!esummary

Tables, first with math headings:

|-l----r-------r--------r--|
|$i$|$h_i$|$\bar T_i$|`L_i`|
|-l-----r-------r----r-----|
|0   |0     |288   |-0.0065|
|1   |11,000|216   |0.0	   |
|2   |20,000|216   |0.001  |
|3   |32,000|228   |0.0028 |
|4   |47,000|270   |0.0	   |
|5   |51,000|270   |-0.0028|
|6   |71,000|214   |`NaN`  |
|--------------------------|

And then with plain words:

|-l----r-------r--------r--|
|i|height|Temperature | L  |
|-l-----r-------r----r-----|
|0   |0     |288   |-0.0065|
|1   |11,000|216   |0.0	   |
|2   |20,000|216   |0.001  |
|3   |32,000|228   |0.0028 |
|4   |47,000|270   |0.0	   |
|5   |51,000|270   |-0.0028|
|6   |71,000|214   |`NaN`  |
|--------------------------|



!split
======= Horizontal alignment of document elements =======
label{sec:examples}

===== Principles of grid structures =====

The HTML page can feature a grid structure of cells, defined by
the following syntax in case of a 1x3 grid:

!bc
# begin-grid-area

|bslidecell 00
...
|eslidecell

|bslidecell 01
...
|eslidecell

|bslidecell 02
...
|eslidecell

# end-grid-area
!ec

===== Example on a 1x3 grid structure =====

# begin-grid-area

Some text like this is lost.

!bslidecell 00
__Mathematics.__
Given a function

!bt
\[ f(x) = e^{-ax}\sin wx\thinspace .\]
!et
Write a program for evaluating $f(x)$, and test the program
for the value of $f(0)$.
!eslidecell

!bslidecell 01
__Implementation.__
The Python implementation reads

!bc pycod
from math import exp, sin

def f(x):
    return exp(-a*x)*sin(w*x)
!ec
where `a` and `w` must be *global variables*, initialized in the
main program.
!eslidecell

!bslidecell 02

__Computational experiment.__
With a main program

!bc pycod
a = 1
from math import pi
w = pi
print(f(0))
!ec
we can run the program:

!bc sys
Terminal> python prog.py
0
!ec
!eslidecell
# end-grid-area

===== Variation of the previous grid structure using panels =====

# Note: panels are realized as admons, using --admon_style=bootstrap_panel

# begin-grid-area

!bslidecell 00
!bnotice Mathematics
Given a function

!bt
\[ f(x) = e^{-ax}\sin wx\thinspace .\]
!et
Write a program for evaluating $f(x)$, and test the program
for the value of $f(0)$.
!enotice
!eslidecell

!bslidecell 01
!bnotice Implementation
The Python implementation reads

!bc pycod
from math import exp, sin

def f(x):
    return exp(-a*x)*sin(w*x)
!ec
where `a` and `w` must be *global variables*, initialized in the
main program.
!enotice
!eslidecell

!bslidecell 02
!bnotice Computational experiment
With a main program

!bc pycod
a = 1
from math import pi
w = pi
print(f(0))
!ec
we can run the program:

!bc sys
Terminal> python prog.py
0
!ec
!enotice
!eslidecell
# end-grid-area

************** File: test_boots.html *****************
<!--
Automatically generated HTML file from DocOnce source
(https://github.com/doconce/doconce/)
-->
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="DocOnce: https://github.com/doconce/doconce/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="description" content="Test of the Bootstrap style">

<title>Test of the Bootstrap style</title>

<!-- Bootstrap style: bootswatch_journal -->
<link href="https://netdna.bootstrapcdn.com/bootswatch/3.1.1/journal/bootstrap.min.css" rel="stylesheet">
<!-- not necessary
<link href="https://netdna.bootstrapcdn.com/font-awesome/4.0.3/css/font-awesome.css" rel="stylesheet">
-->

<style type="text/css">
/* Let inline verbatim have the same color as the surroundings */
code { color: inherit; background-color: transparent; }

/* Add scrollbar to dropdown menus in bootstrap navigation bar */
.dropdown-menu {
   height: auto;
   max-height: 400px;
   overflow-x: hidden;
}

/* Adds an invisible element before each target to offset for the navigation
   bar */
.anchor::before {
  content:"";
  display:block;
  height:60px;      /* fixed header height for style bootswatch_journal */
  margin:-60px 0 0; /* negative fixed header height */
}
</style>


</head>

<!-- tocinfo
{'highest level': 0,
 'sections': [('More details on writing DocOnce documents with Bootstrap '
               'layout',
               0,
               None,
               'more-details-on-writing-doconce-documents-with-bootstrap-layout'),
              ('Demonstrations of admons', 1, None, 'demonstrations-of-admons'),
              ('Horizontal alignment of document elements',
               1,
               'sec:examples',
               'sec:examples'),
              ('Principles of grid structures',
               2,
               None,
               'principles-of-grid-structures'),
              ('Example on a 1x3 grid structure',
               2,
               None,
               'example-on-a-1x3-grid-structure'),
              ('Variation of the previous grid structure using panels',
               2,
               None,
               'variation-of-the-previous-grid-structure-using-panels')]}
end of tocinfo -->

<body>



<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  TeX: {
     equationNumbers: {  autoNumber: "none"  },
     extensions: ["AMSmath.js", "AMSsymbols.js", "autobold.js", "color.js"]
  }
});
</script>
<script type="text/javascript" async
 src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>



    
<!-- Bootstrap navigation bar -->
<div class="navbar navbar-default navbar-fixed-top">
  <div class="navbar-header">
    <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-responsive-collapse">
      <span class="icon-bar"></span>
      <span class="icon-bar"></span>
      <span class="icon-bar"></span>
    </button>
    <a class="navbar-brand" href="test_boots.html">Test of the Bootstrap style</a>
  </div>

  <div class="navbar-collapse collapse navbar-responsive-collapse">
    <ul class="nav navbar-nav navbar-right">
      <li class="dropdown">
        <a href="#" class="dropdown-toggle" data-toggle="dropdown">Contents <b class="caret"></b></a>
        <ul class="dropdown-menu">
     <!-- navigation toc: --> <li><a href="._test_boots001.html#more-details-on-writing-doconce-documents-with-bootstrap-layout" style="font-size: 80%;"><b>More details on writing DocOnce documents with Bootstrap layout</b></a></li>
     <!-- navigation toc: --> <li><a href="._test_boots001.html#demonstrations-of-admons" style="font-size: 80%;">&nbsp;&nbsp;&nbsp;Demonstrations of admons</a></li>
     <!-- navigation toc: --> <li><a href="._test_boots002.html#sec:examples" style="font-size: 80%;">&nbsp;&nbsp;&nbsp;Horizontal alignment of document elements</a></li>
     <!-- navigation toc: --> <li><a href="._test_boots002.html#principles-of-grid-structures" style="font-size: 80%;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Principles of grid structures</a></li>
     <!-- navigation toc: --> <li><a href="._test_boots002.html#example-on-a-1x3-grid-structure" style="font-size: 80%;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Example on a 1x3 grid structure</a></li>
     <!-- navigation toc: --> <li><a href="._test_boots002.html#variation-of-the-previous-grid-structure-using-panels" style="font-size: 80%;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Variation of the previous grid structure using panels</a></li>

        </ul>
      </li>
    </ul>
  </div>
</div>
</div> <!-- end of navigation bar -->

<div class="container">

<p>&nbsp;</p><p>&nbsp;</p><p>&nbsp;</p> <!-- add vertical space -->

<a name="part0000"></a>
<!-- ------------------- main content ---------------------- -->



<div class="jumbotron">
<center><h1>Test of the Bootstrap style</h1></center>  <!-- document title -->

<p>
DocOnce can work with Bootstrap HTML styles this way:

<p>

<!-- code=text (!bc sys) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>Terminal&gt; doconce format html mydoc --html_style=bootswatch --html_admon=bootstrap_panel
</pre></div>
<p>
Here goes optional text.

<p>
<!-- A split before the first section will enable a button in the jumbotron -->
<!-- for going to the first real page -->

<p>


<p><a href="._test_boots001.html" class="btn btn-primary btn-lg">Read &raquo;</a></p>


</div> <!-- end jumbotron -->

<p>
<!-- navigation buttons at the bottom of the page -->
<ul class="pager">

  <li class="next">
    <a href="._test_boots001.html">Next &rarr;</a>
  </li>
</ul>
<!-- ------------------- end of main content --------------- -->

</div>  <!-- end container -->
<!-- include javascript, jQuery *first* -->
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>
<script src="https://netdna.bootstrapcdn.com/bootstrap/3.0.0/js/bootstrap.min.js"></script>

<!-- Bootstrap footer
<footer>
<a href="https://..."><img width="250" align=right src="https://..."></a>
</footer>
-->


</body>
</html>
    


************** File: ._test_boots001.html *****************
<!--
Automatically generated HTML file from DocOnce source
(https://github.com/doconce/doconce/)
-->
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="DocOnce: https://github.com/doconce/doconce/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="description" content="Test of the Bootstrap style">

<title>Test of the Bootstrap style</title>

<!-- Bootstrap style: bootswatch_journal -->
<link href="https://netdna.bootstrapcdn.com/bootswatch/3.1.1/journal/bootstrap.min.css" rel="stylesheet">
<!-- not necessary
<link href="https://netdna.bootstrapcdn.com/font-awesome/4.0.3/css/font-awesome.css" rel="stylesheet">
-->

<style type="text/css">
/* Let inline verbatim have the same color as the surroundings */
code { color: inherit; background-color: transparent; }

/* Add scrollbar to dropdown menus in bootstrap navigation bar */
.dropdown-menu {
   height: auto;
   max-height: 400px;
   overflow-x: hidden;
}

/* Adds an invisible element before each target to offset for the navigation
   bar */
.anchor::before {
  content:"";
  display:block;
  height:60px;      /* fixed header height for style bootswatch_journal */
  margin:-60px 0 0; /* negative fixed header height */
}
</style>


</head>

<!-- tocinfo
{'highest level': 0,
 'sections': [('More details on writing DocOnce documents with Bootstrap '
               'layout',
               0,
               None,
               'more-details-on-writing-doconce-documents-with-bootstrap-layout'),
              ('Demonstrations of admons', 1, None, 'demonstrations-of-admons'),
              ('Horizontal alignment of document elements',
               1,
               'sec:examples',
               'sec:examples'),
              ('Principles of grid structures',
               2,
               None,
               'principles-of-grid-structures'),
              ('Example on a 1x3 grid structure',
               2,
               None,
               'example-on-a-1x3-grid-structure'),
              ('Variation of the previous grid structure using panels',
               2,
               None,
               'variation-of-the-previous-grid-structure-using-panels')]}
end of tocinfo -->

<body>



<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  TeX: {
     equationNumbers: {  autoNumber: "none"  },
     extensions: ["AMSmath.js", "AMSsymbols.js", "autobold.js", "color.js"]
  }
});
</script>
<script type="text/javascript" async
 src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>



    
<!-- Bootstrap navigation bar -->
<div class="navbar navbar-default navbar-fixed-top">
  <div class="navbar-header">
    <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-responsive-collapse">
      <span class="icon-bar"></span>
      <span class="icon-bar"></span>
      <span class="icon-bar"></span>
    </button>
    <a class="navbar-brand" href="test_boots.html">Test of the Bootstrap style</a>
  </div>

  <div class="navbar-collapse collapse navbar-responsive-collapse">
    <ul class="nav navbar-nav navbar-right">
      <li class="dropdown">
        <a href="#" class="dropdown-toggle" data-toggle="dropdown">Contents <b class="caret"></b></a>
        <ul class="dropdown-menu">
     <!-- navigation toc: --> <li><a href="#more-details-on-writing-doconce-documents-with-bootstrap-layout" style="font-size: 80%;"><b>More details on writing DocOnce documents with Bootstrap layout</b></a></li>
     <!-- navigation toc: --> <li><a href="#demonstrations-of-admons" style="font-size: 80%;">&nbsp;&nbsp;&nbsp;Demonstrations of admons</a></li>
     <!-- navigation toc: --> <li><a href="._test_boots002.html#sec:examples" style="font-size: 80%;">&nbsp;&nbsp;&nbsp;Horizontal alignment of document elements</a></li>
     <!-- navigation toc: --> <li><a href="._test_boots002.html#principles-of-grid-structures" style="font-size: 80%;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Principles of grid structures</a></li>
     <!-- navigation toc: --> <li><a href="._test_boots002.html#example-on-a-1x3-grid-structure" style="font-size: 80%;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Example on a 1x3 grid structure</a></li>
     <!-- navigation toc: --> <li><a href="._test_boots002.html#variation-of-the-previous-grid-structure-using-panels" style="font-size: 80%;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Variation of the previous grid structure using panels</a></li>

        </ul>
      </li>
    </ul>
  </div>
</div>
</div> <!-- end of navigation bar -->

<div class="container">

<p>&nbsp;</p><p>&nbsp;</p><p>&nbsp;</p> <!-- add vertical space -->

<a name="part0001"></a>
<!-- !split -->

<center><h1 id="more-details-on-writing-doconce-documents-with-bootstrap-layout" class="anchor">More details on writing DocOnce documents with Bootstrap layout </h1></center> <!-- chapter heading -->

<h1 id="demonstrations-of-admons" class="anchor">Demonstrations of admons </h1>

<p>
The Bootstrap/Bootswatch styles support two kinds of admons:

<ul>
 <li> alert admons (<code>bootstrap_alert</code>) with colored background (default)</li>
 <li> panel admon (<code>bootstrap_panel</code>) where only the title has colored background</li>
</ul>

Below are some examples on admons.

<p>
<div class="panel panel-warning">
  <div class="panel-heading">
  <h3 class="panel-title">Warning: recall to prefix module functions</h3>
  </div>
<div class="panel-body">
<p> <!-- subsequent paragraphs come in larger fonts, so start with a paragraph -->

<p>

<!-- code=ipy (!bc ipy) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #000080; font-weight: bold">In [1]: </span><span style="color: #008000; font-weight: bold">import</span> <span style="color: #0000FF; font-weight: bold">numpy</span> <span style="color: #008000; font-weight: bold">as</span> <span style="color: #0000FF; font-weight: bold">np</span>

<span style="color: #000080; font-weight: bold">In [2]: </span>x <span style="color: #666666">=</span> np<span style="color: #666666">.</span>linspace(<span style="color: #666666">0</span>, <span style="color: #666666">4*</span>np<span style="color: #666666">.</span>pi, <span style="color: #666666">11</span>)

<span style="color: #000080; font-weight: bold">In [3]: </span>y <span style="color: #666666">=</span> exp(<span style="color: #666666">-0.1*</span>x)<span style="color: #666666">*</span>sin(x)
<span style="color: #0044DD">---------------------------------------------------------------------------</span>
<span style="color: #D2413A; font-weight: bold">NameError</span>                                 Traceback (most recent call last)
<span style="color: #0000FF; font-weight: bold">&lt;ipython-input-3-c1040545fa6c&gt;</span> in <span style="color: #999999; font-weight: bold">&lt;module&gt;</span><span style="color: #008000; font-weight: bold">()</span>
<span style="color: #D2413A; font-weight: bold">----&gt; </span><span style="color: #666666">1</span> y <span style="color: #666666">=</span> exp(<span style="color: #666666">-0.1*</span>x)<span style="color: #666666">*</span>sin(x)

<span style="color: #D2413A; font-weight: bold">NameError</span>: name &#39;exp&#39; is not defined

<span style="color: #000080; font-weight: bold">In [4]: </span>y <span style="color: #666666">=</span> np<span style="color: #666666">.</span>exp(<span style="color: #666666">-0.1*</span>x)<span style="color: #666666">*</span>np<span style="color: #666666">.</span>sin(x)

<span style="color: #000080; font-weight: bold">In [5]: </span>y
<span style="color: #000080; font-weight: bold">Out[5]:</span>
<span style="color: #888888">array([  0.00000000e+00,   8.38747563e-01,   4.57160372e-01,</span>
<span style="color: #888888">        -4.03174933e-01,  -5.75315545e-01,  -1.30666897e-16,</span>
<span style="color: #888888">         4.47461836e-01,   2.43889614e-01,  -2.15089026e-01,</span>
<span style="color: #888888">        -3.06923992e-01,  -1.39418467e-16])</span>
</pre></div>
<p>
This is the admon for warnings or paying attention.
</div>
</div>


<p>
<div class="panel panel-primary">
  <div class="panel-heading">
  <h3 class="panel-title">Information</h3>
  </div>
<div class="panel-body">
<p> <!-- subsequent paragraphs come in larger fonts, so start with a paragraph -->
This is the notice admon with nice-to-have information.
</div>
</div>


<p>
<div class="panel panel-success">
  <div class="panel-heading">
  <h3 class="panel-title">Testing the understanding</h3>
  </div>
<div class="panel-body">
<p> <!-- subsequent paragraphs come in larger fonts, so start with a paragraph -->
How many admon styles are supported by the DocOnce Boostrap and Bootswatch
styles?
</div>
</div>


<p>
<div class="panel panel-danger">
  <div class="panel-heading">
  <h3 class="panel-title">Summary</h3>
  </div>
<div class="panel-body">
<p> <!-- subsequent paragraphs come in larger fonts, so start with a paragraph -->
DocOnce supports the following elements of Bootstrap elements:

<ul>
 <li> Admons</li>
 <li> Panels (via admons)</li>
 <li> Jumbotron for title and intro</li>
 <li> Columns of content (grid structure via the <code>slidecell</code> environment)</li>
 <li> Tooltips via footnotes</li>
</ul>
</div>
</div>


<p>
Tables, first with math headings:

<p>

<div class="row">
  <div class="col-xs-5">
    <table class="table table-striped table-hover table-condensed">
<thead>
<tr><td align="left">\( i \)</td> <td align="right">\( h_i \)</td> <td align="right">\( \bar T_i \)</td> <td align="right"><code>L_i</code></td> </tr>
</thead>
<tbody>
<tr><td align="left">   0          </td> <td align="right">   0            </td> <td align="right">   288               </td> <td align="right">   -0.0065             </td> </tr>
<tr><td align="left">   1          </td> <td align="right">   11,000       </td> <td align="right">   216               </td> <td align="right">   0.0                 </td> </tr>
<tr><td align="left">   2          </td> <td align="right">   20,000       </td> <td align="right">   216               </td> <td align="right">   0.001               </td> </tr>
<tr><td align="left">   3          </td> <td align="right">   32,000       </td> <td align="right">   228               </td> <td align="right">   0.0028              </td> </tr>
<tr><td align="left">   4          </td> <td align="right">   47,000       </td> <td align="right">   270               </td> <td align="right">   0.0                 </td> </tr>
<tr><td align="left">   5          </td> <td align="right">   51,000       </td> <td align="right">   270               </td> <td align="right">   -0.0028             </td> </tr>
<tr><td align="left">   6          </td> <td align="right">   71,000       </td> <td align="right">   214               </td> <td align="right">   <code>NaN</code>    </td> </tr>
</tbody>
    </table>
  </div> <!-- col-xs-5 -->
</div> <!-- cell row -->
<p>
And then with plain words:

<p>

<div class="row">
  <div class="col-xs-4">
    <table class="table table-striped table-hover table-condensed">
<thead>
<tr><td align="left"><b>i</b></td> <td align="right"><b>height</b></td> <td align="right"><b>Temperature</b></td> <td align="right"><b>       L        </b></td> </tr>
</thead>
<tbody>
<tr><td align="left">   0    </td> <td align="right">   0         </td> <td align="right">   288            </td> <td align="right">   -0.0065             </td> </tr>
<tr><td align="left">   1    </td> <td align="right">   11,000    </td> <td align="right">   216            </td> <td align="right">   0.0                 </td> </tr>
<tr><td align="left">   2    </td> <td align="right">   20,000    </td> <td align="right">   216            </td> <td align="right">   0.001               </td> </tr>
<tr><td align="left">   3    </td> <td align="right">   32,000    </td> <td align="right">   228            </td> <td align="right">   0.0028              </td> </tr>
<tr><td align="left">   4    </td> <td align="right">   47,000    </td> <td align="right">   270            </td> <td align="right">   0.0                 </td> </tr>
<tr><td align="left">   5    </td> <td align="right">   51,000    </td> <td align="right">   270            </td> <td align="right">   -0.0028             </td> </tr>
<tr><td align="left">   6    </td> <td align="right">   71,000    </td> <td align="right">   214            </td> <td align="right">   <code>NaN</code>    </td> </tr>
</tbody>
    </table>
  </div> <!-- col-xs-4 -->
</div> <!-- cell row -->
<p>
<p>
<!-- navigation buttons at the bottom of the page -->
<ul class="pager">

  <li class="previous">
    <a href="._test_boots000.html">&larr; Prev</a>
  </li>

  <li class="next">
    <a href="._test_boots002.html">Next &rarr;</a>
  </li>
</ul>
<!-- ------------------- end of main content --------------- -->

</div>  <!-- end container -->
<!-- include javascript, jQuery *first* -->
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>
<script src="https://netdna.bootstrapcdn.com/bootstrap/3.0.0/js/bootstrap.min.js"></script>

<!-- Bootstrap footer
<footer>
<a href="https://..."><img width="250" align=right src="https://..."></a>
</footer>
-->


</body>
</html>
    


************** File: ._test_boots002.html *****************
<!--
Automatically generated HTML file from DocOnce source
(https://github.com/doconce/doconce/)
-->
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="DocOnce: https://github.com/doconce/doconce/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="description" content="Test of the Bootstrap style">

<title>Test of the Bootstrap style</title>

<!-- Bootstrap style: bootswatch_journal -->
<link href="https://netdna.bootstrapcdn.com/bootswatch/3.1.1/journal/bootstrap.min.css" rel="stylesheet">
<!-- not necessary
<link href="https://netdna.bootstrapcdn.com/font-awesome/4.0.3/css/font-awesome.css" rel="stylesheet">
-->

<style type="text/css">
/* Let inline verbatim have the same color as the surroundings */
code { color: inherit; background-color: transparent; }

/* Add scrollbar to dropdown menus in bootstrap navigation bar */
.dropdown-menu {
   height: auto;
   max-height: 400px;
   overflow-x: hidden;
}

/* Adds an invisible element before each target to offset for the navigation
   bar */
.anchor::before {
  content:"";
  display:block;
  height:60px;      /* fixed header height for style bootswatch_journal */
  margin:-60px 0 0; /* negative fixed header height */
}
</style>


</head>

<!-- tocinfo
{'highest level': 0,
 'sections': [('More details on writing DocOnce documents with Bootstrap '
               'layout',
               0,
               None,
               'more-details-on-writing-doconce-documents-with-bootstrap-layout'),
              ('Demonstrations of admons', 1, None, 'demonstrations-of-admons'),
              ('Horizontal alignment of document elements',
               1,
               'sec:examples',
               'sec:examples'),
              ('Principles of grid structures',
               2,
               None,
               'principles-of-grid-structures'),
              ('Example on a 1x3 grid structure',
               2,
               None,
               'example-on-a-1x3-grid-structure'),
              ('Variation of the previous grid structure using panels',
               2,
               None,
               'variation-of-the-previous-grid-structure-using-panels')]}
end of tocinfo -->

<body>



<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  TeX: {
     equationNumbers: {  autoNumber: "none"  },
     extensions: ["AMSmath.js", "AMSsymbols.js", "autobold.js", "color.js"]
  }
});
</script>
<script type="text/javascript" async
 src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>



    
<!-- Bootstrap navigation bar -->
<div class="navbar navbar-default navbar-fixed-top">
  <div class="navbar-header">
    <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-responsive-collapse">
      <span class="icon-bar"></span>
      <span class="icon-bar"></span>
      <span class="icon-bar"></span>
    </button>
    <a class="navbar-brand" href="test_boots.html">Test of the Bootstrap style</a>
  </div>

  <div class="navbar-collapse collapse navbar-responsive-collapse">
    <ul class="nav navbar-nav navbar-right">
      <li class="dropdown">
        <a href="#" class="dropdown-toggle" data-toggle="dropdown">Contents <b class="caret"></b></a>
        <ul class="dropdown-menu">
     <!-- navigation toc: --> <li><a href="._test_boots001.html#more-details-on-writing-doconce-documents-with-bootstrap-layout" style="font-size: 80%;"><b>More details on writing DocOnce documents with Bootstrap layout</b></a></li>
     <!-- navigation toc: --> <li><a href="._test_boots001.html#demonstrations-of-admons" style="font-size: 80%;">&nbsp;&nbsp;&nbsp;Demonstrations of admons</a></li>
     <!-- navigation toc: --> <li><a href="#sec:examples" style="font-size: 80%;">&nbsp;&nbsp;&nbsp;Horizontal alignment of document elements</a></li>
     <!-- navigation toc: --> <li><a href="#principles-of-grid-structures" style="font-size: 80%;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Principles of grid structures</a></li>
     <!-- navigation toc: --> <li><a href="#example-on-a-1x3-grid-structure" style="font-size: 80%;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Example on a 1x3 grid structure</a></li>
     <!-- navigation toc: --> <li><a href="#variation-of-the-previous-grid-structure-using-panels" style="font-size: 80%;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Variation of the previous grid structure using panels</a></li>

        </ul>
      </li>
    </ul>
  </div>
</div>
</div> <!-- end of navigation bar -->

<div class="container">

<p>&nbsp;</p><p>&nbsp;</p><p>&nbsp;</p> <!-- add vertical space -->

<a name="part0002"></a>
<!-- !split -->

<h1 id="sec:examples" class="anchor">Horizontal alignment of document elements</h1>

<h2 id="principles-of-grid-structures" class="anchor">Principles of grid structures </h2>

<p>
The HTML page can feature a grid structure of cells, defined by
the following syntax in case of a 1x3 grid:

<p>

<!-- code=text typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span># begin-grid-area

!bslidecell 00
...
!eslidecell

!bslidecell 01
...
!eslidecell

!bslidecell 02
...
!eslidecell

# end-grid-area
</pre></div>

<h2 id="example-on-a-1x3-grid-structure" class="anchor">Example on a 1x3 grid structure </h2>

<p>
<div class="row"> <!-- begin cell row -->
  <div class="col-sm-4">

<p> <!-- subsequent paragraphs come in larger fonts, so start with a paragraph -->
<b>Mathematics.</b>
Given a function

$$ f(x) = e^{-ax}\sin wx\thinspace .$$

Write a program for evaluating \( f(x) \), and test the program
for the value of \( f(0) \).
  </div> <!-- column col-sm-4 -->
  <div class="col-sm-4">

<p> <!-- subsequent paragraphs come in larger fonts, so start with a paragraph -->
<b>Implementation.</b>
The Python implementation reads

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">from</span> <span style="color: #0000FF; font-weight: bold">math</span> <span style="color: #008000; font-weight: bold">import</span> exp, sin

<span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">f</span>(x):
    <span style="color: #008000; font-weight: bold">return</span> exp(<span style="color: #666666">-</span>a<span style="color: #666666">*</span>x)<span style="color: #666666">*</span>sin(w<span style="color: #666666">*</span>x)
</pre></div>
<p>
where <code>a</code> and <code>w</code> must be <em>global variables</em>, initialized in the
main program.
  </div> <!-- column col-sm-4 -->
  <div class="col-sm-4">

<p> <!-- subsequent paragraphs come in larger fonts, so start with a paragraph -->

<p>
<b>Computational experiment.</b>
With a main program

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>a <span style="color: #666666">=</span> <span style="color: #666666">1</span>
<span style="color: #008000; font-weight: bold">from</span> <span style="color: #0000FF; font-weight: bold">math</span> <span style="color: #008000; font-weight: bold">import</span> pi
w <span style="color: #666666">=</span> pi
<span style="color: #008000">print</span>(f(<span style="color: #666666">0</span>))
</pre></div>
<p>
we can run the program:

<p>

<!-- code=text (!bc sys) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>Terminal&gt; python prog.py
0
</pre></div>
<p>
</div> <!-- column col-sm-4 -->
</div> <!-- end cell row -->

<h2 id="variation-of-the-previous-grid-structure-using-panels" class="anchor">Variation of the previous grid structure using panels </h2>

<p>
<!-- Note: panels are realized as admons, using --admon_style=bootstrap_panel -->

<p>
<div class="row"> <!-- begin cell row -->
  <div class="col-sm-4">

<p> <!-- subsequent paragraphs come in larger fonts, so start with a paragraph -->
<div class="panel panel-primary">
  <div class="panel-heading">
  <h3 class="panel-title">Mathematics</h3>
  </div>
<div class="panel-body">
<p> <!-- subsequent paragraphs come in larger fonts, so start with a paragraph -->
Given a function

$$ f(x) = e^{-ax}\sin wx\thinspace .$$

Write a program for evaluating \( f(x) \), and test the program
for the value of \( f(0) \).
</div>
</div>

  </div> <!-- column col-sm-4 -->
  <div class="col-sm-4">

<p> <!-- subsequent paragraphs come in larger fonts, so start with a paragraph -->
<div class="panel panel-primary">
  <div class="panel-heading">
  <h3 class="panel-title">Implementation</h3>
  </div>
<div class="panel-body">
<p> <!-- subsequent paragraphs come in larger fonts, so start with a paragraph -->
The Python implementation reads

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">from</span> <span style="color: #0000FF; font-weight: bold">math</span> <span style="color: #008000; font-weight: bold">import</span> exp, sin

<span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">f</span>(x):
    <span style="color: #008000; font-weight: bold">return</span> exp(<span style="color: #666666">-</span>a<span style="color: #666666">*</span>x)<span style="color: #666666">*</span>sin(w<span style="color: #666666">*</span>x)
</pre></div>
<p>
where <code>a</code> and <code>w</code> must be <em>global variables</em>, initialized in the
main program.
</div>
</div>

  </div> <!-- column col-sm-4 -->
  <div class="col-sm-4">

<p> <!-- subsequent paragraphs come in larger fonts, so start with a paragraph -->
<div class="panel panel-primary">
  <div class="panel-heading">
  <h3 class="panel-title">Computational experiment</h3>
  </div>
<div class="panel-body">
<p> <!-- subsequent paragraphs come in larger fonts, so start with a paragraph -->
With a main program

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>a <span style="color: #666666">=</span> <span style="color: #666666">1</span>
<span style="color: #008000; font-weight: bold">from</span> <span style="color: #0000FF; font-weight: bold">math</span> <span style="color: #008000; font-weight: bold">import</span> pi
w <span style="color: #666666">=</span> pi
<span style="color: #008000">print</span>(f(<span style="color: #666666">0</span>))
</pre></div>
<p>
we can run the program:

<p>

<!-- code=text (!bc sys) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>Terminal&gt; python prog.py
0
</pre></div>
<p>
</div>
</div>

  </div> <!-- column col-sm-4 -->
</div> <!-- end cell row -->


<p>
<!-- navigation buttons at the bottom of the page -->
<ul class="pager">

  <li class="previous">
    <a href="._test_boots001.html">&larr; Prev</a>
  </li>
</ul>
<!-- ------------------- end of main content --------------- -->

</div>  <!-- end container -->
<!-- include javascript, jQuery *first* -->
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>
<script src="https://netdna.bootstrapcdn.com/bootstrap/3.0.0/js/bootstrap.min.js"></script>

<!-- Bootstrap footer
<footer>
<a href="https://..."><img width="250" align=right src="https://..."></a>
</footer>
-->


</body>
</html>
    


************** File: mdinput2do.do.txt *****************

======= Test of Markdown input syntax in DocOnce =======

DocOnce can recognize basic Markdown as input in the `.do.txt` file
and transform such text to native DocOnce.

# DocOnce comments also start with #, and can be confused with
# Markdown headings. The confusion is avoided by not having blanks
# after the # character in single-line comments. Multi-line
# comments work well and are never confused with Markdown headings.

# Markdown applies standard HTML
# comments

[hpl: This is a special comment on text that
is rendered by extended Markdown versions. ]

[comment:  This is another version of the special comment on text;
this one without any author name and colon in the beginning.
]

##Table of contents
TOC: on

===== Test of inline formatting =====

Markdown has _boldface_ and *emphasize* typesetting, as well
as `inline verbatim computer code`.

__Paragraph headings.__ These are written using standard Markdown
boldface syntax.

=== Subsubsection heading ===

The Markdown headings can only be of three types: section, subsection,
and subsubsection.

======= Typesetting of computer code =======

Here is a plain code snippet without language specification:

!bc
file=$1
if [ -f $file ]; then
  cp $file $file.cop
fi
# This is Bash - what happens to this comment?
!ec


The same snippet typeset explicitly as Bash, but with a common
indentation to be removed:

!bc shcod
file=$1
if [ -f $file ]; then
  cp $file $file.cop
fi
# This is Bash - what happens to this comment?
!ec


And here is Python:

!bc pycod
from math import sin

def f(x):
    return x*sin(x)

x = 1.4
print(f(x))
!ec


And HTML:

!bc htmlcod
<h1>Some heading</h1>
# And a comment
!ec



======= Test of quoted sections =======

!bblock
Markdown also features quoted
paragraphs that start with a greater
than sign, either just in the beginning
or at every line.
!eblock

If a quoted paragraph with blank lines is desired, you
must use `>` on the beginning of every line.

!bblock
_NOTE_:

This quoted paragragraph is a simulation of a primitive
admon in Markdown.
!eblock

======= Test of lists =======

Markdown applies the dash in itemized lists:

 * This is item 1
 * This is item 2
 * This is item 3

Let us test this in a quoted environment too:

!bblock
_List_:
  * This is item 1
  * This is item 2, which cannot be split between lines
  * This is item 3
!eblock

Enumerated lists go as follows.

 o Item 1
 o Item 2
 o Item 3

======= Test of tables =======

_Markdown Extra_ has a special syntax for tables:


|-----------------------------|
| Item      |    Value | Qty  |
|---l-------r-------c---|
| Computer  | 1600 USD |  5   |
| Phone     |   12 USD |  12  |
| Pipe      |    1 USD | 234  |
|-----------------------------|
#Horizontal marker/rule

-------------------------

======= Test of mathematics =======

You can render *LaTeX* mathematical expressions using _MathJax_, as on "math.stackexchange.com": "https://math.stackexchange.com/":

The *Gamma function* satisfying $\Gamma(n) = (n-1)!\quad\forall
n\in\mathbb N$ is via the Euler integral

!bt
\[ \Gamma(z) = \int_0^\infty t^{z-1}e^{-t}dt\,. \]
!et

************** File: .testdoc.quiz *****************
[{'choices': [['right', '$y=e^{-y}$'],
              ['wrong',
               '$y=e^{y}$',
               'Almost, but the sign is wrong (note the minus!).'],
              ['wrong',
               '~~~{.Python}\n'
               'from math import exp\n'
               'def f(x):\n'
               '    return exp(x)\n'
               '~~~',
               'Ooops, forgot a minus: `exp(-x)`, otherwise this Python code\n'
               'must be considered as a good answer. It is more natural,\n'
               'though, to write the solution to the problem\n'
               'in mathematical notation:\n'
               '\n'
               '$$\n'
               ' y(x) = e^{-y}.\n'
               '$$'],
              ['wrong',
               'The solution cannot be found because there is a derivative in '
               'the equation.',
               'Equations with derivatives can be solved;\n'
               'they are termed *differential\n'
               'equations*.'],
              ['wrong',
               'The equation is meaningless: an equation must be an equation\n'
               'for $x$ or $y$, not a function $y(x)$.',
               'Equations where the unknown is a function, as $y(x)$\n'
               'here, are called *differential equations*, and are solved by\n'
               'special techniques.']],
  'embedding': 'exercise',
  'heading': 'SOlution of differential equation',
  'keywords': ['derivatives',
               'exponential function',
               'equation, differential',
               'differential equation'],
  'label': 'quiz:diff:eq1',
  'no': 1,
  'question': 'Given\n'
              '\n'
              '$$\n'
              ' \\frac{dy}{dx} = -y(x),\\quad y(0)=1 \n'
              '$$\n'
              'What is the solution of this equation?'},
 {'choice prefix': ['Answer 1:', 'Answer 2:', 'Answer 3:', None],
  'choices': [['wrong', 'Stockholm', 'Stockholm is the capital of Sweden.'],
              ['wrong', 'London'],
              ['right', 'Oslo'],
              ['wrong',
               'Bergen',
               'Those from Bergen would claim so, but nobody else.']],
  'embedding': 'subsection',
  'heading': 'Capital of Norway',
  'keywords': ['capitals', 'basic intelligence', 'geography'],
  'new page': 'Test of quizzes',
  'no': 2,
  'question': 'What is the capital of Norway?',
  'question prefix': 'Fundamental test:'}]
************** File: encoding1.html *****************

<!-- tocinfo
{'highest level': 3,
 'sections': [('Test of æ, ø, å in headline',
               3,
               None,
               'test-of-&#230;-&#248;-&#229;-in-headline')]}
end of tocinfo -->


<!-- ------------------- main content ---------------------- -->

<!-- Important to test both heading (for rst and plain) and running text -->

<h3 id="test-of-&#230;-&#248;-&#229;-in-headline">Test of &#230;, &#248;, &#229; in headline </h3>

<p>
Name with Norwegian characters: &#197;smund &#216;deg&#229;rd.
Test inline tagging too: &quot;&#216;deg&#229;rd&quot;, <em>&#216;deg&#229;rd</em>, <b>&#216;deg&#229;rd</b>.
[&#197;smund: non-English chars in names in inline
comments are not accepted.]

<!-- ------------------- end of main content --------------- -->


************** File: testdoc_exer.do.txt *****************
TITLE: Exercises from A Document for Testing DocOnce
AUTHOR: Hans Petter Langtangen Email: hpl@simula.no at Center for Biomedical Computing, Simula Research Laboratory & Department of Informatics, University of Oslo
AUTHOR: Kaare Dump at Segfault, Cyberspace
AUTHOR: A. Dummy Author
AUTHOR: I. S. Overworked and Outburned at Inst1 & Inst2, Somewhere & Third Inst, Elsewhere & Fourth Inst
AUTHOR: J. Doe mail: j_doe@cyberspace.com
DATE: today


# Externaldocuments: testdoc
# Mapping from exercise labels to numbers: label2numbers = {'demo:ex:1': 'None.None', 'proj:circle1': 'None.None'}

TOC: on
===== Problem: Flip a Coin =====
label{demo:ex:1}
files = flip_coin.py, flip_coin.pdf
solutions = mysol.txt, mysol_flip_coin.py
keywords = random numbers; Monte Carlo simulation; ipynb

# Torture tests
file=myfile_should_be_a_part_of_the_text
solutions = mysol.txt, mysol_flip_coin.py, yet_another.file

!bsubex
Make a program that simulates flipping a coin $N$ times.
Print out ``tail'' or ``head'' for each flip and
let the program count the number of heads.

!bhint
Use `r = random.random()` and define head as `r <= 0.5`.
!ehint

!bhint
Draw an integer among $\{1,2\}$ with
`r = random.randint(1,2)` and define head when `r` is 1.
!ehint

!bans
If the `random.random()` function returns a number $<1/2$, let it be
head, otherwise tail. Repeat this $N$ number of times.
!eans

!bsol
!bc pycod
import sys, random
N = int(sys.argv[1])
heads = 0
for i in range(N):
    r = random.random()
    if r <= 0.5:
        heads += 1
print('Flipping a coin %d times gave %d heads' % (N, heads))
!ec
!esol
!esubex

!bsubex
Vectorize the code in a) using boolean indexing.
!esubex

Vectorized code can be written in many ways.
Sometimes the code is less intuitive, sometimes not.
At least there is not much to find in Section ref{sec1}.

!bsubex
Vectorize the code in a) using `numpy.sum`.


!bans
`np.sum(np.where(r <= 0.5, 1, 0))` or `np.sum(r <= 0.5)`.
!eans
!esubex

In this latter subexercise, we have an
example where the code is easy to read.

!bremarks
These are the exercise remarks, appearing at the very end.
!eremarks

=== My remarks ===

Remarks with such a subsubsection is treated as more text
after the last subexercise. Test a list too:

 o Mark 1.
 o Mark 2.

===== Project: Explore Distributions of Random Circles =====

label{proj:circle1}
file=circles
kw=ipynb

The formula for a circle is given by

!bt
\begin{align}
x &= x_0 + R\cos 2\pi t,
label{circle:x}\\ 
y &= y_0 + R\sin 2\pi t,
label{circle:y}
\end{align}
!et
where $R$ is the radius of the circle, $(x_0,y_0)$ is the
center point, and $t$ is a parameter in the unit interval $[0,1]$.
For any $t$, $(x,y)$ computed from (ref{circle:x})-(ref{circle:y})
is a point on the circle.
The formula can be used to generate `n` points on a circle:

!bc pypro
import numpy as np

def circle(R, x0, y0, n=501):
    t = np.linspace(0, 1, n)
    x = x0 + R*np.cos(2*np.pi*t)
    y = y0 + R*np.sin(2*np.pi*t)
    return x, y

x, y = circle(2.0, 0, 0)
!ec

# Often in an exercise we have some comments about the solution
# which we normally want to keep where they are.

The goal of this project is to draw $N$ circles with random
center and radius. Plot each circle using the `circle` function
above.

!bsubex
Let $R$ be normally distributed and $(x_0,y_0)$ uniformly distributed.

!bans
Here goes the short answer to part a).
!eans

!bsol
Here goes a full solution to part a).
!esol

!bhint
Use the `numpy.random` module to draw the
$x_0$, $y_0$, and $R$ quantities.
!ehint

!esubex

!bsubex
Let $R$ be uniformly distributed and $(x_0,y_0)$ normally distributed.

file=norm  # test local filename for subexercise
!esubex

!bsubex
Let $R$ and $(x_0,y_0)$ be normally distributed.
!esubex

!bremarks
At the very end of the exercise it may be appropriate to summarize
and give some perspectives.
!eremarks


************** File: nbdemo.ipynb *****************
{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<!-- dom:TITLE: Example on interactive live documents versus traditional static documents -->\n",
    "# Example on interactive live documents versus traditional static documents\n",
    "<!-- dom:AUTHOR: hpl -->\n",
    "<!-- Author: -->  \n",
    "**hpl**\n",
    "\n",
    "Date: **Jan 32, 2100**\n",
    "\n",
    "## Physics\n",
    "<div id=\"ipynbex:physics\"></div>\n",
    "\n",
    "We consider a vibrating mechanical system as shown in [Figure 1](#ipynbex:physics:fig).\n",
    "\n",
    "<!-- dom:FIGURE: [../doc/src/ipynb/fig/oscillator_general.png, width=600 frac=0.8] Oscillating system with spring and damper. <div id=\"ipynbex:physics:fig\"></div> -->\n",
    "<!-- begin figure -->\n",
    "<div id=\"ipynbex:physics:fig\"></div>\n",
    "<img src=\"../doc/src/ipynb/fig/oscillator_general.png\" width=600><p style=\"font-size: 0.9em\"><i>Figure 1: Oscillating system with spring and damper.</i></p><!-- end figure -->\n",
    "\n",
    "\n",
    "## Mathematics\n",
    "<div id=\"ipynbex:math\"></div>\n",
    "\n",
    "A differential equation for the system in [Figure 1](#ipynbex:physics:fig) reads"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "$$\n",
    "mu'' + f(u') + s(u) = F(t),\\quad u(0)=I,\\ u'(0)=V\\thinspace .\n",
    "$$"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the linear damping case, where $f(u')=bu'$ for some constant\n",
    "$b\\geq 0$, we can solve the problem numerically by a scheme"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<!-- Equation labels as ordinary links -->\n",
    "<div id=\"ipynbex:u:scheme:lin\"></div>\n",
    "\n",
    "$$\n",
    "\\begin{equation}\n",
    "u^{n+1} = \\left(2mu^n + (\\frac{b}{2}\\Delta t - m)u^{n-1} +\n",
    "\\Delta t^2(F^n - s(u^n))\n",
    "\\right)(m + \\frac{b}{2}\\Delta t)^{-1},\n",
    "\\label{ipynbex:u:scheme:lin} \\tag{1}\n",
    "\\end{equation}\n",
    "$$"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "for $n=0,1,\\ldots$. A special formula is required for $n=0$:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<!-- Equation labels as ordinary links -->\n",
    "<div id=\"ipynbex:u:scheme0:lin\"></div>\n",
    "\n",
    "$$\n",
    "\\begin{equation}\n",
    "u^1 = u^0 + \\Delta t\\, V\n",
    "+ \\frac{\\Delta t^2}{2m}(-bV - s(u^0) + F^0)\n",
    "\\thinspace .\n",
    "\\label{ipynbex:u:scheme0:lin} \\tag{2}\n",
    "\\end{equation}\n",
    "$$"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Implementation\n",
    "\n",
    "<!-- Note: Plain Markdown cannot refer to equations with numbers. -->\n",
    "<!-- This is a DocOnce extension. -->\n",
    "\n",
    "The formulas ([1](#ipynbex:u:scheme:lin)) and ([2](#ipynbex:u:scheme0:lin))\n",
    "can be implemented as follows in a Python function:\n",
    "\n",
    "<!-- Next code (hidden code): -->\n",
    "<!-- Not strictly needed since zeros inside the next function -->\n",
    "<!-- is not called before the main program has imported zeros... -->\n",
    "<!-- But in general one may need special imports for the next -->\n",
    "<!-- code segments to execute properly. -->"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "from numpy import zeros"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "editable": true
   },
   "outputs": [],
   "source": [
    "def solver_linear_damping(I, V, m, b, s, F, t):\n",
    "    N = t.size - 1              # No of time intervals\n",
    "    dt = t[1] - t[0]            # Time step\n",
    "    u = zeros(N+1)              # Result array\n",
    "    u[0] = I\n",
    "    u[1] = u[0] + dt*V + dt**2/(2*m)*(-b*V - s(u[0]) + F[0])\n",
    "\n",
    "    for n in range(1,N):\n",
    "        u[n+1] = 1./(m + b*dt/2)*(2*m*u[n] + \\\n",
    "                 (b*dt/2 - m)*u[n-1] + dt**2*(F[n] - s(u[n])))\n",
    "    return u"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Dissection\n",
    "\n",
    "<!-- Code here is not meant to be executed, just shown for discussion. -->\n",
    "\n",
    "The array `t` holds all the time points where we want a solution.\n",
    "The total number of intervals, $N$, is then computed as"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```Python\n",
    "        N = t.size - 1   # or len(t) - 1\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Creating an array of length $N+1$ where we can store the solution\n",
    "is done by"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```Python\n",
    "        u = zeros(N+1)\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For loops over array indices are coded as"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```Python\n",
    "        for n in range(1, N):\n",
    "            ...\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "which generates a sequence of integers from 1 up to `N`, *but not\n",
    "including* `N`.\n",
    "\n",
    "## Usage\n",
    "\n",
    "The function `solve_linear_damping` resides in a file `solver.py`.\n",
    "\n",
    "<!-- Need to tell where solver.py is for the notebook to execute properly. -->\n",
    "<!-- For this we use a hidden python code (pyhid). It will be hidden -->\n",
    "<!-- in all formats, except in the notebook. -->"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# The solver module is in src/solver.py; tell Python about that\n",
    "import sys\n",
    "sys.path.insert(0, 'src')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<!-- For matplotlib we need to insert %matplotlib inline in the notebook. -->\n",
    "<!-- (Automatically done by DocOnce.) -->"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "editable": true
   },
   "outputs": [],
   "source": [
    "%matplotlib inline\n",
    "\n",
    "from solver import solver_linear_damping\n",
    "from numpy import linspace, zeros, pi\n",
    "\n",
    "def s(u):\n",
    "    return 2*u\n",
    "\n",
    "T = 10*pi      # simulate for t in [0,T]\n",
    "dt = 0.2\n",
    "N = int(round(T/dt))\n",
    "t = linspace(0, T, N+1)\n",
    "F = zeros(t.size)\n",
    "I = 1; V = 0\n",
    "m = 2; b = 0.2\n",
    "u = solver_linear_damping(I, V, m, b, s, F, t)\n",
    "\n",
    "from matplotlib.pyplot import *\n",
    "plot(t, u)\n",
    "show()"
   ]
  }
 ],
 "metadata": {},
 "nbformat": 4,
 "nbformat_minor": 4
}

************** File: nbdemo.do.txt *****************
TITLE: Example on interactive live documents versus traditional static documents
AUTHOR: hpl
# Author:
_hpl_

DATE: Jan 32, 2100

===== Physics =====
label{ipynbex:physics}

We consider a vibrating mechanical system as shown in "Figure 1": "#ipynbex:physics:fig".

FIGURE: [../doc/src/ipynb/fig/oscillator_general, width=600 frac=0.8] Oscillating system with spring and damper. label{ipynbex:physics:fig}


===== Mathematics =====
label{ipynbex:math}

A differential equation for the system in "Figure 1": "#ipynbex:physics:fig" reads

!bt
\[ mu'' + f(u') + s(u) = F(t),\quad u(0)=I,\ u'(0)=V\thinspace . \]
!et
In the linear damping case, where $f(u')=bu'$ for some constant
$b\geq 0$, we can solve the problem numerically by a scheme

!bt
\begin{equation}
u^{n+1} = \left(2mu^n + (\frac{b}{2}\Delta t - m)u^{n-1} +
\Delta t^2(F^n - s(u^n))
\right)(m + \frac{b}{2}\Delta t)^{-1},
label{ipynbex:u:scheme:lin}
\end{equation}
!et
for $n=0,1,\ldots$. A special formula is required for $n=0$:

!bt
\begin{equation}
u^1 = u^0 + \Delta t\, V
+ \frac{\Delta t^2}{2m}(-bV - s(u^0) + F^0)
\thinspace .
label{ipynbex:u:scheme0:lin}
\end{equation}
!et

===== Implementation =====

# Note: Plain Markdown cannot refer to equations with numbers.
# This is a DocOnce extension.

The formulas ("1": "#ipynbex:u:scheme:lin") and ("2": "#ipynbex:u:scheme0:lin")
can be implemented as follows in a Python function:

# Next code (hidden code):
# Not strictly needed since zeros inside the next function
# is not called before the main program has imported zeros...
# But in general one may need special imports for the next
# code segments to execute properly.

!bc pyhid
from numpy import zeros
!ec

!bc pycod
def solver_linear_damping(I, V, m, b, s, F, t):
    N = t.size - 1              # No of time intervals
    dt = t[1] - t[0]            # Time step
    u = zeros(N+1)              # Result array
    u[0] = I
    u[1] = u[0] + dt*V + dt**2/(2*m)*(-b*V - s(u[0]) + F[0])

    for n in range(1,N):
        u[n+1] = 1./(m + b*dt/2)*(2*m*u[n] + \
                 (b*dt/2 - m)*u[n-1] + dt**2*(F[n] - s(u[n])))
    return u
!ec

===== Dissection =====

# Code here is not meant to be executed, just shown for discussion.

The array `t` holds all the time points where we want a solution.
The total number of intervals, $N$, is then computed as

!bc pycod-t
N = t.size - 1   # or len(t) - 1
!ec
Creating an array of length $N+1$ where we can store the solution
is done by

!bc pycod-t
u = zeros(N+1)
!ec
For loops over array indices are coded as

!bc pycod-t
for n in range(1, N):
    ...
!ec
which generates a sequence of integers from 1 up to `N`, *but not
including* `N`.

===== Usage =====

The function `solve_linear_damping` resides in a file `solver.py`.

# Need to tell where solver.py is for the notebook to execute properly.
# For this we use a hidden python code (pyhid). It will be hidden
# in all formats, except in the notebook.

!bc pyhid
# The solver module is in src/solver.py; tell Python about that
import sys
sys.path.insert(0, 'src')
!ec
# For matplotlib we need to insert %matplotlib inline in the notebook.
# (Automatically done by DocOnce.)

!bc pycod
from solver import solver_linear_damping
from numpy import linspace, zeros, pi

def s(u):
    return 2*u

T = 10*pi      # simulate for t in [0,T]
dt = 0.2
N = int(round(T/dt))
t = linspace(0, T, N+1)
F = zeros(t.size)
I = 1; V = 0
m = 2; b = 0.2
u = solver_linear_damping(I, V, m, b, s, F, t)

from matplotlib.pyplot import *
plot(t, u)
show()
!ec

************** File: test_copyright.out *****************
------------------- File: tmp_copyright.tex

\fancyfoot[C]{{\footnotesize \copyright\ 20XX, Hans Petter Langtangen, Simula, Kaare Dump. Made with \href{https://github.com/hplgit/doconce}{DocOnce}}}
\fancyfoot[C]{{\footnotesize \copyright\ 20XX, Hans Petter Langtangen, Simula, Kaare Dump. Made with \href{https://github.com/hplgit/doconce}{DocOnce}}}
------------------- File: tmp_copyright.tex

\fancyfoot[C]{{\footnotesize \copyright\ 20XX, Hans Petter Langtangen, Simula, Kaare Dump. \\ Released under CC Attribution 4.0 license. Made with \href{https://github.com/hplgit/doconce}{DocOnce}}}
\fancyfoot[C]{{\footnotesize \copyright\ 20XX, Hans Petter Langtangen, Simula, Kaare Dump. \\ Released under CC Attribution 4.0 license. Made with \href{https://github.com/hplgit/doconce}{DocOnce}}}
------------------- File: tmp_copyright.tex

\fancyfoot[C]{{\footnotesize \copyright\ 20XX, Hans Petter Langtangen, Simula, Kaare Dump. \\ Released under CC Attribution-NonCommercial 4.0 license. Made with \href{https://github.com/hplgit/doconce}{DocOnce}}}
\fancyfoot[C]{{\footnotesize \copyright\ 20XX, Hans Petter Langtangen, Simula, Kaare Dump. \\ Released under CC Attribution-NonCommercial 4.0 license. Made with \href{https://github.com/hplgit/doconce}{DocOnce}}}
------------------- File: tmp_copyright.tex

\fancyfoot[C]{{\footnotesize \copyright\ 20XX, Hans Petter Langtangen, Simula, Kaare Dump. \\ Released under the MIT license.. Made with \href{https://github.com/hplgit/doconce}{DocOnce}}}
\fancyfoot[C]{{\footnotesize \copyright\ 20XX, Hans Petter Langtangen, Simula, Kaare Dump. \\ Released under the MIT license.. Made with \href{https://github.com/hplgit/doconce}{DocOnce}}}
------------------- File: tmp_sphinx-rootdir1/conf.py

copyright = '2021, Test'
------------------- File: tmp_sphinx-rootdir2/conf.py

copyright = '2021, Test'
------------------- File: tmp_sphinx-rootdir3/conf.py

copyright = '2021, Test'
------------------- File: tmp_sphinx-rootdir4/conf.py

copyright = '2021, Test'
------------------- File: tmp_copyright1.html

&copy; 20XX, Hans Petter Langtangen, Simula, Kaare Dump. Made with <a href="https://github.com/hplgit/doconce">DocOnce</a>
------------------- File: ._tmp_copyright1001.html


------------------- File: ._tmp_copyright1000.html

&copy; 20XX, Hans Petter Langtangen, Simula, Kaare Dump. Made with <a href="https://github.com/hplgit/doconce">DocOnce</a>
------------------- File: ._tmp_copyright1002.html


------------------- File: tmp_copyright2.html

&copy; 20XX, Hans Petter Langtangen, Simula, Kaare Dump. Released under CC Attribution 4.0 license. Made with <a href="https://github.com/hplgit/doconce">DocOnce</a>
------------------- File: ._tmp_copyright2002.html


------------------- File: ._tmp_copyright2001.html


------------------- File: ._tmp_copyright2000.html

&copy; 20XX, Hans Petter Langtangen, Simula, Kaare Dump. Released under CC Attribution 4.0 license. Made with <a href="https://github.com/hplgit/doconce">DocOnce</a>
------------------- File: tmp_copyright3.html

&copy; 20XX, Hans Petter Langtangen, Simula, Kaare Dump. Released under CC Attribution-NonCommercial 4.0 license. Made with <a href="https://github.com/hplgit/doconce">DocOnce</a>
------------------- File: ._tmp_copyright3001.html


------------------- File: ._tmp_copyright3000.html

&copy; 20XX, Hans Petter Langtangen, Simula, Kaare Dump. Released under CC Attribution-NonCommercial 4.0 license. Made with <a href="https://github.com/hplgit/doconce">DocOnce</a>
------------------- File: ._tmp_copyright3002.html


------------------- File: tmp_copyright4.html

&copy; 20XX, Hans Petter Langtangen, Simula, Kaare Dump. Released under the MIT license.. Made with <a href="https://github.com/hplgit/doconce">DocOnce</a>
------------------- File: ._tmp_copyright4001.html


------------------- File: ._tmp_copyright4000.html

&copy; 20XX, Hans Petter Langtangen, Simula, Kaare Dump. Released under the MIT license.. Made with <a href="https://github.com/hplgit/doconce">DocOnce</a>
------------------- File: ._tmp_copyright4002.html


************** File: tailored_conf.py *****************
# -*- coding: utf-8 -*-
#
# All configuration values have a default; values that are commented out
# serve to show the default.

import sys, os

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#sys.path.insert(0, os.path.abspath('.'))

# -- General configuration -----------------------------------------------------

# If your documentation needs a minimal Sphinx version, state it here.
#needs_sphinx = '1.0'

# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = [
          'sphinx.ext.mathjax',
          'matplotlib.sphinxext.plot_directive',
          'sphinx.ext.autodoc',
          'sphinx.ext.doctest',
          'sphinx.ext.viewcode',
          'sphinx.ext.intersphinx',
          'sphinx.ext.inheritance_diagram',
          'IPython.sphinxext.ipython_console_highlighting']

# Make sphinx aware of the DocOnce lexer
def setup(app):
    from sphinx.highlighting import lexers
    from doconce.misc import DocOnceLexer
    lexers['doconce'] = DocOnceLexer()


# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

# The suffix of source filenames.
source_suffix = '.rst'

# The encoding of source files.
#source_encoding = 'utf-8-sig'

# The master toctree document.
master_doc = 'index'

# General information about the project.
# Leave empty if DocOnce is to fill them in.
project = u'Test'
copyright = u'20XX, Hans Petter Langtangen, Simula, Kaare Dump'

# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = '1.0'
# The full version, including alpha/beta/rc tags.
release = '1.0'

# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#language = None

# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#today = ''
# Else, today_fmt is used as the format for a strftime call.
#today_fmt = '%B %d, %Y'

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = ['_build']

# The reST default role (used for this markup: `text`) to use for all documents.
#default_role = None

# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True

# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#add_module_names = True

# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#show_authors = False

# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'

# A list of ignored prefixes for module index sorting.
#modindex_common_prefix = []

# Add any paths that contain custom themes here, relative to this directory.
html_theme_path = ['_themes']

# -- Options for HTML output ---------------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
html_theme = 'bootstrap'

# Theme options are theme-specific and customize the look and feel of a theme
# further.  For a list of options available for each theme, see the
# documentation.

if html_theme == 'bootstrap':
    import sphinx_bootstrap_theme
    html_theme_path += sphinx_bootstrap_theme.get_html_theme_path()
    html_theme_options = {
        # Global TOC depth for "site" navbar tab. (Default: 1)
        # Switching to -1 shows all levels.
        'globaltoc_depth': 2,

        # HTML navbar class (Default: "navbar") to attach to <div> element.
        # For black navbar, do "navbar navbar-inverse"
        'navbar_class': "navbar navbar-inverse",

        # Fix navigation bar to top of page?
        # Values: "true" (default) or "false"
        'navbar_fixed_top': "true",

        # Location of link to source.
        # Options are "nav" (default), "footer" or anything else to exclude.
        'source_link_position': "nav",

        # TODO: Future.
        # Add page navigation to it's own navigation bar.
        #'navbar_page_separate': True,
    }

# The name for this set of Sphinx documents.  If None, it defaults to
# "<project> v<release> documentation".
html_title = project

# A shorter title for the navigation bar.  Default is the same as html_title = project
#html_short_title = None

# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#html_logo = None

# The name of an image file (within the static path) to use as favicon of the
# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#html_favicon = None

# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']

# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
#html_last_updated_fmt = '%b %d, %Y'

# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
#html_use_smartypants = True

# Custom sidebar templates, maps document names to template names.
#html_sidebars = {}

# Additional templates that should be rendered to pages, maps page names to
# template names.
#html_additional_pages = {}

# If false, no module index is generated.
#html_domain_indices = True

# If false, no index is generated.

# If true, the index is split into individual pages for each letter.
#html_split_index = False

# If true, links to the reST sources are added to the pages.
#html_show_sourcelink = True

# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#html_show_sphinx = True

# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
#html_show_copyright = True

# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it.  The value of this option must be the
# base URL from which the finished HTML is served.
#html_use_opensearch = ''

# This is the file name suffix for HTML files (e.g. ".xhtml").
#html_file_suffix = None

# Output file base name for HTML help builder.
htmlhelp_basename = 'htmlhelp'


# -- Options for LaTeX output --------------------------------------------------

latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#'papersize': 'letterpaper',

# The font size ('10pt', '11pt' or '12pt').
#'pointsize': '10pt',

# Additional stuff for the LaTeX preamble.
#'preamble': '',
}

# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [('index', 'doc.tex', project, u'Hans Petter Langtangen, Kaare Dump and Joe Doe',  'manual'),]

# The name of an image file (relative to this directory) to place at the top of
# the title page.
#latex_logo = None

# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
#latex_use_parts = False

# If true, show page references after internal links.
#latex_show_pagerefs = False

# If true, show URL addresses after external links.
#latex_show_urls = False

# Documents to append as an appendix to all manuals.
#latex_appendices = []

# If false, no module index is generated.
#latex_domain_indices = True


# -- Options for manual page output --------------------------------------------

# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [('index', 'doc', project, [u'Hans Petter Langtangen, Kaare Dump and Joe Doe'], 1),]

# If true, show URL addresses after external links.
#man_show_urls = False


# -- Options for Texinfo output ------------------------------------------------

# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
#  dir menu entry, description, category)
texinfo_documents = [('index', 'doc', project, u'Hans Petter Langtangen, Kaare Dump and Joe Doe', 'doc', 'One line description of project.', 'Miscellaneous'),]

# Documents to append as an appendix to all manuals.
#texinfo_appendices = []

# If false, no module index is generated.
#texinfo_domain_indices = True

# How to display URL addresses: 'footnote', 'no', or 'inline'.
#texinfo_show_urls = 'footnote'


# -- Options for Epub output ---------------------------------------------------

# Bibliographic Dublin Core info.
epub_title = project
epub_author = u'Hans Petter Langtangen, Kaare Dump and Joe Doe'
epub_publisher = u'Hans Petter Langtangen, Kaare Dump and Joe Doe'
epub_copyright = u'20XX, Hans Petter Langtangen, Simula, Kaare Dump'

# The language of the text. It defaults to the language option
# or en if the language is not set.
#epub_language = ''

# The scheme of the identifier. Typical schemes are ISBN or URL.
#epub_scheme = ''

# The unique identifier of the text. This can be a ISBN number
# or the project homepage.
#epub_identifier = ''

# A unique identification for the text.
#epub_uid = ''

# A tuple containing the cover image and cover page html template filenames.
#epub_cover = ()

# HTML files that should be inserted before the pages created by sphinx.
# The format is a list of tuples containing the path and title.
#epub_pre_files = []

# HTML files shat should be inserted after the pages created by sphinx.
# The format is a list of tuples containing the path and title.
#epub_post_files = []

# A list of files that should not be packed into the epub file.
#epub_exclude_files = []

# The depth of the table of contents in toc.ncx.
#epub_tocdepth = 3

# Allow duplicate toc entries.
#epub_tocdup = True

************** File: testdoc_code_prefix.html *****************
<!--
Automatically generated HTML file from DocOnce source
(https://github.com/doconce/doconce/)
-->
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="DocOnce: https://github.com/doconce/doconce/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="description" content="A Document for Testing DocOnce">
<meta name="keywords" content="figures,movies,index with subindex,_boldface word_ in index,index with _boldface word_,index with _boldface word_ in subentry,double _boldface word_  _boldface word_ in subentry too,index, with comma, and one more">

<title>A Document for Testing DocOnce</title>


<style type="text/css">
/* blueish style */

/* Color definitions:  https://www.december.com/html/spec/color0.html
   CSS examples:       https://www.w3schools.com/css/css_examples.asp */

body {
  margin-top: 1.0em;
  background-color: #ffffff;
  font-family: Helvetica, Arial, FreeSans, san-serif;
  color: #000000;
}
h1 { font-size: 1.8em; color: #1e36ce; }
h2 { font-size: 1.6em; color: #1e36ce; }
h3 { font-size: 1.4em; color: #1e36ce; }
a { color: #1e36ce; text-decoration:none; }
tt { font-family: "Courier New", Courier; }
/* pre style removed because it will interfer with pygments */
p { text-indent: 0px; }
hr { border: 0; width: 80%; border-bottom: 1px solid #aaa}
p.caption { width: 80%; font-style: normal; text-align: left; }
hr.figure { border: 0; width: 80%; border-bottom: 1px solid #aaa}
.alert-text-small   { font-size: 80%;  }
.alert-text-large   { font-size: 130%; }
.alert-text-normal  { font-size: 90%;  }
.alert {
  padding:8px 35px 8px 14px; margin-bottom:18px;
  text-shadow:0 1px 0 rgba(255,255,255,0.5);
  border:1px solid #bababa;
  border-radius: 4px;
  -webkit-border-radius: 4px;
  -moz-border-radius: 4px;
  color: #555;
  background-color: #f8f8f8;
  background-position: 10px 5px;
  background-repeat: no-repeat;
  background-size: 38px;
  padding-left: 55px;
  width: 75%;
 }
.alert-block {padding-top:14px; padding-bottom:14px}
.alert-block > p, .alert-block > ul {margin-bottom:1em}
.alert li {margin-top: 1em}
.alert-block p+p {margin-top:5px}
.alert-notice { background-image: url(https://cdn.rawgit.com/doconce/doconce/master/bundled/html_images/small_gray_notice.png); }
.alert-summary  { background-image:url(https://cdn.rawgit.com/doconce/doconce/master/bundled/html_images/small_gray_summary.png); }
.alert-warning { background-image: url(https://cdn.rawgit.com/doconce/doconce/master/bundled/html_images/small_gray_warning.png); }
.alert-question {background-image:url(https://cdn.rawgit.com/doconce/doconce/master/bundled/html_images/small_gray_question.png); }

div { text-align: justify; text-justify: inter-word; }
</style>


<script src="https://sagecell.sagemath.org/static/jquery.min.js"></script>
<script src="https://sagecell.sagemath.org/embedded_sagecell.js"></script>
<link rel="stylesheet" type="text/css" href="https://sagecell.sagemath.org/static/sagecell_embed.css">
<script>
$(function () {
    // Make the div with id 'mycell' a Sage cell
    sagecell.makeSagecell({inputLocation:  '#mycell',
                           template:       sagecell.templates.minimal,
                           evalButtonText: 'Activate'});
    // Make *any* div with class 'compute' a Sage cell
    sagecell.makeSagecell({inputLocation: 'div.compute',
                           evalButtonText: 'Evaluate'});
});
</script>




<!-- Tools for embedded Bokeh plots -->
<link rel="stylesheet"
      href="https://cdn.pydata.org/bokeh/release/bokeh-0.9.0.min.css"
      type="text/css" />
<script type="text/javascript"
	src="https://cdn.pydata.org/bokeh/release/bokeh-0.9.0.min.js">
</script>
<script type="text/javascript">
  Bokeh.set_log_level("info");
</script>


</head>

<!-- tocinfo
{'highest level': 1,
 'sections': [('Table of contents',
               1,
               'table_of_contents',
               'table_of_contents'),
              ('Section 1', 1, 'sec1', 'sec1'),
              ('Here is a list with subsubsection heading',
               3,
               None,
               'here-is-a-list-with-subsubsection-heading'),
              ('Subsection 1', 2, 'subsec1', 'subsec1'),
              ('Test Section reference at beginning of line and after a '
               'sentence',
               3,
               None,
               'test-section-reference-at-beginning-of-line-and-after-a-sentence'),
              ('Computer code', 3, None, 'computer-code'),
              ('Subsubsection heading before code',
               3,
               None,
               'subsubsection-heading-before-code'),
              ('Running OS commands', 3, None, 'running-os-commands'),
              ('Footnotes', 3, None, 'footnotes'),
              ('Subsection 2: Testing figures', 2, 'subsec:ex', 'subsec:ex'),
              ('The $\\theta$ parameter (not $\\nabla$?)',
               2,
               'decay:sec:theta',
               'decay:sec:theta'),
              ('Custom Environments', 2, None, 'custom-environments'),
              ('Tables', 2, 'subsec:table', 'subsec:table'),
              ('A test of verbatim words in heading with subscript $a_i$: '
               '`my_file_v1` and `my_file_v2`',
               2,
               None,
               'a-test-of-verbatim-words-in-heading-with-subscript-a_i-my_file_v1-and-my_file_v2'),
              ('_Just bold_', 2, None, '_just-bold_'),
              ('*Just emphasize*', 2, None, 'just-emphasize'),
              ('`Just verbatim`', 2, None, 'just-verbatim'),
              ('_Bold_ beginning', 2, None, '_bold_-beginning'),
              ('*Emphasize* beginning', 2, None, 'emphasize-beginning'),
              ('`Verbatim` beginning', 2, None, 'verbatim-beginning'),
              ('Maybe _bold end_', 2, None, 'maybe-_bold-end_'),
              ('Maybe *emphasize end*', 2, None, 'maybe-emphasize-end'),
              ('Maybe `verbatim end`', 2, None, 'maybe-verbatim-end'),
              ('The middle has _bold_ word',
               2,
               None,
               'the-middle-has-_bold_-word'),
              ('The middle has *emphasize* word',
               2,
               None,
               'the-middle-has-emphasize-word'),
              ('The middle has `verbatim` word',
               2,
               None,
               'the-middle-has-verbatim-word'),
              ('Bibliography test', 2, None, 'bibliography-test'),
              ('Example 1: Examples can be typeset as exercises',
               2,
               'Example',
               'Example'),
              ('User-defined environments',
               2,
               None,
               'user-defined-environments'),
              ('Example 1: A test function', 2, 'ex:test:1p1', 'ex:test:1p1'),
              ('Example 2: Addition', 2, 'ex:math:1p1', 'ex:math:1p1'),
              ('URLs', 2, 'subsubsec:ex', 'subsubsec:ex'),
              ('LaTeX Mathematics', 1, None, 'latex-mathematics'),
              ('Exercises', 1, None, 'exercises'),
              ('Problem 2: Flip a Coin', 2, 'demo:ex:1', 'demo:ex:1'),
              ('My remarks', 3, None, 'my-remarks'),
              ('Remarks', 3, None, 'remarks'),
              ('Not an exercise', 2, None, 'not-an-exercise'),
              ('Exercise 3: Test of plain text exercise',
               2,
               'my:exer1',
               'my:exer1'),
              ('Project 4: Compute a Probability', 2, 'demo:ex:2', 'demo:ex:2'),
              ('Project 5: Explore Distributions of Random Circles',
               2,
               'proj:circle1',
               'proj:circle1'),
              ('Remarks', 3, None, 'remarks'),
              ('Exercise 6: Determine some Distance',
               2,
               'exer:dist',
               'exer:dist'),
              ('Remarks', 3, None, 'remarks'),
              ('Some exercise without the "Exercise:" prefix',
               2,
               None,
               'some-exercise-without-the-exercise-prefix'),
              ('Exercise 8: Solution of differential equation',
               2,
               'sec:this:exer:de',
               'sec:this:exer:de'),
              ('Example 9: Just an example',
               2,
               None,
               'example-9-just-an-example'),
              ('Here goes another section',
               1,
               None,
               'here-goes-another-section'),
              ('More Exercises', 1, None, 'more-exercises'),
              ('Exercise 10: Make references to projects and problems',
               2,
               'exer:some:formula',
               'exer:some:formula'),
              ('Project 11: References in a headings do not work well in html',
               2,
               'exer:you',
               'exer:you'),
              ('References', 1, None, 'references'),
              ('Appendix: Just for testing; part I', 1, 'app1', 'app1'),
              ('A subsection within an appendix',
               2,
               None,
               'a-subsection-within-an-appendix'),
              ('Appendix: Just for testing; part II', 1, 'app2', 'app2'),
              ('Appendix: Testing identical titles',
               2,
               None,
               'appendix-testing-identical-titles'),
              ('Appendix: Testing identical titles',
               2,
               'test:title:id1',
               'test:title:id1'),
              ('Appendix: Testing identical titles',
               2,
               'test:title:id2',
               'test:title:id2'),
              ('Appendix: Testing identical titles',
               2,
               None,
               'appendix-testing-identical-titles'),
              ('Appendix: Testing inline comments',
               2,
               None,
               'appendix-testing-inline-comments'),
              ('Appendix: Testing headings ending with `verbatim inline`',
               2,
               None,
               'appendix-testing-headings-ending-with-verbatim-inline')]}
end of tocinfo -->

<body>



<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  TeX: {
     equationNumbers: {  autoNumber: "AMS"  },
     extensions: ["AMSmath.js", "AMSsymbols.js", "autobold.js", "color.js"]
  }
});
</script>
<script type="text/javascript" async
 src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>



    
<!-- ------------------- main content ---------------------- -->



<center><h1>A Document for Testing DocOnce</h1></center>  <!-- document title -->

<p>
<!-- author(s): Hans Petter Langtangen, Kaare Dump, A. Dummy Author, I. S. Overworked and Outburned, and J. Doe -->

<center>
<b>Hans Petter Langtangen</b> [1, 2] (<tt>hpl at simula.no</tt>)
</center>

<center>
<b>Kaare Dump</b> [3]
</center>

<center>
<b>A. Dummy Author</b> 
</center>

<center>
<b>I. S. Overworked and Outburned</b> [4, 5, 6, 7]
</center>

<center>
<b>J. Doe</b>  (<tt>j_doe at cyberspace.com</tt>)
</center>

<p>
<!-- institution(s) -->

<center>[1] <b>Center for Biomedical Computing, Simula Research Laboratory</b></center>
<center>[2] <b>Department of Informatics, University of Oslo</b></center>
<center>[3] <b>Segfault, Cyberspace</b></center>
<center>[4] <b>Inst1</b></center>
<center>[5] <b>Inst2, Somewhere</b></center>
<center>[6] <b>Third Inst, Elsewhere</b></center>
<center>[7] <b>Fourth Inst</b></center>
<br>
<p>
<center><h4>Jan 32, 2100</h4></center> <!-- date -->
<br>

<h1 id="table_of_contents">Table of contents</h2>

<p>
<a href="#sec1"> Section 1 </a><br>
&nbsp; &nbsp; &nbsp; <a href="#subsec1"> Subsection 1 </a><br>
&nbsp; &nbsp; &nbsp; <a href="#subsec:ex"> Subsection 2: Testing figures </a><br>
&nbsp; &nbsp; &nbsp; <a href="#decay:sec:theta"> The \( \theta \) parameter (not \( \nabla \)?) </a><br>
&nbsp; &nbsp; &nbsp; <a href="#custom-environments"> Custom Environments </a><br>
&nbsp; &nbsp; &nbsp; <a href="#subsec:table"> Tables </a><br>
&nbsp; &nbsp; &nbsp; <a href="#a-test-of-verbatim-words-in-heading-with-subscript-a_i-my_file_v1-and-my_file_v2"> A test of verbatim words in heading with subscript \( a_i \): <code>my_file_v1</code> and <code>my_file_v2</code> </a><br>
&nbsp; &nbsp; &nbsp; <a href="#_just-bold_"> <b>Just bold</b> </a><br>
&nbsp; &nbsp; &nbsp; <a href="#just-emphasize"> <em>Just emphasize</em> </a><br>
&nbsp; &nbsp; &nbsp; <a href="#just-verbatim"> <code>Just verbatim</code> </a><br>
&nbsp; &nbsp; &nbsp; <a href="#_bold_-beginning"> <b>Bold</b> beginning </a><br>
&nbsp; &nbsp; &nbsp; <a href="#emphasize-beginning"> <em>Emphasize</em> beginning </a><br>
&nbsp; &nbsp; &nbsp; <a href="#verbatim-beginning"> <code>Verbatim</code> beginning </a><br>
&nbsp; &nbsp; &nbsp; <a href="#maybe-_bold-end_"> Maybe <b>bold end</b> </a><br>
&nbsp; &nbsp; &nbsp; <a href="#maybe-emphasize-end"> Maybe <em>emphasize end</em> </a><br>
&nbsp; &nbsp; &nbsp; <a href="#maybe-verbatim-end"> Maybe <code>verbatim end</code> </a><br>
&nbsp; &nbsp; &nbsp; <a href="#the-middle-has-<b>bold</b>-word"> The middle has <b>bold</b> word </a><br>
&nbsp; &nbsp; &nbsp; <a href="#the-middle-has-emphasize-word"> The middle has <em>emphasize</em> word </a><br>
&nbsp; &nbsp; &nbsp; <a href="#the-middle-has-verbatim-word"> The middle has <code>verbatim</code> word </a><br>
&nbsp; &nbsp; &nbsp; <a href="#bibliography-test"> Bibliography test </a><br>
&nbsp; &nbsp; &nbsp; <a href="#Example"> Example 1: Examples can be typeset as exercises </a><br>
&nbsp; &nbsp; &nbsp; <a href="#user-defined-environments"> User-defined environments </a><br>
&nbsp; &nbsp; &nbsp; <a href="#ex:test:1p1"> Example 1: A test function </a><br>
&nbsp; &nbsp; &nbsp; <a href="#ex:math:1p1"> Example 2: Addition </a><br>
&nbsp; &nbsp; &nbsp; <a href="#subsubsec:ex"> URLs </a><br>
<a href="#latex-mathematics"> LaTeX Mathematics </a><br>
<a href="#exercises"> Exercises </a><br>
&nbsp; &nbsp; &nbsp; <a href="#demo:ex:1"> Problem 2: Flip a Coin </a><br>
&nbsp; &nbsp; &nbsp; <a href="#not-an-exercise"> Not an exercise </a><br>
&nbsp; &nbsp; &nbsp; <a href="#my:exer1"> Exercise 3: Test of plain text exercise </a><br>
&nbsp; &nbsp; &nbsp; <a href="#demo:ex:2"> Project 4: Compute a Probability </a><br>
&nbsp; &nbsp; &nbsp; <a href="#proj:circle1"> Project 5: Explore Distributions of Random Circles </a><br>
&nbsp; &nbsp; &nbsp; <a href="#exer:dist"> Exercise 6: Determine some Distance </a><br>
&nbsp; &nbsp; &nbsp; <a href="#some-exercise-without-the-exercise-prefix"> Some exercise without the "Exercise:" prefix </a><br>
&nbsp; &nbsp; &nbsp; <a href="#sec:this:exer:de"> Exercise 8: Solution of differential equation </a><br>
&nbsp; &nbsp; &nbsp; <a href="#example-9-just-an-example"> Example 9: Just an example </a><br>
<a href="#here-goes-another-section"> Here goes another section </a><br>
<a href="#more-exercises"> More Exercises </a><br>
&nbsp; &nbsp; &nbsp; <a href="#exer:some:formula"> Exercise 10: Make references to projects and problems </a><br>
&nbsp; &nbsp; &nbsp; <a href="#exer:you"> Project 11: References in a headings do not work well in html </a><br>
<a href="#references"> References </a><br>
<a href="#app1"> Appendix: Just for testing; part I </a><br>
&nbsp; &nbsp; &nbsp; <a href="#a-subsection-within-an-appendix"> A subsection within an appendix </a><br>
<a href="#app2"> Appendix: Just for testing; part II </a><br>
&nbsp; &nbsp; &nbsp; <a href="#appendix-testing-identical-titles"> Appendix: Testing identical titles </a><br>
&nbsp; &nbsp; &nbsp; <a href="#test:title:id1"> Appendix: Testing identical titles </a><br>
&nbsp; &nbsp; &nbsp; <a href="#test:title:id2"> Appendix: Testing identical titles </a><br>
&nbsp; &nbsp; &nbsp; <a href="#appendix-testing-identical-titles"> Appendix: Testing identical titles </a><br>
&nbsp; &nbsp; &nbsp; <a href="#appendix-testing-inline-comments"> Appendix: Testing inline comments </a><br>
&nbsp; &nbsp; &nbsp; <a href="#appendix-testing-headings-ending-with-verbatim-inline"> Appendix: Testing headings ending with <code>verbatim inline</code> </a><br>
</p>
<p>
<!-- !split -->

<p>
The format of this document is
plain, homemade HTML (from DocOnce).

<p>
<b>Abstract.</b> This is a document with many test constructions for doconce syntax.
It was used heavily for the development and kept for testing
numerous constructions, also special and less common cases.

<p>
And exactly for test purposes we have an extra line here, which
is part of the abstract.

<p>
<!-- Cannot demonstrate chapter headings since abstract and chapter -->
<!-- are mutually exclusive in LaTeX -->

<h1 id="sec1">Section 1</h1>

<p>
Here is a nested list:

<ul>
  <li> item1</li>
  <li> item2</li>
  <li> item3 which continues
    on the next line to test that feature</li>
  <li> and a sublist</li>

<ul>
    <li> with indented subitem1</li>
    <li> and a subitem2</li>
</ul>

  <li> and perhaps an ordered sublist

<ol type="a"></li>
   <li> first item</li>
   <li> second item,
      continuing on a new line</li>
</ol>

</ul>

<b>Here is a list with paragraph heading.</b>

<ul>
  <li> item1</li>
  <li> item2</li>
</ul>

<h3 id="here-is-a-list-with-subsubsection-heading">Here is a list with subsubsection heading </h3>

<ul>
  <li> item1</li>
  <li> item2</li>
</ul>

<blockquote>
    Here are two lines that make up
    a block quote for testing <em>emphasized words</em> and <b>boldface words</b>,
    also with hypens:
    <em>pre</em>-fix, post-<em>fix</em>, <b>pre</b>-fix, post-<b>fix</b>.
</blockquote>


<p>
Here are two references. Equation&nbsp;\eqref{my:eq1} is fine. Eq.&nbsp;\eqref{my:eq1} too.
Even Equation \eqref{my:eq1} without the tilde.
This equation appears in another part if this document is split.

<p>
Let us add a paragraph to
test that HTML,
with WordPress
(<code>--wordpress</code> option)
can handle linebreaks
<em>correctly</em>,
even when lines begin with
<b>bold words</b> and
<code>verbatim words</code> in
<font color="red">red color</font>, and
<a href="https://google.com" target="_self">links</a> as well as math:
\( 1+1=2 \).

<p>
Test also that <em>emphasize</em>
at the end of line, and <b>bold</b>
works, as well as <font color="blue">color</font>
and <a href="https://google.com" target="_self">links2</a>
and <code>verbatim</code>
as well.

<h2 id="subsec1">Subsection 1</h2>

<p>
<!-- Refer to section/appendix etc. at the beginning of the line -->
<!-- and other special fix situations for HTML. -->

<p>
More text, with a reference back to
the section <a href="#sec1">Section 1</a> and <a href="#subsec1">Subsection 1</a>, and further to the
the sections <a href="#subsec1">Subsection 1</a> and <a href="#subsubsec:ex">URLs</a>, which
encourages you to do the tasks in <a href="#demo:ex:1">Problem 2: Flip a Coin</a> and <a href="#exer:some:formula">Exercise 10: Make references to projects and problems</a>.
 <a href="#app1">Appendix: Just for testing; part I</a> and <a href="#app2">Appendix: Just for testing; part II</a> are also nice elements.

<h3 id="test-section-reference-at-beginning-of-line-and-after-a-sentence">Test Section reference at beginning of line and after a sentence </h3>

<p>
The section <a href="#subsec1">Subsection 1</a> is fine.
The section <a href="#subsubsec:ex">URLs</a> too.

<p>
<!-- sphinx code-blocks: pycod=python cod=fortran cppcod=c++ sys=console -->

<h3 id="computer-code">Computer code </h3>

<p>
Let's do some copying from files too. First from subroutine up to the very end,

<p>

<!-- code=fortran (!bc fcod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>      <span style="color: #008000; font-weight: bold">subroutine </span>test()
      <span style="color: #B00040">integer </span>i
      <span style="color: #B00040">real</span><span style="color: #666666">*8</span> r
      r <span style="color: #666666">=</span> <span style="color: #666666">0</span>
      <span style="color: #008000; font-weight: bold">do </span>i <span style="color: #666666">=</span> <span style="color: #666666">1</span>, i
         r <span style="color: #666666">=</span> r <span style="color: #666666">+</span> i
      <span style="color: #008000; font-weight: bold">end do</span>
<span style="color: #008000; font-weight: bold">      return</span>
C     END1

      <span style="color: #008000; font-weight: bold">program </span>testme
      <span style="color: #008000; font-weight: bold">call </span>test()
      <span style="color: #008000; font-weight: bold">return</span>
</pre></div>
<p>
and then just the subroutine,
<p>

<!-- code=fortran (!bc fcod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>      <span style="color: #008000; font-weight: bold">subroutine </span>test()
      <span style="color: #B00040">integer </span>i
      <span style="color: #B00040">real</span><span style="color: #666666">*8</span> r
      r <span style="color: #666666">=</span> <span style="color: #666666">0</span>
      <span style="color: #008000; font-weight: bold">do </span>i <span style="color: #666666">=</span> <span style="color: #666666">1</span>, i
         r <span style="color: #666666">=</span> r <span style="color: #666666">+</span> i
      <span style="color: #008000; font-weight: bold">end do</span>
<span style="color: #008000; font-weight: bold">      return</span>
</pre></div>
<p>
and finally the complete file with a plain text verbatim environment
(<code>envir=ccq</code>):
<p>

<!-- code=text (!bc ccq) typeset with pygments style "default" -->
<blockquote>
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>b&#39;C     a comment\n\n      subroutine test()\n      integer i\n      real*8 r\n      r = 0\n      do i = 1, i\n         r = r + i\n      end do\n      return\nC     END1\n\n      program testme\n      call test()\n      return&#39;
</pre></div>
</blockquote><p>
Testing other code environments. First Python:

<p>

<!-- code=text typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>!bc pycod
def f(x):
    return x+1
!ec
</pre></div>
<p>
which gets rendered as

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">f</span>(x):
    <span style="color: #008000; font-weight: bold">return</span> x<span style="color: #666666">+1</span>
</pre></div>
<p>
Test paragraph and subsubsection headings before
before code.

<p>
<b>Paragraph heading before code.</b>

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">import</span> <span style="color: #0000FF; font-weight: bold">sys</span>
sys<span style="color: #666666">.</span>path<span style="color: #666666">.</span>insert(<span style="color: #666666">0</span>, os<span style="color: #666666">.</span>pardir)
</pre></div>

<h3 id="subsubsection-heading-before-code">Subsubsection heading before code </h3>

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">h</span>(z):
    <span style="color: #008000; font-weight: bold">return</span> z<span style="color: #666666">+1</span>
</pre></div>
<p>
Now a complete program to be shown via Python Online Tutorial:

<p>

<iframe width="950" height="500" frameborder="0"
        src="https://pythontutor.com/iframe-embed.html#code=class+Line%3A%0A++++def+__init__%28self%2C+a%2C+b%29%3A%0A++++++++self.a%2C+self.b+%3D+a%2C+b%0A%0A++++def+__call__%28self%2C+x%29%3A%0A++++++++a%2C+b+%3D+self.a%2C+self.b%0A++++++++return+a%2Ax+%2B+b%0A%0Aline+%3D+Line%282%2C+1%29%0Ay+%3D+line%28x%3D3%29%0Aprint%28y%29&py=2&curInstr=0&cumulative=false">
</iframe>
<p>
Some more Python code (actually specified as a sage cell, but
such cells are not supported by this format).

<p>


<div class="compute"><script type="text/x-sage">
a = 2
b = 3
print('a+b:', a + b)

# In a sage cell we can also plot
from matplotlib.pyplot import *
from numpy import *
x = linspace(0, 4*pi, 101)
y = exp(-0.1*x)*cos(x)
plot(x, y)
xlabel('x'); ylabel('y')
show()

</script></div>
<p>
Then Cython (with -h option so it is hidden in html/sphinx):

<p>

<!-- code=cython (!bc cycod-h) typeset with pygments style "default" -->

<script type="text/javascript">
function show_hide_code9(){
  $("#code9").toggle();
}
</script>
<button type="button" onclick="show_hide_code9()">Show/hide code</button>
<div id="code9" style="display:none">
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">cpdef</span> <span style="color: #0000FF">f</span>(double x):
    <span style="color: #008000; font-weight: bold">return</span> x <span style="color: #666666">+</span> <span style="color: #666666">1</span>
</pre></div>

</div>
<p>
Standard Python shell sessions:

<p>

<!-- code=python (!bc pyshell) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #666666">&gt;&gt;&gt;</span> <span style="color: #008000; font-weight: bold">from</span> <span style="color: #0000FF; font-weight: bold">numpy</span> <span style="color: #008000; font-weight: bold">import</span> linspace, sin
<span style="color: #666666">&gt;&gt;&gt;</span> <span style="color: #408080; font-style: italic"># Some comment</span>
<span style="color: #666666">&gt;&gt;&gt;</span> x <span style="color: #666666">=</span> linspace(<span style="color: #666666">0</span>, <span style="color: #666666">2</span>, <span style="color: #666666">11</span>)
<span style="color: #666666">&gt;&gt;&gt;</span> y <span style="color: #666666">=</span> sin(x)
<span style="color: #666666">&gt;&gt;&gt;</span> y[<span style="color: #666666">0</span>]
<span style="color: #666666">0</span>
<span style="color: #666666">&gt;&gt;&gt;</span> <span style="color: #008000; font-weight: bold">import</span> <span style="color: #0000FF; font-weight: bold">matplotlib.pyplot</span> <span style="color: #008000; font-weight: bold">as</span> <span style="color: #0000FF; font-weight: bold">plt</span>
<span style="color: #666666">&gt;&gt;&gt;</span> plt<span style="color: #666666">.</span>plot(x, y)
</pre></div>
<p>
Similar IPython sessions:

<p>

<!-- code=ipy (!bc ipy) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #000080; font-weight: bold">In [1]: </span><span style="color: #008000; font-weight: bold">from</span> <span style="color: #0000FF; font-weight: bold">numpy</span> <span style="color: #008000; font-weight: bold">import</span> linspace, sin
<span style="color: #000080; font-weight: bold">In [2]: </span><span style="color: #408080; font-style: italic"># Some comment</span>
<span style="color: #000080; font-weight: bold">In [3]: </span>x <span style="color: #666666">=</span> linspace(<span style="color: #666666">0</span>, <span style="color: #666666">2</span>, <span style="color: #666666">11</span>)
<span style="color: #000080; font-weight: bold">In [4]: </span>y <span style="color: #666666">=</span> sin(x)
<span style="color: #000080; font-weight: bold">In [5]: </span>y[<span style="color: #666666">0</span>]
<span style="color: #000080; font-weight: bold">Out[5]: </span><span style="color: #888888">0</span>
<span style="color: #000080; font-weight: bold">In [6]: </span><span style="color: #008000; font-weight: bold">import</span> <span style="color: #0000FF; font-weight: bold">matplotlib.pyplot</span> <span style="color: #008000; font-weight: bold">as</span> <span style="color: #0000FF; font-weight: bold">plt</span>
<span style="color: #000080; font-weight: bold">In [7]: </span>plt<span style="color: #666666">.</span>plot(x, y)
<span style="color: #000080; font-weight: bold">In [8]: </span>a<span style="color: #666666">=</span><span style="color: #BA2121">&#39;multiple-</span><span style="color: #BB6622; font-weight: bold">\n</span><span style="color: #BA2121">line</span><span style="color: #BB6622; font-weight: bold">\n</span><span style="color: #BA2121">output&#39;</span>
<span style="color: #000080; font-weight: bold">In [9]: </span>a
<span style="color: #000080; font-weight: bold">Out[9]: </span><span style="color: #888888">&#39;multiple-\nline\noutput&#39;</span>
<span style="color: #000080; font-weight: bold">In [10]: </span><span style="color: #008000">print</span>(a)
<span style="color: #888888">multiple-</span>
<span style="color: #888888">line</span>
<span style="color: #888888">output</span>
</pre></div>
<p>
Here is the interactive session again, but with <code>pyshell-t</code>.

<p>

<!-- code=python (!bc pyshell) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #666666">&gt;&gt;&gt;</span> <span style="color: #008000; font-weight: bold">from</span> <span style="color: #0000FF; font-weight: bold">numpy</span> <span style="color: #008000; font-weight: bold">import</span> linspace, sin
<span style="color: #666666">&gt;&gt;&gt;</span> <span style="color: #408080; font-style: italic"># Some comment</span>
<span style="color: #666666">&gt;&gt;&gt;</span> x <span style="color: #666666">=</span> linspace(<span style="color: #666666">0</span>, <span style="color: #666666">2</span>, <span style="color: #666666">11</span>)
<span style="color: #666666">&gt;&gt;&gt;</span> y <span style="color: #666666">=</span> sin(x)
<span style="color: #666666">&gt;&gt;&gt;</span> y[<span style="color: #666666">0</span>]
<span style="color: #666666">0</span>
<span style="color: #666666">&gt;&gt;&gt;</span> <span style="color: #008000; font-weight: bold">import</span> <span style="color: #0000FF; font-weight: bold">matplotlib.pyplot</span> <span style="color: #008000; font-weight: bold">as</span> <span style="color: #0000FF; font-weight: bold">plt</span>
<span style="color: #666666">&gt;&gt;&gt;</span> plt<span style="color: #666666">.</span>plot(x, y)
</pre></div>
<p>
<!-- This one tests a + sign before a code environment -->
C++:
<p>

<!-- code=c++ (!bc cpppro) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #BC7A00">#include</span> <span style="color: #408080; font-style: italic">&lt;iostream&gt;</span><span style="color: #BC7A00"></span>

<span style="color: #B00040">int</span> <span style="color: #0000FF">main</span>()
{
   std<span style="color: #666666">::</span>cout <span style="color: #666666">&lt;&lt;</span> <span style="color: #BA2121">&quot;Sample output&quot;</span> <span style="color: #666666">&lt;&lt;</span> std<span style="color: #666666">::</span>endl;
   <span style="color: #008000; font-weight: bold">return</span> <span style="color: #666666">0</span>
}
</pre></div>
<p>
<!-- The next should get correctly typset in sphinx (cod is fcod) -->
<!-- It also tests emoji before code -->
And a little bit of Fortran: <img src="https://raw.githubusercontent.com/hplgit/doconce/master/bundled/emoji/png/dizzy_face.png" width="22px" height="22px" align="center">

<p>

<!-- code=text typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>!bc cod
      subroutine midpt(x, length, a, b)
      real*8 a, b, x
      x = (a + b)/2
      length = b - a
      return
      end
!ec
</pre></div>
<p>
which then is typeset as

<p>

<!-- code=text (!bc cod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>      subroutine midpt(x, length, a, b)
      real*8 a, b, x
      x = (a + b)/2
      length = b - a
      return
      end
</pre></div>
<p>
HTML:

<p>

<!-- code=html (!bc htmlcod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>&lt;<span style="color: #008000; font-weight: bold">table</span>&gt;
&lt;<span style="color: #008000; font-weight: bold">tr</span>&gt;&lt;<span style="color: #008000; font-weight: bold">td</span>&gt;Column 1&lt;/<span style="color: #008000; font-weight: bold">td</span>&gt;&lt;<span style="color: #008000; font-weight: bold">td</span>&gt;Column 2&lt;/<span style="color: #008000; font-weight: bold">td</span>&gt;&lt;/<span style="color: #008000; font-weight: bold">tr</span>&gt;
&lt;<span style="color: #008000; font-weight: bold">tr</span>&gt;&lt;<span style="color: #008000; font-weight: bold">td</span>&gt;0.67526 &lt;/<span style="color: #008000; font-weight: bold">td</span>&gt;&lt;<span style="color: #008000; font-weight: bold">td</span>&gt;0.92871 &lt;/<span style="color: #008000; font-weight: bold">td</span>&gt;&lt;/<span style="color: #008000; font-weight: bold">tr</span>&gt;
<span style="color: #408080; font-style: italic">&lt;!-- comment --&gt;</span>
&lt;/<span style="color: #008000; font-weight: bold">table</span>&gt;
</pre></div>
<p>
But inline HTML code is also important, like text that starts with
<code>&lt;a href=&quot;</code> (which can destroy the following text if not properly
quoted).

<p>
Matlab with comments requires special typesetting:

<p>

<!-- code=matlab (!bc mcod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #408080; font-style: italic">% Comment on the beginning of the line can be escaped by %%</span>
<span style="color: #008000; font-weight: bold">if</span> a <span style="color: #666666">&gt;</span> b
  <span style="color: #408080; font-style: italic">% Indented comment needs this trick</span>
  c = a <span style="color: #666666">+</span> b
<span style="color: #008000; font-weight: bold">end</span>
</pre></div>
<p>
And here is a system call:

<p>

<!-- code=text (!bc sys) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>Terminal&gt; mkdir test
Terminal&gt; cd test
Terminal&gt; myprog -f
output1
output2
</pre></div>
<p>
Any valid pygments lexer/language name can appear to, e.g.,

<p>

<!-- code=text typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>!bc restructuredtext
=======
Heading
=======

Some text.
!ec
</pre></div>
<p>
results in

<p>

<!-- code=restructuredtext (!bc restructuredtext) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #000080; font-weight: bold">=======</span>
<span style="color: #000080; font-weight: bold">Heading</span>
<span style="color: #000080; font-weight: bold">=======</span>

Some text.
</pre></div>
<p>
<!-- Here goes hidden code. -->
<!-- Python can be treated by some formats, Fortran is always out. -->

<p>
Finally, <code>!bc do</code> supports highlighting of DocOnce source:

<p>

<!-- code=doconce (!bc do) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #000080; font-weight: bold">======= DocOnce test file =======</span>

<span style="color: #000080; font-weight: bold">===== Computer code =====</span>

Inline verbatim code, as in `import numpy as np`, is allowed, as well as
code blocks:

!bc pycod
from math import sin

def f(x):
    &quot;&quot;&quot;Example on a function.&quot;&quot;&quot;
    return sin(x) + 1

print(f(0))
!ec


<span style="color: #000080; font-weight: bold">===== Mathematics =====</span>

Formulas can be inline, as in $\nabla\cdot\boldsymbol{u} = 0$, or typeset
as equations:

!bt
<span style="color: #008000">\begin{align*}</span>
\nabla\cdot\boldsymbol{u} &amp;= 0,\\ 
\boldsymbol{u} &amp;= \nabla\phi .
<span style="color: #008000">\end{align*}</span>
!et

<span style="color: #000080; font-weight: bold">=== Subsubsection heading ===</span>

DocOnce files can have chapters, sections, subsections, and subsubsections.

<span style="color: #800080; font-weight: bold">__Paragraph heading.__</span> Paragraphs may have headings.
</pre></div>
<p>
It is time to test <code>verbatim inline font</code> especially with <code>a newline
inside the text</code> and an exclamation mark at the end: <code>BEGIN</code>! For
spellcheck, test <code>a verbatim expression</code> in <code>another</code> in a <code>third</code>.
Also test exclamation mark as in <code>!bc</code> and <code>!ec</code> as well as <code>a != b</code>.
Also test backslashes and braces like <code>\begin</code>, <code>\begin{enumerate}</code>,
<code>\end{this}\end{that}</code>, and <code>{something \inside braces}</code>.

<p>
Here is some <font color="red">red color</font> and an attempt to write <font color="green">with
green color containing a linebreak<br />
code.</font> Some formats will only display <br />
this correctly when <code>html</code> <br />
is the output format.
But here some more running text is added which is not part of
the previous blocks with line breaks.

<h3 id="running-os-commands">Running OS commands </h3>

<p>

<!-- code=text (!bc sys) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>Terminal&gt; python -c &#39;print(&quot;Testing\noutput\nfrom\nPython.&quot;)&#39;
Testing
output
from
Python.
</pre></div>

<h3 id="footnotes">Footnotes </h3>

<p>
Here is a test of footnotes [<a id="link_footnote_1" href="#def_footnote_1">1</a>], which are handy in text.
They are used in different flavors, now in

<ul>
 <li> list items (note below that footnotes work after math, verbatim, and URLs - bin fact old and emphasize too!)</li>
 <li> even with math \( \nabla^2u \) [<a id="link_footnote_2" href="#def_footnote_2">2</a>]</li>
 <li> and code <code>h[i] += 1</code> [<a id="link_footnote_3" href="#def_footnote_3">3</a>]
   (<em>must</em> have space between inline code and footnote!)</li>
 <li> and <a href="https://google.com" target="_self">links</a> [<a id="link_footnote_4" href="#def_footnote_4">4</a>]</li>
</ul>

which gives flexibility in writing.
This is the third [<a id="link_footnote_5" href="#def_footnote_5">5</a>] example.

<p id="def_footnote_1"><a href="#link_footnote_1"><b>1:</b></a> Typesetting of the footnote depends on the format.
Plain text does nothing, LaTeX removes the
definition and inserts the footnote as part of the LaTeX text.
reStructuredText and Sphinx employ a similar type of typesetting
as Extended Markdown and DocOnce, and in HTML we keep the same
syntax, just displayed properly in HTML.</p>

<p id="def_footnote_2"><a href="#link_footnote_2"><b>2:</b></a> Math footnotes can be dangerous since it
interferes with an exponent.</p>

<p id="def_footnote_3"><a href="#link_footnote_3"><b>3:</b></a> One-line footnote.</p>

<p id="def_footnote_4"><a href="#link_footnote_4"><b>4:</b></a> <a href="google.com" target="_self"><tt>google.com</tt></a> is perhaps the most famous
web site today.</p>

<p>
Here is some more text before a new definition of a footnote that was
used above.

<p>
<div class="alert alert-block alert-notice alert-text-normal">
<b>Non-breaking space character</b>
<p>
This paragraph aims to test <a href="https://en.wikipedia.org/wiki/Non-breaking_space" target="_self">non-breaking space character</a>, and a typical
example where this is needed is in physical units: 7.4&nbsp;km is traveled
in&nbsp;\( 7.4/5.5\approx 1.345 \)&nbsp;s.  Also check that a&nbsp;<a href="https://google.com" target="_self">link</a>&nbsp;is
not broken across lines (drag the browser window to test this).
(On the other hand, the tilde is used in
computer code, e.g., as in <code>[~x for x in y]</code> or in <code>y=~x</code>, and should
of course remain a tilde in those contexts.)
</div>


<h2 id="subsec:ex">Subsection 2: Testing figures</h2>

<p>
Test of figures. In particular we refer to Figure <a href="#fig:impact">1</a> in which
there is a flow.

<p>
<center> <!-- figure label: --> <div id="fig:impact"></div> <!-- FIGURE -->
<hr class="figure">
<center><p class="caption">Figure 1:  Visualization <b>of</b> a <em>wave</em>.  <!-- caption label: fig:impact --> </p></center>
<p><img src="../doc/src/manual/fig/wave1D.png" align="bottom" width=200></p>
</center>

<p>
Figures without captions are allowed and will be inlined.

<p>
<br /><br /><center><p><img src="../doc/src/manual/fig/wave1D.png" align="bottom" width=200></p></center><br /><br />

<p>
<!-- Test multi-line caption in figure with sidecap=True -->

<p>
Here is figure <a href="#myfig">2</a> with a long (illegal) multi-line caption
containing inline verbatim text:

<p>
<center> <!-- figure label: --> <div id="myfig"></div> <!-- FIGURE -->
<hr class="figure">
<table><tr>
<td><img src="../doc/src/manual/fig/wave1D.png" align="bottom" width=500></td>
<td><p class="caption">Figure 2:  A long caption spanning several lines and containing verbatim words like <code>my_file_v1</code> and <code>my_file_v2</code> as well as math with subscript as in \( t_{i+1} \).  <!-- caption label: myfig --> </p></td>
</tr></table>
</center>

<p>
<!-- Must be a blank line after MOVIE or FIGURE to detect this problem -->

<p>
Test URL as figure name:

<p>
<br /><br /><center><p><img src="https://raw.github.com/doconce/doconce/master/doc/src/blog/f_plot.png" align="bottom" width=500></p></center><br /><br />

<p>
Test SVG figure:

<p>
<br /><br /><center><p><img src="https://openclipart.org/people/jpneok/junebug.svg" align="bottom" width=200></p></center><br /><br />

<p>
<!-- Test wikimedia type of files that otherwise reside in subdirs -->

<p>
HTML output may feature Bokeh plots:

<p>
<br /><br /><center><p>
<!-- Bokeh plot -->
<script type="text/javascript">
            Bokeh.$(function() {
                var modelid = "dc6ef912-b325-4c34-996a-cdeb5aa4d7c1";
                var modeltype = "PlotContext";
                var elementid = "ffba6087-a45a-46eb-9368-11527f1f0a34";
                Bokeh.logger.info("Realizing plot:")
                Bokeh.logger.info(" - modeltype: PlotContext");
                Bokeh.logger.info(" - modelid: dc6ef912-b325-4c34-996a-cdeb5aa4d7c1");
                Bokeh.logger.info(" - elementid: ffba6087-a45a-46eb-9368-11527f1f0a34");
                var all_models = [{"attributes": {"line_color": {"value": "#1f77b4"}, "line_alpha": {"value": 1.0}, "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "y": {"field": "y"}, "x": {"field": "x"}, "id": "f55b6039-f6a1-48ce-be42-ce4e37ec18de"}, "type": "Line", "id": "f55b6039-f6a1-48ce-be42-ce4e37ec18de"}, {"attributes": {"tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "mantissas": [2, 5, 10], "id": "d8f3c08e-df44-47cd-ab00-9391128fc8ba", "num_minor_ticks": 5}, "type": "BasicTicker", "id": "d8f3c08e-df44-47cd-ab00-9391128fc8ba"}, {"attributes": {"column_names": ["x", "y"], "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "selected": {"2d": {"indices": []}, "1d": {"indices": []}, "0d": {"indices": [], "flag": false}}, "callback": null, "data": {"y": [0.0, 1.0, 8.0, 27.0], "x": [0.0, 1.0, 2.0, 3.0]}, "id": "51fd7aaa-934d-4dab-97d6-7be6eea30d89"}, "type": "ColumnDataSource", "id": "51fd7aaa-934d-4dab-97d6-7be6eea30d89"}, {"attributes": {"plot": {"subtype": "Figure", "type": "Plot", "id": "bac26888-fe18-4833-afe3-61e241eed748"}, "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "id": "8a41a3f3-b32f-4813-bc9d-78656dd129b0"}, "type": "ResizeTool", "id": "8a41a3f3-b32f-4813-bc9d-78656dd129b0"}, {"attributes": {"plot": {"subtype": "Figure", "type": "Plot", "id": "bac26888-fe18-4833-afe3-61e241eed748"}, "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "id": "734545fc-60c1-4271-bc10-b2b490266002"}, "type": "HelpTool", "id": "734545fc-60c1-4271-bc10-b2b490266002"}, {"attributes": {"names": [], "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "id": "294cc5ee-f95b-4023-8b38-eb845e408397", "renderers": []}, "type": "DataRange1d", "id": "294cc5ee-f95b-4023-8b38-eb845e408397"}, {"attributes": {"plot": {"subtype": "Figure", "type": "Plot", "id": "bac26888-fe18-4833-afe3-61e241eed748"}, "dimensions": ["width", "height"], "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "id": "26f46aa8-dc6f-4265-84dd-4525866c89d0"}, "type": "PanTool", "id": "26f46aa8-dc6f-4265-84dd-4525866c89d0"}, {"attributes": {"plot": {"subtype": "Figure", "type": "Plot", "id": "bac26888-fe18-4833-afe3-61e241eed748"}, "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "formatter": {"type": "BasicTickFormatter", "id": "a1aa95e9-9b48-4736-8854-fd7faf6b25ed"}, "ticker": {"type": "BasicTicker", "id": "71a73f31-ff56-477b-83da-62dfb4cb7d93"}, "id": "6980f350-9b3e-40f2-9ebb-d8a349a0207e"}, "type": "LinearAxis", "id": "6980f350-9b3e-40f2-9ebb-d8a349a0207e"}, {"attributes": {"plot": {"subtype": "Figure", "type": "Plot", "id": "bac26888-fe18-4833-afe3-61e241eed748"}, "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "id": "2de49bc5-9815-4275-a6de-e81ef1840cbe"}, "type": "ResetTool", "id": "2de49bc5-9815-4275-a6de-e81ef1840cbe"}, {"attributes": {"tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "mantissas": [2, 5, 10], "id": "71a73f31-ff56-477b-83da-62dfb4cb7d93", "num_minor_ticks": 5}, "type": "BasicTicker", "id": "71a73f31-ff56-477b-83da-62dfb4cb7d93"}, {"attributes": {"plot": {"subtype": "Figure", "type": "Plot", "id": "bac26888-fe18-4833-afe3-61e241eed748"}, "dimensions": ["width", "height"], "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "id": "d242820f-6005-4e2d-aaca-d2a19392726a"}, "type": "BoxZoomTool", "id": "d242820f-6005-4e2d-aaca-d2a19392726a"}, {"attributes": {"doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "id": "a1aa95e9-9b48-4736-8854-fd7faf6b25ed", "tags": []}, "type": "BasicTickFormatter", "id": "a1aa95e9-9b48-4736-8854-fd7faf6b25ed"}, {"subtype": "Figure", "type": "Plot", "id": "bac26888-fe18-4833-afe3-61e241eed748", "attributes": {"x_range": {"type": "DataRange1d", "id": "294cc5ee-f95b-4023-8b38-eb845e408397"}, "right": [], "tags": [], "tools": [{"type": "PanTool", "id": "26f46aa8-dc6f-4265-84dd-4525866c89d0"}, {"type": "WheelZoomTool", "id": "747f14a5-9f75-417c-8168-fb0a0ae3aa11"}, {"type": "BoxZoomTool", "id": "d242820f-6005-4e2d-aaca-d2a19392726a"}, {"type": "PreviewSaveTool", "id": "0c4a0cdc-08d4-4019-b03a-c03954d8f00a"}, {"type": "ResizeTool", "id": "8a41a3f3-b32f-4813-bc9d-78656dd129b0"}, {"type": "ResetTool", "id": "2de49bc5-9815-4275-a6de-e81ef1840cbe"}, {"type": "HelpTool", "id": "734545fc-60c1-4271-bc10-b2b490266002"}], "title": "Bokeh test", "extra_y_ranges": {}, "renderers": [{"type": "LinearAxis", "id": "6980f350-9b3e-40f2-9ebb-d8a349a0207e"}, {"type": "Grid", "id": "4765692c-4f39-462b-91c6-28b2f2981e00"}, {"type": "LinearAxis", "id": "ade0b05a-7b91-42dd-98de-74fb64acf6f7"}, {"type": "Grid", "id": "b9b421c8-77f3-4e7e-826b-ac6bf659b06a"}, {"type": "GlyphRenderer", "id": "2880ba24-eb39-4b26-b4fc-475578d6fd4c"}], "extra_x_ranges": {}, "below": [{"type": "LinearAxis", "id": "6980f350-9b3e-40f2-9ebb-d8a349a0207e"}], "tool_events": {"type": "ToolEvents", "id": "1695660e-4ea6-4d6d-9921-0d71ad942082"}, "above": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "y_range": {"type": "DataRange1d", "id": "c973a007-1e1b-45a1-a7ba-d05f16dfaad0"}, "id": "bac26888-fe18-4833-afe3-61e241eed748", "left": [{"type": "LinearAxis", "id": "ade0b05a-7b91-42dd-98de-74fb64acf6f7"}]}}, {"attributes": {"names": [], "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "id": "c973a007-1e1b-45a1-a7ba-d05f16dfaad0", "renderers": []}, "type": "DataRange1d", "id": "c973a007-1e1b-45a1-a7ba-d05f16dfaad0"}, {"attributes": {"tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "id": "dc6ef912-b325-4c34-996a-cdeb5aa4d7c1", "children": [{"subtype": "Figure", "type": "Plot", "id": "bac26888-fe18-4833-afe3-61e241eed748"}]}, "type": "PlotContext", "id": "dc6ef912-b325-4c34-996a-cdeb5aa4d7c1"}, {"attributes": {"line_color": {"value": "#1f77b4"}, "line_alpha": {"value": 0.1}, "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "y": {"field": "y"}, "x": {"field": "x"}, "id": "af17e0b1-cd09-4529-b97b-aefe6bff3ee2"}, "type": "Line", "id": "af17e0b1-cd09-4529-b97b-aefe6bff3ee2"}, {"attributes": {"plot": {"subtype": "Figure", "type": "Plot", "id": "bac26888-fe18-4833-afe3-61e241eed748"}, "dimensions": ["width", "height"], "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "id": "747f14a5-9f75-417c-8168-fb0a0ae3aa11"}, "type": "WheelZoomTool", "id": "747f14a5-9f75-417c-8168-fb0a0ae3aa11"}, {"attributes": {"plot": {"subtype": "Figure", "type": "Plot", "id": "bac26888-fe18-4833-afe3-61e241eed748"}, "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "formatter": {"type": "BasicTickFormatter", "id": "e6be9566-7576-4bac-a09f-bf95a818d7f8"}, "ticker": {"type": "BasicTicker", "id": "d8f3c08e-df44-47cd-ab00-9391128fc8ba"}, "id": "ade0b05a-7b91-42dd-98de-74fb64acf6f7"}, "type": "LinearAxis", "id": "ade0b05a-7b91-42dd-98de-74fb64acf6f7"}, {"attributes": {"plot": {"subtype": "Figure", "type": "Plot", "id": "bac26888-fe18-4833-afe3-61e241eed748"}, "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "dimension": 1, "ticker": {"type": "BasicTicker", "id": "d8f3c08e-df44-47cd-ab00-9391128fc8ba"}, "id": "b9b421c8-77f3-4e7e-826b-ac6bf659b06a"}, "type": "Grid", "id": "b9b421c8-77f3-4e7e-826b-ac6bf659b06a"}, {"attributes": {"nonselection_glyph": {"type": "Line", "id": "af17e0b1-cd09-4529-b97b-aefe6bff3ee2"}, "data_source": {"type": "ColumnDataSource", "id": "51fd7aaa-934d-4dab-97d6-7be6eea30d89"}, "name": null, "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "selection_glyph": null, "id": "2880ba24-eb39-4b26-b4fc-475578d6fd4c", "glyph": {"type": "Line", "id": "f55b6039-f6a1-48ce-be42-ce4e37ec18de"}}, "type": "GlyphRenderer", "id": "2880ba24-eb39-4b26-b4fc-475578d6fd4c"}, {"attributes": {"plot": {"subtype": "Figure", "type": "Plot", "id": "bac26888-fe18-4833-afe3-61e241eed748"}, "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "dimension": 0, "ticker": {"type": "BasicTicker", "id": "71a73f31-ff56-477b-83da-62dfb4cb7d93"}, "id": "4765692c-4f39-462b-91c6-28b2f2981e00"}, "type": "Grid", "id": "4765692c-4f39-462b-91c6-28b2f2981e00"}, {"attributes": {"plot": {"subtype": "Figure", "type": "Plot", "id": "bac26888-fe18-4833-afe3-61e241eed748"}, "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "id": "0c4a0cdc-08d4-4019-b03a-c03954d8f00a"}, "type": "PreviewSaveTool", "id": "0c4a0cdc-08d4-4019-b03a-c03954d8f00a"}, {"attributes": {"geometries": [], "tags": [], "doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "id": "1695660e-4ea6-4d6d-9921-0d71ad942082"}, "type": "ToolEvents", "id": "1695660e-4ea6-4d6d-9921-0d71ad942082"}, {"attributes": {"doc": "c82fd997-ea77-4590-926c-2e524ba8395d", "id": "e6be9566-7576-4bac-a09f-bf95a818d7f8", "tags": []}, "type": "BasicTickFormatter", "id": "e6be9566-7576-4bac-a09f-bf95a818d7f8"}];
                Bokeh.load_models(all_models);
                var model = Bokeh.Collections(modeltype).get(modelid);
                var view = new model.default_view({model: model, el: '#ffba6087-a45a-46eb-9368-11527f1f0a34'});
                Bokeh.index[modelid] = view
            });
        </script>
<div class="plotdiv" id="ffba6087-a45a-46eb-9368-11527f1f0a34"></div></p></center><br /><br />

<p>
<b>Remark.</b>
Movies are tested in separate file <code>movies.do.txt</code>.

<p>
<!-- Somewhat challenging heading with latex math, \t, \n, ? and parenthesis -->

<h2 id="decay:sec:theta">The \( \theta \) parameter (not \( \nabla \)?)</h2>

<p>
Functions do not always need to be advanced, here is one
involving \( \theta \):
<p>

<!-- code=text typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>def f(theta):
    return theta**2
</pre></div>
<p>
<b>More on \( \theta \).</b>
Here is more text following headline with math.

<p>
Newcommands must also be tested in this test report:
\( \frac{1}{2} \), \( {1/2} \), \( \pmb{x} \), \( \frac{Du}{dt} \),
both inline and in block:

$$
\begin{align}
\frac{Du}{dt} &= 0\nonumber
\\ 
\frac{1}{2} &= {1/2}
\label{_auto1}\\ 
\frac{1}{2}\pmb{x} &= \pmb{n}
\label{_auto2}
\end{align}
$$

<p>
Or with align with label and numbers:

$$
\begin{align}
\frac{Du}{dt} &= 0
\label{aligneq1}
\\ 
\frac{1}{2} &= {1/2}
\label{_auto3}\\ 
\frac{1}{2}\pmb{x} &= \pmb{n}
\label{aligneq2}
\end{align}
$$

<p>
<!-- Must test more complicated align and matrix compositions -->
<!-- where DocOnce inserts auto-numbered labels etc. -->

<p>
First one numbered (automatically):

$$
\begin{align}
\begin{pmatrix}
G_2 + G_3 & -G_3 & -G_2 & 0 \\ 
-G_3 & G_3 + G_4 & 0 & -G_4 \\ 
-G_2 & 0 & G_1 + G_2 & 0 \\ 
0 & -G_4 & 0 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
 v_1 \\ 
 v_2 \\ 
 v_3 \\ 
 v_4
\end{pmatrix}
+ \cdots  \label{_auto4}
\\ 
\begin{pmatrix}
 C_5 + C_6 & -C_6 & 0 & 0 \\ 
 -C_6 & C_6 & 0 & 0 \\ 
 0 & 0 & 0 & 0 \\ 
 0 & 0 & 0 & 0
\end{pmatrix}
  &= \frac{d}{dt}\begin{pmatrix}
 v_1 \\ 
 v_2 \\ 
 v_3 \\ 
 v_4
\end{pmatrix} +
\begin{pmatrix}
 0 \\ 
 0 \\ 
 0 \\ 
 -i_0
\end{pmatrix}
\nonumber
\label{_auto5}
\end{align}$$

<p>
Second numbered (automatically):

$$
\begin{align}
\begin{pmatrix}
G_1 + G_2\\ 
-G_3 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
 v_1 \\ 
 v_2
\end{pmatrix}
+ \cdots\nonumber
\label{_auto6}
\\ 
\left(\begin{array}{ll}
y & 2\\ 
2 & 1
\end{array}\right)
\left(\begin{array}{ll}
0 \\ x
\end{array}\right)
&= \begin{pmatrix}
A \\ B
\end{pmatrix}
\label{_auto7}
\end{align}$$

<p>
Both numbered, with label by the user:

$$
\begin{align}
\begin{pmatrix}
G_1 + G_2\\ 
-G_3 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
 v_1 \\ 
 v_2
\end{pmatrix}
+ \cdots \label{mymatrix:eq1}
\\ 
\label{mymatrix:eq2}
\left(\begin{array}{ll}
y & 2\\ 
2 & 1
\end{array}\right)
\left(\begin{array}{ll}
0 \\ x
\end{array}\right)
&= \begin{pmatrix}
A \\ B
\end{pmatrix}
\end{align}$$

Now we refer to \eqref{mymatrix:eq1}-\eqref{mymatrix:eq2}.

<h2 id="custom-environments">Custom Environments </h2>

<p>
Here is an attempt to create a theorem environment via Mako
(for counting theorems) and comment lines to help replacing lines in
the <code>.tex</code> by proper begin-end LaTeX environments for theorems.
Should look nice in most formats!

<p>
<!-- begin theorem -->
<div id="theorem:fundamental1"></div>

<p>
<b>Theorem 5.</b>
Let \( a=1 \) and \( b=2 \). Then \( c=3 \).
<!-- end theorem -->

<p>
<!-- begin proof -->
<b>Proof.</b>
Since \( c=a+b \), the result follows from straightforward addition.
\( \Diamond \)
<!-- end proof -->

<p>
As we see, the proof of Theorem 5 is a modest
achievement.

<h2 id="subsec:table">Tables</h2>

<p>
<!-- index with comma could fool sphinx -->

<p>
Let us take this table from the manual:

<p>
<table border="1">
<thead>
<tr><th align="center">time</th> <th align="center">velocity</th> <th align="center">acceleration</th> </tr>
</thead>
<tbody>
<tr><td align="left">   0.0     </td> <td align="right">   1.4186      </td> <td align="right">   -5.01           </td> </tr>
<tr><td align="left">   2.0     </td> <td align="right">   1.376512    </td> <td align="right">   11.919          </td> </tr>
<tr><td align="left">   4.0     </td> <td align="right">   1.1E+1      </td> <td align="right">   14.717624       </td> </tr>
</tbody>
</table>
<p>
The DocOnce source code reads
<p>

<!-- code=text (!bc ccq) typeset with pygments style "default" -->
<blockquote>
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>  |--------------------------------|
  |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>
</blockquote><p>
Here is yet another table to test that we can handle more than
one table:

<p>
<table border="1">
<thead>
<tr><th align="left">time</th> <th align="left">velocity</th> <th align="left">acceleration</th> </tr>
</thead>
<tbody>
<tr><td align="left">   0.0     </td> <td align="left">   1.4186      </td> <td align="left">   -5.01           </td> </tr>
<tr><td align="left">   1.0     </td> <td align="left">   1.376512    </td> <td align="left">   11.919          </td> </tr>
<tr><td align="left">   3.0     </td> <td align="left">   1.1E+1      </td> <td align="left">   14.717624       </td> </tr>
</tbody>
</table>
<p>
And one with math headings (that are expanded and must be treated
accordingly), verbatim heading and entry, and no space around the pipe
symbol:

<p>
<table border="1">
<thead>
<tr><td align="center">\( i \)</td> <td align="center">\( h_i \)</td> <td align="center">\( \bar T_i \)</td> <td align="center"><code>L_i</code></td> </tr>
</thead>
<tbody>
<tr><td align="left">   0          </td> <td align="right">   0            </td> <td align="right">   288               </td> <td align="right">   -0.0065             </td> </tr>
<tr><td align="left">   1          </td> <td align="right">   11,000       </td> <td align="right">   216               </td> <td align="right">   0.0                 </td> </tr>
<tr><td align="left">   2          </td> <td align="right">   20,000       </td> <td align="right">   216               </td> <td align="right">   0.001               </td> </tr>
<tr><td align="left">   3          </td> <td align="right">   32,000       </td> <td align="right">   228               </td> <td align="right">   0.0028              </td> </tr>
<tr><td align="left">   4          </td> <td align="right">   47,000       </td> <td align="right">   270               </td> <td align="right">   0.0                 </td> </tr>
<tr><td align="left">   5          </td> <td align="right">   51,000       </td> <td align="right">   270               </td> <td align="right">   -0.0028             </td> </tr>
<tr><td align="left">   6          </td> <td align="right">   71,000       </td> <td align="right">   214               </td> <td align="right">   <code>NaN</code>    </td> </tr>
</tbody>
</table>
<p>
And add one with verbatim headings (with underscores),
and rows starting with <code>|-</code> because of a negative number,
and <code>|</code> right before and after verbatim word (with no space):

<p>
<table border="1">
<thead>
<tr><th align="center">exact</th> <td align="center"><code>v_1</code></td> <td align="center">\( a_i \) + <code>v_2</code></td> <td align="center"><code>verb_3_</code></td> </tr>
</thead>
<tbody>
<tr><td align="right">   9        </td> <td align="right">   9.62                </td> <td align="right">   5.57                            </td> <td align="right">   8.98                    </td> </tr>
<tr><td align="right">   -20      </td> <td align="right">   -23.39              </td> <td align="right">   -7.65                           </td> <td align="right">   -19.93                  </td> </tr>
<tr><td align="right">   10       </td> <td align="right">   17.74               </td> <td align="right">   -4.50                           </td> <td align="right">   9.96                    </td> </tr>
<tr><td align="right">   0        </td> <td align="right">   -9.19               </td> <td align="right">   4.13                            </td> <td align="right">   -0.26                   </td> </tr>
</tbody>
</table>
<p>
Pipe symbols in verbatim and math text in tables used to pose difficulties,
but not
anymore:

<p>
<table border="1">
<thead>
<tr><td align="center">   \( S \)   </td> <th align="center">        command         </th> </tr>
</thead>
<tbody>
<tr><td align="left">   $ ||a_0|| $      </td> <td align="right">   <code>norm|length</code>    </td> </tr>
<tr><td align="left">   \( x\cap y \)    </td> <td align="right">   <code>x|y</code>            </td> </tr>
</tbody>
</table>
<p>
Here is a table with X alignment:

<p>
<table border="1">
<thead>
<tr><th align="center"> Type</th> <th align="center">                                                                                                                Description                                                                                                                 </th> </tr>
</thead>
<tbody>
<tr><td align="center">   X        </td> <td align="left">   Alignment character that is used for specifying a potentially very long text in a column in a table. It makes use of the <code>tabularx</code> package in LaTeX, otherwise (for other formats) it means <code>l</code> (centered alignment).    </td> </tr>
<tr><td align="center">   l,r,c    </td> <td align="left">   standard alignment characters                                                                                                                                                                                                                   </td> </tr>
</tbody>
</table>
<p>
Finally, a table with math
(<code>bm</code> that expands to <code>boldsymbol</code>, was tricky, but
cleanly handled now)
and URLs.

<p>
<!-- Mako code to expand URLs in the table -->
<!-- (These types of tables did not work before Jan 2014) -->

<p>
<table border="1">
<tr></tr>
<tbody>
<tr><td align="center">   \( \mathcal{L}=0 \)                    </td> <td align="center">   <a href="../doc/src/manual/mov/wave_frames/frame_0080.png"><img src="../doc/src/manual/mov/wave_frames/frame_0080.png" width="300"></a>    </td> <td align="center">   <a href="../doc/src/manual/mov/wave_frames/frame_0085.png"><img src="../doc/src/manual/mov/wave_frames/frame_0085.png" width="300"></a>    </td> </tr>
<tr><td align="center">   \( a=b \)                              </td> <td align="center">   <a href="../doc/src/manual/mov/wave_frames/frame_0090.png"><img src="../doc/src/manual/mov/wave_frames/frame_0090.png" width="300"></a>    </td> <td align="center">   <a href="../doc/src/manual/mov/wave_frames/frame_0095.png"><img src="../doc/src/manual/mov/wave_frames/frame_0095.png" width="300"></a>    </td> </tr>
<tr><td align="center">   \( \nabla\cdot\boldsymbol{u} =0  \)    </td> <td align="center">   <a href="../doc/src/manual/mov/wave_frames/frame_0100.png"><img src="../doc/src/manual/mov/wave_frames/frame_0100.png" width="300"></a>    </td> <td align="center">   <a href="../doc/src/manual/mov/wave_frames/frame_0105.png"><img src="../doc/src/manual/mov/wave_frames/frame_0105.png" width="300"></a>    </td> </tr>
</tbody>
</table>

<h2 id="a-test-of-verbatim-words-in-heading-with-subscript-a_i-my_file_v1-and-my_file_v2">A test of verbatim words in heading with subscript \( a_i \): <code>my_file_v1</code> and <code>my_file_v2</code> </h2>

<p>
<b>Paragraph with verbatim and math: <code>my_file_v1.py</code> and <code>my_file_v2.py</code> define some math \( a_{i-1} \).</b>
Here is more <code>__verbatim__</code> code and
some plain text on a new line.

<p>
<!-- Test various types of headlines -->

<h2 id="_just-bold_"><b>Just bold</b> </h2>

<p>
Some text.

<h2 id="just-emphasize"><em>Just emphasize</em> </h2>

<p>
Some text.

<h2 id="just-verbatim"><code>Just verbatim</code> </h2>

<p>
Some text.

<h2 id="_bold_-beginning"><b>Bold</b> beginning </h2>

<p>
Some text.

<h2 id="emphasize-beginning"><em>Emphasize</em> beginning </h2>

<p>
Some text.

<h2 id="verbatim-beginning"><code>Verbatim</code> beginning </h2>

<p>
Some text.

<h2 id="maybe-_bold-end_">Maybe <b>bold end</b> </h2>

<p>
Some text.

<h2 id="maybe-emphasize-end">Maybe <em>emphasize end</em> </h2>

<p>
Some text.

<h2 id="maybe-verbatim-end">Maybe <code>verbatim end</code> </h2>

<p>
Some text.

<h2 id="the-middle-has-<b>bold</b>-word">The middle has <b>bold</b> word </h2>

<p>
Some text.

<h2 id="the-middle-has-emphasize-word">The middle has <em>emphasize</em> word </h2>

<p>
Some text.

<h2 id="the-middle-has-verbatim-word">The middle has <code>verbatim</code> word </h2>

<p>
Some text.

<p>
<b><em>Just emphasize</em>.</b>
Some text.

<p>
<b><code>Just verbatim</code>.</b>
Some text.

<p>
<b><em>Emphasize</em> beginning.</b>
Some text.

<p>
<b><code>Verbatim beginning</code>.</b>
Some text.

<p>
<b>Maybe <em>emphasize end</em>.</b>
Some text.

<p>
<b>Maybe <code>verbatim end</code>.</b>
Some text.

<p>
<b>The middle has <em>emphasize</em> word.</b>
Some text.

<p>
<b>The middle has <code>verbatim</code> word.</b>
Some text.

<p>
<b>Ampersand.</b>
We can test Hennes &amp; Mauritz, often abbreviated H&amp;M, but written
as <code>Hennes & Mauritz</code> and <code>H & M</code>.
A sole <code>&</code> must also work.
<!-- Note: substitutions must not occur inside verbatim, just in ordinary text. -->

<p>

<!-- code=text typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span># Just to check that ampersand works in code blocks:
c = a &amp; b
</pre></div>
<p>
<b>Quotes.</b>
Let us also add a test of quotes such as &quot;double quotes, with numbers
like 3.14 and newline/comma and hyphen (as in double-quote)&quot;; written
in the standard LaTeX-style that gives correct LaTeX formatting and
ordinary double quotes for all non-LaTeX formats.  Here is another
sentence that &quot;caused&quot; a bug in the past because double backtick
quotes could imply verbatim text up to a verbatim word starting with
period, like <code>.txt</code>.

<p>
More quotes to be tested for spellcheck:
(&quot;with parenthesis&quot;), &quot;with newline&quot;
and &quot;with comma&quot;, &quot;hyphen&quot;-wise, and &quot;period&quot;.

<h2 id="bibliography-test">Bibliography test </h2>

<p>
Here is an example: <a href="#Langtangen_Pedersen_2002">[1]</a> discussed propagation of
large destructive water waves, <a href="#Langtangen_et_al_2002">[2]</a> gave
an overview of numerical methods for solving the Navier&ndash;Stokes equations,
while the use of Backward Kolmogorov equations for analyzing
random vibrations was investigated in <a href="#Langtangen_1994a">[3]</a>.
The book chapter <a href="#Mardal_et_al_2003a">[4]</a> contains information on
C++ software tools for programming multigrid methods. A real retro
reference is <a href="#Langtangen_1988d">[5]</a> about a big FORTRAN package.
Multiple references are also possible, e.g., see
<a href="#Langtangen_Pedersen_2002">[1]</a> <a href="#Mardal_et_al_2003a">[4]</a>.

<p>
We need to cite more than 10 papers to reproduce an old formatting
problem with blanks in the keys in reST format:
<a href="#Langtangen_1992c">[6]</a> <a href="#Langtangen_1994a">[3]</a> <a href="#Mortensen_et_al_2011">[7]</a> <a href="#Langtangen_Pedersen_2002">[1]</a>
and
<a href="#Langtangen_et_al_2002">[2]</a> <a href="#Glimsdal_et_al_20006">[8]</a> <a href="#Rahman_et_al_2006b">[9]</a> <a href="#Haga_et_al_2011a">[10]</a> <a href="#Langtangen_2003a">[11]</a> <a href="#Langtangen_2008a">[12]</a> <a href="#Langtangen:95">[13]</a>
and all the work of
<a href="#Langtangen_2012">[14]</a> <a href="#Mardal_et_al_2003a">[4]</a> <a href="#Jeberg_et_al_2004">[15]</a> as well as
old work <a href="#Langtangen_1988d">[5]</a> and <a href="#Langtangen_1989e">[16]</a>, and the
talk <a href="#Langtangen_talk_2007a">[17]</a>.
Langtangen also had two thesis <a href="#Langtangen:85">[18]</a> <a href="#Langtangen_1989e">[16]</a>
back in the days.
More retro citations are
the old ME-IN323 book <a href="#Langtangen:91">[19]</a> and the
<a href="#Langtangen:94b">[20]</a> OONSKI '94 paper.

<p>
<!-- --- begin exercise --- -->

<h2 id="Example">Example 1: Examples can be typeset as exercises</h2>

<p>
Examples can start with a subsection heading starting with <code>Example:</code>
and then, with the command-line option <code>--examples_as_exercises</code> be
typeset as exercises. This is useful if one has solution
environments as part of the example.

<p>
<b>a)</b>
State some problem.

<p>
<b>Solution.</b>
The answer to this subproblem can be written here.

<p>
<b>b)</b>
State some other problem.

<p>
<b>Hint 1.</b>
A hint can be given.

<p>
<b>Hint 2.</b>
Maybe even another hint?

<p>
<b>Solution.</b>
The answer to this other subproblem goes here,
maybe over multiple doconce input lines.

<p>
<!-- --- end exercise --- -->

<h2 id="user-defined-environments">User-defined environments </h2>

<p>
The example in the section <a href="#ex:test:1p1">Example 1: A test function</a> demonstrates how to write a test function.
That is, a special test function for a function <code>add</code> appears in
the example in the section <a href="#ex:test:1p1">Example 1: A test function</a>.

<h2 id="ex:test:1p1">Example 1: A test function</h2>

<p>
Suppose we want to write a test function for checking the
implementation of a Python function for addition.

<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">add</span>(a, b):
    <span style="color: #008000; font-weight: bold">return</span> a <span style="color: #666666">+</span> b

<span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">test_add</span>():
    a <span style="color: #666666">=</span> <span style="color: #666666">1</span>; b <span style="color: #666666">=</span> <span style="color: #666666">1</span>
    expected <span style="color: #666666">=</span> a <span style="color: #666666">+</span> b
    computed <span style="color: #666666">=</span> add(a, b)
    <span style="color: #008000; font-weight: bold">assert</span> expected <span style="color: #666666">==</span> computed
</pre></div>

<h2 id="ex:math:1p1">Example 2: Addition</h2>

<p>
We have

$$ 1 + 1 = 2 $$

or in tabular form:

<p>
<table border="1">
<thead>
<tr><th align="center"> Problem </th> <th align="center"> Result</th> </tr>
</thead>
<tbody>
<tr><td align="center">   \( 1+1 \)    </td> <td align="center">   \( 2 \)    </td> </tr>
</tbody>
</table>
<p>
<div style="width: 60%; padding: 10px; border: 1px solid #000;
 border-radius: 4px; box-shadow: 8px 8px 5px #888888;
 background: #cce5ff;">
 <b>Highlight box!</b><hr>
This environment is used to highlight something:

$$ E = mc^2 $$

</div>

<h2 id="subsubsec:ex">URLs</h2>

<p>
Testing of URLs: hpl's home page <a href="https://folk.uio.no/hpl" target="_self">hpl</a>, or
the entire URL if desired, <a href="https://folk.uio.no/hpl" target="_self"><tt>https://folk.uio.no/hpl</tt></a>.  Here is a
plain file link <a href="testdoc.do.txt" target="_self"><tt>testdoc.do.txt</tt></a>, or <a href="testdoc.do.txt" target="_self"><tt>testdoc.do.txt</tt></a>, or
<a href="testdoc.do.txt" target="_self"><tt>testdoc.do.txt</tt></a> or <a href="testdoc.do.txt" target="_self"><tt>testdoc.do.txt</tt></a> or <a href="testdoc.do.txt" target="_self">a link with
newline</a>. Can test spaces with the link with word
too: <a href="https://folk.uio.no/hpl" target="_self">hpl</a> or <a href="https://folk.uio.no/hpl" target="_self">hpl</a>. Also <code>file:///</code> works: <a href="file:///home/hpl/vc/doconce/doc/demos/manual/manual.html" target="_self">link to a
file</a> is
fine to have. Moreover, &quot;loose&quot; URLs work, i.e., no quotes, just
the plain URL as in <a href="https://folk.uio.no/hpl" target="_self"><tt>https://folk.uio.no/hpl</tt></a>, if followed by space, comma,
colon, semi-colon, question mark, exclamation mark, but not a period
(which gets confused with the periods inside the URL).

<p>
Mail addresses can also be used: <a href="mailto:hpl@simula.no" target="_self"><tt>hpl@simula.no</tt></a>, or just a <a href="mailto:hpl@simula.no" target="_self">mail link</a>, or a raw <a href="mailto:hpl@simula.no" target="_self"><tt>mailto:hpl@simula.no</tt></a>.

<p>
Here are some tough tests of URLs, especially for the <code>latex</code> format:
<a href="https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas" target="_self">Newton-Cotes</a> formulas
and a <a href="https://www.springer.com/mathematics/computational+science+%26+engineering/book/978-3-642-23098-1" target="_self">good book</a>. Need to test
Newton-Cotes with percentage in URL too:
<a href="https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas" target="_self"><tt>https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas</tt></a>
and <a href="https://en.wikipedia.org/wiki/Newton-Cotes#Open_Newton.E2.80.93Cotes_formulae" target="_self"><tt>https://en.wikipedia.org/wiki/Newton-Cotes#Open_Newton.E2.80.93Cotes_formulae</tt></a> which has a shebang.

<p>
For the <code>--device=paper</code> option it is important to test that URLs with
monospace font link text get a footnote
(unless the <code>--latex_no_program_footnotelink</code>
is used), as in this reference to
<a href="https://github.com/hplgit/INF5620/tree/gh-pages/src/decay/experiments/decay_mod.py" target="_self"><tt>decay_mod</tt></a>, <a href="https://tinyurl.com/pwyasaa/formulas.ball1.py" target="_self"><tt>ball1.py</tt></a>,
and <a href="https://tinyurl.com/pwyasaa/formulas.ball2.py" target="_self"><tt>ball2.py</tt></a>.

<p>
<!-- Comments should be inserted outside paragraphs (because in the rst -->
<!-- format extra blanks make a paragraph break). -->

<p>
<!-- Note that when there is no https: or file:, it can be a file link -->
<!-- if the link name is URL, url, "URL", or "url". Such files should, -->
<!-- if rst output is desired, but placed in a <code>_static*</code> folder. -->

<p>
More tough tests: repeated URLs whose footnotes when using the
<code>--device=paper</code> option must be correct. We have
<a href="https://google.com" target="_self">google</a>, <a href="https://google.com" target="_self">google</a>, and
<a href="https://google.com" target="_self">google</a>, which should result in exactly three
footnotes.

<p>
<!-- !split and check if these extra words are included properly in the comment -->

<h1 id="latex-mathematics">LaTeX Mathematics </h1>

<p>
Here is an equation without label using backslash-bracket environment:
$$ a = b + c $$

<p>
or with number and label, as in \eqref{my:eq1}, using the equation environment:

$$
\begin{equation}
{\partial u\over\partial t} = \nabla^2 u \label{my:eq1}
\end{equation}
$$

<p>
We can refer to this equation by \eqref{my:eq1}.

<p>
Here is a system without equation numbers, using the align-asterisk environment:

$$
\begin{align*}
\pmb{a} &= \pmb{q}\times\pmb{n} \\ 
b &= \nabla^2 u + \nabla^4 v
\end{align*}
$$

<p>
And here is a system of equations with labels in an align environment:

$$
\begin{align}
a &= q + 4 + 5+ 6 \label{eq1} \\ 
b &= \nabla^2 u + \nabla^4 x \label{eq2}
\end{align}

$$

We can refer to \eqref{eq1}-\eqref{eq2}. They are a bit simpler than
the Navier&ndash;Stokes equations. And test LaTeX hyphen in <code>CG-2</code>.
Also test \( a_{i-j} \) as well as \( kx-wt \).

<p>
Testing <code>alignat</code> environment:

$$
\begin{alignat}{2}
a &= q + 4 + 5+ 6\qquad & \mbox{for } q\geq 0 \label{eq1a} \\ 
b &= \nabla^2 u + \nabla^4 x & x\in\Omega \label{eq2a}
\end{alignat}
$$

<p>
More mathematical typesetting is demonstrated in the coming exercises.

<p>
Below, we have <a href="#demo:ex:1">Problem 2: Flip a Coin</a> and <a href="#demo:ex:2">Project 4: Compute a Probability</a>,
as well as <a href="#proj:circle1">Project 5: Explore Distributions of Random Circles</a> and <a href="#exer:you">Project 11: References in a headings do not work well in html</a>, and in
between there we have <a href="#exer:some:formula">Exercise 10: Make references to projects and problems</a>.

<h1 id="exercises">Exercises </h1>

<p>
<!-- --- begin exercise --- -->

<h2 id="demo:ex:1">Problem 2: Flip a Coin</h2>
<!-- keywords = random numbers; Monte Carlo simulation; ipynb -->

<p>
<!-- Torture tests -->

<p>
<b>a)</b>
Make a program that simulates flipping a coin \( N \) times.
Print out &quot;tail&quot; or &quot;head&quot; for each flip and
let the program count the number of heads.

<p>
<!-- --- begin hint in exercise --- -->

<p>
<b>Hint 1.</b>
Use <code>r = random.random()</code> and define head as <code>r &lt;= 0.5</code>.

<p>
<!-- --- end hint in exercise --- -->

<p>
<!-- --- begin hint in exercise --- -->

<p>
<b>Hint 2.</b>
Draw an integer among \( \{1,2\} \) with
<code>r = random.randint(1,2)</code> and define head when <code>r</code> is 1.

<p>
<!-- --- end hint in exercise --- -->

<p>
<!-- --- begin answer of exercise --- -->
<b>Answer.</b>
If the <code>random.random()</code> function returns a number \( < 1/2 \), let it be
head, otherwise tail. Repeat this \( N \) number of times.
<!-- --- end answer of exercise --- -->

<p>
<!-- --- begin solution of exercise --- -->
<b>Solution.</b>
<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">import</span> <span style="color: #0000FF; font-weight: bold">sys</span><span style="color: #666666">,</span> <span style="color: #0000FF; font-weight: bold">random</span>
N <span style="color: #666666">=</span> <span style="color: #008000">int</span>(sys<span style="color: #666666">.</span>argv[<span style="color: #666666">1</span>])
heads <span style="color: #666666">=</span> <span style="color: #666666">0</span>
<span style="color: #008000; font-weight: bold">for</span> i <span style="color: #AA22FF; font-weight: bold">in</span> <span style="color: #008000">range</span>(N):
    r <span style="color: #666666">=</span> random<span style="color: #666666">.</span>random()
    <span style="color: #008000; font-weight: bold">if</span> r <span style="color: #666666">&lt;=</span> <span style="color: #666666">0.5</span>:
        heads <span style="color: #666666">+=</span> <span style="color: #666666">1</span>
<span style="color: #008000">print</span>(<span style="color: #BA2121">&#39;Flipping a coin </span><span style="color: #BB6688; font-weight: bold">%d</span><span style="color: #BA2121"> times gave </span><span style="color: #BB6688; font-weight: bold">%d</span><span style="color: #BA2121"> heads&#39;</span> <span style="color: #666666">%</span> (N, heads))
</pre></div>
<p>
<!-- --- end solution of exercise --- -->

<p>
<b>b)</b>
Vectorize the code in a) using boolean indexing.

<p>
Vectorized code can be written in many ways.
Sometimes the code is less intuitive, sometimes not.
At least there is not much to find in the section <a href="#sec1">Section 1</a>.

<p>
<b>c)</b>
Vectorize the code in a) using <code>numpy.sum</code>.

<p>
<!-- --- begin answer of exercise --- -->
<b>Answer.</b>
<code>np.sum(np.where(r &lt;= 0.5, 1, 0))</code> or <code>np.sum(r &lt;= 0.5)</code>.
<!-- --- end answer of exercise --- -->

<p>
In this latter subexercise, we have an
example where the code is easy to read.

<h3 id="my-remarks">My remarks </h3>

<p>
Remarks with such a subsubsection is treated as more text
after the last subexercise. Test a list too:

<ol>
<li> Mark 1.</li>
<li> Mark 2.</li>
</ol>

Filenames: <code>flip_coin.py</code>, <code>flip_coin.pdf</code>.

<p>
<!-- Closing remarks for this Problem -->

<h3 id="remarks">Remarks </h3>

<p>
These are the exercise remarks, appearing at the very end.

<p>
<!-- solution files: mysol.txt, mysol_flip_coin.py, yet_another.file -->

<p>
<!-- --- end exercise --- -->

<h2 id="not-an-exercise">Not an exercise </h2>

<p>
Should be possible to stick a normal section in the middle of many
exercises.

<p>
<!-- --- begin exercise --- -->

<h2 id="my:exer1">Exercise 3: Test of plain text exercise</h2>

<p>
Very short exercise. What is the capital
of Norway?
Filename: <code>myexer1</code>.

<p>
<!-- --- end exercise --- -->

<p>
<!-- --- begin exercise --- -->

<h2 id="demo:ex:2">Project 4: Compute a Probability</h2>

<p>
<!-- Minimalistic exercise -->

<p>
What is the probability of getting a number between 0.5 and 0.6 when
drawing uniformly distributed random numbers from the interval \( [0,1) \)?

<p>
At the end we have a list because that caused problems in LaTeX
in previous DocOnce versions:

<ol>
<li> item1</li>
<li> item2</li>
</ol>

<!-- --- begin hint in exercise --- -->

<p>
<b>Hint.</b>
To answer this question empirically, let a program
draw \( N \) such random numbers using Python's standard <code>random</code> module,
count how many of them, \( M \), that fall in the interval \( (0.5,0.6) \), and
compute the probability as \( M/N \).

<p>
<!-- --- end hint in exercise --- -->

<p>
<!-- --- end exercise --- -->

<p>
<!-- --- begin exercise --- -->

<h2 id="proj:circle1">Project 5: Explore Distributions of Random Circles</h2>
<!-- keywords = ipynb -->

<p>
The formula for a circle is given by

$$
\begin{align}
x &= x_0 + R\cos 2\pi t,
\label{circle:x}\\ 
y &= y_0 + R\sin 2\pi t,
\label{circle:y}
\end{align}
$$

where \( R \) is the radius of the circle, \( (x_0,y_0) \) is the
center point, and \( t \) is a parameter in the unit interval \( [0,1] \).
For any \( t \), \( (x,y) \) computed from \eqref{circle:x}-\eqref{circle:y}
is a point on the circle.
The formula can be used to generate <code>n</code> points on a circle:

<p>

<!-- code=python (!bc pypro) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">import</span> <span style="color: #0000FF; font-weight: bold">numpy</span> <span style="color: #008000; font-weight: bold">as</span> <span style="color: #0000FF; font-weight: bold">np</span>

<span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">circle</span>(R, x0, y0, n<span style="color: #666666">=501</span>):
    t <span style="color: #666666">=</span> np<span style="color: #666666">.</span>linspace(<span style="color: #666666">0</span>, <span style="color: #666666">1</span>, n)
    x <span style="color: #666666">=</span> x0 <span style="color: #666666">+</span> R<span style="color: #666666">*</span>np<span style="color: #666666">.</span>cos(<span style="color: #666666">2*</span>np<span style="color: #666666">.</span>pi<span style="color: #666666">*</span>t)
    y <span style="color: #666666">=</span> y0 <span style="color: #666666">+</span> R<span style="color: #666666">*</span>np<span style="color: #666666">.</span>sin(<span style="color: #666666">2*</span>np<span style="color: #666666">.</span>pi<span style="color: #666666">*</span>t)
    <span style="color: #008000; font-weight: bold">return</span> x, y

x, y <span style="color: #666666">=</span> circle(<span style="color: #666666">2.0</span>, <span style="color: #666666">0</span>, <span style="color: #666666">0</span>)
</pre></div>
<p>
<!-- Often in an exercise we have some comments about the solution -->
<!-- which we normally want to keep where they are. -->

<p>
The goal of this project is to draw \( N \) circles with random
center and radius. Plot each circle using the <code>circle</code> function
above.

<p>
<b>a)</b>
Let \( R \) be normally distributed and \( (x_0,y_0) \) uniformly distributed.

<p>
<!-- --- begin hint in exercise --- -->

<p>
<b>Hint.</b>
Use the <code>numpy.random</code> module to draw the
\( x_0 \), \( y_0 \), and \( R \) quantities.

<p>
<!-- --- end hint in exercise --- -->

<p>
<!-- --- begin answer of exercise --- -->
<b>Answer.</b>
Here goes the short answer to part a).
<!-- --- end answer of exercise --- -->

<p>
<!-- --- begin solution of exercise --- -->
<b>Solution.</b>
Here goes a full solution to part a).
<!-- --- end solution of exercise --- -->

<p>
<b>b)</b>
Let \( R \) be uniformly distributed and \( (x_0,y_0) \) normally distributed.
Filename: <code>norm</code>.

<p>
<b>c)</b>
Let \( R \) and \( (x_0,y_0) \) be normally distributed.

<p>
Filename: <code>circles</code>.

<p>
<!-- Closing remarks for this Project -->

<h3 id="remarks">Remarks </h3>

<p>
At the very end of the exercise it may be appropriate to summarize
and give some perspectives.

<p>
<!-- --- end exercise --- -->

<p>
<!-- --- begin exercise --- -->

<h2 id="exer:dist">Exercise 6: Determine some Distance</h2>

<p>
Intro to this exercise. Questions are in subexercises below.

<p>
<!-- --- begin solution of exercise --- -->
<b>Solution.</b>
Here goes a full solution of the whole exercise.
With some math \( a=b \) in this solution:
$$ \hbox{math in solution: } a = b $$

And code <code>a=b</code> in this solution:
<p>

<!-- code=text typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>a = b  # code in solution
</pre></div>
<p>
End of solution is here.

<p>
<!-- --- end solution of exercise --- -->

<p>
<b>a)</b>
Subexercises are numbered a), b), etc.

<p>
<!-- --- begin hint in exercise --- -->

<p>
<b>Hint 1.</b>
First hint to subexercise a).
With math \( a=b \) in hint:

$$ a=b. $$

And with code (in plain verbatim) returning \( x+1 \) in hint:

<p>

<!-- code=text typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>def func(x):
    return x + 1  # with code in hint
</pre></div>
<p>
<!-- --- end hint in exercise --- -->

<p>
<!-- --- begin hint in exercise --- -->

<p>
<b>Hint 2.</b>
Second hint to subexercise a).

<p>
Test list in hint:

<ol>
<li> item1</li>
<li> item2</li>
</ol>

<!-- --- end hint in exercise --- -->
Filename: <code>subexer_a.pdf</code>.

<p>
<!-- --- begin answer of exercise --- -->
<b>Answer.</b>
Short answer to subexercise a).
With math in answer: \( a=b \).
<!-- --- end answer of exercise --- -->

<p>
<b>b)</b>
Here goes the text for subexercise b).

<p>
Some math \( \cos^2 x + \sin^2 x = 1 \) written one a single line:

$$ \cos^2 x + \sin^2 x = 1 \thinspace .$$

<p>
<!-- --- begin hint in exercise --- -->

<p>
<b>Hint.</b>
A hint for this subexercise.

<p>
<!-- --- end hint in exercise --- -->
Filename: <code>subexer_b.pdf</code>.

<p>
<!-- --- begin solution of exercise --- -->
<b>Solution.</b>
Here goes the solution of this subexercise.
<!-- --- end solution of exercise --- -->

<p>
<!-- No meaning in this weired test example: -->
The text here belongs to the main (intro) part of the exercise. Need
closing remarks to have text after subexercises.

<p>
Test list in exercise:

<ol>
<li> item1</li>
<li> item2
<!-- Closing remarks for this Exercise --></li>
</ol>

<h3 id="remarks">Remarks </h3>

<p>
Some final closing remarks, e.g., summarizing the main findings
and their implications in other problems can be made. These
remarks will appear at the end of the typeset exercise.

<p>
<!-- --- end exercise --- -->

<p>
<!-- --- begin exercise --- -->

<h2 id="some-exercise-without-the-exercise-prefix">Some exercise without the "Exercise:" prefix </h2>

<p>
<!-- Another minimalistic exercise -->

<p>
Just some text. And some math saying that \( e^0=1 \) on a single line,
to test that math block insertion is correct:

$$ \exp{(0)} = 1 $$

<p>
And a test that the code <code>lambda x: x+2</code> is correctly placed here:

<p>

<!-- code=text typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span>lambda x: x+2
</pre></div>
<p>
<!-- Have some comments at the end of the exercise to see that -->
<!-- the Filename: ... is written correctly. -->
<!-- --- end exercise --- -->

<p>
<!-- --- begin exercise --- -->

<h2 id="sec:this:exer:de">Exercise 8: Solution of differential equation</h2>

<p>
<!-- begin quiz -->
Given

$$ \frac{dy}{dx} = -y(x),\quad y(0)=1 $$

What is the solution of this equation?</p>

<p><div title="Right! "><b>Choice A:</b>
\( y=e^{-y} \)
</div></p>

<p><div title="Wrong! Almost, but the sign is wrong (note the minus!)."><b>Choice B:</b>
\( y=e^{y} \)
</div></p>

<p><div title="Wrong! "><b>Choice C:</b>
<p>

<!-- code=python (!bc pycod) typeset with pygments style "default" -->
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%;"><span></span><span style="color: #008000; font-weight: bold">from</span> <span style="color: #0000FF; font-weight: bold">math</span> <span style="color: #008000; font-weight: bold">import</span> exp
<span style="color: #008000; font-weight: bold">def</span> <span style="color: #0000FF">f</span>(x):
    <span style="color: #008000; font-weight: bold">return</span> exp(x)
</pre></div>
<p>
</div></p>

<p><div title="Wrong! Equations with derivatives can be solved; they are termed  differential equations ."><b>Choice D:</b>
The solution cannot be found because there is a derivative in the equation.
</div></p>

<p><div title="Wrong! Equations where the unknown is a function, as \( y(x) \) here, are called  differential equations , and are solved by special techniques."><b>Choice E:</b>
The equation is meaningless: an equation must be an equation
for \( x \) or \( y \), not a function \( y(x) \).
</div></p>
<hr>
<!-- end quiz -->


<p>
<!-- --- end exercise --- -->

<p>
<!-- --- begin exercise --- -->

<h2 id="example-9-just-an-example">Example 9: Just an example </h2>

<p>
<!-- This example needs the --examples_as_exercises option, otherwise -->
<!-- it is just typeset as it is written. -->

<p>
<b>a)</b>
What is the capital of Norway?

<p>
<b>Answer.</b>
Oslo.

<p>
<!-- --- end exercise --- -->

<h1 id="here-goes-another-section">Here goes another section </h1>

<p>
With some text, before we continue with exercises.

<h1 id="more-exercises">More Exercises </h1>

<p>
<!-- --- begin exercise --- -->

<h2 id="exer:some:formula">Exercise 10: Make references to projects and problems</h2>

<p>
<!-- Test comments not at the end only -->
Pick a statement from <a href="#proj:circle1">Project 5: Explore Distributions of Random Circles</a> or <a href="#demo:ex:1">Problem 2: Flip a Coin</a>
and verify it.

<p>
Test list at the end of an exercise without other elements (like subexercise,
hint, etc.):

<ol>
<li> item1</li>
<li> item2</li>
</ol>

Filename: <code>verify_formula.py</code>.

<p>
<!-- --- end exercise --- -->

<p>
<!-- --- begin exercise --- -->

<h2 id="exer:you">Project 11: References in a headings do not work well in html</h2>

<p>
Refer to the previous exercise as <a href="#exer:some:formula">Exercise 10: Make references to projects and problems</a>,
the two before that as <a href="#demo:ex:2">Project 4: Compute a Probability</a> and <a href="#proj:circle1">Project 5: Explore Distributions of Random Circles</a>,
and this one as <a href="#exer:you">Project 11: References in a headings do not work well in html</a>.
Filename: <code>selc_composed.pdf</code>.

<p>
<!-- --- end exercise --- -->

<h1 id="references">References </h1>

<p>
<!-- begin bibliography -->

<ol>
 <li> <div id="Langtangen_Pedersen_2002"></div> <b>H. P. Langtangen and G. Pedersen</b>. 
    Propagation of Large Destructive Waves,
    <em>International Journal of Applied Mechanics and Engineering</em>,
    7(1),
    pp. 187-204,
    2002.</li>
 <li> <div id="Langtangen_et_al_2002"></div> <b>H. P. Langtangen, K.-A. Mardal and R. Winther</b>. 
    Numerical Methods for Incompressible Viscous Flow,
    <em>Advances in Water Resources</em>,
    25,
    pp. 1125-1146,
    2002.</li>
 <li> <div id="Langtangen_1994a"></div> <b>H. P. Langtangen</b>. 
    Numerical Solution of First Passage Problems in Random Vibrations,
    <em>SIAM Journal of Scientific and Statistical Computing</em>,
    15,
    pp. 997-996,
    1994.</li>
 <li> <div id="Mardal_et_al_2003a"></div> <b>K.-A. Mardal, G. W. Zumbusch and H. P. Langtangen</b>. 
    Software Tools for Multigrid Methods,
    <em>Advanced Topics in Computational Partial Differential Equations -- Numerical Methods and Diffpack Programming</em>,
    edited by <b>H. P. Langtangen and A. Tveito</b>,
    Springer,
    2003,
    Edited book,
    <a href="http://some.where.org" target="_self"><tt>http://some.where.org</tt></a>.</li>
 <li> <div id="Langtangen_1988d"></div> <b>H. P. Langtangen</b>. 
    The FEMDEQS Program System,
    <em>Department of Mathematics, University of Oslo</em>,
    1989,
    <a href="http://www.math.uio.no/old/days/hpl/femdeqs.pdf" target="_self"><tt>http://www.math.uio.no/old/days/hpl/femdeqs.pdf</tt></a>.</li>
 <li> <div id="Langtangen_1992c"></div> <b>H. P. Langtangen</b>. 
    Stochastic Breakthrough Time Analysis of an Enhanced Oil Recovery Process,
    <em>SIAM Journal on Scientific Computing</em>,
    13,
    pp. 1394-1417,
    1992.</li>
 <li> <div id="Mortensen_et_al_2011"></div> <b>M. Mortensen, H. P. Langtangen and G. N. Wells</b>. 
    A FEniCS-Based Programming Framework for Modeling Turbulent Flow by the Reynolds-Averaged Navier-Stokes Equations,
    <em>Advances in Water Resources</em>,
    34(9),
    <a href="https://dx.doi.org/10.1016/j.advwatres.2011.02.013" target="_self">doi: 10.1016/j.advwatres.2011.02.013</a>,
    2011.</li>
 <li> <div id="Glimsdal_et_al_20006"></div> <b>S. Glimsdal, G. Pedersen, K. Atakan, C. B. Harbitz, H. P. Langtangen and F. L\ovholt</b>. 
    Propagation of the Dec.&nbsp;26, 2004 Indian Ocean Tsunami: Effects of Dispersion and Source Characteristics,
    <em>International Journal of Fluid Mechanics Research</em>,
    33(1),
    pp. 15-43,
    2006.</li>
 <li> <div id="Rahman_et_al_2006b"></div> <b>S. Rahman, J. Gorman, C. H. W. Barnes, D. A. Williams and H. P. Langtangen</b>. 
    Numerical Investigation of a Piezoelectric Surface Acoustic Wave Interaction With a One-Dimensional Channel,
    <em>Physical Review B: Condensed Matter and Materials Physics</em>,
    74,
    2006,
    035308.</li>
<li> <div id="Haga_et_al_2011a"></div> <b>J. B. Haga, H. Osnes and H. P. Langtangen</b>. 
    On the Causes of Pressure Oscillations in Low-Permeable and Low-Compressible Porous Media,
    <em>International Journal of Analytical and Numerical Methods in Geomechanics</em>,
    <a href="https://dx.doi.org/10.1002/nag.1062" target="_self">doi: 10.1002/nag.1062</a>,
    2011,
    <a href="http://onlinelibrary.wiley.com/doi/10.1002/nag.1062/abstract" target="_self"><tt>http://onlinelibrary.wiley.com/doi/10.1002/nag.1062/abstract</tt></a>.</li>
<li> <div id="Langtangen_2003a"></div> <b>H. P. Langtangen</b>. 
    <em>Computational Partial Differential Equations - Numerical Methods and Diffpack Programming</em>,
    second edition,
    <em>Texts in Computational Science and Engineering</em>,
    Springer,
    2003.</li>
<li> <div id="Langtangen_2008a"></div> <b>H. P. Langtangen</b>. 
    <em>Python Scripting for Computational Science</em>,
    third edition,
    <em>Texts in Computational Science and Engineering</em>,
    Springer,
    2008.</li>
<li> <div id="Langtangen:95"></div> <b>H. P. Langtangen and G. Pedersen</b>. 
    Finite Elements for the Boussinesq Wave Equations,
    Waves and Non-linear Processes in Hydrodynamics,
    edited by <b>J. Grue, B. Gjevik and J. E. Weber</b>,
    Kluwer Academic Publishers,
    pp. pp. 117-126,
    1995,
    <a href="http://www.amazon.ca/Waves-Nonlinear-Processes-Hydrodynamics-John/dp/0792340310" target="_self"><tt>http://www.amazon.ca/Waves-Nonlinear-Processes-Hydrodynamics-John/dp/0792340310</tt></a>.</li>
<li> <div id="Langtangen_2012"></div> <b>H. P. Langtangen</b>. 
    <em>A Primer on Scientific Programming With Python</em>,
    third edition,
    <em>Texts in Computational Science and Engineering</em>,
    Springer,
    2012.</li>
<li> <div id="Jeberg_et_al_2004"></div> <b>P. V. Jeberg, H. P. Langtangen and C. B. Terp</b>. 
    Optimization With Diffpack: Practical Example From Welding,
    <em>Simula Research Laboratory</em>,
    2004,
    Internal report.</li>
<li> <div id="Langtangen_1989e"></div> <b>H. P. Langtangen</b>. 
    Computational Methods for Two-Phase Flow in Oil Reservoirs,
    Ph.D. Thesis,
    Mechanics Division, Department of Mathematics, University of Oslo,
    1989,
    Dr.&nbsp;Scient.&nbsp;thesis..</li>
<li> <div id="Langtangen_talk_2007a"></div> <b>H. P. Langtangen</b>. 
    Computational Modeling of Huge Tsunamis From Asteroid Impacts,
    2007,
    Invited keynote lecture at the \emphInternational conference on Computational Science 2007 (ICCS'07), Beijing, China.</li>
<li> <div id="Langtangen:85"></div> <b>H. P. Langtangen</b>. 
    Solution of the Navier-Stokes Equations With the Finite Element Method in Two and Three Dimensions,
    M.Sc. Thesis,
    Mechanics Division, Department of Mathematics, University of Oslo,
    1985,
    Cand.Scient. thesis.</li>
<li> <div id="Langtangen:91"></div> <b>H. P. Langtangen and A. Tveito</b>. 
    Numerical Methods in Continuum Mechanics,
    <em>Center for Industrial Research</em>,
    1991,
    Lecture notes for a course (ME-IN 324). 286 pages..</li>
<li> <div id="Langtangen:94b"></div> <b>H. P. Langtangen</b>. 
    Diffpack: Software for Partial Differential Equations,
    <em>Proceedings of the Second Annual Object-Oriented Numerics Conference (OON-SKI'94), Sunriver, Oregon, USA</em>,
    edited by <b>A. Vermeulen</b>,
    1994.</li>
</ol>

<!-- end bibliography -->

<h1 id="app1">Appendix: Just for testing; part I</h1>

<p>
This is the first appendix.

<h2 id="a-subsection-within-an-appendix">A subsection within an appendix </h2>

<p>
Some text.

<h1 id="app2">Appendix: Just for testing; part II</h1>

<p>
This is more stuff for an appendix.

<h2 id="appendix-testing-identical-titles">Appendix: Testing identical titles </h2>

<p>
Without label.

<h2 id="test:title:id1">Appendix: Testing identical titles</h2>

<p>
With label.

<h2 id="test:title:id2">Appendix: Testing identical titles</h2>

<p>
What about inserting a quiz?

<p>
<!-- !split -->
<h2>Test of quizzes</h2>

<!-- begin quiz -->
<hr>
<p>
<b>Fundamental test:</b> What is the capital of Norway?</p>

<p><div title="Wrong! Stockholm is the capital of Sweden."><b>Answer 1:</b>
Stockholm
</div></p>

<p><div title="Wrong! "><b>Answer 2:</b>
London
</div></p>

<p><div title="Right! "><b>Answer 3:</b>
Oslo
</div></p>

<p><div title="Wrong! Those from Bergen would claim so, but nobody else."><b>Choice D:</b>
Bergen
</div></p>
<hr>
<!-- end quiz -->


<h2 id="appendix-testing-identical-titles">Appendix: Testing identical titles </h2>

<p>
Without label.

<p>
<div class="alert alert-block alert-notice alert-text-normal">
<b>Tip</b>
<p>
Here is a tip or hint box, typeset as a notice box.
</div>


<p>
Need a lot of text to surround the summary box.
Version control systems allow you to record the history of files
and share files among several computers and collaborators in a
professional way. File changes on one computer are updated or
merged with changes on another computer. Especially when working
with programs or technical reports it is essential
to have changes documented and to
ensure that every computer and person involved in the project
have the latest updates of the files.
Greg Wilson' excellent <a href="https://software-carpentry.org/2010/07/script-for-introduction-to-version-control/" target="_self">Script for Introduction to Version Control</a> provides a more detailed motivation why you will benefit greatly
from using version control systems.

<p>
<div class="alert alert-block alert-summary alert-text-normal">
<b>Summary</b>
<p>
<b>Bold remark:</b> Make some text with this summary.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
Much testing in this document, otherwise stupid content.
</div>


<p>
Projects that you want to share among several computers or project
workers are today most conveniently stored at some web site "in the
cloud" and updated through communication with that site. I strongly
recommend you to use such sites for all serious programming and
scientific writing work - and all other important files.

<p>
The simplest services for hosting project files are <a href="https://dropbox.com" target="_self">Dropbox</a> and <a href="https://drive.google.com" target="_self">Google Drive</a>.
It is very easy to get started with these systems, and they allow you
to share files among laptops and mobile units with as many users as
you want. The systems offer a kind of version control in that the
files are stored frequently (several times per minute), and you can go
back to previous versions for the last 30 days. However, it is
challenging  to find the right version from the past when there are
so many of them.

<p>
More seriously, when several people may edit files simultaneously, it
can be difficult detect who did what when, roll back to previous
versions, and to manually merge the edits when these are
incompatible. Then one needs more sophisticated tools than Dropbox or
Google Drive: project hosting services with true version control
systems.  The following text aims at providing you with the minimum
information to started with such systems. Numerous other tutorials
contain more comprehensive material and in-depth explanations of the
concepts and tools.

<p>
The idea with project hosting services is that you have the files
associated with a project in the cloud. Many people may share these
files.  Every time you want to work on the project you explicitly
update your version of the files, edit the files as you like, and
synchronize the files with the "master version" at the site where the
project is hosted.  If you at some point need to go back to a
version of the files at some particular point in the past,
this is an easy operation. You can also use tools to see
what various people have done with the files in the various versions.

<p>
All these services are very similar. Below we describe how you get
started with Bitbucket, GitHub, and Googlecode. Launchpad works very
similarly to the latter three. All the project hosting services have
excellent introductions available at their web sites, but the recipes
below are much shorter and aim at getting you started as quickly as
possible by concentrating on the most important need-to-know steps.
The Git tutorials we refer to later in this document contain more
detailed information and constitute of course very valuable readings
when you use version control systems every day. The point now is
to get started.

<h2 id="appendix-testing-inline-comments">Appendix: Testing inline comments </h2>

<p>
<!-- Names can be [ A-Za-z0-9_'+-]+ -->

<p>
Projects that you want to share among several computers or project
workers are today most conveniently stored at some web site "in the
cloud" and updated through communication with that
site. 
<!-- begin inline comment -->
<font color="red">(<b>hpl's semi opinion 1</b>: not sure if in the cloud is understood by all.)</font>
<!-- end inline comment -->
 I strongly recommend you to use such sites for all serious
programming and scientific writing work - and all other important
files.

<p>
The simplest services for hosting project files is Dropbox. 
<!-- begin inline comment -->
<font color="red">(<b>mp 2</b>: Simply go to <a href="https://dropbox.com" target="_self"><tt>https://dropbox.com</tt></a> and watch the video. It explains how files, like <code>myfile.py</code>, perhaps containing much math, like \( \partial u/\partial t \), are easily communicated between machines.)</font>
<!-- end inline comment -->
 It
is very easy to get started with Dropbox, and it allows you to share
files among  <font color="red">(<b>hpl 3</b>:)</font> <del> laptops and mobile units </del> <font color="red">computers, tablets, and phones</font>.

<p>
<!-- Test horizontal rule -->

<p>
<hr>

<p>
<!-- Coments for editing -->

<p>
First<font color="red">, (<b>edit 4</b>: add comma)</font> consider a quantity \( Q \).  <font color="red">(<b>edit 5</b>:)</font> <del> To this end, </del> <font color="red">We note that</font>
\( Q>0 \), because  <font color="red">(<b>edit 6</b>:)</font> <del> a </del> negative  <font color="red">(<b>edit 7</b>:)</font> <del> quantity is </del> <font color="red">quantities are</font>  <font color="red">(<b>edit 8</b>:)</font> <del> just </del> negative.  <font color="red">(<b>edit 9</b>:) This comes as no surprise.</font>

<p>
<!-- Test tailored latex figure references with page number -->
Let us refer to Figure <a href="#fig:impact">1</a> again.

<p>
Test references in a list:

<ul>
 <li> <a href="#sec1">Section 1</a></li>
 <li> <a href="#subsec1">Subsection 1</a></li>
 <li> <a href="#fig:impact">1</a></li>
</ul>

<h2 id="appendix-testing-headings-ending-with-verbatim-inline">Appendix: Testing headings ending with <code>verbatim inline</code> </h2>

<p>
The point here is to test 1) <code>verbatim</code> code in headings, and 2)
ending a heading with verbatim code as this triggers a special
case in LaTeX.

<p>
We also test mdash&mdash;used as alternative to hyphen without spaces around,
or in quotes:

<p>
<blockquote>
    <em>Fun is fun</em>.&mdash;Unknown.
</blockquote>


<p>
The ndash should also be tested &ndash; as in the Hanson&ndash;Nilson equations
on page 277&ndash;278.

<p>
And finally, what about admons, quotes, and boxes? They are tested
in a separate document: <code>admon.do.txt</code>.

<p id="def_footnote_5"><a href="#link_footnote_5"><b>5:</b></a> Not much to add here, but the footnote
is at the end with only one newline.</p>

<!-- ------------------- end of main content --------------- -->

<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.js"></script>


</body>
</html>
    

************** File: automake_sphinx.log *****************
INFO - running doconce format sphinx admon 
INFO - copy: admon.rst to tmp_admon and reading the content
INFO - copy: ../doc/src/manual/fig/wave1D.png to tmp_admon
INFO - edit: figure path to wave1D.png
INFO - running make clean and make html
INFO - edit: genindex.html
INFO - edit: index.html
INFO - edit: admon.html
INFO - edit: search.html

************** File: standalone_exercises/exercise_1.do.txt *****************
TITLE: Example 1: Examples can be typeset as exercises
AUTHOR: Jane Doe Email:jane.doe@cyberspace.net
DATE: Due Jan 32, 2100



Examples can start with a subsection heading starting with `Example:`
and then, with the command-line option `--examples_as_exercises` be
typeset as exercises. This is useful if one has solution
environments as part of the example.


__a)__
State some problem.

__Solution.__
The answer to this subproblem can be written here.

__b)__
State some other problem.

__Hint 1.__
A hint can be given.

__Hint 2.__
Maybe even another hint?

__Solution.__
The answer to this other subproblem goes here,
maybe over multiple doconce input lines.

************** File: standalone_exercises/selc_composed.do.txt *****************
TITLE: Project 11: References to Project ref{demo:ex:2} in a heading works for plain
AUTHOR: Jane Doe Email:jane.doe@cyberspace.net
DATE: Due Jan 32, 2100

# Logical name of exercise: selc_composed
# This document contains references to a parent document (../testdoc).
# These references will work for latex (using the xr package and
# a compiled parent document (with ../testdoc.aux file), but other formats
# will have missing references.
# Externaldocuments: ../testdoc



Refer to the previous exercise as Exercise ref{exer:some:formula},
the two before that as Projects ref{demo:ex:2} and ref{proj:circle1},
and this one as Project ref{exer:you}.

************** File: standalone_exercises/subexer_a.do.txt *****************
TITLE: Exercise 6: Determine some Distance
AUTHOR: Jane Doe Email:jane.doe@cyberspace.net
DATE: Due Jan 32, 2100

# Logical name of exercise: subexer_a



Intro to this exercise. Questions are in subexercises below.




__a)__
Subexercises are numbered a), b), etc.


__Hint 1.__
First hint to subexercise a).
With math $a=b$ in hint:

!bt
\[ a=b. \]
!et
And with code (in plain verbatim) returning $x+1$ in hint:

!bc
def func(x):
    return x + 1  # with code in hint
!ec



__Hint 2.__
Second hint to subexercise a).

Test list in hint:

 o item1
 o item2





__b)__
Here goes the text for subexercise b).


Some math $\cos^2 x + \sin^2 x = 1$ written one a single line:

!bt
\[ \cos^2 x + \sin^2 x = 1 \thinspace .\]
!et


__Hint.__
A hint for this subexercise.







#  No meaning in this weired test example:
The text here belongs to the main (intro) part of the exercise. Need
closing remarks to have text after subexercises.

Test list in exercise:

 o item1
 o item2


# Closing remarks for this Exercise

=== Remarks ===

Some final closing remarks, e.g., summarizing the main findings
and their implications in other problems can be made. These
remarks will appear at the end of the typeset exercise.

************** File: standalone_exercises/exercise_4.do.txt *****************
TITLE: Project 4: Compute a Probability
AUTHOR: Jane Doe Email:jane.doe@cyberspace.net
DATE: Due Jan 32, 2100



# Minimalistic exercise


What is the probability of getting a number between 0.5 and 0.6 when
drawing uniformly distributed random numbers from the interval $[0,1)$?


At the end we have a list because that caused problems in LaTeX
in previous DocOnce versions:

 o item1
 o item2


__Hint.__
To answer this question empirically, let a program
draw $N$ such random numbers using Python's standard `random` module,
count how many of them, $M$, that fall in the interval $(0.5,0.6)$, and
compute the probability as $M/N$.


************** File: standalone_exercises/verify_formula.do.txt *****************
TITLE: Exercise 10: Make references to projects and problems
AUTHOR: Jane Doe Email:jane.doe@cyberspace.net
DATE: Due Jan 32, 2100

# Logical name of exercise: verify_formula
# This document contains references to a parent document (../testdoc).
# These references will work for latex (using the xr package and
# a compiled parent document (with ../testdoc.aux file), but other formats
# will have missing references.
# Externaldocuments: ../testdoc



# Test comments not at the end only
Pick a statement from Project ref{proj:circle1} or Problem ref{demo:ex:1}
and verify it.

Test list at the end of an exercise without other elements (like subexercise,
hint, etc.):

 o item1
 o item2

************** File: standalone_exercises/exercise_7.do.txt *****************
TITLE: Some exercise without the "Exercise:" prefix
AUTHOR: Jane Doe Email:jane.doe@cyberspace.net
DATE: Due Jan 32, 2100


# Another minimalistic exercise

Just some text. And some math saying that $e^0=1$ on a single line,
to test that math block insertion is correct:

!bt
\[ \exp{(0)} = 1 \]
!et

And a test that the code `lambda x: x+2` is correctly placed here:

!bc
lambda x: x+2
!ec


# Have some comments at the end of the exercise to see that
# the Filename: ... is written correctly.

************** File: standalone_exercises/myexer1.do.txt *****************
TITLE: Exercise 3: Test of plain text exercise
AUTHOR: Jane Doe Email:jane.doe@cyberspace.net
DATE: Due Jan 32, 2100

# Logical name of exercise: myexer1



Very short exercise. What is the capital
of Norway?

************** File: standalone_exercises/exercise_8.do.txt *****************
TITLE: Exercise 8: Solution of differential equation
AUTHOR: Jane Doe Email:jane.doe@cyberspace.net
DATE: Due Jan 32, 2100




Given

!bt
\[ \frac{dy}{dx} = -y(x),\quad y(0)=1 \]
!et
What is the solution of this equation?


$y=e^{-y}$

$y=e^{y}$

Almost, but the sign is wrong (note the minus!).

!bc pycod
from math import exp
def f(x):
    return exp(x)
!ec

Ooops, forgot a minus: `exp(-x)`, otherwise this Python code
must be considered as a good answer. It is more natural,
though, to write the solution to the problem
in mathematical notation:

!bt
\[ y(x) = e^{-y}.\]
!et

The solution cannot be found because there is a derivative in the equation.

Equations with derivatives can be solved;
they are termed *differential
equations*.

The equation is meaningless: an equation must be an equation
for $x$ or $y$, not a function $y(x)$.

Equations where the unknown is a function, as $y(x)$
here, are called *differential equations*, and are solved by
special techniques.

************** File: standalone_exercises/exercise_9.do.txt *****************
TITLE: Example 9: Just an example
AUTHOR: Jane Doe Email:jane.doe@cyberspace.net
DATE: Due Jan 32, 2100


# This example needs the --examples_as_exercises option, otherwise
# it is just typeset as it is written.


__a)__
What is the capital of Norway?

__Answer.__
Oslo.

************** File: standalone_exercises/norm.do.txt *****************
TITLE: Project 5: Explore Distributions of Random Circles
AUTHOR: Jane Doe Email:jane.doe@cyberspace.net
DATE: Due Jan 32, 2100

# Logical name of exercise: norm
# This document contains references to a parent document (../testdoc).
# These references will work for latex (using the xr package and
# a compiled parent document (with ../testdoc.aux file), but other formats
# will have missing references.
# Externaldocuments: ../testdoc


# keywords = ipynb

The formula for a circle is given by

!bt
\begin{align}
x &= x_0 + R\cos 2\pi t,
label{circle:x}\\ 
y &= y_0 + R\sin 2\pi t,
label{circle:y}
\end{align}
!et
where $R$ is the radius of the circle, $(x_0,y_0)$ is the
center point, and $t$ is a parameter in the unit interval $[0,1]$.
For any $t$, $(x,y)$ computed from (ref{circle:x})-(ref{circle:y})
is a point on the circle.
The formula can be used to generate `n` points on a circle:

!bc pypro
import numpy as np

def circle(R, x0, y0, n=501):
    t = np.linspace(0, 1, n)
    x = x0 + R*np.cos(2*np.pi*t)
    y = y0 + R*np.sin(2*np.pi*t)
    return x, y

x, y = circle(2.0, 0, 0)
!ec

# Often in an exercise we have some comments about the solution
# which we normally want to keep where they are.

The goal of this project is to draw $N$ circles with random
center and radius. Plot each circle using the `circle` function
above.


__a)__
Let $R$ be normally distributed and $(x_0,y_0)$ uniformly distributed.


__Hint.__
Use the `numpy.random` module to draw the
$x_0$, $y_0$, and $R$ quantities.






__b)__
Let $R$ be uniformly distributed and $(x_0,y_0)$ normally distributed.


__c)__
Let $R$ and $(x_0,y_0)$ be normally distributed.




# Closing remarks for this Project

=== Remarks ===

At the very end of the exercise it may be appropriate to summarize
and give some perspectives.

************** File: standalone_exercises/index.do.txt *****************
TITLE: List of stand-alone files with exercises

# Edit FILE_EXTENSIONS to the type of documents that will
# be listed in the this index
<%
FILE_EXTENSIONS = ['.tex', '.ipynb']
#FILE_EXTENSIONS = ['.tex', '.ipynb', '.do.txt', '.html']
%>

% for EXT in FILE_EXTENSIONS:
`exercise_1${EXT}`": "exercise_1${EXT}
% endfor
<linebreak>

% for EXT in FILE_EXTENSIONS:
`flip_coin${EXT}`": "flip_coin${EXT}
% endfor
<linebreak>

% for EXT in FILE_EXTENSIONS:
`myexer1${EXT}`": "myexer1${EXT}
% endfor
<linebreak>

% for EXT in FILE_EXTENSIONS:
`exercise_4${EXT}`": "exercise_4${EXT}
% endfor
<linebreak>

% for EXT in FILE_EXTENSIONS:
`norm${EXT}`": "norm${EXT}
% endfor
<linebreak>

% for EXT in FILE_EXTENSIONS:
`subexer_a${EXT}`": "subexer_a${EXT}
% endfor
<linebreak>

% for EXT in FILE_EXTENSIONS:
`exercise_7${EXT}`": "exercise_7${EXT}
% endfor
<linebreak>

% for EXT in FILE_EXTENSIONS:
`exercise_8${EXT}`": "exercise_8${EXT}
% endfor
<linebreak>

% for EXT in FILE_EXTENSIONS:
`exercise_9${EXT}`": "exercise_9${EXT}
% endfor
<linebreak>

% for EXT in FILE_EXTENSIONS:
`verify_formula${EXT}`": "verify_formula${EXT}
% endfor
<linebreak>

% for EXT in FILE_EXTENSIONS:
`selc_composed${EXT}`": "selc_composed${EXT}
% endfor
<linebreak>


************** File: standalone_exercises/make.py *****************
#!/usr/bin/env python
# Compile all stand-alone exercises to latex and ipynb
# (Must first unzip archive)

import glob, os

dofiles = glob.glob('*.do.txt')
dofiles.remove('index.do.txt')   # compile to html only

for dofile in dofiles:
    cmd = 'doconce format pdflatex %s --latex_code_style=vrb --figure_prefix=../ --movie_prefix=../' % dofile
    os.system(cmd)
    # Edit .tex file and remove doconce-specific things
    cmd = 'doconce subst "%% #.+" "" %s.tex' % dofile[:-7]  # preprocess
    os.system(cmd)
    cmd = 'doconce subst "%%.*" "" %s.tex' % dofile[:-7]

    cmd = 'doconce format ipynb %s --figure_prefix=../  --movie_prefix=../' % dofile
    os.system(cmd)

# Edit FILE_EXTENSIONS to adjust what kind of files that is listed in index.html
cmd = 'doconce format html index --html_style=bootstrap'
os.system(cmd)

************** File: Springer_T2/standalone_exercises/Chapter_2.1.do.txt *****************
TITLE: Problem 2.1: Add numbers
AUTHOR: Jane Doe Email:jane.doe@cyberspace.net
DATE: Due Jan 32, 2100

# Logical name of exercise: add



Compute

!bt
\[ 1 + 1 \]
!et





************** File: Springer_T2/standalone_exercises/Chapter_2.2.do.txt *****************
TITLE: Problem 2.2: Multiply numbers
AUTHOR: Jane Doe Email:jane.doe@cyberspace.net
DATE: Due Jan 32, 2100

# Logical name of exercise: multiply




__a)__
Compute $1\cdot 3$.



__b)__
Compute $2\cdot 3$.


__Hint.__
Use a Python shell.




************** File: Springer_T2/standalone_exercises/index.do.txt *****************
TITLE: List of stand-alone files with exercises

# Edit FILE_EXTENSIONS to the type of documents that will
# be listed in the this index
<%
FILE_EXTENSIONS = ['.tex', '.ipynb']
#FILE_EXTENSIONS = ['.tex', '.ipynb', '.do.txt', '.html']
%>

========= Chapter: Storing results in data files and adding more words here to get a very long chapter heading =========

% for EXT in FILE_EXTENSIONS:
`Chapter_2.1${EXT}`": "Chapter_2.1${EXT}
% endfor
<linebreak>

% for EXT in FILE_EXTENSIONS:
`Chapter_2.2${EXT}`": "Chapter_2.2${EXT}
% endfor
<linebreak>


************** File: Springer_T2/standalone_exercises/make.py *****************
#!/usr/bin/env python
# Compile all stand-alone exercises to latex and ipynb
# (Must first unzip archive)

import glob, os

dofiles = glob.glob('*.do.txt')
dofiles.remove('index.do.txt')   # compile to html only

for dofile in dofiles:
    cmd = 'doconce format pdflatex %s --latex_code_style=vrb --figure_prefix=../ --movie_prefix=../' % dofile
    os.system(cmd)
    # Edit .tex file and remove doconce-specific things
    cmd = 'doconce subst "%% #.+" "" %s.tex' % dofile[:-7]  # preprocess
    os.system(cmd)
    cmd = 'doconce subst "%%.*" "" %s.tex' % dofile[:-7]

    cmd = 'doconce format ipynb %s --figure_prefix=../  --movie_prefix=../' % dofile
    os.system(cmd)

# Edit FILE_EXTENSIONS to adjust what kind of files that is listed in index.html
cmd = 'doconce format html index --html_style=bootstrap'
os.system(cmd)

************** File: tmp_DocOnce.do.txt *****************

TITLE: My Test of Class DocOnce
AUTHOR: Hans Petter Langtangen; Simula Research Laboratory; Dept. of Informatics, Univ. of Oslo
DATE: Jan 32, 2100



======= First Section =======


Here is some
text for section 1.

This is a *first* example of using the _DocWriter
module_ for writing documents from *Python* scripts.
It could be a nice tool since we do not need to bother
with special typesetting, such as `fixed width fonts`
in plain text.

===== First Subsection =====

Some text for the subsection.

__Test of a Paragraph.__ 
Some paragraph text taken from "Documenting Python": The Python language
has a substantial body of documentation, much of it contributed by various
authors. The markup used for the Python documentation is based on
LaTeX and requires a significant set of macros written specifically
for documenting Python. This document describes the macros introduced
to support Python documentation and how they should be used to support
a wide range of output formats.

This document describes the document classes and special markup used
in the Python documentation. Authors may use this guide, in
conjunction with the template files provided with the distribution, to
create or maintain whole documents or sections.

If you're interested in contributing to Python's documentation,
there's no need to learn LaTeX if you're not so inclined; plain text
contributions are more than welcome as well.
Here is an enumerate list:
o item1
o item2

    o subitem1
    o subitem2

o item3

    o subitem3
    o subitem4
...with some trailing text.
=== First Subsubsection with an Itemize List ===


* item1
* item2

    * subitem1
    * subitem2

* item3

    * subitem3
    * subitem4
Here is some Python code:
!bc

class A:
    pass

class B(A):
    pass

b = B()
b.item = 0  # create a new attribute

!ec

======= Second Section =======

Here is a description list:
- keyword1:  item1
- keyword2:  item2 goes here, with a colon : and some text after

    - key3:  subitem1
    - key4:  subitem2

- key5:  item3

    - key6:  subitem3
    - key7:  subitem4


And here is a table:

   |---------------------------------------|
   | a                 | b                 |
   | c                 | d                 |
   | e                 | and a longer text |
   |---------------------------------------|


************** File: tmp_DocWriter.do.txt *****************

TITLE: My Test of Class DocWriter
AUTHOR: Hans Petter Langtangen; Simula Research Laboratory; Dept. of Informatics, Univ. of Oslo
DATE: Jan 32, 2100



======= First Section =======


Here is some
text for section 1.

This is a *first* example of using the _DocWriter
module_ for writing documents from *Python* scripts.
It could be a nice tool since we do not need to bother
with special typesetting, such as `fixed width fonts`
in plain text.

===== First Subsection =====

Some text for the subsection.

__Test of a Paragraph.__ 
Some paragraph text taken from "Documenting Python": The Python language
has a substantial body of documentation, much of it contributed by various
authors. The markup used for the Python documentation is based on
LaTeX and requires a significant set of macros written specifically
for documenting Python. This document describes the macros introduced
to support Python documentation and how they should be used to support
a wide range of output formats.

This document describes the document classes and special markup used
in the Python documentation. Authors may use this guide, in
conjunction with the template files provided with the distribution, to
create or maintain whole documents or sections.

If you're interested in contributing to Python's documentation,
there's no need to learn LaTeX if you're not so inclined; plain text
contributions are more than welcome as well.
Here is an enumerate list:
o item1
o item2

    o subitem1
    o subitem2

o item3

    o subitem3
    o subitem4
...with some trailing text.
=== First Subsubsection with an Itemize List ===


* item1
* item2

    * subitem1
    * subitem2

* item3

    * subitem3
    * subitem4
Here is some Python code:
!bc

class A:
    pass

class B(A):
    pass

b = B()
b.item = 0  # create a new attribute

!ec

======= Second Section =======

Here is a description list:
- keyword1:  item1
- keyword2:  item2 goes here, with a colon : and some text after

    - key3:  subitem1
    - key4:  subitem2

- key5:  item3

    - key6:  subitem3
    - key7:  subitem4


And here is a table:

   |---------------------------------------|
   | a                 | b                 |
   | c                 | d                 |
   | e                 | and a longer text |
   |---------------------------------------|


************** File: tmp_DocWriter.html *****************
<!-- HTML document generated by __main__.HTML -->
<html>
<body bgcolor="white">

<title>My Test of Class DocWriter</title>
<center><h1>My Test of Class DocWriter</h1></center>

<center>
<h4>Hans Petter Langtangen</h4>
<h6>Simula Research Laboratory</h6>
<h6>Dept. of Informatics, Univ. of Oslo</h6>
</center>

<center>Jan 32, 2100</center>



<p>

<h1>First Section</h1>

Here is some
text for section 1.

This is a <em>first</em> example of using the <b>DocWriter
module</b> for writing documents from <em>Python</em> scripts.
It could be a nice tool since we do not need to bother
with special typesetting, such as <tt>fixed width fonts</tt>
in plain text.

<h3>First Subsection</h3>
Some text for the subsection.

<p><!-- paragraph with heading -->
<b>Test of a Paragraph.</b>

Some paragraph text taken from "Documenting Python": The Python language
has a substantial body of documentation, much of it contributed by various
authors. The markup used for the Python documentation is based on
LaTeX and requires a significant set of macros written specifically
for documenting Python. This document describes the macros introduced
to support Python documentation and how they should be used to support
a wide range of output formats.

This document describes the document classes and special markup used
in the Python documentation. Authors may use this guide, in
conjunction with the template files provided with the distribution, to
create or maintain whole documents or sections.

If you're interested in contributing to Python's documentation,
there's no need to learn LaTeX if you're not so inclined; plain text
contributions are more than welcome as well.
Here is an enumerate list:
<ol> <!-- start of "enumerate" list -->
<p><li> item1
<p><li> item2

  <ol> <!-- start of "enumerate" list -->
    <p><li> subitem1
    <p><li> subitem2
  </ol> <!-- end of "enumerate" list -->
<p><li> item3

  <ol> <!-- start of "enumerate" list -->
    <p><li> subitem3
    <p><li> subitem4
  </ol> <!-- end of "enumerate" list -->
</ol> <!-- end of "enumerate" list -->
...with some trailing text.
<h4>First Subsubsection with an Itemize List</h4>

<ul> <!-- start of "itemize" list -->
<p><li> item1
<p><li> item2

  <ul> <!-- start of "itemize" list -->
    <p><li> subitem1
    <p><li> subitem2
  </ul> <!-- end of "itemize" list -->
<p><li> item3

  <ul> <!-- start of "itemize" list -->
    <p><li> subitem3
    <p><li> subitem4
  </ul> <!-- end of "itemize" list -->
</ul> <!-- end of "itemize" list -->
Here is some Python code:
<pre>
class A:
    pass

class B(A):
    pass

b = B()
b.item = 0  # create a new attribute

</pre>

<h1>Second Section</h1>
Here is a description list:
<dl> <!-- start of "description" list -->
<p><dt>keyword1</dt><dd> item1</dd>
<p><dt>keyword2</dt><dd> item2 goes here, with a colon : and some text after</dd>

  <dl> <!-- start of "description" list -->
    <p><dt>key3</dt><dd> subitem1</dd>
    <p><dt>key4</dt><dd> subitem2</dd>
  </dl> <!-- end of "description" list -->
<p><dt>key5</dt><dd> item3</dd>

  <dl> <!-- start of "description" list -->
    <p><dt>key6</dt><dd> subitem3</dd>
    <p><dt>key7</dt><dd> subitem4</dd>
  </dl> <!-- end of "description" list -->
</dl> <!-- end of "description" list -->

<p>
And here is a table:
<p>
<table border="2" cellpadding="5" cellspacing="2">
<tr><td>a</td><td>b</td></tr>
<tr><td>c</td><td>d</td></tr>
<tr><td>e</td><td>and a longer text</td></tr>
</table>


</body>
</html>

************** File: tmp_HTML.html *****************
<!-- HTML document generated by __main__.HTML -->
<html>
<body bgcolor="white">

<title>My Test of Class HTML</title>
<center><h1>My Test of Class HTML</h1></center>

<center>
<h4>Hans Petter Langtangen</h4>
<h6>Simula Research Laboratory</h6>
<h6>Dept. of Informatics, Univ. of Oslo</h6>
</center>

<center>Jan 32, 2100</center>



<p>

<h1>First Section</h1>

Here is some
text for section 1.

This is a <em>first</em> example of using the <b>DocWriter
module</b> for writing documents from <em>Python</em> scripts.
It could be a nice tool since we do not need to bother
with special typesetting, such as <tt>fixed width fonts</tt>
in plain text.

<h3>First Subsection</h3>
Some text for the subsection.

<p><!-- paragraph with heading -->
<b>Test of a Paragraph.</b>

Some paragraph text taken from "Documenting Python": The Python language
has a substantial body of documentation, much of it contributed by various
authors. The markup used for the Python documentation is based on
LaTeX and requires a significant set of macros written specifically
for documenting Python. This document describes the macros introduced
to support Python documentation and how they should be used to support
a wide range of output formats.

This document describes the document classes and special markup used
in the Python documentation. Authors may use this guide, in
conjunction with the template files provided with the distribution, to
create or maintain whole documents or sections.

If you're interested in contributing to Python's documentation,
there's no need to learn LaTeX if you're not so inclined; plain text
contributions are more than welcome as well.
Here is an enumerate list:
<ol> <!-- start of "enumerate" list -->
<p><li> item1
<p><li> item2

  <ol> <!-- start of "enumerate" list -->
    <p><li> subitem1
    <p><li> subitem2
  </ol> <!-- end of "enumerate" list -->
<p><li> item3

  <ol> <!-- start of "enumerate" list -->
    <p><li> subitem3
    <p><li> subitem4
  </ol> <!-- end of "enumerate" list -->
</ol> <!-- end of "enumerate" list -->
...with some trailing text.
<h4>First Subsubsection with an Itemize List</h4>

<ul> <!-- start of "itemize" list -->
<p><li> item1
<p><li> item2

  <ul> <!-- start of "itemize" list -->
    <p><li> subitem1
    <p><li> subitem2
  </ul> <!-- end of "itemize" list -->
<p><li> item3

  <ul> <!-- start of "itemize" list -->
    <p><li> subitem3
    <p><li> subitem4
  </ul> <!-- end of "itemize" list -->
</ul> <!-- end of "itemize" list -->
Here is some Python code:
<pre>
class A:
    pass

class B(A):
    pass

b = B()
b.item = 0  # create a new attribute

</pre>

<h1>Second Section</h1>
Here is a description list:
<dl> <!-- start of "description" list -->
<p><dt>keyword1</dt><dd> item1</dd>
<p><dt>keyword2</dt><dd> item2 goes here, with a colon : and some text after</dd>

  <dl> <!-- start of "description" list -->
    <p><dt>key3</dt><dd> subitem1</dd>
    <p><dt>key4</dt><dd> subitem2</dd>
  </dl> <!-- end of "description" list -->
<p><dt>key5</dt><dd> item3</dd>

  <dl> <!-- start of "description" list -->
    <p><dt>key6</dt><dd> subitem3</dd>
    <p><dt>key7</dt><dd> subitem4</dd>
  </dl> <!-- end of "description" list -->
</dl> <!-- end of "description" list -->

<p>
And here is a table:
<p>
<table border="2" cellpadding="5" cellspacing="2">
<tr><td>a</td><td>b</td></tr>
<tr><td>c</td><td>d</td></tr>
<tr><td>e</td><td>and a longer text</td></tr>
</table>


</body>
</html>

************** File: make.sh *****************
#!/bin/bash -x
#set -x
#export PS4='+ l.${LINENO}: ${FUNCNAME[0]:+${FUNCNAME[0]}(): }'
name=quickref

function system {
  "$@"
  if [ $? -ne 0 ]; then
    echo "make.sh: unsuccessful command $@"
    echo "abort!"
    exit 1
  fi
}

set -x
sh ./clean.sh

# Mako include cannot accept ../manual/quidelines.do.txt so we need a local link
if [ ! -L guidelines.do.txt ]; then
    ln -s ../manual/guidelines.do.txt guidelines.do.txt
fi

# Make latest bin/doconce doc. The next commands will print this output to $name.html and $name.tex
# Use sed to replace terminal colors (four special characters per line) or pdflatex will halt
doconce > doconce_program.sh
sed -i 's/^\x1b\[[0-9;]*m//' doconce_program.sh
sed -i 's/\x1b\[[0-9;]*m//' doconce_program.sh
sed -i 's/\x1b\[[0-9;]*m\s*/\n# /' doconce_program.sh
sed -i 's/\x1b\[[0-9;]*m//g' doconce_program.sh

system doconce format html $name --pygments_html_style=none --no_preprocess --no_abort --html_style=bootswatch_readable

# This document has error message from multiple labels: some:fig:label
# (because the document is a doconce instruction!)

# pdflatex
system doconce format pdflatex $name --no_preprocess --latex_font=helvetica --no_ampersand_quote --latex_code_style=vrb --no_abort

# Since we have native latex table and --no_ampersand_quote, we need to
# manually fix the quote examples elsewhere
doconce subst '([^`])Guns & Roses([^`])' '\g<1>Guns {\&} Roses\g<2>' $name.tex
doconce subst '([^`])Texas A & M([^`])' '\g<2>Texas A {\&} M\g<2>' $name.tex
system pdflatex -shell-escape $name
system pdflatex -shell-escape $name

# Sphinx
system doconce format sphinx $name --no_preprocess --no_abort
rm -rf sphinx-rootdir
#ALE problem reproducible after: `git clean -fd && rm -rf sphinx-rootdir`
#Hack: because doconce sphinx_dir ony works the second time (after an error), trigger that error by creating a bogus conf.py in ./
touch conf.py
system doconce sphinx_dir theme=cbc $name dirname=sphinx-rootdir
doconce replace 'doconce format sphinx %s' 'doconce format sphinx %s --no-preprocess' automake_sphinx.py
system python automake_sphinx.py
cp $name.rst $name.sphinx.rst  # save

# reStructuredText:
system doconce format rst $name --no_preprocess --no_abort
rst2xml.py $name.rst > $name.xml
rst2odt.py $name.rst > $name.odt
rst2html.py $name.rst > $name.rst.html
rst2latex.py $name.rst > $name.rst.tex
system latex $name.rst.tex
latex $name.rst.tex
dvipdf $name.rst.dvi

# Other formats:
system doconce format plain $name --no_preprocess --no_abort
system doconce format gwiki $name --no_preprocess --no_abort
system doconce format mwiki $name --no_preprocess --no_abort
system doconce format cwiki $name --no_preprocess --no_abort
system doconce format st $name --no_preprocess --no_abort
system doconce format epytext $name --no_preprocess --no_abort
system doconce format pandoc $name --no_preprocess --strict_markdown_output --github_md --no_abort

rm -rf demo
mkdir demo
cp -r $name.do.txt $name.html $name.p.tex $name.tex $name.pdf $name.rst $name.xml $name.rst.html $name.rst.tex $name.rst.pdf $name.gwiki $name.mwiki $name.cwiki $name.txt $name.epytext $name.st $name.md sphinx-rootdir/_build/html demo

cd demo
cat > index.html <<EOF
<HTML><BODY>
<TITLE>Demo of Doconce formats</TITLE>
<H3>Doconce demo</H3>

Doconce is a minimum tagged markup language. The file
<a href="$name.do.txt">$name.do.txt</a> is the source of the
Doconce $name, written in the Doconce format.
Running
<pre>
doconce format html $name.do.txt
</pre>
produces the HTML file <a href="$name.html">$name.html</a>.
Going from Doconce to LaTeX is done by
<pre>
doconce format latex $name.do.txt
</pre>
resulting in the file <a href="$name.tex">$name.tex</a>, which can
be compiled to a PDF file <a href="$name.pdf">$name.pdf</a>
by running <tt>latex</tt> and <tt>dvipdf</tt> the standard way.
<p>
The reStructuredText (reST) format is of particular interest:
<pre>
doconce format rst    $name.do.txt  # standard reST
doconce format sphinx $name.do.txt  # Sphinx extension of reST
</pre>
The reST file <a href="$name.rst">$name.rst</a> is a starting point
for conversion to many other formats: OpenOffice,
<a href="$name.xml">XML</a>, <a href="$name.rst.html">HTML</a>,
<a href="$name.rst.tex">LaTeX</a>,
and from LaTeX to <a href="$name.rst.pdf">PDF</a>.
The <a href="$name.sphinx.rst">Sphinx</a> dialect of reST
can be translated to <a href="$name.sphinx.pdf">PDF</a>
and <a href="html/index.html">HTML</a>.
<p>
Doconce can also be converted to
<a href="$name.gwiki">Googlecode wiki</a>,
<a href="$name.mwiki">MediaWiki</a>,
<a href="$name.cwiki">Creole wiki</a>,
<a href="$name.md">aPandoc</a>,
<a href="$name.st">Structured Text</a>,
<a href="$name.epytext">Epytext</a>,
and maybe the most important format of all:
<a href="$name.txt">plain untagged ASCII text</a>.
</BODY>
</HTML>
EOF

echo
echo "Go to the demo directory $PWD and load index.html into a web browser."

cd ..
dest=../../pub/$name
cp -r demo/html demo/$name.pdf demo/$name.html $dest

dest=../../../../doconce.wiki
cp -r demo/$name.md $dest

************** File: quickref.do.txt *****************
TITLE: DocOnce Quick Reference
AUTHOR: Hans Petter Langtangen at Center for Biomedical Computing, Simula Research Laboratory & Department of Informatics, University of Oslo
DATE: today
TOC: on

_WARNING: This quick reference is very incomplete!_

__Mission.__ Enable writing documentation with much mathematics and
computer code *once, in one place* and include it in traditional LaTeX
books, thesis, and reports, and, without extra efforts, also make
professional looking web versions with Sphinx or HTML. Other outlets
include Google's `blogger.com`, Wikipedia/Wikibooks, IPython/Jupyter
notebooks, plus a wide variety of other formats for documents without
mathematics and code.

===== Supported Formats =====

DocOnce currently translates files to the following formats:

 * LaTeX (format `latex` or `pdflatex`)
 * HTML (format `html`)
 * Sphinx (format `sphinx`)
 * Pandoc-extended or GitHub-flavored Markdown (format `pandoc`)
 * IPython notebook (format `ipynb`)
 * Matlab notebook (format `matlabnb`)
 * MediaWiki (format `mwiki`)
 * Googlecode wiki (format `gwiki`)
 * Creoloe wiki (format `cwiki`)
 * reStructuredText (format `rst`)
 * plain (untagged) ASCII (format `plain`)
 * Epydoc (format `epydoc`)
 * StructuredText (format `st`)

For documents with much code and mathematics, the best (and most supported)
formats are `latex`, `pdflatex`, `sphinx`, and `html`; and to a slightly
less extent `mwiki` and `pandoc`. The HTML format supports blog posts on
Google and Wordpress.

!bwarning Use a text editor with monospace font!
Some DocOnce constructions are sensitive to whitespace,
so you *must* use a text editor with monospace font.
!ewarning

===== Emacs syntax support =====

The file ".doconce-mode.el":
"https://github.com/doconce/doconce/blob/master/misc/.doconce-mode.el"
in the DocOnce source distribution gives a "DocOnce Editing Mode" in
Emacs. Store the raw version of the file in the home directory and add
`(load-file "~/.doconce-mode.el")` to the `.emacs` file.

Besides syntax highlighting of DocOnce documents, this Emacs mode
provides a lot of shortcuts for setting up many elements in a document:

|--------------------------------------------------------|
| Emacs key      | Action                                |
|----l-------------------------l-------------------------|
|  Ctrl+c f      | figure                                |
|  Ctrl+c v      | movie/video                           |
|  Ctrl+c h1     | heading level 1 (section/h1)          |
|  Ctrl+c h2     | heading level 2 (subsection/h2)       |
|  Ctrl+c h3     | heading level 2 (subsection/h3)       |
|  Ctrl+c hp     | heading for paragraph                 |
|  Ctrl+c me     | math environment: `!bt` equation `!et`|
|  Ctrl+c ma     | math environment: `!bt` align `!et`   |
|  Ctrl+c ce     | code environment: `!bc` code `!ec`    |
|  Ctrl+c cf     | code from file: `@@@CODE`             |
|  Ctrl+c table2 | table with 2 columns                  |
|  Ctrl+c table3 | table with 3 columns                  |
|  Ctrl+c table4 | table with 4 columns                  |
|  Ctrl+c exer   | exercise outline                      |
|  Ctrl+c slide  | slide outline                         |
|  Ctrl+c help   | print this table                      |
|--------------------------------------------------------|

===== Title, Authors, and Date =====

A typical example of giving a title, a set of authors, a date,
and an optional table of contents
reads

!bc do
TITLE: On an Ultimate Markup Language
AUTHOR: H. P. Langtangen at Center for Biomedical Computing, Simula Research Laboratory & Dept. of Informatics, Univ. of Oslo
AUTHOR: Kaare Dump Email: dump@cyb.space.com at Segfault, Cyberspace Inc.
AUTHOR: A. Dummy Author
DATE: today
TOC: on
!ec
The entire title must appear on a single line.
The author syntax is
!bc
name Email: somename@adr.net at institution1 & institution2
!ec
where the email is optional, the "at" keyword is required if one or
more institutions are to be specified, and the `&` keyword
separates the institutions (the keyword `and` works too).
Each author specification must appear
on a single line.
When more than one author belong to the
same institution, make sure that the institution is specified in an identical
way for each author.

The date can be set as any text different from `today` if not the
current date is wanted, e.g., `Jan 32, 2100`.

The table of contents is removed by writing `TOC: off`.

===== Copyright =====

# Recall to ident AUTHOR commands to avoid interpretation

Copyright for selected authors and/or institutions are easy to insert as part
of the `AUTHOR` command. The copyright syntax is

!bc do
{copyright,year1-year2|license}
!ec
and can be placed after the author or after an institution, e.g.,

!bc do
 AUTHOR: name Email: somename@adr.net {copyright,2006-present} at inst1
 AUTHOR: name {copyright} at inst1 {copyright}
!ec
The first line gives `name` a copyright for 2006 up to the present year,
while the second line gives copyright to `name` and the institution `inst1`
for the present year. The license can be any formulation, but there are
some convenient abbreviations for Creative Commons (``public domain'')
licenses: `CC BY` for Creative Commons Attribution 4.0 license,
`CC BY-NC` for Creative Commons Attribution-NonCommercial 4.0 license.
For example,

!bc do
 AUTHOR: name1 {copyright|CC BY} at institution1
 AUTHOR: name2 {copyright|CC BY} at institution2
!ec
is a very common copyright for the present year with the Attribution license.
The copyright must be identical for all authors and institutions.


===== Section Types =====
label{quick:sections}

|----------------c---------------------------c---------------------------|
|      Section type       |        Syntax                                |
|----------------l---------------------------l---------------------------|
| chapter                 | `========= Heading ========` (9 `=`)         |
| section                 | `======= Heading =======`    (7 `=`)         |
| subsection              | `===== Heading =====`        (5 `=`)         |
| subsubsection           | `=== Heading ===`            (3 `=`)         |
| paragraph               | `__Heading.__`               (2 `_`)         |
| abstract                | `__Abstract.__` Running text...              |
| appendix                | `======= Appendix: heading =======` (7 `=`)  |
| appendix                | `===== Appendix: heading =====` (5 `=`)      |
| exercise                | `===== Exercise: heading =====` (5 `=`)      |
|------------------------------------------------------------------------|

Note that abstracts are recognized by starting with `__Abstract.__` or
`__Summary.__` at the beginning of a line and ending with three or
more `=` signs of the next heading.

The `Exercise:` keyword can be substituted by `Problem:` or `Project:`.
A recommended convention is that an exercise is tied to the text,
a problem can stand on its own, and a project is a comprehensive
problem.

===== Inline Formatting =====

Words surrounded by `*` are emphasized: `*emphasized words*` becomes
*emphasized words*. Similarly, an underscore surrounds words that
appear in boldface: `_boldface_` becomes _boldface_. Colored words
are also possible: the text

!bc
`color{red}{two red words}`
!ec
becomes color{red}{two red words}.
% if FORMAT not in ("latex", "pdflatex", "html"):
(But colors do not work in format ${FORMAT}).
% endif

Quotations appear inside double backticks and double single quotes:

!bc
This is a sentence with ``words to be quoted''.
!ec

A forced linebreak is specified by `<linebreak>` at the point where the
linebreak in the output is wanted.

Footnotes use a label in the text with the footnote text separate,
preferably after the paragraph where the footnote appears:

!bc
Differentiating[^diff2] this equation leads
to a new and much simpler equation.

[^diff2]: More precisely, we apply the divergence
$\nabla\cdot$ on both sides.

Here comes a new paragraph...
!ec

Non-breaking space is inserted using the tilde character as in LaTeX:

!bc
This distance corresponds to 7.5~km, which is traveled in $7.5/5$~s.
!ec

A horizontal rule for separating content vertically, like this:

-----

is typeset as four or more hyphens on a single line:

!bc
---------
!ec

The `latex`, `pdflatex`, `sphinx`, and `html` formats support em-dash,
indicated by three hyphens: `---`. Here is an example:

!bc
The em-dash is used - without spaces - as alternative to hyphen with
space around in sentences---this way, or in quotes:
*Premature optimization is the root of all evil.*--- Donald Knuth.
!ec
This text is in the ${FORMAT} rendered as

The em-dash is used - without spaces - as alternative to hyphen with
space around in sentences---this way, or in quotes:
*Premature optimization is the root of all evil.*--- Donald Knuth.

The en-dash consists of two hyphens, either with blanks on both sides -- for
something in the middle of a sentence -- or in number ranges like 240--249.
LaTeX writes are used to and fond of en-dash.

An ampersand, as in Guns & Roses or Texas A & M, is written as a
plain `&` *with space(s) on both sides*. Single upper case letters on each
side of `&`, as in `Texas A & M`, remove the spaces and result in
Texas A & M, while words on both sides of `&`, as in `Guns & Roses`,
preserve the spaces: Guns & Roses. Failing to have spaces before and
after `&` will result in wrong typesetting of the ampersand in the `html`,
`latex`, and `pdflatex` formats.

Emojis, as defined in URL: "http://www.emoji-cheat-sheet.com", can be
inserted in the text, as (e.g.) `:dizzy_face:` with blank or newline
before or after :dizzy_face: Only the `pdflatex`, `html`, and `pandoc` output
formats translate emoji specifications to images, while all other
formats leave the textual specification in the document. The
command-line option `--no_emoji` removes all emojis from the output
document.

===== Lists =====

There are three types of lists: *bullet lists*, where each item starts
with `*`, *enumeration lists*, where each item starts with `o` and gets
consecutive numbers,
and *description* lists, where each item starts with `-` followed
by a keyword and a colon.
!bc
Here is a bullet list:

 * item1
 * item2
  * subitem1 of item2
  * subitem2 of item2,
    second line of subitem2
 * item3

Note that sublists are consistently indented by one or more blanks as
shown: bullets must exactly match and continuation lines must start
right below the line above.

Here is an enumeration list:

 o item1
 o item2
   may appear on
   multiple lines
  o subitem1 of item2
  o subitem2 of item2
 o item3

And finally a description list:

 - keyword1: followed by
   some text
   over multiple
   lines
 - keyword2:
   followed by text on the next line
 - keyword3: and its description may fit on one line
!ec
The code above follows.

Here is a bullet list:

 * item1
 * item2
  * subitem1 of item2
  * subitem2 of item2
 * item3

Note that sublists are consistently indented by one or more blanks as
shown: bullets must exactly match and continuation lines must start
right below the line above.

Here is an enumeration list:

 o item1
 o item2
   may appear on
   multiple lines
  o subitem1 of item2
  o subitem2 of item2
 o item3

And finally a description list:

 - keyword1: followed by
   some text
   over multiple
   lines
 - keyword2:
   followed by text on the next line
 - keyword3: and its description may fit on one line


!bwarning No indentation - except in lists!
DocOnce syntax is sensitive to whitespace.
No lines should be indented, only lines belonging to lists.
Indented lines may give strange output in some formats.
!ewarning


===== Comment lines =====

Lines starting with `#` are treated as comments in the document and
translated to the proper syntax for comments in the output
document. Such comment lines should not appear before LaTeX math
blocks, verbatim code blocks, or lists if the formats `rst` and
`sphinx` are desired.

Comment lines starting with `##` are not propagated to the output
document and can be used for comments that are only of interest in
the DocOnce file.

Large portions of text can be left out using Preprocess. Just place
`# #ifdef EXTRA` and `# #endif` around the text. The command line
option `-DEXTRA` will bring the text alive again.

When using the Mako preprocessor one can also place comments in
the DocOnce source file that will be removed by Mako before
DocOnce starts processing the file.


===== Inline comments =====

Inline comments meant as messages or notes, to authors during development
in particular,
are enabled by the syntax
!bc
[name: running text]
!ec
where `name` is the name or ID of an author or reader making the comment,
and `running text` is the comment. The name can contain upper and lower
case characters, digits, single quote, `+` and `-`, as well
as space. Here goes an example.

!bc
Some running text. [hpl: There must be a space after the colon,
but the running text can occupy multiple lines.]
!ec
which is rendered as

!bquote
Some running text. [hpl: There must be a space after the colon,
but the running text can occupy multiple lines.]
!equote

The inline comments have simple typesetting in most formats, typically
boldface name, a comment number, with everything surrounded by
parenthesis.  However, with LaTeX output and the `--latex_todonotes`
option to `doconce format`, colorful margin or inline boxes (using the
`todonotes` package) make it very easy to spot the comments.

Running
!bc sys
doconce format html mydoc.do.txt --skip_inline_comments
!ec
removes all inline comments from the output. This feature makes it easy
to turn on and off notes to authors during the development of the document.

All inline comments to readers can also be physically
removed from the DocOnce source by
!bc sys
doconce remove_inline_comments mydoc.do.txt
!ec

Inline comments can also be used to markup edits. There are add, delete, and
replacement comments for editing:

!bc
[add: ,]
[add: .]
[add: ;]
[del: ,]
[del: ,]
[del: .]
[del: ;]
[add: some text]
[del: some text]
[edit: some text -> some replacement for text]
[name: some text -> some replacement for text]
!ec

For example, the text

!bc
First consider a quantity $Q$. Without loss of generality, we assume
$Q>0$. There are three, fundamental, basic property of $Q$.
!ec
can be edited as

!bc
First[add: ,] consider [edit: a quantity -> the flux]
[del: $Q$. Without loss of generality,
we assume] $Q>0$. There are three[del: ,] fundamental[del: , basic]
[edit: property -> properties] of $Q$. [add: These are not
important for the following discussion.]
!ec
which in the ${FORMAT} output format results in

!bquote
First[add: ,] consider [edit: a quantity -> the flux]
[del: $Q$. Without loss of generality,
we assume] $Q>0$. There are three[del: ,] fundamental[del: , basic]
[edit: property -> properties] of $Q$. [add: These are not
important for the following discussion.]
!equote

To implement these edits, run

!bc sys
Terminal> doconce apply_edit_comments mydoc.do.txt
!ec

===== Verbatim/Computer Code =====

Inline verbatim code is typeset within back-ticks, as in
!bc
Some sentence with `words in verbatim style`.
!ec
resulting in Some sentence with `words in verbatim style`.

Multi-line blocks of verbatim text, typically computer code, is typeset
in between `!bc xxx` and `!ec` directives, which must appear on the
beginning of the line. A specification `xxx` indicates what verbatim
formatting style that is to be used. Typical values for `xxx` are
nothing, `cod` for a code snippet, `pro` for a complete program,
`sys` for a terminal session, `dat` for a data file (or output from a
program),
`Xpro` or `Xcod` for a program or code snipped, respectively,
in programming `X`, where `X` may be `py` for Python,
`cy` for Cython, `sh` for Bash or other Unix shells,
`f` for Fortran, `c` for C, `cpp` for C++, `m` for MATLAB,
`pl` for Perl. For output in `latex` one can let `xxx` reflect any
defined verbatim environment in the `ptex2tex` configuration file
(`.ptex2tex.cfg`). For `sphinx` output one can insert a comment
!bc
# sphinx code-blocks: pycod=python cod=fortran cppcod=c++ sys=console
!ec
that maps environments (`xxx`) onto valid language types for
Pygments (which is what `sphinx` applies to typeset computer code).

The `xxx` specifier has only effect for `latex` and
`sphinx` output. All other formats use a fixed monospace font for all
kinds of verbatim output.

Here is an example of computer code (see the source of this document
for exact syntax):

!bc cod
from numpy import sin, cos, exp, pi

def f(x, y, z, t):
    return exp(-t)*sin(pi*x)*sin(pi*y)*cos(2*pi*z)
!ec

# When showing copy from file in !bc envir, indent a character - otherwise
# ptex2tex is confused and starts copying...
Computer code can also be copied from a file:
!bc
 @@@CODE doconce_program.sh
 @@@CODE doconce_program.sh  fromto: doconce clean@^doconce split_rst
 @@@CODE doconce_program.sh  from-to: doconce clean@^doconce split_rst
 @@@CODE doconce_program.sh  envir=shpro fromto: name=@
!ec
The `@@@CODE` identifier must appear at the very beginning of the line.
The first line copies the complete file `doconce_program.sh`.
The second line copies from the first line matching the *regular
expression* `doconce clean` up to, but not including, the line
matching the *regular expression* `^doconce split_rst`.
The third line behaves as the second, but the line matching
the first regular expression is not copied (this construction is often
used for copying text between begin-end comment pair in the file).

The copied lines from file are in this example put inside `!bc shpro`
and `!ec` directives, if a complete file is copied, while the
directives become `!bc shcod` and `!ec` when a code snippet is copied
from a file. In general, for a filename extension `.X`, the environment
becomes `!bc Xpro` or `!bc Xcod` for a complete program or snippet,
respectively. The enivorments (`Xcod` and `Xpro`) are only active for
`latex`, `pdflatex`, html`, and `sphinx` output.  The fourth line
above specifies the code environment explicitly (`envir=shpro`) such
that it indicates a complete shell program (`shpro`) even if we copy a
part of the file (here from `name=` until the end of the file).
Copying a part of a file will by default lead to `!bc shcod`, which indicates a
code snippet that normally needs more code to run properly.

The `--code_prefix=text` option adds a path `text` to the filename specified
in the `@@@CODE` command (URLs work). For example

!bc
 @@@CODE src/myfile.py
!ec
and `--code_prefix=http://some.place.net`, the file

!bc
http://some.place.net/src/myfile.py
!ec
will be included. If source files have a header with author, email, etc.,
one can remove this header by the option `'--code_skip_until=# ---`.
The lines up to and including (the first) `# ---` will then be excluded.

Important warnings:

 * A code block must come after a plain sentence (at least for successful
   output in reStructredText), not directly after a section/paragraph heading,
   table, comment, figure, or movie.
 * Verbatim code blocks inside lists can be ugly when typeset in some
   output formats. A more robust approach is to replace the list with
   paragraphs that include headings.

===== LaTeX Mathematics =====

DocOnce supports inline mathematics and blocks of mathematics, using
standard LaTeX syntax. The output formats `html`, `sphinx`, `latex`,
pdflatex`, `pandoc`, and `mwiki` work with this syntax while all other
formats will just display the raw LaTeX code.

Inline expressions are written in the standard
LaTeX way with the mathematics surrounded by dollar signs, as in
$Ax=b$. To help increase readability in other formats than `sphinx`,
`latex`, and `pdflatex`, inline mathematics may have a more human
readable companion expression. The syntax is like
!bc
$\sin(\norm{\bf u})$|$sin(||u||)$
!ec
That is, the LaTeX expression appears to the left of a vertical bar (pipe
symbol) and the more readable expression appears to the right. Both
expressions are surrounded by dollar signs.

Blocks of LaTeX mathematics are written within
`!bt`
and
`!et` (begin/end TeX) directives starting on the beginning of a line:

!bc
|bt
\begin{align*}
\nabla\cdot \pmb{u} &= 0,\\
\nabla\times \pmb{u} &= 0.
\end{align*}
|et
!ec
## Note: |bt and |et (and |bc and |ec below) are used to illustrate
## tex and code blocks in inside verbatim blocks and are replaced
## by !bt, !et, !bc, and !ec after all other formatting is finished.

This LaTeX code gets rendered as

!bt
\begin{align*}
\nabla\cdot \pmb{u} &= 0,\\
\nabla\times \pmb{u} &= 0.
\end{align*}
!et
Here is a single equation:

!bc
|bt
\[ \frac{\partial\pmb{u}}{\partial t} + \pmb{u}\cdot\nabla\pmb{u} = 0.\]
|et
!ec
which results in

!bt
\[ \frac{\partial\pmb{u}}{\partial t} + \pmb{u}\cdot\nabla\pmb{u} = 0.\]
!et


__LaTeX Newcommands.__
The author can define `newcommand` statements in files with names
`newcommands*.tex`. Such commands should only be used for mathematics
(other LaTeX constructions are only understood by LaTeX itself).
The convention is that `newcommands_keep.tex`
contains the newcommands that are kept in the document, while
those in `newcommands_replace.tex` will be replaced by their full
LaTeX code. This conventions helps make readable documents in formats
without LaTeX support. For `html`, `sphinx`, `latex`, `pdflatex`,
`mwiki`, `ipynb`, and `pandoc`, the mathematics in newcommands is
rendered nicely anyway. If you desire `newcommand` outside LaTeX
mathematics, simply use a Mako variable or a Mako function (which
will be much more flexible and powerful).

# include with mako must be in this root tree, so we need a link, see make.sh

<%include file="guidelines.do.txt" />

===== Hyperlinks =====

Links use either a link text or the raw URL:

!bc
Here is some "some link text": "http://some.net/address"
(as in "search google": "http://google.com")
or just the raw address: URL: "http://google.com".

Links to files typeset in verbatim mode applies backtics:
"`myfile.py`": "http://some.net/some/place/myfile.py".

Mail addresses works too: send problems to
"`hpl@simula.no`": "mailto:hpl@simula.no"
or just "send mail": "mailto:hpl@simula.no".
!ec

===== Figures and Movies =====

Figures and movies have almost equal syntax:
!bc
FIGURE: [relative/path/to/figurefile, width=500 frac=0.8] Here goes the caption which must be on a single line. label{some:fig:label}

MOVIE: [relative/path/to/moviefile, width=500] Here goes the caption which must be on a single line. 

!ec
Note three important syntax details:

  o A mandatory comma after the figure/movie filename,
  o no comments between `width`, `height`, and `frac` and no spaces
    around the `=` characters,
  o all of the commands must appear on a single line,
  o there must be a blank line after the command.

The figure file can be listed without extension. DocOnce will then find
the version of the file with the most appropriate extension for the chosen
output format. If not suitable version is found, DocOnce will convert
another format to the needed one.

The caption is optional. If omitted, the figure will be inlined (meaning
no use of any figure environment in HTML or LaTeX formats). The `width`
and `height` parameters affect HTML formats (`html`, `rst`, `sphinx`),
while `frac` is the width of the image as a fraction of the total text
width in the `latex` and `pdflatex` formats.

The command-line options `--fig_prefix=...` and `--mov_prefix=...` can
be used to add a path (can be a URL) to all figure and movie files,
respectively.  This is useful when including DocOnce documents in
other DocOnce documents such that the text is compiled in different
directories (with different paths to the figure directory).

Movie files can either be a video or a wildcard expression for a
series of frames. In the latter case, a simple device in an HTML page
will display the individual frame files as a movie.

Combining several image files into one can be done by the
!bc sys
doconce combine_images image1 image2 ... output_image
!ec
This command applies `montage` or PDF-based tools to combine the images
to get the highest quality.

YouTube and Vimeo movies will be embedded in `html` and `sphinx` documents
and otherwise be represented by a link. The syntax is

!bc
MOVIE: [http://www.youtube.com/watch?v=_O7iUiftbKU, width=420 height=315] YouTube movie.

MOVIE: [http://vimeo.com/55562330, width=500 height=278] Vimeo movie.

!ec
The latter results in

MOVIE: [http://vimeo.com/55562330, width=500 height=278] Vimeo movie.


===== Tables =====

The table in Section ref{quick:sections} was written with this
syntax:
!bc

|----------------c--------|------------------c--------------------|
|      Section type       |        Syntax                         |
|----------------l--------|------------------l--------------------|
| chapter                 | `========= Heading ========` (9 `=`)  |
| section                 | `======= Heading =======`    (7 `=`)  |
| subsection              | `===== Heading =====`        (5 `=`)  |
| subsubsection           | `=== Heading ===`            (3 `=`)  |
| paragraph               | `__Heading.__`               (2 `_`)  |
|-----------------------------------------------------------------|

!ec

Note that

 * Each line begins and ends with a vertical bar (pipe symbol).
 * Column data are separated by a vertical bar (pipe symbol).
 * There must be a blank line before and after the table.
 * There may be horizontal rules, i.e., lines with dashes for
   indicating the heading and the end of the table, and these may
   contain characters 'c', 'l', or 'r' for how to align headings or
   columns. The first horizontal rule may indicate how to align
   headings (center, left, right), and the horizontal rule after the
   heading line may indicate how to align the data in the columns
   (center, left, right).
   One can also use `X` for potentially very wide text that must be
   wrapped and left-adjusted (will only affect `latex` and `pdflatex` where the
   `tabularx` package is then used; `X` means `l` in all other formats).
 * If the horizontal rules are without alignment information there should
   be no vertical bar (pipe symbol) between the columns. Otherwise, such
   a bar indicates a vertical bar between columns in LaTeX.
 * Many output formats are so primitive that heading and column alignment
   have no effect.

A quick way of generating tables is to place all the entries in a file
with comma as separator (a CSV file) and then run the utility
`doconce csv2table` to create a table in the DocOnce format.

The command-line option `--tables2csv` (to `doconce format`)
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.

DocOnce tables can be efficiently made directly from data in CSV files.

!bc sys
Terminal> doconce csv2table mydata.csv > mydata_table.do.txt
!ec
Now we can do `# #include "mydata_table.do.txt"` in the DocOnce
source file or simply copy the table in `mydata_table.do.txt`
into the DocOnce file.

===== Labels and References =====

The notion of labels and references (as well as bibliography and index)
is adopted
from LaTeX with a very similar syntax. As in LaTeX, a label can be
inserted anywhere, using the syntax
!bc
label{name}
!ec
with no backslash
preceding the label keyword. It is common practice to choose `name`
as some hierarchical name, using a delimiter like `:` or `_` between
(e.g.) section, subsection, and topic.

A reference to the label `name` is written as
!bc
ref{name}
!ec
again with no backslash before `ref`.

Use labels for sections and equations only, and precede the reference
by "Section" or "Chapter", or in case of an equation, surround the
reference by parenthesis.


===== Citations and Bibliography =====

Single citations are written as
!bc
cite{name}
!ec
where `name` is a logical name
of the reference (again, LaTeX writers must not insert a backslash).
Bibliography citations often have `name` on the form
`Author1_Author2_YYYY`, `Author_YYYY`, or `Author1_etal_YYYY`, where
`YYYY` is the year of the publication.
Multiple citations at once is possible by separating the logical names
by comma:
!bc
cite{name1,name2,name3}
!ec

The bibliography is specified by a line `BIBFILE: papers.pub`,
where `papers.pub` is a publication database in the
"Publish": "https://github.com/doconce/publish" format.
BibTeX `.bib` files can easily be combined to a Publish database
(which DocOnce needs to create bibliographies in other formats
than LaTeX).

===== Generalized References =====

There is a *generalized referencing* feature in DocOnce that allows
a reference with `ref` to have one formulation if the label is
in the same document and another formulation if the reference is
to an item in an external document. This construction makes it easy
to work with many small, independent documents in parallel with
a book assembly of some of the small elements.
The syntax of a generalized reference is

!bc do
ref[internal][cite][external]
!ec
with a specific example being

!bc do
As explained in
ref[Section ref{subsec:ex}][in cite{testdoc:12}][a "section":
"testdoc.html#___sec2" in the document
"A Document for Testing DocOnce": "testdoc.html" cite{testdoc:12}],
DocOnce documents may include movies.
!ec
The output from a generalized reference is the text `internal` if all
references with `ref` in the text `internal` are references to labels
defined in the
present document. Otherwise, if `cite` is non-empty and the format is
`latex` or `pdflatex`, one assumes that the references in `internal`
are to external documents declared by a comment line
`# Externaldocuments: testdoc, mydoc` (usually after the title, authors,
and date). In this case the output text is `internal` followed by `cite`,
and the
LaTeX package `xr` is used to handle the labels in the external
documents.  If none of the two situations above applies, the
`external` text will be the output.

===== Index of Keywords =====

DocOnce supports creating an index of keywords. A certain keyword
is registered for the index by a syntax like (no
backslash!)
!bc
index{name}
!ec
It is recommended to place any index of this type outside
running text, i.e., after (sub)section titles and in the space between
paragraphs. Index specifications placed right before paragraphs also
gives the doconce source code an indication of the content in the
forthcoming text. The index is only produced for the `latex`,
`pdflatex`, `rst`, and `sphinx` formats.

===== Capabilities of The Program `doconce` =====

The `doconce` program can be used for a number of purposes besides
transforming a `.do.txt` file to some format. Here is the
list of capabilities:

@@@CODE doconce_program.sh

===== Exercises =====

DocOnce supports *Exercise*, *Problem*, *Project*, and *Example*.
These are typeset
as ordinary sections and referred to by their section labels.
Exercise, problem, project, or example sections contains certain *elements*:

  * a headline at the level of a subsection
    containing one of the words "Exercise:", "Problem:",
    "Project:", or "Example:", followed by a title (required)
  * a label (optional)
  * a solution file (optional)
  * name of file with a student solution (optional)
  * main exercise text (required)
  * a short answer (optional)
  * a full solution (optional)
  * one or more hints (optional)
  * one or more subexercises (subproblems, subprojects), which can also
    contain a text, a short answer, a full solution, name student file
    to be handed in, and one or more hints (optional)

A typical sketch of a a problem without subexercises goes as follows:
!bc
===== Problem: Derive the Formula for the Area of an Ellipse =====
label{problem:ellipsearea1}
file=ellipse_area.pdf
solution=ellipse_area1_sol.pdf

Derive an expression for the area of an ellipse by integrating
the area under a curve that defines half of the ellipse.
Show each step in the mathematical derivation.

|bhint
Wikipedia has the formula for the curve.
|ehint

|bhint
"Wolframalpha": "http://wolframalpha.com" can perhaps
compute the integral.
|ehint
!ec
If the exercise type (Exercise, Problem, Project, or Example)
is enclosed in braces, the type is left out of the title in the
output. For example, the if the title line above reads

!bc
===== {Problem}: Derive the Formula for the Area of an Ellipse =====
!ec
the title becomes just "Derive the ...".

An exercise with subproblems, answers and full solutions has this
setup-up:

!bc
===== Exercise: Determine the Distance to the Moon =====
label{exer:moondist}

Intro to this exercise. Questions are in subexercises below.

|bsubex
Subexercises are numbered a), b), etc.

file=subexer_a.pdf

|bans
Short answer to subexercise a).
|eans

|bhint
First hint to subexercise a).
|ehint

|bhint
Second hint to subexercise a).
|ehint
|esubex

|bsubex
Here goes the text for subexercise b).

file=subexer_b.pdf

|bhint
A hint for this subexercise.
|ehint

|bsol
Here goes the solution of this subexercise.
|esol
|esubex

|bremarks
At the very end of the exercise it may be appropriate to summarize
and give some perspectives. The text inside the `!bremarks` and `!eremarks`
directives is always typeset at the end of the exercise.
|eremarks

|bsol
Here goes a full solution of the whole exercise.
|esol

!ec
By default, answers, solutions, and hints are typeset as paragraphs.
The command-line arguments `--without_answers` and `--without_solutions`
turn off output of answers and solutions, respectively, except for examples. The command line options `--answers_at_end` and `--solutions_at_end` write all answers and solutions to exercises to a separate section at the end of the document, respectively. Combine with `--without_answers` and `--without_solutions` to remove answers and solutions from the main text.

The commands `!anshide` and `!solhide` can be used to hide from the main text answers and solutions, respectively, until the `!ansoff` and `!soloff` commands are encountered. Similarly, the `!ansdocend` and `!soldocend` commands move answers and solutions to the end of the book. 

===== Environments =====

DocOnce environments start with `!benvirname` and end with `!eenvirname`,
where `envirname` is the name of the environment. Here is a listing of
the environments:

 * `c`: computer code (or verbatim text)
 * `t`: math blocks with LaTeX syntax
 * `subex`: sub-exercise
 * `ans`: short answer to exercise or sub-exercise
 * `sol`: full solution to exercise or sub-exercise
 * `hint`: multiple help items in an exercise or sub-exercise
 * `quote`: indented text
 * `notice`, `summary`, `warning`, `question`: admonition boxes with
    custom title, special icon, and (sometimes) background color
 * `block`, `box`: simpler boxes (`block` may have title but never any icon)
 * `pop`: text to gradually pop up in slide presentations
 * `slidecell`: indication of cells in a grid layout for elements on a
   slide

In addition, the user can define new environments `!bc-name` as
explained in the "manual": "http://doconce.github.io/doconce/doc/pub/manual/manual.html#manual:userdef:envir".

===== Preprocessing =====

DocOnce documents may utilize a preprocessor, either `preprocess` and/or
`mako`. The former is a C-style preprocessor that allows if-tests
and including other files (but not macros with arguments).
The `mako` preprocessor is much more advanced - it is actually a full
programming language, very similar to Python.

The command `doconce format` first runs `preprocess` and then `mako`.
Here is a typical example on utilizing `preprocess` to include another
document, ``comment out'' a large portion of text, and to write format-specific
constructions:

!bc do
# #include "myotherdoc.do.txt"

# #if FORMAT in ("latex", "pdflatex")
\begin{table}
\caption{Some words... label{mytab}}
\begin{tabular}{lrr}
\hline\noalign{\smallskip}
\multicolumn{1}{c}{time} & \multicolumn{1}{c}{velocity} & \multicolumn{1}{c}{acceleration} \\
\hline
0.0          & 1.4186       & -5.01        \\
2.0          & 1.376512     & 11.919       \\
4.0          & 1.1E+1       & 14.717624    \\
\hline
\end{tabular}
\end{table}
# #else
  |--------------------------------|
  |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    |
  |--------------------------------|
# #endif

# #ifdef EXTRA_MATERIAL
....large portions of text...
# #endif
!ec

With the `mako` preprocessor the if-else tests have slightly different syntax.
An "example document": "http://doconce.github.com/bioinf-py/" contains
some illustrations on how to utilize `mako` (clone the GitHub project and
examine the DocOnce source and the `doc/src/make.sh` script).

===== Resources =====

 * Excellent "Sphinx Tutorial" by C. Reller: "http://people.ee.ethz.ch/~creller/web/tricks/reST.html"

************** File: quickref.html *****************
<!--
Automatically generated HTML file from DocOnce source
(https://github.com/doconce/doconce/)
-->
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="DocOnce: https://github.com/doconce/doconce/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="description" content="DocOnce Quick Reference">

<title>DocOnce Quick Reference</title>

<!-- Bootstrap style: bootswatch_readable -->
<link href="https://netdna.bootstrapcdn.com/bootswatch/3.1.1/readable/bootstrap.min.css" rel="stylesheet">
<!-- not necessary
<link href="https://netdna.bootstrapcdn.com/font-awesome/4.0.3/css/font-awesome.css" rel="stylesheet">
-->

<style type="text/css">

/* Add scrollbar to dropdown menus in bootstrap navigation bar */
.dropdown-menu {
   height: auto;
   max-height: 400px;
   overflow-x: hidden;
}

/* Adds an invisible element before each target to offset for the navigation
   bar */
.anchor::before {
  content:"";
  display:block;
  height:64px;      /* fixed header height for style bootswatch_readable */
  margin:-64px 0 0; /* negative fixed header height */
}
</style>


<!-- USER-DEFINED ENVIRONMENTS -->

</head>

<!-- tocinfo
{'highest level': 2,
 'sections': [('Table of contents',
               2,
               'table_of_contents',
               'table_of_contents'),
              ('Supported Formats', 2, None, 'supported-formats'),
              ('Emacs syntax support', 2, None, 'emacs-syntax-support'),
              ('Title, Authors, and Date', 2, None, 'title-authors-and-date'),
              ('Copyright', 2, None, 'copyright'),
              ('Section Types', 2, 'quick:sections', 'quick:sections'),
              ('Inline Formatting', 2, None, 'inline-formatting'),
              ('Lists', 2, None, 'lists'),
              ('Comment lines', 2, None, 'comment-lines'),
              ('Inline comments', 2, None, 'inline-comments'),
              ('Verbatim/Computer Code', 2, None, 'verbatim-computer-code'),
              ('LaTeX Mathematics', 2, None, 'latex-mathematics'),
              ('Writing Guidelines (Especially for LaTeX Users!)',
               2,
               'manual:latex:guide',
               'manual:latex:guide'),
              ('Hyperlinks', 2, None, 'hyperlinks'),
              ('Figures and Movies', 2, None, 'figures-and-movies'),
              ('Tables', 2, None, 'tables'),
              ('Labels and References', 2, None, 'labels-and-references'),
              ('Citations and Bibliography',
               2,
               None,
               'citations-and-bibliography'),
              ('Generalized References', 2, None, 'generalized-references'),
              ('Index of Keywords', 2, None, 'index-of-keywords'),
              ('Capabilities of The Program `doconce`',
               2,
               None,
               'capabilities-of-the-program-doconce'),
              ('Exercises', 2, None, 'exercises'),
              ('Environments', 2, None, 'environments'),
              ('Preprocessing', 2, None, 'preprocessing'),
              ('Resources', 2, None, 'resources')]}
end of tocinfo -->

<body>



<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  TeX: {
     equationNumbers: {  autoNumber: "AMS"  },
     extensions: ["AMSmath.js", "AMSsymbols.js", "autobold.js", "color.js"]
  }
});
</script>
<script type="text/javascript" async
 src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>



    
<!-- Bootstrap navigation bar -->
<div class="navbar navbar-default navbar-fixed-top">
  <div class="navbar-header">
    <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-responsive-collapse">
      <span class="icon-bar"></span>
      <span class="icon-bar"></span>
      <span class="icon-bar"></span>
    </button>
    <a class="navbar-brand" href="quickref.html">DocOnce Quick Reference</a>
  </div>

  <div class="navbar-collapse collapse navbar-responsive-collapse">
    <ul class="nav navbar-nav navbar-right">
      <li class="dropdown">
        <a href="#" class="dropdown-toggle" data-toggle="dropdown">Contents <b class="caret"></b></a>
        <ul class="dropdown-menu">
     <!-- navigation toc: --> <li><a href="#table_of_contents" style="font-size: 80%;">Table of contents</a></li>
     <!-- navigation toc: --> <li><a href="#supported-formats" style="font-size: 80%;">Supported Formats</a></li>
     <!-- navigation toc: --> <li><a href="#emacs-syntax-support" style="font-size: 80%;">Emacs syntax support</a></li>
     <!-- navigation toc: --> <li><a href="#title-authors-and-date" style="font-size: 80%;">Title, Authors, and Date</a></li>
     <!-- navigation toc: --> <li><a href="#copyright" style="font-size: 80%;">Copyright</a></li>
     <!-- navigation toc: --> <li><a href="#quick:sections" style="font-size: 80%;">Section Types</a></li>
     <!-- navigation toc: --> <li><a href="#inline-formatting" style="font-size: 80%;">Inline Formatting</a></li>
     <!-- navigation toc: --> <li><a href="#lists" style="font-size: 80%;">Lists</a></li>
     <!-- navigation toc: --> <li><a href="#comment-lines" style="font-size: 80%;">Comment lines</a></li>
     <!-- navigation toc: --> <li><a href="#inline-comments" style="font-size: 80%;">Inline comments</a></li>
     <!-- navigation toc: --> <li><a href="#verbatim-computer-code" style="font-size: 80%;">Verbatim/Computer Code</a></li>
     <!-- navigation toc: --> <li><a href="#latex-mathematics" style="font-size: 80%;">LaTeX Mathematics</a></li>
     <!-- navigation toc: --> <li><a href="#manual:latex:guide" style="font-size: 80%;">Writing Guidelines (Especially for LaTeX Users!)</a></li>
     <!-- navigation toc: --> <li><a href="#hyperlinks" style="font-size: 80%;">Hyperlinks</a></li>
     <!-- navigation toc: --> <li><a href="#figures-and-movies" style="font-size: 80%;">Figures and Movies</a></li>
     <!-- navigation toc: --> <li><a href="#tables" style="font-size: 80%;">Tables</a></li>
     <!-- navigation toc: --> <li><a href="#labels-and-references" style="font-size: 80%;">Labels and References</a></li>
     <!-- navigation toc: --> <li><a href="#citations-and-bibliography" style="font-size: 80%;">Citations and Bibliography</a></li>
     <!-- navigation toc: --> <li><a href="#generalized-references" style="font-size: 80%;">Generalized References</a></li>
     <!-- navigation toc: --> <li><a href="#index-of-keywords" style="font-size: 80%;">Index of Keywords</a></li>
     <!-- navigation toc: --> <li><a href="#capabilities-of-the-program-doconce" style="font-size: 80%;">Capabilities of The Program <code>doconce</code></a></li>
     <!-- navigation toc: --> <li><a href="#exercises" style="font-size: 80%;">Exercises</a></li>
     <!-- navigation toc: --> <li><a href="#environments" style="font-size: 80%;">Environments</a></li>
     <!-- navigation toc: --> <li><a href="#preprocessing" style="font-size: 80%;">Preprocessing</a></li>
     <!-- navigation toc: --> <li><a href="#resources" style="font-size: 80%;">Resources</a></li>

        </ul>
      </li>
    </ul>
  </div>
</div>
</div> <!-- end of navigation bar -->

<div class="container">

<p>&nbsp;</p><p>&nbsp;</p><p>&nbsp;</p> <!-- add vertical space -->

<!-- ------------------- main content ---------------------- -->



<div class="jumbotron">
<center><h1>DocOnce Quick Reference</h1></center>  <!-- document title -->

<p>
<!-- author(s): Hans Petter Langtangen -->

<center>
<b>Hans Petter Langtangen</b> [1, 2]
</center>

<p>
<!-- institution(s) -->

<center>[1] <b>Center for Biomedical Computing, Simula Research Laboratory</b></center>
<center>[2] <b>Department of Informatics, University of Oslo</b></center>
<br>
<p>
<center><h4>Jan 32, 2100</h4></center> <!-- date -->
<br>
<p>
</div> <!-- end jumbotron -->

<h1 id="table_of_contents">Table of contents</h2>

<p>
<a href="#supported-formats"> Supported Formats </a><br>
<a href="#emacs-syntax-support"> Emacs syntax support </a><br>
<a href="#title-authors-and-date"> Title, Authors, and Date </a><br>
<a href="#copyright"> Copyright </a><br>
<a href="#quick:sections"> Section Types </a><br>
<a href="#inline-formatting"> Inline Formatting </a><br>
<a href="#lists"> Lists </a><br>
<a href="#comment-lines"> Comment lines </a><br>
<a href="#inline-comments"> Inline comments </a><br>
<a href="#verbatim-computer-code"> Verbatim/Computer Code </a><br>
<a href="#latex-mathematics"> LaTeX Mathematics </a><br>
<a href="#manual:latex:guide"> Writing Guidelines (Especially for LaTeX Users!) </a><br>
<a href="#hyperlinks"> Hyperlinks </a><br>
<a href="#figures-and-movies"> Figures and Movies </a><br>
<a href="#tables"> Tables </a><br>
<a href="#labels-and-references"> Labels and References </a><br>
<a href="#citations-and-bibliography"> Citations and Bibliography </a><br>
<a href="#generalized-references"> Generalized References </a><br>
<a href="#index-of-keywords"> Index of Keywords </a><br>
<a href="#capabilities-of-the-program-doconce"> Capabilities of The Program <code>doconce</code> </a><br>
<a href="#exercises"> Exercises </a><br>
<a href="#environments"> Environments </a><br>
<a href="#preprocessing"> Preprocessing </a><br>
<a href="#resources"> Resources </a><br>
</p>
<p>
<b>WARNING: This quick reference is very incomplete!</b>

<p>
<b>Mission.</b>
Enable writing documentation with much mathematics and
computer code <em>once, in one place</em> and include it in traditional LaTeX
books, thesis, and reports, and, without extra efforts, also make
professional looking web versions with Sphinx or HTML. Other outlets
include Google's <code>blogger.com</code>, Wikipedia/Wikibooks, IPython/Jupyter
notebooks, plus a wide variety of other formats for documents without
mathematics and code.

<h2 id="supported-formats" class="anchor">Supported Formats </h2>

<p>
DocOnce currently translates files to the following formats:

<ul>
 <li> LaTeX (format <code>latex</code> or <code>pdflatex</code>)</li>
 <li> HTML (format <code>html</code>)</li>
 <li> Sphinx (format <code>sphinx</code>)</li>
 <li> Pandoc-extended or GitHub-flavored Markdown (format <code>pandoc</code>)</li>
 <li> IPython notebook (format <code>ipynb</code>)</li>
 <li> Matlab notebook (format <code>matlabnb</code>)</li>
 <li> MediaWiki (format <code>mwiki</code>)</li>
 <li> Googlecode wiki (format <code>gwiki</code>)</li>
 <li> Creoloe wiki (format <code>cwiki</code>)</li>
 <li> reStructuredText (format <code>rst</code>)</li>
 <li> plain (untagged) ASCII (format <code>plain</code>)</li>
 <li> Epydoc (format <code>epydoc</code>)</li>
 <li> StructuredText (format <code>st</code>)</li>
</ul>

For documents with much code and mathematics, the best (and most supported)
formats are <code>latex</code>, <code>pdflatex</code>, <code>sphinx</code>, and <code>html</code>; and to a slightly
less extent <code>mwiki</code> and <code>pandoc</code>. The HTML format supports blog posts on
Google and Wordpress.

<p>
<div class="alert alert-block alert-danger alert-text-normal"><b>Use a text editor with monospace font!</b>
Some DocOnce constructions are sensitive to whitespace,
so you <em>must</em> use a text editor with monospace font.
</div>


<h2 id="emacs-syntax-support" class="anchor">Emacs syntax support </h2>

<p>
The file <a href="https://github.com/doconce/doconce/blob/master/misc/.doconce-mode.el" target="_self">.doconce-mode.el</a>
in the DocOnce source distribution gives a "DocOnce Editing Mode" in
Emacs. Store the raw version of the file in the home directory and add
<code>(load-file &quot;~/.doconce-mode.el&quot;)</code> to the <code>.emacs</code> file.

<p>
Besides syntax highlighting of DocOnce documents, this Emacs mode
provides a lot of shortcuts for setting up many elements in a document:

<p>

<div class="row">
  <div class="col-xs-8">
    <table class="table table-striped table-hover table-condensed">
<thead>
<tr><td align="center"><b>  Emacs key  </b></td> <td align="center"><b>                           Action                           </b></td> </tr>
</thead>
<tbody>
<tr><td align="left">   Ctrl+c f         </td> <td align="left">   figure                                                          </td> </tr>
<tr><td align="left">   Ctrl+c v         </td> <td align="left">   movie/video                                                     </td> </tr>
<tr><td align="left">   Ctrl+c h1        </td> <td align="left">   heading level 1 (section/h1)                                    </td> </tr>
<tr><td align="left">   Ctrl+c h2        </td> <td align="left">   heading level 2 (subsection/h2)                                 </td> </tr>
<tr><td align="left">   Ctrl+c h3        </td> <td align="left">   heading level 2 (subsection/h3)                                 </td> </tr>
<tr><td align="left">   Ctrl+c hp        </td> <td align="left">   heading for paragraph                                           </td> </tr>
<tr><td align="left">   Ctrl+c me        </td> <td align="left">   math environment: <code>!bt</code> equation <code>!et</code>    </td> </tr>
<tr><td align="left">   Ctrl+c ma        </td> <td align="left">   math environment: <code>!bt</code> align <code>!et</code>       </td> </tr>
<tr><td align="left">   Ctrl+c ce        </td> <td align="left">   code environment: <code>!bc</code> code <code>!ec</code>        </td> </tr>
<tr><td align="left">   Ctrl+c cf        </td> <td align="left">   code from file: <code>@@@CODE</code>                            </td> </tr>
<tr><td align="left">   Ctrl+c table2    </td> <td align="left">   table with 2 columns                                            </td> </tr>
<tr><td align="left">   Ctrl+c table3    </td> <td align="left">   table with 3 columns                                            </td> </tr>
<tr><td align="left">   Ctrl+c table4    </td> <td align="left">   table with 4 columns                                            </td> </tr>
<tr><td align="left">   Ctrl+c exer      </td> <td align="left">   exercise outline                                                </td> </tr>
<tr><td align="left">   Ctrl+c slide     </td> <td align="left">   slide outline                                                   </td> </tr>
<tr><td align="left">   Ctrl+c help      </td> <td align="left">   print this table                                                </td> </tr>
</tbody>
    </table>
  </div> <!-- col-xs-8 -->
</div> <!-- cell row -->

<h2 id="title-authors-and-date" class="anchor">Title, Authors, and Date </h2>

<p>
A typical example of giving a title, a set of authors, a date,
and an optional table of contents
reads

<p>
<!-- begin verbatim block  do-->
<pre><code>TITLE: On an Ultimate Markup Language
AUTHOR: H. P. Langtangen at Center for Biomedical Computing, Simula Research Laboratory &amp; Dept. of Informatics, Univ. of Oslo
AUTHOR: Kaare Dump Email: dump@cyb.space.com at Segfault, Cyberspace Inc.
AUTHOR: A. Dummy Author
DATE: today
TOC: on
</code></pre>
<!-- end verbatim block -->
The entire title must appear on a single line.
The author syntax is
<!-- begin verbatim block -->
<pre><code>name Email: somename@adr.net at institution1 &amp; institution2
</code></pre>
<!-- end verbatim block -->
where the email is optional, the "at" keyword is required if one or
more institutions are to be specified, and the <code>&</code> keyword
separates the institutions (the keyword <code>and</code> works too).
Each author specification must appear
on a single line.
When more than one author belong to the
same institution, make sure that the institution is specified in an identical
way for each author.

<p>
The date can be set as any text different from <code>today</code> if not the
current date is wanted, e.g., <code>Jan 32, 2100</code>.

<p>
The table of contents is removed by writing <code>TOC: off</code>.

<h2 id="copyright" class="anchor">Copyright </h2>

<p>
<!-- Recall to ident AUTHOR commands to avoid interpretation -->

<p>
Copyright for selected authors and/or institutions are easy to insert as part
of the <code>AUTHOR</code> command. The copyright syntax is

<p>
<!-- begin verbatim block  do-->
<pre><code>{copyright,year1-year2|license}
</code></pre>
<!-- end verbatim block -->
and can be placed after the author or after an institution, e.g.,

<p>
<!-- begin verbatim block  do-->
<pre><code> AUTHOR: name Email: somename@adr.net {copyright,2006-present} at inst1
 AUTHOR: name {copyright} at inst1 {copyright}
</code></pre>
<!-- end verbatim block -->
The first line gives <code>name</code> a copyright for 2006 up to the present year,
while the second line gives copyright to <code>name</code> and the institution <code>inst1</code>
for the present year. The license can be any formulation, but there are
some convenient abbreviations for Creative Commons (&quot;public domain&quot;)
licenses: <code>CC BY</code> for Creative Commons Attribution 4.0 license,
<code>CC BY-NC</code> for Creative Commons Attribution-NonCommercial 4.0 license.
For example,

<p>
<!-- begin verbatim block  do-->
<pre><code> AUTHOR: name1 {copyright|CC BY} at institution1
 AUTHOR: name2 {copyright|CC BY} at institution2
</code></pre>
<!-- end verbatim block -->
is a very common copyright for the present year with the Attribution license.
The copyright must be identical for all authors and institutions.

<h2 id="quick:sections" class="anchor">Section Types</h2>

<p>

<div class="row">
  <div class="col-xs-9">
    <table class="table table-striped table-hover table-condensed">
<thead>
<tr><td align="center"><b> Section type</b></td> <td align="center"><b>                              Syntax                             </b></td> </tr>
</thead>
<tbody>
<tr><td align="left">   chapter          </td> <td align="left">   <code>========= Heading ========</code> (9 <code>=</code>)           </td> </tr>
<tr><td align="left">   section          </td> <td align="left">   <code>======= Heading =======</code>    (7 <code>=</code>)           </td> </tr>
<tr><td align="left">   subsection       </td> <td align="left">   <code>===== Heading =====</code>        (5 <code>=</code>)           </td> </tr>
<tr><td align="left">   subsubsection    </td> <td align="left">   <code>=== Heading ===</code>            (3 <code>=</code>)           </td> </tr>
<tr><td align="left">   paragraph        </td> <td align="left">   <code>__Heading.__</code>               (2 <code>_</code>)           </td> </tr>
<tr><td align="left">   abstract         </td> <td align="left">   <code>__Abstract.__</code> Running text...                           </td> </tr>
<tr><td align="left">   appendix         </td> <td align="left">   <code>======= Appendix: heading =======</code> (7 <code>=</code>)    </td> </tr>
<tr><td align="left">   appendix         </td> <td align="left">   <code>===== Appendix: heading =====</code> (5 <code>=</code>)        </td> </tr>
<tr><td align="left">   exercise         </td> <td align="left">   <code>===== Exercise: heading =====</code> (5 <code>=</code>)        </td> </tr>
</tbody>
    </table>
  </div> <!-- col-xs-9 -->
</div> <!-- cell row -->
<p>
Note that abstracts are recognized by starting with <code>__Abstract.__</code> or
<code>__Summary.__</code> at the beginning of a line and ending with three or
more <code>=</code> signs of the next heading.

<p>
The <code>Exercise:</code> keyword can be substituted by <code>Problem:</code> or <code>Project:</code>.
A recommended convention is that an exercise is tied to the text,
a problem can stand on its own, and a project is a comprehensive
problem.

<h2 id="inline-formatting" class="anchor">Inline Formatting </h2>

<p>
Words surrounded by <code>*</code> are emphasized: <code>*emphasized words*</code> becomes
<em>emphasized words</em>. Similarly, an underscore surrounds words that
appear in boldface: <code>_boldface_</code> becomes <b>boldface</b>. Colored words
are also possible: the text

<p>
<!-- begin verbatim block -->
<pre><code>`color{red}{two red words}`
</code></pre>
<!-- end verbatim block -->
becomes <font color="red">two red words</font>.

<p>
Quotations appear inside double backticks and double single quotes:

<p>
<!-- begin verbatim block -->
<pre><code>This is a sentence with ``words to be quoted''.
</code></pre>
<!-- end verbatim block -->

<p>
A forced linebreak is specified by <code>&lt;linebreak&gt;</code> at the point where the
linebreak in the output is wanted.

<p>
Footnotes use a label in the text with the footnote text separate,
preferably after the paragraph where the footnote appears:

<p>
<!-- begin verbatim block -->
<pre><code>Differentiating[^diff2] this equation leads
to a new and much simpler equation.

[^diff2]: More precisely, we apply the divergence
$\nabla\cdot$ on both sides.

Here comes a new paragraph...
</code></pre>
<!-- end verbatim block -->

<p>
Non-breaking space is inserted using the tilde character as in LaTeX:

<p>
<!-- begin verbatim block -->
<pre><code>This distance corresponds to 7.5~km, which is traveled in $7.5/5$~s.
</code></pre>
<!-- end verbatim block -->

<p>
A horizontal rule for separating content vertically, like this:

<p>
<hr>

<p>
is typeset as four or more hyphens on a single line:

<p>
<!-- begin verbatim block -->
<pre><code>---------
</code></pre>
<!-- end verbatim block -->

<p>
The <code>latex</code>, <code>pdflatex</code>, <code>sphinx</code>, and <code>html</code> formats support em-dash,
indicated by three hyphens: <code>---</code>. Here is an example:

<p>
<!-- begin verbatim block -->
<pre><code>The em-dash is used - without spaces - as alternative to hyphen with
space around in sentences---this way, or in quotes:
*Premature optimization is the root of all evil.*--- Donald Knuth.
</code></pre>
<!-- end verbatim block -->
This text is in the html rendered as

<p>
The em-dash is used - without spaces - as alternative to hyphen with
space around in sentences&mdash;this way, or in quotes:
<em>Premature optimization is the root of all evil.</em>&mdash; Donald Knuth.

<p>
The en-dash consists of two hyphens, either with blanks on both sides &ndash; for
something in the middle of a sentence &ndash; or in number ranges like 240&ndash;249.
LaTeX writes are used to and fond of en-dash.

<p>
An ampersand, as in Guns &amp; Roses or Texas A&amp;M, is written as a
plain <code>&</code> <em>with space(s) on both sides</em>. Single upper case letters on each
side of <code>&</code>, as in <code>Texas A & M</code>, remove the spaces and result in
Texas A&amp;M, while words on both sides of <code>&</code>, as in <code>Guns & Roses</code>,
preserve the spaces: Guns &amp; Roses. Failing to have spaces before and
after <code>&</code> will result in wrong typesetting of the ampersand in the <code>html</code>,
<code>latex</code>, and <code>pdflatex</code> formats.

<p>
Emojis, as defined in <a href="http://www.emoji-cheat-sheet.com" target="_self"><tt>http://www.emoji-cheat-sheet.com</tt></a>, can be
inserted in the text, as (e.g.) <code>:dizzy_face:</code> with blank or newline
before or after <img src="https://raw.githubusercontent.com/hplgit/doconce/master/bundled/emoji/png/dizzy_face.png" width="22px" height="22px" align="center"> Only the <code>pdflatex</code>, <code>html</code>, and <code>pandoc</code> output
formats translate emoji specifications to images, while all other
formats leave the textual specification in the document. The
command-line option <code>--no_emoji</code> removes all emojis from the output
document.

<h2 id="lists" class="anchor">Lists </h2>

<p>
There are three types of lists: <em>bullet lists</em>, where each item starts
with <code>*</code>, <em>enumeration lists</em>, where each item starts with <code>o</code> and gets
consecutive numbers,
and <em>description</em> lists, where each item starts with <code>-</code> followed
by a keyword and a colon.
<!-- begin verbatim block -->
<pre><code>Here is a bullet list:

 * item1
 * item2
  * subitem1 of item2
  * subitem2 of item2,
    second line of subitem2
 * item3

Note that sublists are consistently indented by one or more blanks as
shown: bullets must exactly match and continuation lines must start
right below the line above.

Here is an enumeration list:

 o item1
 o item2
   may appear on
   multiple lines
  o subitem1 of item2
  o subitem2 of item2
 o item3

And finally a description list:

 - keyword1: followed by
   some text
   over multiple
   lines
 - keyword2:
   followed by text on the next line
 - keyword3: and its description may fit on one line
</code></pre>
<!-- end verbatim block -->
The code above follows.

<p>
Here is a bullet list:

<ul>
 <li> item1</li>
 <li> item2</li>

<ul>
  <li> subitem1 of item2</li>
  <li> subitem2 of item2</li>
</ul>

 <li> item3</li>
</ul>

Note that sublists are consistently indented by one or more blanks as
shown: bullets must exactly match and continuation lines must start
right below the line above.

<p>
Here is an enumeration list:

<ol>
<li> item1</li>
<li> item2
   may appear on
   multiple lines

<ol type="a"></li>
 <li> subitem1 of item2</li>
 <li> subitem2 of item2</li>
</ol>

<li> item3</li>
</ol>

And finally a description list:

<p>

<dl>
 <dt>keyword1:<dd> 
   followed by
   some text
   over multiple
   lines
 <dt>keyword2:<dd> 
   followed by text on the next line
 <dt>keyword3:<dd> 
   and its description may fit on one line
</dl>

<div class="alert alert-block alert-danger alert-text-normal"><b>No indentation - except in lists!</b>
DocOnce syntax is sensitive to whitespace.
No lines should be indented, only lines belonging to lists.
Indented lines may give strange output in some formats.
</div>


<h2 id="comment-lines" class="anchor">Comment lines </h2>

<p>
Lines starting with <code>#</code> are treated as comments in the document and
translated to the proper syntax for comments in the output
document. Such comment lines should not appear before LaTeX math
blocks, verbatim code blocks, or lists if the formats <code>rst</code> and
<code>sphinx</code> are desired.

<p>
Comment lines starting with <code>##</code> are not propagated to the output
document and can be used for comments that are only of interest in
the DocOnce file.

<p>
Large portions of text can be left out using Preprocess. Just place
<code># #ifdef EXTRA</code> and <code># #endif</code> around the text. The command line
option <code>-DEXTRA</code> will bring the text alive again.

<p>
When using the Mako preprocessor one can also place comments in
the DocOnce source file that will be removed by Mako before
DocOnce starts processing the file.

<h2 id="inline-comments" class="anchor">Inline comments </h2>

<p>
Inline comments meant as messages or notes, to authors during development
in particular,
are enabled by the syntax
<!-- begin verbatim block -->
<pre><code>[name: running text]
</code></pre>
<!-- end verbatim block -->
where <code>name</code> is the name or ID of an author or reader making the comment,
and <code>running text</code> is the comment. The name can contain upper and lower
case characters, digits, single quote, <code>+</code> and <code>-</code>, as well
as space. Here goes an example.

<p>
<!-- begin verbatim block -->
<pre><code>Some running text. [hpl: There must be a space after the colon,
but the running text can occupy multiple lines.]
</code></pre>
<!-- end verbatim block -->
which is rendered as

<p>
<blockquote>
    Some running text. 
    <!-- begin inline comment -->
    <font color="red">(<b>hpl 1</b>: There must be a space after the colon, but the running text can occupy multiple lines.)</font>
    <!-- end inline comment -->
</blockquote>


<p>
The inline comments have simple typesetting in most formats, typically
boldface name, a comment number, with everything surrounded by
parenthesis.  However, with LaTeX output and the <code>--latex_todonotes</code>
option to <code>doconce format</code>, colorful margin or inline boxes (using the
<code>todonotes</code> package) make it very easy to spot the comments.

<p>
Running
<!-- begin verbatim block  sys-->
<pre><code>doconce format html mydoc.do.txt --skip_inline_comments
</code></pre>
<!-- end verbatim block -->
removes all inline comments from the output. This feature makes it easy
to turn on and off notes to authors during the development of the document.

<p>
All inline comments to readers can also be physically
removed from the DocOnce source by
<!-- begin verbatim block  sys-->
<pre><code>doconce remove_inline_comments mydoc.do.txt
</code></pre>
<!-- end verbatim block -->

<p>
Inline comments can also be used to markup edits. There are add, delete, and
replacement comments for editing:

<p>
<!-- begin verbatim block -->
<pre><code>[add: ,]
[add: .]
[add: ;]
[del: ,]
[del: ,]
[del: .]
[del: ;]
[add: some text]
[del: some text]
[edit: some text -&gt; some replacement for text]
[name: some text -&gt; some replacement for text]
</code></pre>
<!-- end verbatim block -->

<p>
For example, the text

<p>
<!-- begin verbatim block -->
<pre><code>First consider a quantity $Q$. Without loss of generality, we assume
$Q&gt;0$. There are three, fundamental, basic property of $Q$.
</code></pre>
<!-- end verbatim block -->
can be edited as

<p>
<!-- begin verbatim block -->
<pre><code>First[add: ,] consider [edit: a quantity -&gt; the flux]
[del: $Q$. Without loss of generality,
we assume] $Q&gt;0$. There are three[del: ,] fundamental[del: , basic]
[edit: property -&gt; properties] of $Q$. [add: These are not
important for the following discussion.]
</code></pre>
<!-- end verbatim block -->
which in the html output format results in

<p>
<blockquote>
    First<font color="red">, (<b>edit 2</b>: add comma)</font> consider  <font color="red">(<b>edit 3</b>:)</font> <del> a quantity </del> <font color="red">the flux</font>
     <font color="red">(<b>edit 4</b>:)</font> <del> \( Q \). Without loss of generality,
    we assume </del> \( Q>0 \). There are three <font color="red"> (<b>edit 5</b>: delete comma)</font> fundamental <font color="red">(<b>edit 6</b>:)</font> <del> , basic </del>
     <font color="red">(<b>edit 7</b>:)</font> <del> property </del> <font color="red">properties</font> of \( Q \).  <font color="red">(<b>edit 8</b>:) These are not
    important for the following discussion.</font>
</blockquote>


<p>
To implement these edits, run

<p>
<!-- begin verbatim block  sys-->
<pre><code>Terminal&gt; doconce apply_edit_comments mydoc.do.txt
</code></pre>
<!-- end verbatim block -->

<h2 id="verbatim-computer-code" class="anchor">Verbatim/Computer Code </h2>

<p>
Inline verbatim code is typeset within back-ticks, as in
<!-- begin verbatim block -->
<pre><code>Some sentence with `words in verbatim style`.
</code></pre>
<!-- end verbatim block -->
resulting in Some sentence with <code>words in verbatim style</code>.

<p>
Multi-line blocks of verbatim text, typically computer code, is typeset
in between <code>!bc xxx</code> and <code>!ec</code> directives, which must appear on the
beginning of the line. A specification <code>xxx</code> indicates what verbatim
formatting style that is to be used. Typical values for <code>xxx</code> are
nothing, <code>cod</code> for a code snippet, <code>pro</code> for a complete program,
<code>sys</code> for a terminal session, <code>dat</code> for a data file (or output from a
program),
<code>Xpro</code> or <code>Xcod</code> for a program or code snipped, respectively,
in programming <code>X</code>, where <code>X</code> may be <code>py</code> for Python,
<code>cy</code> for Cython, <code>sh</code> for Bash or other Unix shells,
<code>f</code> for Fortran, <code>c</code> for C, <code>cpp</code> for C++, <code>m</code> for MATLAB,
<code>pl</code> for Perl. For output in <code>latex</code> one can let <code>xxx</code> reflect any
defined verbatim environment in the <code>ptex2tex</code> configuration file
(<code>.ptex2tex.cfg</code>). For <code>sphinx</code> output one can insert a comment
<!-- begin verbatim block -->
<pre><code># sphinx code-blocks: pycod=python cod=fortran cppcod=c++ sys=console
</code></pre>
<!-- end verbatim block -->
that maps environments (<code>xxx</code>) onto valid language types for
Pygments (which is what <code>sphinx</code> applies to typeset computer code).

<p>
The <code>xxx</code> specifier has only effect for <code>latex</code> and
<code>sphinx</code> output. All other formats use a fixed monospace font for all
kinds of verbatim output.

<p>
Here is an example of computer code (see the source of this document
for exact syntax):

<p>
<!-- begin verbatim block  cod-->
<pre><code>from numpy import sin, cos, exp, pi

def f(x, y, z, t):
    return exp(-t)*sin(pi*x)*sin(pi*y)*cos(2*pi*z)
</code></pre>
<!-- end verbatim block -->

<p>
<!-- When showing copy from file in !bc envir, indent a character - otherwise -->
<!-- ptex2tex is confused and starts copying... -->
Computer code can also be copied from a file:
<!-- begin verbatim block -->
<pre><code> @@@CODE doconce_program.sh
 @@@CODE doconce_program.sh  fromto: doconce clean@^doconce split_rst
 @@@CODE doconce_program.sh  from-to: doconce clean@^doconce split_rst
 @@@CODE doconce_program.sh  envir=shpro fromto: name=@
</code></pre>
<!-- end verbatim block -->
The <code>@@@CODE</code> identifier must appear at the very beginning of the line.
The first line copies the complete file <code>doconce_program.sh</code>.
The second line copies from the first line matching the <em>regular
expression</em> <code>doconce clean</code> up to, but not including, the line
matching the <em>regular expression</em> <code>^doconce split_rst</code>.
The third line behaves as the second, but the line matching
the first regular expression is not copied (this construction is often
used for copying text between begin-end comment pair in the file).

<p>
The copied lines from file are in this example put inside <code>!bc shpro</code>
and <code>!ec</code> directives, if a complete file is copied, while the
directives become <code>!bc shcod</code> and <code>!ec</code> when a code snippet is copied
from a file. In general, for a filename extension <code>.X</code>, the environment
becomes <code>!bc Xpro</code> or <code>!bc Xcod</code> for a complete program or snippet,
respectively. The enivorments (<code>Xcod</code> and <code>Xpro</code>) are only active for
<code>latex</code>, <code>pdflatex</code>, html`, and <code>sphinx</code> output.  The fourth line
above specifies the code environment explicitly (<code>envir=shpro</code>) such
that it indicates a complete shell program (<code>shpro</code>) even if we copy a
part of the file (here from <code>name=</code> until the end of the file).
Copying a part of a file will by default lead to <code>!bc shcod</code>, which indicates a
code snippet that normally needs more code to run properly.

<p>
The <code>--code_prefix=text</code> option adds a path <code>text</code> to the filename specified
in the <code>@@@CODE</code> command (URLs work). For example

<p>
<!-- begin verbatim block -->
<pre><code> @@@CODE src/myfile.py
</code></pre>
<!-- end verbatim block -->
and <code>--code_prefix=http://some.place.net</code>, the file

<p>
<!-- begin verbatim block -->
<pre><code>http://some.place.net/src/myfile.py
</code></pre>
<!-- end verbatim block -->
will be included. If source files have a header with author, email, etc.,
one can remove this header by the option <code>'--code_skip_until=# ---</code>.
The lines up to and including (the first) <code># ---</code> will then be excluded.

<p>
Important warnings:

<ul>
 <li> A code block must come after a plain sentence (at least for successful
   output in reStructredText), not directly after a section/paragraph heading,
   table, comment, figure, or movie.</li>
 <li> Verbatim code blocks inside lists can be ugly when typeset in some
   output formats. A more robust approach is to replace the list with
   paragraphs that include headings.</li>
</ul>

<h2 id="latex-mathematics" class="anchor">LaTeX Mathematics </h2>

<p>
DocOnce supports inline mathematics and blocks of mathematics, using
standard LaTeX syntax. The output formats <code>html</code>, <code>sphinx</code>, <code>latex</code>,
pdflatex`, <code>pandoc</code>, and <code>mwiki</code> work with this syntax while all other
formats will just display the raw LaTeX code.

<p>
Inline expressions are written in the standard
LaTeX way with the mathematics surrounded by dollar signs, as in
\( Ax=b \). To help increase readability in other formats than <code>sphinx</code>,
<code>latex</code>, and <code>pdflatex</code>, inline mathematics may have a more human
readable companion expression. The syntax is like
<!-- begin verbatim block -->
<pre><code>$\sin(\norm{\bf u})$|$sin(||u||)$
</code></pre>
<!-- end verbatim block -->
That is, the LaTeX expression appears to the left of a vertical bar (pipe
symbol) and the more readable expression appears to the right. Both
expressions are surrounded by dollar signs.

<p>
Blocks of LaTeX mathematics are written within
<code>!bt</code>
and
<code>!et</code> (begin/end TeX) directives starting on the beginning of a line:

<p>
<!-- begin verbatim block -->
<pre><code>!bt
\begin{align*}
\nabla\cdot \pmb{u} &amp;= 0,\\ 
\nabla\times \pmb{u} &amp;= 0.
\end{align*}
!et
</code></pre>
<!-- end verbatim block -->

<p>
This LaTeX code gets rendered as

$$
\begin{align*}
\nabla\cdot \pmb{u} &= 0,\\ 
\nabla\times \pmb{u} &= 0.
\end{align*}
$$

Here is a single equation:

<p>
<!-- begin verbatim block -->
<pre><code>!bt
\[ \frac{\partial\pmb{u}}{\partial t} + \pmb{u}\cdot\nabla\pmb{u} = 0.\]
!et
</code></pre>
<!-- end verbatim block -->
which results in

$$ \frac{\partial\pmb{u}}{\partial t} + \pmb{u}\cdot\nabla\pmb{u} = 0.$$

<p>
<b>LaTeX Newcommands.</b>
The author can define <code>newcommand</code> statements in files with names
<code>newcommands*.tex</code>. Such commands should only be used for mathematics
(other LaTeX constructions are only understood by LaTeX itself).
The convention is that <code>newcommands_keep.tex</code>
contains the newcommands that are kept in the document, while
those in <code>newcommands_replace.tex</code> will be replaced by their full
LaTeX code. This conventions helps make readable documents in formats
without LaTeX support. For <code>html</code>, <code>sphinx</code>, <code>latex</code>, <code>pdflatex</code>,
<code>mwiki</code>, <code>ipynb</code>, and <code>pandoc</code>, the mathematics in newcommands is
rendered nicely anyway. If you desire <code>newcommand</code> outside LaTeX
mathematics, simply use a Mako variable or a Mako function (which
will be much more flexible and powerful).

<p>
<!-- include with mako must be in this root tree, so we need a link, see make.sh -->

<h2 id="manual:latex:guide" class="anchor">Writing Guidelines (Especially for LaTeX Users!)</h2>

<p>
LaTeX writers often have their own writing habits and have preferred
LaTeX packages. DocOnce is a simpler format and
corresponds to writing in quite plain LaTeX and making the ascii text
look nice (be careful with the use of white space!). This means that
although DocOnce has borrowed a lot from LaTeX, there are a few points
LaTeX writers should pay attention to. Experience shows that these
points are so important that we list them <em>before</em> we list typical
DocOnce syntax!

<p>
Any LaTeX syntax in mathematical formulas is accepted when DocOnce
translates the text to LaTeX, but the following rules should be
followed when transalting the text to <code>sphinx</code>, <code>pandoc</code>,
<code>mwiki</code>, <code>html</code>, or <code>ipynb</code> formats.

<ul>
 <li> AMS LaTeX mathematics is supported, also for the <code>html</code>, <code>sphinx</code>,
   and <code>ipynb</code> formats.</li>
 <li> If you want LaTeX math blocks to work with <code>latex</code>, <code>html</code>, <code>sphinx</code>,
   <code>markdown</code>, and <code>ipynb</code>, only use
   the following equation environments: <code>\[ ... \]</code>,
   <code>equation*</code>, <code>equation</code>, <code>align*</code>, <code>align</code>. <code>alignat*</code>, <code>alignat</code>.
   Other environments, such as <code>split</code>, <code>multiline</code>, <code>gather</code> are
   supported in modern MathJax in HTML and Sphinx, but may have
   rendering problems (to a larger extent than <code>equation</code> and <code>align</code>).
   DocOnce performs extensions to <code>sphinx</code>, <code>ipynb</code>,
   and other formats such that
   labels in <code>align</code> and <code>alignat</code> environments work well.
   If you face problems with fancy LaTeX equation environments in
   web formats, try rewriting with plain <code>align</code>, <code>nonumber</code>, etc.</li>
 <li> Do not use comments inside equations.</li>
 <li> Newcommands in mathematical formulas are allowed, but not in
   the running text. Newcommands must be defined in files with names
   <code>newcommands*.tex</code>. Use <code>\newcommands</code> and not <code>\def</code>.
   Each newcommand must be defined on a single line.
   Use Mako functions if you need macros in the running text.</li>
 <li> Use labels and refer to them
   for sections, figures, movies, and equations only.
   MediaWiki (<code>mwiki</code>) does not support references to equations.</li>
 <li> Spaces are not allowed in labels.</li>
 <li> There is just one <code>ref</code> command (no <code>\eqref</code> for equations) and references to
   equations must use parentheses. Never use the tilde <code>&nbsp;</code> (non-breaking
   space) character before references to figures, sections, etc., but
   tilde is allowed for references to equations.</li>
 <li> Never use <code>\pageref</code> as pages are not a concept in web documents
   (there is only a <code>ref</code> command in DocOnce and it refers to labels).</li>
 <li> Only figures and movies are floating elements in DocOnce, all other elements
   (code, tables, algorithms) must appear <em>inline</em> without numbers or labels
   for reference <button type="button" class="btn btn-primary btn-xs" rel="tooltip" data-placement="top" title="There is an exception: by using user-defined environments within !bu-name and !eu-name directives, it is possible to label any type of text and refer to it. For example, one can have environments for examples, tables, code snippets, theorems, lemmas, etc. One can also use Mako functions to implement environments."><a href="#def_footnote_1" id="link_footnote_1" style="color: white">1</a></button> (refer to inline elements by a section label).
   The reason is that floating elements are in general
   not used in web documents, but we made an exception with figures
   and movies.</li>
 <li> Keep figure captions shorts as they are used as references in the
   Sphinx format. Avoid inline mathematics since Sphinx will strip it
   away in the figure reference.
   (Many writing styles encourage rich captions that
   explains everything about the figure; this work well
   only in the HTML and LaTeX formats.)</li>
 <li> You cannot use <code>subfigure</code> to combine several image files in one
   figure, but you can combine the files into one file using
   the <code>doconce combine_images</code> tool. Refer to individual image files
   in the caption or text by (e.g.) &quot;left&quot; and &quot;right&quot;, or
   &quot;upper left&quot;, &quot;lower right&quot;, etc.</li>
 <li> Footnotes can be used as usual in LaTeX, but some HTML formats are not
   able to display mathematics or inline verbatim or other formatted
   code (emphasis, boldface, color) in footnotes - keep that in mind.</li>
 <li> Use plain <code>cite</code> for references (e.g., <code>\citeauthor</code> has no counterpart
   in DocOnce). The bibliography must be prepared in the Publish format,
   but import from (clean) BibTeX is possible.</li>
 <li> Use <code>idx</code> for index entries, but put the definitions between paragraphs,
   not inside them (required by Sphinx).</li>
 <li> Use the <code>\bm</code> command (from the <code>bm</code> package, always included by DocOnce)
   for boldface in mathematics.</li>
 <li> Make sure all ordinary text starts in column 1 on each line. Equations
   can be indented. The <code>\begin{}</code> and <code>\end{}</code> directives should start
   in column 1.</li>
 <li> If you depend on various LaTeX environments for your writings, you have
   to give these up, or implement <em>user-defined environments</em> in DocOnce.
   For instance, examples are normally typeset as subsections in DocOnce,
   but can also utilize a user-defined example environment.
   Learn about the exercise support in DocOnce for typesetting
   exercises, problems, and projects.</li>
 <li> Learn about the preprocessors Preprocess and Mako - these are smart
   tools for, e.g., commenting out/in large portions of text and creating
   macros.</li>
 <li> Use <em>generalized references</em> when referring to companion documents
   that may later become part of this document (or migrated out of this document).</li>
 <li> Follow <a href="https://github.com/doconce/setup4book-doconce" target="_self">recommendations for DocOnce books</a> if you plan to write a book.</li>
</ul>

<p id="def_footnote_1"><a href="#link_footnote_1"><b>1:</b></a> There is an exception: by using <em>user-defined environments</em>
within <code>!bu-name</code> and <code>!eu-name</code> directives, it is possible to
label any type of text and refer to it. For example, one can have
environments for examples, tables, code snippets, theorems, lemmas, etc.
One can also use Mako functions to implement environments.</p>

<p>
<div class="alert alert-block alert-success alert-text-normal"><b>Use the preprocessor to tailor output</b>
If you really need special LaTeX constructs in the LaTeX output
from DocOnce, you may use use preprocessor if-tests on
the format (typically <code>#if FORMAT in (&quot;latex&quot;, &quot;pdflatex&quot;)</code>) to
include such special LaTeX code. With an else clause you can easily
create corresponding constructions for other formats. This way
of using Preprocess or Mako
allows you to use advanced LaTeX features (or HTML features for the HTML formats)
to fine tune the resulting
document. More tuning can be done by automatic editing of the
output file (e.g., <code>.tex</code> or <code>.html</code>) produced by DocOnce using
your own scripts or the <code>doconce replace</code> and <code>doconce subst</code> commands.
</div>


<p>
<div class="alert alert-block alert-success alert-text-normal"><b>Autotranslation of LaTeX to DocOnce?</b>
The tool <code>doconce latex2doconce</code> may help you translate LaTeX files
to DocOnce syntax. However, if you use computer code in floating
list environments, special packages for typesetting algorithms,
example environments, <code>subfigure</code> in figures,
or a lot of newcommands in the running text, there will be need for
a lot of manual edits and adjustments.

<p>
For examples, figure environments can only be translated by
<code>doconce latex2doconce</code> if the label is inside the caption and
the figure is typeset like

<p>
<!-- begin verbatim block  latexcod-->
<pre><code>\begin{figure}
  \centering
  \includegraphics[width=0.55\linewidth]{figs/myfig.pdf}
  \caption{This is a figure. \labe{myfig}}
\end{figure}
</code></pre>
<!-- end verbatim block -->
If the LaTeX text is consistent with respect to the placement of the label, a
simple script can autoedit the label inside the caption, but many
LaTeX writers put the label at different places in different figures,
and then it becomes more difficult to autoedit figures and translate
them to the DocOnce <code>FIGURE:</code> syntax.

<p>
Tables are hard to interpret and translate because headings and
caption can be typeset in many different ways. The type of table
that is recognized looks like

<p>
<!-- begin verbatim block  latexcod-->
<pre><code>\begin{table}
\caption{Here goes the caption.}
\begin{tabular}{lr}
\hline
\multicolumn{1}{c}{$v_0$} &amp; \multicolumn{1}{c}{$f_R(v_0)$}\\hline
1.2 &amp; 4.2\1.1 &amp; 4.0\0.9 &amp; 3.7
\hline
\end{tabular}
\end{table}
</code></pre>
<!-- end verbatim block -->
Recall that table captions do not make sense in DocOnce since tables
must be inlined and explained in the surrounding text.

<p>
Footnotes are also problematic for <code>doconce latex2doconce</code> since DocOnce
footnotes must have the explanation outside the paragraph where the
footnote is used. This calls for manual work. The translator from
LaTeX to DocOnce will insert <code>_PROBLEM_</code> and mark footnotes. One
solution is to avoid footnotes in the LaTeX document if fully automatic
translation is desired.
</div>


<h2 id="hyperlinks" class="anchor">Hyperlinks </h2>

<p>
Links use either a link text or the raw URL:

<p>
<!-- begin verbatim block -->
<pre><code>Here is some &quot;some link text&quot;: &quot;http://some.net/address&quot;
(as in &quot;search google&quot;: &quot;http://google.com&quot;)
or just the raw address: URL: &quot;http://google.com&quot;.

Links to files typeset in verbatim mode applies backtics:
&quot;`myfile.py`&quot;: &quot;http://some.net/some/place/myfile.py&quot;.

Mail addresses works too: send problems to
&quot;`hpl@simula.no`&quot;: &quot;mailto:hpl@simula.no&quot;
or just &quot;send mail&quot;: &quot;mailto:hpl@simula.no&quot;.
</code></pre>
<!-- end verbatim block -->

<h2 id="figures-and-movies" class="anchor">Figures and Movies </h2>

<p>
Figures and movies have almost equal syntax:
<!-- begin verbatim block -->
<pre><code>FIGURE: [relative/path/to/figurefile, width=500 frac=0.8] Here goes the caption which must be on a single line. label{some:fig:label}

MOVIE: [relative/path/to/moviefile, width=500] Here goes the caption which must be on a single line. 

</code></pre>
<!-- end verbatim block -->
Note three important syntax details:

<ol>
 <li> A mandatory comma after the figure/movie filename,</li>
 <li> no comments between <code>width</code>, <code>height</code>, and <code>frac</code> and no spaces
    around the <code>=</code> characters,</li>
 <li> all of the commands must appear on a single line,</li>
 <li> there must be a blank line after the command.</li>
</ol>

The figure file can be listed without extension. DocOnce will then find
the version of the file with the most appropriate extension for the chosen
output format. If not suitable version is found, DocOnce will convert
another format to the needed one.

<p>
The caption is optional. If omitted, the figure will be inlined (meaning
no use of any figure environment in HTML or LaTeX formats). The <code>width</code>
and <code>height</code> parameters affect HTML formats (<code>html</code>, <code>rst</code>, <code>sphinx</code>),
while <code>frac</code> is the width of the image as a fraction of the total text
width in the <code>latex</code> and <code>pdflatex</code> formats.

<p>
The command-line options <code>--fig_prefix=...</code> and <code>--mov_prefix=...</code> can
be used to add a path (can be a URL) to all figure and movie files,
respectively.  This is useful when including DocOnce documents in
other DocOnce documents such that the text is compiled in different
directories (with different paths to the figure directory).

<p>
Movie files can either be a video or a wildcard expression for a
series of frames. In the latter case, a simple device in an HTML page
will display the individual frame files as a movie.

<p>
Combining several image files into one can be done by the
<!-- begin verbatim block  sys-->
<pre><code>doconce combine_images image1 image2 ... output_image
</code></pre>
<!-- end verbatim block -->
This command applies <code>montage</code> or PDF-based tools to combine the images
to get the highest quality.

<p>
YouTube and Vimeo movies will be embedded in <code>html</code> and <code>sphinx</code> documents
and otherwise be represented by a link. The syntax is

<p>
<!-- begin verbatim block -->
<pre><code>MOVIE: [http://www.youtube.com/watch?v=_O7iUiftbKU, width=420 height=315] YouTube movie.

MOVIE: [http://vimeo.com/55562330, width=500 height=278] Vimeo movie.

</code></pre>
<!-- end verbatim block -->
The latter results in

<p>

<iframe width="500" height="278" src="https://player.vimeo.com/video/55562330" frameborder="0" allowfullscreen></iframe>

<em>Vimeo movie.</em>

<h2 id="tables" class="anchor">Tables </h2>

<p>
The table in the section <a href="#quick:sections">Section Types</a> was written with this
syntax:
<!-- begin verbatim block -->
<pre><code>
|----------------c--------|------------------c--------------------|
|      Section type       |        Syntax                         |
|----------------l--------|------------------l--------------------|
| chapter                 | `========= Heading ========` (9 `=`)  |
| section                 | `======= Heading =======`    (7 `=`)  |
| subsection              | `===== Heading =====`        (5 `=`)  |
| subsubsection           | `=== Heading ===`            (3 `=`)  |
| paragraph               | `__Heading.__`               (2 `_`)  |
|-----------------------------------------------------------------|

</code></pre>
<!-- end verbatim block -->

<p>
Note that

<ul>
 <li> Each line begins and ends with a vertical bar (pipe symbol).</li>
 <li> Column data are separated by a vertical bar (pipe symbol).</li>
 <li> There must be a blank line before and after the table.</li>
 <li> There may be horizontal rules, i.e., lines with dashes for
   indicating the heading and the end of the table, and these may
   contain characters 'c', 'l', or 'r' for how to align headings or
   columns. The first horizontal rule may indicate how to align
   headings (center, left, right), and the horizontal rule after the
   heading line may indicate how to align the data in the columns
   (center, left, right).
   One can also use <code>X</code> for potentially very wide text that must be
   wrapped and left-adjusted (will only affect <code>latex</code> and <code>pdflatex</code> where the
   <code>tabularx</code> package is then used; <code>X</code> means <code>l</code> in all other formats).</li>
 <li> If the horizontal rules are without alignment information there should
   be no vertical bar (pipe symbol) between the columns. Otherwise, such
   a bar indicates a vertical bar between columns in LaTeX.</li>
 <li> Many output formats are so primitive that heading and column alignment
   have no effect.</li>
</ul>

A quick way of generating tables is to place all the entries in a file
with comma as separator (a CSV file) and then run the utility
<code>doconce csv2table</code> to create a table in the DocOnce format.

<p>
The command-line option <code>--tables2csv</code> (to <code>doconce format</code>)
makes DocOnce dump each table to CSV format in a file <code>table_X.csv</code>,
where <code>X</code> is the table number. This feature makes it easy to
load tables into spreadsheet programs for further analysis.

<p>
DocOnce tables can be efficiently made directly from data in CSV files.

<p>
<!-- begin verbatim block  sys-->
<pre><code>Terminal&gt; doconce csv2table mydata.csv &gt; mydata_table.do.txt
</code></pre>
<!-- end verbatim block -->
Now we can do <code># #include &quot;mydata_table.do.txt&quot;</code> in the DocOnce
source file or simply copy the table in <code>mydata_table.do.txt</code>
into the DocOnce file.

<h2 id="labels-and-references" class="anchor">Labels and References </h2>

<p>
The notion of labels and references (as well as bibliography and index)
is adopted
from LaTeX with a very similar syntax. As in LaTeX, a label can be
inserted anywhere, using the syntax
<!-- begin verbatim block -->
<pre><code>label{name}
</code></pre>
<!-- end verbatim block -->
with no backslash
preceding the label keyword. It is common practice to choose <code>name</code>
as some hierarchical name, using a delimiter like <code>:</code> or <code>_</code> between
(e.g.) section, subsection, and topic.

<p>
A reference to the label <code>name</code> is written as
<!-- begin verbatim block -->
<pre><code>ref{name}
</code></pre>
<!-- end verbatim block -->
again with no backslash before <code>ref</code>.

<p>
Use labels for sections and equations only, and precede the reference
by "Section" or "Chapter", or in case of an equation, surround the
reference by parenthesis.

<h2 id="citations-and-bibliography" class="anchor">Citations and Bibliography </h2>

<p>
Single citations are written as
<!-- begin verbatim block -->
<pre><code>cite{name}
</code></pre>
<!-- end verbatim block -->
where <code>name</code> is a logical name
of the reference (again, LaTeX writers must not insert a backslash).
Bibliography citations often have <code>name</code> on the form
<code>Author1_Author2_YYYY</code>, <code>Author_YYYY</code>, or <code>Author1_etal_YYYY</code>, where
<code>YYYY</code> is the year of the publication.
Multiple citations at once is possible by separating the logical names
by comma:
<!-- begin verbatim block -->
<pre><code>cite{name1,name2,name3}
</code></pre>
<!-- end verbatim block -->

<p>
The bibliography is specified by a line <code>BIBFILE: papers.pub</code>,
where <code>papers.pub</code> is a publication database in the
<a href="https://github.com/doconce/publish" target="_self">Publish</a> format.
BibTeX <code>.bib</code> files can easily be combined to a Publish database
(which DocOnce needs to create bibliographies in other formats
than LaTeX).

<h2 id="generalized-references" class="anchor">Generalized References </h2>

<p>
There is a <em>generalized referencing</em> feature in DocOnce that allows
a reference with <code>ref</code> to have one formulation if the label is
in the same document and another formulation if the reference is
to an item in an external document. This construction makes it easy
to work with many small, independent documents in parallel with
a book assembly of some of the small elements.
The syntax of a generalized reference is

<p>
<!-- begin verbatim block  do-->
<pre><code>ref[internal][cite][external]
</code></pre>
<!-- end verbatim block -->
with a specific example being

<p>
<!-- begin verbatim block  do-->
<pre><code>As explained in
ref[Section ref{subsec:ex}][in cite{testdoc:12}][a &quot;section&quot;:
&quot;testdoc.html#___sec2&quot; in the document
&quot;A Document for Testing DocOnce&quot;: &quot;testdoc.html&quot; cite{testdoc:12}],
DocOnce documents may include movies.
</code></pre>
<!-- end verbatim block -->
The output from a generalized reference is the text <code>internal</code> if all
references with <code>ref</code> in the text <code>internal</code> are references to labels
defined in the
present document. Otherwise, if <code>cite</code> is non-empty and the format is
<code>latex</code> or <code>pdflatex</code>, one assumes that the references in <code>internal</code>
are to external documents declared by a comment line
<code># Externaldocuments: testdoc, mydoc</code> (usually after the title, authors,
and date). In this case the output text is <code>internal</code> followed by <code>cite</code>,
and the
LaTeX package <code>xr</code> is used to handle the labels in the external
documents.  If none of the two situations above applies, the
<code>external</code> text will be the output.

<h2 id="index-of-keywords" class="anchor">Index of Keywords </h2>

<p>
DocOnce supports creating an index of keywords. A certain keyword
is registered for the index by a syntax like (no
backslash!)
<!-- begin verbatim block -->
<pre><code>index{name}
</code></pre>
<!-- end verbatim block -->
It is recommended to place any index of this type outside
running text, i.e., after (sub)section titles and in the space between
paragraphs. Index specifications placed right before paragraphs also
gives the doconce source code an indication of the content in the
forthcoming text. The index is only produced for the <code>latex</code>,
<code>pdflatex</code>, <code>rst</code>, and <code>sphinx</code> formats.

<h2 id="capabilities-of-the-program-doconce" class="anchor">Capabilities of The Program <code>doconce</code> </h2>

<p>
The <code>doconce</code> program can be used for a number of purposes besides
transforming a <code>.do.txt</code> file to some format. Here is the
list of capabilities:

<p>
<!-- begin verbatim block  shpro-->
<pre><code>DocOnce version 1.5.4 (from /home/amarin/doconce/venv/lib/python3.6/site-packages/DocOnce-1.5.4-py3.6.egg/doconce)
Usage: doconce command [optional arguments]
commands: help format find subst replace remove spellcheck apply_inline_edits capitalize change_encoding clean combine_images csv2table diff expand_commands expand_mako extract_exercises find_nonascii_chars fix_bibtex4publish gitdiff grab grep guess_encoding gwiki_figsubst html2doconce html_colorbullets jupyterbook include_map insertdocstr ipynb2doconce latex2doconce latex_dislikes latex_exercise_toc latex_footer latex_header latex_problems latin2html lightclean linkchecker list_fig_src_files list_labels makefile md2html md2latex old2new_format ptex2tex pygmentize ref_external remove_exercise_answers remove_inline_comments replace_from_file slides_beamer slides_html slides_markdown sphinx_dir sphinxfix_localURLs split_html split_rst teamod

doconce format html|latex|pdflatex|rst|sphinx|plain|gwiki|mwiki|
               cwiki|pandoc|st|epytext dofile 
# transform doconce file to another format

doconce subst [-s -m -x --restore] regex-pattern \ 
        regex-replacement file1 file2 ... 
# substitute a phrase by another using regular expressions (in this example -s is the re.DOTALL modifier, -m is the re.MULTILINE modifier, -x is the re.VERBOSE modifier, --restore copies backup files back again)

doconce replace from-text to-text file1 file2 ...                      
# replace a phrase by another literally (exact text substitution)

doconce replace_from_file file-with-from-to-replacements file1 file2 ... 
# replace using from and to phrases from file

doconce find expression                                                
# search for a (regular) expression in all .do.txt files in the current directory tree (useful when removing compilation errors)

doconce include_map mydoc.do.txt                                       
# print an overview of how various files are included in the root doc

doconce expand_mako mako_code_file funcname file1 file2 ...            
# replace all mako function calls by the `results of the calls

doconce remove_inline_comments dofile                                  
# remove all inline comments in a doconce file

doconce apply_inline_edits                                             
# apply all edits specified through inline comments

doconce sphinx_dir copyright='John Doe' title='Long title' \
        short_title=&quot;Short title&quot; version=0.1 intersphinx \
        /path/to/mylogo.png dofile 
# create a directory for the sphinx format (requires sphinx version &gt;= 1.1)

doconce format sphinx complete_file 
doconce split_rst complete_file 
doconce sphinx_dir complete_file 
python automake_sphinx.py 
# split a sphinx/rst file into parts according to !split commands

doconce insertdocstr rootdir                                           
# walk through a directory tree and insert doconce files as docstrings in *.p.py files

doconce lightclean                                                     
# remove all redundant files (keep source .do.txt and results: .pdf, .html, sphinx- dirs, .mwiki, .ipynb, etc.)

doconce clean                                                          
# remove all files that the doconce can regenerate

doconce change_encoding utf-8 latin1 dofile                            
# change encoding

doconce guess_encoding filename                                        
# guess the encoding in a text

doconce find_nonascii_chars file1 file2 ...                            
# find non-ascii characters in a file

doconce split_html complete_file.html                                  
# split an html file into parts according to !split commands

doconce slides_html slide_type complete_file.html                      
# create HTML slides from a (doconce) html file

doconce slides_beamer complete_file.tex                                
# create LaTeX Beamer slides from a (doconce) latex/pdflatex file

doconce slides_markdown complete_file.md remark --slide_style=light    
# create Remark slides from Markdown

doconce html_colorbullets file1.html file2.html ...                    
# replace bullets in lists by colored bullets

doconce extract_exercises tmp_mako__mydoc                              
# extract all exercises (projects and problems too)

doconce grab --from[-] from-text [--to[-] to-text] file &gt; result       
# grab selected text from a file

doconce remove --from[-] from-text [--to[-] to-text] file &gt; result     
# remove selected text from a file

doconce grep FIGURE|MOVIE|CODE dofile                                  
# list all figure, movie or included code files

doconce spellcheck [-d .mydict.txt] *.do.txt                           
# run spellcheck on a set of files

doconce ptex2tex mydoc -DMINTED pycod=minted sys=Verbatim \
        dat=\begin{quote}\begin{verbatim};\end{verbatim}\end{quote} 
# transform ptex2tex files (.p.tex) to ordinary latex file and manage the code environments

doconce md2html file.md                                                
# make HTML file via pandoc from Markdown (.md) file

doconce md2latex file.md                                               
# make LaTeX file via pandoc from Markdown (.md) file

doconce combine_images image1 image2 ... output_file                   
# combine several images into one

doconce latex_problems mydoc.log [overfull-hbox-limit]                 
# report problems from a LaTeX .log file

doconce list_fig_src_files *.do.txt                                    
# list all figure files, movie files, and source code files needed

doconce list_labels myfile                                             
# list all labels in a document (for purposes of cleaning them up)

doconce ref_external mydoc [pubfile]                                   
# generate script for substituting generalized references

doconce linkchecker *.html                                             
# check all links in HTML files

doconce capitalize [-d .mydict.txt] *.do.txt                           
# change headings from &quot;This is a Heading&quot; to &quot;This is a heading&quot;

doconce latex2doconce latexfile                                        
# translate a latex document to doconce (requires usually manual fixing)

doconce latex_dislikes latexfile                                       
# check if there are problems with translating latex to doconce

doconce ipynb2doconce notebookfile                                     
# translate an IPython/Jupyter notebook to doconce

doconce pygmentize myfile [pygments-style]                             
# typeset a doconce document with pygments (for pretty print of doconce itself)

doconce makefile docname doconcefile [html sphinx pdflatex ...]        
# generate a make.py script for translating a doconce file to various formats

doconce diff file1.do.txt file2.do.txt [diffprog]                      
# find differences between two files (diffprog can be difflib, diff, pdiff, latexdiff, kdiff3, diffuse, ...)

doconce gitdiff file1 file2 file3 ...                                  
# find differences between the last two Git versions of several files

doconce csv2table somefile.csv                                         
# convert csv file to doconce table format

doconce sphinxfix_local_URLs file.rst                                  
# edit URLs to local files and place them in _static

doconce latin2html file.html                                           
# replace latex-1 (non-ascii) characters by html codes

doconce fix_bibtex4publish file1.bib file2.bib ...                     
# fix common problems in bibtex files for publish import

doconce latex_header                                                   
# print the header (preamble) for latex file

doconce latex_footer                                                   
# print the footer for latex files

doconce expand_commands file1 file2 ...                                
# expand short cut commands to full form in files

doconce latex_exercise_toc myfile                                      
# insert a table of exercises in a latex file myfile.p.tex
</code></pre>
<!-- end verbatim block -->

<h2 id="exercises" class="anchor">Exercises </h2>

<p>
DocOnce supports <em>Exercise</em>, <em>Problem</em>, <em>Project</em>, and <em>Example</em>.
These are typeset
as ordinary sections and referred to by their section labels.
Exercise, problem, project, or example sections contains certain <em>elements</em>:

<ul>
  <li> a headline at the level of a subsection
    containing one of the words "Exercise:", "Problem:",
    "Project:", or "Example:", followed by a title (required)</li>
  <li> a label (optional)</li>
  <li> a solution file (optional)</li>
  <li> name of file with a student solution (optional)</li>
  <li> main exercise text (required)</li>
  <li> a short answer (optional)</li>
  <li> a full solution (optional)</li>
  <li> one or more hints (optional)</li>
  <li> one or more subexercises (subproblems, subprojects), which can also
    contain a text, a short answer, a full solution, name student file
    to be handed in, and one or more hints (optional)</li>
</ul>

A typical sketch of a a problem without subexercises goes as follows:
<!-- begin verbatim block -->
<pre><code>===== Problem: Derive the Formula for the Area of an Ellipse =====
label{problem:ellipsearea1}
file=ellipse_area.pdf
solution=ellipse_area1_sol.pdf

Derive an expression for the area of an ellipse by integrating
the area under a curve that defines half of the ellipse.
Show each step in the mathematical derivation.

!bhint
Wikipedia has the formula for the curve.
!ehint

!bhint
&quot;Wolframalpha&quot;: &quot;http://wolframalpha.com&quot; can perhaps
compute the integral.
!ehint
</code></pre>
<!-- end verbatim block -->
If the exercise type (Exercise, Problem, Project, or Example)
is enclosed in braces, the type is left out of the title in the
output. For example, the if the title line above reads

<p>
<!-- begin verbatim block -->
<pre><code>===== {Problem}: Derive the Formula for the Area of an Ellipse =====
</code></pre>
<!-- end verbatim block -->
the title becomes just "Derive the ...".

<p>
An exercise with subproblems, answers and full solutions has this
setup-up:

<p>
<!-- begin verbatim block -->
<pre><code>===== Exercise: Determine the Distance to the Moon =====
label{exer:moondist}

Intro to this exercise. Questions are in subexercises below.

!bsubex
Subexercises are numbered a), b), etc.

file=subexer_a.pdf

!bans
Short answer to subexercise a).
!eans

!bhint
First hint to subexercise a).
!ehint

!bhint
Second hint to subexercise a).
!ehint
!esubex

!bsubex
Here goes the text for subexercise b).

file=subexer_b.pdf

!bhint
A hint for this subexercise.
!ehint

!bsol
Here goes the solution of this subexercise.
!esol
!esubex

!bremarks
At the very end of the exercise it may be appropriate to summarize
and give some perspectives. The text inside the `!bremarks` and `!eremarks`
directives is always typeset at the end of the exercise.
!eremarks

!bsol
Here goes a full solution of the whole exercise.
!esol

</code></pre>
<!-- end verbatim block -->
By default, answers, solutions, and hints are typeset as paragraphs.
The command-line arguments <code>--without_answers</code> and <code>--without_solutions</code>
turn off output of answers and solutions, respectively, except for examples. The command line options <code>--answers_at_end</code> and <code>--solutions_at_end</code> write all answers and solutions to exercises to a separate section at the end of the document, respectively. Combine with <code>--without_answers</code> and <code>--without_solutions</code> to remove answers and solutions from the main text.

<p>
The commands <code>!anshide</code> and <code>!solhide</code> can be used to hide from the main text answers and solutions, respectively, until the <code>!ansoff</code> and <code>!soloff</code> commands are encountered. Similarly, the <code>!ansdocend</code> and <code>!soldocend</code> commands move answers and solutions to the end of the book.

<h2 id="environments" class="anchor">Environments </h2>

<p>
DocOnce environments start with <code>!benvirname</code> and end with <code>!eenvirname</code>,
where <code>envirname</code> is the name of the environment. Here is a listing of
the environments:

<ul>
 <li> <code>c</code>: computer code (or verbatim text)</li>
 <li> <code>t</code>: math blocks with LaTeX syntax</li>
 <li> <code>subex</code>: sub-exercise</li>
 <li> <code>ans</code>: short answer to exercise or sub-exercise</li>
 <li> <code>sol</code>: full solution to exercise or sub-exercise</li>
 <li> <code>hint</code>: multiple help items in an exercise or sub-exercise</li>
 <li> <code>quote</code>: indented text</li>
 <li> <code>notice</code>, <code>summary</code>, <code>warning</code>, <code>question</code>: admonition boxes with
    custom title, special icon, and (sometimes) background color</li>
 <li> <code>block</code>, <code>box</code>: simpler boxes (<code>block</code> may have title but never any icon)</li>
 <li> <code>pop</code>: text to gradually pop up in slide presentations</li>
 <li> <code>slidecell</code>: indication of cells in a grid layout for elements on a
   slide</li>
</ul>

In addition, the user can define new environments <code>!bc-name</code> as
explained in the <a href="http://doconce.github.io/doconce/doc/pub/manual/manual.html#manual:userdef:envir" target="_self">manual</a>.

<h2 id="preprocessing" class="anchor">Preprocessing </h2>

<p>
DocOnce documents may utilize a preprocessor, either <code>preprocess</code> and/or
<code>mako</code>. The former is a C-style preprocessor that allows if-tests
and including other files (but not macros with arguments).
The <code>mako</code> preprocessor is much more advanced - it is actually a full
programming language, very similar to Python.

<p>
The command <code>doconce format</code> first runs <code>preprocess</code> and then <code>mako</code>.
Here is a typical example on utilizing <code>preprocess</code> to include another
document, &quot;comment out&quot; a large portion of text, and to write format-specific
constructions:

<p>
<!-- begin verbatim block  do-->
<pre><code># #include &quot;myotherdoc.do.txt&quot;

# #if FORMAT in (&quot;latex&quot;, &quot;pdflatex&quot;)
\begin{table}
\caption{Some words... label{mytab}}
\begin{tabular}{lrr}
\hline\noalign{\smallskip}
\multicolumn{1}{c}{time} &amp; \multicolumn{1}{c}{velocity} &amp; \multicolumn{1}{c}{acceleration} \\ 
\hline
0.0          &amp; 1.4186       &amp; -5.01        \\ 
2.0          &amp; 1.376512     &amp; 11.919       \\ 
4.0          &amp; 1.1E+1       &amp; 14.717624    \\ 
\hline
\end{tabular}
\end{table}
# #else
  |--------------------------------|
  |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    |
  |--------------------------------|
# #endif

# #ifdef EXTRA_MATERIAL
....large portions of text...
# #endif
</code></pre>
<!-- end verbatim block -->

<p>
With the <code>mako</code> preprocessor the if-else tests have slightly different syntax.
An <a href="http://doconce.github.com/bioinf-py/" target="_self">example document</a> contains
some illustrations on how to utilize <code>mako</code> (clone the GitHub project and
examine the DocOnce source and the <code>doc/src/make.sh</code> script).

<h2 id="resources" class="anchor">Resources </h2>

<ul>
 <li> Excellent "Sphinx Tutorial" by C. Reller: "http://people.ee.ethz.ch/~creller/web/tricks/reST.html"</li>
</ul>


<!-- ------------------- end of main content --------------- -->

</div>  <!-- end container -->
<!-- include javascript, jQuery *first* -->
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>
<script src="https://netdna.bootstrapcdn.com/bootstrap/3.0.0/js/bootstrap.min.js"></script>

<!-- Bootstrap footer
<footer>
<a href="https://..."><img width="250" align=right src="https://..."></a>
</footer>
-->


</body>
</html>
    


************** File: quickref.tex *****************
%%
%% Automatically generated file from DocOnce source
%% (https://github.com/hplgit/doconce/)
%%

% #define PREAMBLE

% #ifdef PREAMBLE
%-------------------- begin preamble ----------------------

\documentclass[%
oneside,                 % oneside: electronic viewing, twoside: printing
final,                   % draft: marks overfull hboxes, figures with paths
10pt]{article}

\listfiles               %  print all files needed to compile this document

\usepackage{relsize,makeidx,color,setspace,amsmath,amsfonts,amssymb}
\usepackage[table]{xcolor}
\usepackage{bm,ltablex,microtype}

\usepackage[pdftex]{graphicx}

% Tools for marking corrections
\usepackage{soul}
\newcommand{\replace}[2]{{\color{red}\text{\st{#1} #2}}}
\newcommand{\remove}[1]{{\color{red}\st{#1}}}

% Movies are handled by the href package
\newenvironment{doconce:movie}{}{}
\newcounter{doconce:movie:counter}


% Packages for typesetting blocks of computer code
\usepackage{fancyvrb,framed,moreverb}

% Define colors
\definecolor{orange}{cmyk}{0,0.4,0.8,0.2}
\definecolor{tucorange}{rgb}{1.0,0.64,0}
\definecolor{darkorange}{rgb}{.71,0.21,0.01}
\definecolor{darkgreen}{rgb}{.12,.54,.11}
\definecolor{myteal}{rgb}{.26, .44, .56}
\definecolor{gray}{gray}{0.45}
\definecolor{mediumgray}{gray}{.8}
\definecolor{lightgray}{gray}{.95}
\definecolor{brown}{rgb}{0.54,0.27,0.07}
\definecolor{purple}{rgb}{0.5,0.0,0.5}
\definecolor{darkgray}{gray}{0.25}
\definecolor{darkblue}{rgb}{0,0.08,0.45}
\definecolor{darkblue2}{rgb}{0,0,0.8}
\definecolor{lightred}{rgb}{1.0,0.39,0.28}
\definecolor{lightgreen}{rgb}{0.48,0.99,0.0}
\definecolor{lightblue}{rgb}{0.53,0.81,0.92}
\definecolor{lightblue2}{rgb}{0.3,0.3,1.0}
\definecolor{lightpurple}{rgb}{0.87,0.63,0.87}
\definecolor{lightcyan}{rgb}{0.5,1.0,0.83}

\colorlet{comment_green}{green!50!black}
\colorlet{string_red}{red!60!black}
\colorlet{keyword_pink}{magenta!70!black}
\colorlet{indendifier_green}{green!70!white}

% Backgrounds for code
\definecolor{cbg_gray}{rgb}{.95, .95, .95}
\definecolor{bar_gray}{rgb}{.92, .92, .92}

\definecolor{cbg_yellowgray}{rgb}{.95, .95, .85}
\definecolor{bar_yellowgray}{rgb}{.95, .95, .65}

\colorlet{cbg_yellow2}{yellow!10}
\colorlet{bar_yellow2}{yellow!20}

\definecolor{cbg_yellow1}{rgb}{.98, .98, 0.8}
\definecolor{bar_yellow1}{rgb}{.98, .98, 0.4}

\definecolor{cbg_red1}{rgb}{1, 0.85, 0.85}
\definecolor{bar_red1}{rgb}{1, 0.75, 0.85}

\definecolor{cbg_blue1}{rgb}{0.87843, 0.95686, 1.0}
\definecolor{bar_blue1}{rgb}{0.7,     0.95686, 1}


\usepackage[T1]{fontenc}
%\usepackage[latin1]{inputenc}
\usepackage{ucs}
\usepackage[utf8x]{inputenc}

% Set helvetica as the default font family:
\RequirePackage{helvet}
\renewcommand\familydefault{phv}

\usepackage{lmodern}         % Latin Modern fonts derived from Computer Modern

% Hyperlinks in PDF:
\definecolor{linkcolor}{rgb}{0,0,0.4}
\usepackage{hyperref}
\hypersetup{
    breaklinks=true,
    colorlinks=true,
    linkcolor=linkcolor,
    urlcolor=linkcolor,
    citecolor=black,
    filecolor=black,
    %filecolor=blue,
    pdfmenubar=true,
    pdftoolbar=true,
    bookmarksdepth=3   % Uncomment (and tweak) for PDF bookmarks with more levels than the TOC
    }
%\hyperbaseurl{}   % hyperlinks are relative to this root

\setcounter{tocdepth}{2}  % levels in table of contents

% Tricks for having figures close to where they are defined:
% 1. define less restrictive rules for where to put figures
\setcounter{topnumber}{2}
\setcounter{bottomnumber}{2}
\setcounter{totalnumber}{4}
\renewcommand{\topfraction}{0.95}
\renewcommand{\bottomfraction}{0.95}
\renewcommand{\textfraction}{0}
\renewcommand{\floatpagefraction}{0.75}
% floatpagefraction must always be less than topfraction!
% 2. ensure all figures are flushed before next section
\usepackage[section]{placeins}
% 3. enable begin{figure}[H] (often leads to ugly pagebreaks)
%\usepackage{float}\restylefloat{figure}

% newcommands for typesetting inline (doconce) comments
\newcommand{\shortinlinecomment}[3]{{\color{red}{\bf #1}: #2}}
\newcommand{\longinlinecomment}[3]{{\color{red}{\bf #1}: #2}}

\usepackage[framemethod=TikZ]{mdframed}

% --- begin definitions of admonition environments ---

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "notice" admon
\colorlet{mdfbox_notice_background}{gray!5}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_notice_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=mdfbox_notice_background,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{notice_mdfboxmdframed}

\newenvironment{notice_mdfboxadmon}[1][]{
\begin{notice_mdfboxmdframed}[frametitle=#1]
}
{
\end{notice_mdfboxmdframed}
}

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "summary" admon
\colorlet{mdfbox_summary_background}{gray!5}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_summary_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=mdfbox_summary_background,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{summary_mdfboxmdframed}

\newenvironment{summary_mdfboxadmon}[1][]{
\begin{summary_mdfboxmdframed}[frametitle=#1]
}
{
\end{summary_mdfboxmdframed}
}

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "warning" admon
\colorlet{mdfbox_warning_background}{gray!5}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_warning_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=mdfbox_warning_background,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{warning_mdfboxmdframed}

\newenvironment{warning_mdfboxadmon}[1][]{
\begin{warning_mdfboxmdframed}[frametitle=#1]
}
{
\end{warning_mdfboxmdframed}
}

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "question" admon
\colorlet{mdfbox_question_background}{gray!5}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_question_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=mdfbox_question_background,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{question_mdfboxmdframed}

\newenvironment{question_mdfboxadmon}[1][]{
\begin{question_mdfboxmdframed}[frametitle=#1]
}
{
\end{question_mdfboxmdframed}
}

% Admonition style "mdfbox" is an oval colored box based on mdframed
% "block" admon
\colorlet{mdfbox_block_background}{gray!5}
\newmdenv[
  skipabove=15pt,
  skipbelow=15pt,
  outerlinewidth=0,
  backgroundcolor=mdfbox_block_background,
  linecolor=black,
  linewidth=2pt,       % frame thickness
  frametitlebackgroundcolor=mdfbox_block_background,
  frametitlerule=true,
  frametitlefont=\normalfont\bfseries,
  shadow=false,        % frame shadow?
  shadowsize=11pt,
  leftmargin=0,
  rightmargin=0,
  roundcorner=5,
  needspace=0pt,
]{block_mdfboxmdframed}

\newenvironment{block_mdfboxadmon}[1][]{
\begin{block_mdfboxmdframed}[frametitle=#1]
}
{
\end{block_mdfboxmdframed}
}

% --- end of definitions of admonition environments ---

% prevent orhpans and widows
\clubpenalty = 10000
\widowpenalty = 10000

\usepackage{calc}

\newenvironment{doconceexercise}{}{}
\newcounter{doconceexercisecounter}


% ------ header in subexercises ------
%\newcommand{\subex}[1]{\paragraph{#1}}
%\newcommand{\subex}[1]{\par\vspace{1.7mm}\noindent{\bf #1}\ \ }
\makeatletter
% 1.5ex is the spacing above the header, 0.5em the spacing after subex title
\newcommand\subex{\@startsection{paragraph}{4}{\z@}%
                  {1.5ex\@plus1ex \@minus.2ex}%
                  {-0.5em}%
                  {\normalfont\normalsize\bfseries}}
\makeatother


% --- end of standard preamble for documents ---

%%% USER-DEFINED ENVIRONMENTS


% insert custom LaTeX commands...

\raggedbottom
\makeindex
\usepackage[totoc]{idxlayout}   % for index in the toc
\usepackage[nottoc]{tocbibind}  % for references/bibliography in the toc

%-------------------- end preamble ----------------------

\begin{document}

% matching end for #ifdef PREAMBLE
% #endif

\newcommand{\exercisesection}[1]{\subsection*{#1}}


% ------------------- main content ----------------------



% ----------------- title -------------------------

\thispagestyle{empty}

\begin{center}
{\LARGE\bf
\begin{spacing}{1.25}
DocOnce Quick Reference
\end{spacing}
}
\end{center}

% ----------------- author(s) -------------------------

\begin{center}
{\bf Hans Petter Langtangen${}^{1, 2}$} \\ [0mm]
\end{center}

\begin{center}
% List of all institutions:
\centerline{{\small ${}^1$Center for Biomedical Computing, Simula Research Laboratory}}
\centerline{{\small ${}^2$Department of Informatics, University of Oslo}}
\end{center}
    
% ----------------- end author(s) -------------------------

% --- begin date ---
\begin{center}
Jan 32, 2100
\end{center}
% --- end date ---

\vspace{1cm}


\tableofcontents


\vspace{1cm} % after toc




\textbf{WARNING: This quick reference is very incomplete!}

\paragraph{Mission.}
Enable writing documentation with much mathematics and
computer code \emph{once, in one place} and include it in traditional {\LaTeX}
books, thesis, and reports, and, without extra efforts, also make
professional looking web versions with Sphinx or HTML. Other outlets
include Google's \texttt{blogger.com}, Wikipedia/Wikibooks, IPython/Jupyter
notebooks, plus a wide variety of other formats for documents without
mathematics and code.

\subsection{Supported Formats}

DocOnce currently translates files to the following formats:

\begin{itemize}
 \item {\LaTeX} (format \texttt{latex} or \texttt{pdflatex})

 \item HTML (format \texttt{html})

 \item Sphinx (format \texttt{sphinx})

 \item Pandoc-extended or GitHub-flavored Markdown (format \texttt{pandoc})

 \item IPython notebook (format \texttt{ipynb})

 \item Matlab notebook (format \texttt{matlabnb})

 \item MediaWiki (format \texttt{mwiki})

 \item Googlecode wiki (format \texttt{gwiki})

 \item Creoloe wiki (format \texttt{cwiki})

 \item reStructuredText (format \texttt{rst})

 \item plain (untagged) ASCII (format \texttt{plain})

 \item Epydoc (format \texttt{epydoc})

 \item StructuredText (format \texttt{st})
\end{itemize}

\noindent
For documents with much code and mathematics, the best (and most supported)
formats are \texttt{latex}, \texttt{pdflatex}, \texttt{sphinx}, and \texttt{html}; and to a slightly
less extent \texttt{mwiki} and \texttt{pandoc}. The HTML format supports blog posts on
Google and Wordpress.


\begin{warning_mdfboxadmon}[Use a text editor with monospace font!]
Some DocOnce constructions are sensitive to whitespace,
so you \emph{must} use a text editor with monospace font.
\end{warning_mdfboxadmon} % title: Use a text editor with monospace font!



\subsection{Emacs syntax support}

The file \href{{https://github.com/doconce/doconce/blob/master/misc/.doconce-mode.el}}{.doconce-mode.el}
in the DocOnce source distribution gives a "DocOnce Editing Mode" in
Emacs. Store the raw version of the file in the home directory and add
\texttt{(load-file "~/.doconce-mode.el")} to the \texttt{.emacs} file.

Besides syntax highlighting of DocOnce documents, this Emacs mode
provides a lot of shortcuts for setting up many elements in a document:


\begin{quote}
\begin{tabular}{ll}
\hline
\multicolumn{1}{c}{ Emacs key } & \multicolumn{1}{c}{ Action } \\
\hline
Ctrl+c f      & figure                                           \\
Ctrl+c v      & movie/video                                      \\
Ctrl+c h1     & heading level 1 (section/h1)                     \\
Ctrl+c h2     & heading level 2 (subsection/h2)                  \\
Ctrl+c h3     & heading level 2 (subsection/h3)                  \\
Ctrl+c hp     & heading for paragraph                            \\
Ctrl+c me     & math environment: \Verb?!bt? equation \Verb?!et? \\
Ctrl+c ma     & math environment: \Verb?!bt? align \Verb?!et?    \\
Ctrl+c ce     & code environment: \Verb?!bc? code \Verb?!ec?     \\
Ctrl+c cf     & code from file: \texttt{@@@CODE}                   \\
Ctrl+c table2 & table with 2 columns                             \\
Ctrl+c table3 & table with 3 columns                             \\
Ctrl+c table4 & table with 4 columns                             \\
Ctrl+c exer   & exercise outline                                 \\
Ctrl+c slide  & slide outline                                    \\
Ctrl+c help   & print this table                                 \\
\hline
\end{tabular}
\end{quote}

\noindent
\subsection{Title, Authors, and Date}

A typical example of giving a title, a set of authors, a date,
and an optional table of contents
reads

\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=2mm]
TITLE: On an Ultimate Markup Language
AUTHOR: H. P. Langtangen at Center for Biomedical Computing, Simula Research Laboratory & Dept. of Informatics, Univ. of Oslo
AUTHOR: Kaare Dump Email: dump@cyb.space.com at Segfault, Cyberspace Inc.
AUTHOR: A. Dummy Author
DATE: today
TOC: on
\end{Verbatim}
The entire title must appear on a single line.
The author syntax is
\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=2mm]
name Email: somename@adr.net at institution1 & institution2
\end{Verbatim}
where the email is optional, the "at" keyword is required if one or
more institutions are to be specified, and the \Verb!&! keyword
separates the institutions (the keyword \texttt{and} works too).
Each author specification must appear
on a single line.
When more than one author belong to the
same institution, make sure that the institution is specified in an identical
way for each author.

The date can be set as any text different from \texttt{today} if not the
current date is wanted, e.g., \texttt{Jan 32, 2100}.

The table of contents is removed by writing \texttt{TOC: off}.

\subsection{Copyright}

% Recall to ident AUTHOR commands to avoid interpretation

Copyright for selected authors and/or institutions are easy to insert as part
of the \texttt{AUTHOR} command. The copyright syntax is

\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=2mm]
{copyright,year1-year2|license}
\end{Verbatim}
and can be placed after the author or after an institution, e.g.,

\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=2mm]
 AUTHOR: name Email: somename@adr.net {copyright,2006-present} at inst1
 AUTHOR: name {copyright} at inst1 {copyright}
\end{Verbatim}
The first line gives \texttt{name} a copyright for 2006 up to the present year,
while the second line gives copyright to \texttt{name} and the institution \texttt{inst1}
for the present year. The license can be any formulation, but there are
some convenient abbreviations for Creative Commons (``public domain'')
licenses: \texttt{CC BY} for Creative Commons Attribution 4.0 license,
\texttt{CC BY-NC} for Creative Commons Attribution-NonCommercial 4.0 license.
For example,

\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=2mm]
 AUTHOR: name1 {copyright|CC BY} at institution1
 AUTHOR: name2 {copyright|CC BY} at institution2
\end{Verbatim}
is a very common copyright for the present year with the Attribution license.
The copyright must be identical for all authors and institutions.


\subsection{Section Types}
\label{quick:sections}


\begin{quote}
\begin{tabular}{ll}
\hline
\multicolumn{1}{c}{ Section type } & \multicolumn{1}{c}{ Syntax } \\
\hline
chapter       & \texttt{========= Heading ========} (9 \texttt{=})        \\
section       & \texttt{======= Heading =======}    (7 \texttt{=})        \\
subsection    & \texttt{===== Heading =====}        (5 \texttt{=})        \\
subsubsection & \texttt{=== Heading ===}            (3 \texttt{=})        \\
paragraph     & \Verb!__Heading.__!               (2 \Verb!_!)        \\
abstract      & \Verb!__Abstract.__! Running text...                  \\
appendix      & \texttt{======= Appendix: heading =======} (7 \texttt{=}) \\
appendix      & \texttt{===== Appendix: heading =====} (5 \texttt{=})     \\
exercise      & \texttt{===== Exercise: heading =====} (5 \texttt{=})     \\
\hline
\end{tabular}
\end{quote}

\noindent
Note that abstracts are recognized by starting with \Verb!__Abstract.__! or
\Verb!__Summary.__! at the beginning of a line and ending with three or
more \texttt{=} signs of the next heading.

The \texttt{Exercise:} keyword can be substituted by \texttt{Problem:} or \texttt{Project:}.
A recommended convention is that an exercise is tied to the text,
a problem can stand on its own, and a project is a comprehensive
problem.

\subsection{Inline Formatting}

Words surrounded by \texttt{*} are emphasized: \texttt{*emphasized words*} becomes
\emph{emphasized words}. Similarly, an underscore surrounds words that
appear in boldface: \Verb!_boldface_! becomes \textbf{boldface}. Colored words
are also possible: the text

\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=2mm]
`color{red}{two red words}`
\end{Verbatim}
becomes \textcolor{red}{two red words}.

Quotations appear inside double backticks and double single quotes:

\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=2mm]
This is a sentence with ``words to be quoted''.
\end{Verbatim}

A forced linebreak is specified by \texttt{<linebreak>} at the point where the
linebreak in the output is wanted.

Footnotes use a label in the text with the footnote text separate,
preferably after the paragraph where the footnote appears:

\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=2mm]
Differentiating[^diff2] this equation leads
to a new and much simpler equation.

[^diff2]: More precisely, we apply the divergence
$\nabla\cdot$ on both sides.

Here comes a new paragraph...
\end{Verbatim}

Non-breaking space is inserted using the tilde character as in {\LaTeX}:

\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=2mm]
This distance corresponds to 7.5~km, which is traveled in $7.5/5$~s.
\end{Verbatim}

A horizontal rule for separating content vertically, like this:

-----

is typeset as four or more hyphens on a single line:

\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=2mm]
---------
\end{Verbatim}

The \texttt{latex}, \texttt{pdflatex}, \texttt{sphinx}, and \texttt{html} formats support em-dash,
indicated by three hyphens: \texttt{---}. Here is an example:

\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=2mm]
The em-dash is used - without spaces - as alternative to hyphen with
space around in sentences---this way, or in quotes:
*Premature optimization is the root of all evil.*--- Donald Knuth.
\end{Verbatim}
This text is in the pdflatex rendered as

The em-dash is used - without spaces - as alternative to hyphen with
space around in sentences---this way, or in quotes:
\emph{Premature optimization is the root of all evil.}--- Donald Knuth.

The en-dash consists of two hyphens, either with blanks on both sides -- for
something in the middle of a sentence -- or in number ranges like 240--249.
{\LaTeX} writes are used to and fond of en-dash.

An ampersand, as in Guns {\&} Roses or,Texas A {\&} M, is written as a
plain \Verb!&! \emph{with space(s) on both sides}. Single upper case letters on each
side of \Verb!&!, as in \Verb!Texas A {\&} M!, remove the spaces and result in,Texas A {\&} M, while words on both sides of \Verb!&!, as in \Verb!Guns {\&} Roses!,
preserve the spaces: Guns {\&} Roses. Failing to have spaces before and
after \Verb!&! will result in wrong typesetting of the ampersand in the \texttt{html},
\texttt{latex}, and \texttt{pdflatex} formats.

Emojis, as defined in \href{{http://www.emoji-cheat-sheet.com}}{\nolinkurl{http://www.emoji-cheat-sheet.com}}, can be
inserted in the text, as (e.g.) \Verb!:dizzy_face:! with blank or newline
before or after \raisebox{-\height+\ht\strutbox}{\includegraphics[height=1.5em]{latex_figs/dizzy_face.png}} Only the \texttt{pdflatex}, \texttt{html}, and \texttt{pandoc} output
formats translate emoji specifications to images, while all other
formats leave the textual specification in the document. The
command-line option \Verb!--no_emoji! removes all emojis from the output
document.

\subsection{Lists}

There are three types of lists: \emph{bullet lists}, where each item starts
with \texttt{*}, \emph{enumeration lists}, where each item starts with \texttt{o} and gets
consecutive numbers,
and \emph{description} lists, where each item starts with \texttt{-} followed
by a keyword and a colon.
\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=2mm]
Here is a bullet list:

 * item1
 * item2
  * subitem1 of item2
  * subitem2 of item2,
    second line of subitem2
 * item3

Note that sublists are consistently indented by one or more blanks as
shown: bullets must exactly match and continuation lines must start
right below the line above.

Here is an enumeration list:

 o item1
 o item2
   may appear on
   multiple lines
  o subitem1 of item2
  o subitem2 of item2
 o item3

And finally a description list:

 - keyword1: followed by
   some text
   over multiple
   lines
 - keyword2:
   followed by text on the next line
 - keyword3: and its description may fit on one line
\end{Verbatim}
The code above follows.

Here is a bullet list:

\begin{itemize}
 \item item1

 \item item2
\begin{itemize}

  \item subitem1 of item2

  \item subitem2 of item2

\end{itemize}

\noindent
 \item item3
\end{itemize}

\noindent
Note that sublists are consistently indented by one or more blanks as
shown: bullets must exactly match and continuation lines must start
right below the line above.

Here is an enumeration list:

\begin{enumerate}
\item item1

\item item2
   may appear on
   multiple lines
\begin{enumerate}

 \item subitem1 of item2

 \item subitem2 of item2

\end{enumerate}

\noindent
\item item3
\end{enumerate}

\noindent
And finally a description list:

\begin{description}
 \item[keyword1:] 
   followed by
   some text
   over multiple
   lines

 \item[keyword2:] 
   followed by text on the next line

 \item[keyword3:] 
   and its description may fit on one line
\end{description}

\noindent

\begin{warning_mdfboxadmon}[No indentation - except in lists!]
DocOnce syntax is sensitive to whitespace.
No lines should be indented, only lines belonging to lists.
Indented lines may give strange output in some formats.
\end{warning_mdfboxadmon} % title: No indentation - except in lists!




\subsection{Comment lines}

Lines starting with \Verb!#! are treated as comments in the document and
translated to the proper syntax for comments in the output
document. Such comment lines should not appear before {\LaTeX} math
blocks, verbatim code blocks, or lists if the formats \texttt{rst} and
\texttt{sphinx} are desired.

Comment lines starting with \Verb!##! are not propagated to the output
document and can be used for comments that are only of interest in
the DocOnce file.

Large portions of text can be left out using Preprocess. Just place
\Verb!# #ifdef EXTRA! and \Verb!# #endif! around the text. The command line
option \texttt{-DEXTRA} will bring the text alive again.

When using the Mako preprocessor one can also place comments in
the DocOnce source file that will be removed by Mako before
DocOnce starts processing the file.


\subsection{Inline comments}

Inline comments meant as messages or notes, to authors during development
in particular,
are enabled by the syntax
\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=2mm]
[name: running text]
\end{Verbatim}
where \texttt{name} is the name or ID of an author or reader making the comment,
and \texttt{running text} is the comment. The name can contain upper and lower
case characters, digits, single quote, \texttt{+} and \texttt{-}, as well
as space. Here goes an example.

\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=2mm]
Some running text. [hpl: There must be a space after the colon,
but the running text can occupy multiple lines.]
\end{Verbatim}
which is rendered as


\begin{quote}
Some running text. \shortinlinecomment{hpl 1}{ There must be a space after the colon, but the running text can occupy multiple lines. }{ There must be a }
\end{quote}


The inline comments have simple typesetting in most formats, typically
boldface name, a comment number, with everything surrounded by
parenthesis.  However, with {\LaTeX} output and the \Verb!--latex_todonotes!
option to \texttt{doconce format}, colorful margin or inline boxes (using the
\texttt{todonotes} package) make it very easy to spot the comments.

Running
\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=2mm]
doconce format html mydoc.do.txt --skip_inline_comments
\end{Verbatim}
removes all inline comments from the output. This feature makes it easy
to turn on and off notes to authors during the development of the document.

All inline comments to readers can also be physically
removed from the DocOnce source by
\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=2mm]
doconce remove_inline_comments mydoc.do.txt
\end{Verbatim}

Inline comments can also be used to markup edits. There are add, delete, and
replacement comments for editing:

\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=2mm]
[add: ,]
[add: .]
[add: ;]
[del: ,]
[del: ,]
[del: .]
[del: ;]
[add: some text]
[del: some text]
[edit: some text -> some replacement for text]
[name: some text -> some replacement for text]
\end{Verbatim}

For example, the text

\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=2mm]
First consider a quantity $Q$. Without loss of generality, we assume
$Q>0$. There are three, fundamental, basic property of $Q$.
\end{Verbatim}
can be edited as

\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=2mm]
First[add: ,] consider [edit: a quantity -> the flux]
[del: $Q$. Without loss of generality,
we assume] $Q>0$. There are three[del: ,] fundamental[del: , basic]
[edit: property -> properties] of $Q$. [add: These are not
important for the following discussion.]
\end{Verbatim}
which in the pdflatex output format results in


\begin{quote}
First\textcolor{red}{, (\textbf{edit 2}: add comma)} consider \textcolor{red}{(edit 3:)} \replace{a quantity}{the flux}
(\textbf{edit 4}:) \remove{$Q$. Without loss of generality,
we assume} $Q>0$. There are three \textcolor{red}{ (\textbf{edit 5}: delete comma)} fundamental(\textbf{edit 6}:) \remove{, basic}
\textcolor{red}{(edit 7:)} \replace{property}{properties} of $Q$.  \textcolor{red}{ (\textbf{edit 8}:) These are not
important for the following discussion.}
\end{quote}


To implement these edits, run

\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=2mm]
Terminal> doconce apply_edit_comments mydoc.do.txt
\end{Verbatim}

\subsection{Verbatim/Computer Code}

Inline verbatim code is typeset within back-ticks, as in
\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=2mm]
Some sentence with `words in verbatim style`.
\end{Verbatim}
resulting in Some sentence with \texttt{words in verbatim style}.

Multi-line blocks of verbatim text, typically computer code, is typeset
in between \Verb?!bc xxx? and \Verb?!ec? directives, which must appear on the
beginning of the line. A specification \texttt{xxx} indicates what verbatim
formatting style that is to be used. Typical values for \texttt{xxx} are
nothing, \texttt{cod} for a code snippet, \texttt{pro} for a complete program,
\texttt{sys} for a terminal session, \texttt{dat} for a data file (or output from a
program),
\texttt{Xpro} or \texttt{Xcod} for a program or code snipped, respectively,
in programming \texttt{X}, where \texttt{X} may be \texttt{py} for Python,
\texttt{cy} for Cython, \texttt{sh} for Bash or other Unix shells,
\texttt{f} for Fortran, \texttt{c} for C, \texttt{cpp} for C++, \texttt{m} for MATLAB,
\texttt{pl} for Perl. For output in \texttt{latex} one can let \texttt{xxx} reflect any
defined verbatim environment in the \texttt{ptex2tex} configuration file
(\texttt{.ptex2tex.cfg}). For \texttt{sphinx} output one can insert a comment
\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=2mm]
# sphinx code-blocks: pycod=python cod=fortran cppcod=c++ sys=console
\end{Verbatim}
that maps environments (\texttt{xxx}) onto valid language types for
Pygments (which is what \texttt{sphinx} applies to typeset computer code).

The \texttt{xxx} specifier has only effect for \texttt{latex} and
\texttt{sphinx} output. All other formats use a fixed monospace font for all
kinds of verbatim output.

Here is an example of computer code (see the source of this document
for exact syntax):

\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=2mm]
from numpy import sin, cos, exp, pi

def f(x, y, z, t):
    return exp(-t)*sin(pi*x)*sin(pi*y)*cos(2*pi*z)
\end{Verbatim}

% When showing copy from file in !bc envir, indent a character - otherwise
% ptex2tex is confused and starts copying...
Computer code can also be copied from a file:
\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=2mm]
 @@@CODE doconce_program.sh
 @@@CODE doconce_program.sh  fromto: doconce clean@^doconce split_rst
 @@@CODE doconce_program.sh  from-to: doconce clean@^doconce split_rst
 @@@CODE doconce_program.sh  envir=shpro fromto: name=@
\end{Verbatim}
The \texttt{@@@CODE} identifier must appear at the very beginning of the line.
The first line copies the complete file \Verb!doconce_program.sh!.
The second line copies from the first line matching the \emph{regular
expression} \texttt{doconce clean} up to, but not including, the line
matching the \emph{regular expression} \Verb!^doconce split_rst!.
The third line behaves as the second, but the line matching
the first regular expression is not copied (this construction is often
used for copying text between begin-end comment pair in the file).

The copied lines from file are in this example put inside \Verb?!bc shpro?
and \Verb?!ec? directives, if a complete file is copied, while the
directives become \Verb?!bc shcod? and \Verb?!ec? when a code snippet is copied
from a file. In general, for a filename extension \texttt{.X}, the environment
becomes \Verb?!bc Xpro? or \Verb?!bc Xcod? for a complete program or snippet,
respectively. The enivorments (\texttt{Xcod} and \texttt{Xpro}) are only active for
\texttt{latex}, \texttt{pdflatex}, html`, and \texttt{sphinx} output.  The fourth line
above specifies the code environment explicitly (\texttt{envir=shpro}) such
that it indicates a complete shell program (\texttt{shpro}) even if we copy a
part of the file (here from \texttt{name=} until the end of the file).
Copying a part of a file will by default lead to \Verb?!bc shcod?, which indicates a
code snippet that normally needs more code to run properly.

The \Verb!--code_prefix=text! option adds a path \texttt{text} to the filename specified
in the \texttt{@@@CODE} command (URLs work). For example

\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=2mm]
 @@@CODE src/myfile.py
\end{Verbatim}
and \Verb!--code_prefix=http://some.place.net!, the file

\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=2mm]
http://some.place.net/src/myfile.py
\end{Verbatim}
will be included. If source files have a header with author, email, etc.,
one can remove this header by the option \Verb!'--code_skip_until=# ---!.
The lines up to and including (the first) \Verb!# ---! will then be excluded.

Important warnings:

\begin{itemize}
 \item A code block must come after a plain sentence (at least for successful
   output in reStructredText), not directly after a section/paragraph heading,
   table, comment, figure, or movie.

 \item Verbatim code blocks inside lists can be ugly when typeset in some
   output formats. A more robust approach is to replace the list with
   paragraphs that include headings.
\end{itemize}

\noindent
\subsection{{\LaTeX} Mathematics}

DocOnce supports inline mathematics and blocks of mathematics, using
standard {\LaTeX} syntax. The output formats \texttt{html}, \texttt{sphinx}, \texttt{latex},
pdflatex`, \texttt{pandoc}, and \texttt{mwiki} work with this syntax while all other
formats will just display the raw {\LaTeX} code.

Inline expressions are written in the standard
{\LaTeX} way with the mathematics surrounded by dollar signs, as in
$Ax=b$. To help increase readability in other formats than \texttt{sphinx},
\texttt{latex}, and \texttt{pdflatex}, inline mathematics may have a more human
readable companion expression. The syntax is like
\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=2mm]
$\sin(\norm{\bf u})$|$sin(||u||)$
\end{Verbatim}
That is, the {\LaTeX} expression appears to the left of a vertical bar (pipe
symbol) and the more readable expression appears to the right. Both
expressions are surrounded by dollar signs.

Blocks of {\LaTeX} mathematics are written within
\Verb?!bt?
and
\Verb?!et? (begin/end TeX) directives starting on the beginning of a line:

\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=2mm]
!bt
\begin{align*}
\nabla\cdot \pmb{u} &= 0,\\ 
\nabla\times \pmb{u} &= 0.
\end{align*}
!et
\end{Verbatim}

This {\LaTeX} code gets rendered as

\begin{align*}
\nabla\cdot \pmb{u} &= 0,\\ 
\nabla\times \pmb{u} &= 0.
\end{align*}
Here is a single equation:

\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=2mm]
!bt
\[ \frac{\partial\pmb{u}}{\partial t} + \pmb{u}\cdot\nabla\pmb{u} = 0.\]
!et
\end{Verbatim}
which results in

\[ \frac{\partial\pmb{u}}{\partial t} + \pmb{u}\cdot\nabla\pmb{u} = 0.\]


\paragraph{LaTeX Newcommands.}
The author can define \texttt{newcommand} statements in files with names
\texttt{newcommands*.tex}. Such commands should only be used for mathematics
(other {\LaTeX} constructions are only understood by {\LaTeX} itself).
The convention is that \Verb!newcommands_keep.tex!
contains the newcommands that are kept in the document, while
those in \Verb!newcommands_replace.tex! will be replaced by their full
{\LaTeX} code. This conventions helps make readable documents in formats
without {\LaTeX} support. For \texttt{html}, \texttt{sphinx}, \texttt{latex}, \texttt{pdflatex},
\texttt{mwiki}, \texttt{ipynb}, and \texttt{pandoc}, the mathematics in newcommands is
rendered nicely anyway. If you desire \texttt{newcommand} outside {\LaTeX}
mathematics, simply use a Mako variable or a Mako function (which
will be much more flexible and powerful).

% include with mako must be in this root tree, so we need a link, see make.sh

\subsection{Writing Guidelines (Especially for {\LaTeX} Users!)}
\label{manual:latex:guide}

{\LaTeX} writers often have their own writing habits and have preferred
{\LaTeX} packages. DocOnce is a simpler format and
corresponds to writing in quite plain {\LaTeX} and making the ascii text
look nice (be careful with the use of white space!). This means that
although DocOnce has borrowed a lot from {\LaTeX}, there are a few points
{\LaTeX} writers should pay attention to. Experience shows that these
points are so important that we list them \emph{before} we list typical
DocOnce syntax!

Any {\LaTeX} syntax in mathematical formulas is accepted when DocOnce
translates the text to {\LaTeX}, but the following rules should be
followed when transalting the text to \texttt{sphinx}, \texttt{pandoc},
\texttt{mwiki}, \texttt{html}, or \texttt{ipynb} formats.

\begin{itemize}
 \item AMS {\LaTeX} mathematics is supported, also for the \texttt{html}, \texttt{sphinx},
   and \texttt{ipynb} formats.

 \item If you want {\LaTeX} math blocks to work with \texttt{latex}, \texttt{html}, \texttt{sphinx},
   \texttt{markdown}, and \texttt{ipynb}, only use
   the following equation environments: \Verb!\[ ... \]!,
   \texttt{equation*}, \texttt{equation}, \texttt{align*}, \texttt{align}. \texttt{alignat*}, \texttt{alignat}.
   Other environments, such as \texttt{split}, \texttt{multiline}, \texttt{gather} are
   supported in modern MathJax in HTML and Sphinx, but may have
   rendering problems (to a larger extent than \texttt{equation} and \texttt{align}).
   DocOnce performs extensions to \texttt{sphinx}, \texttt{ipynb},
   and other formats such that
   labels in \texttt{align} and \texttt{alignat} environments work well.
   If you face problems with fancy {\LaTeX} equation environments in
   web formats, try rewriting with plain \texttt{align}, \texttt{nonumber}, etc.

 \item Do not use comments inside equations.

 \item Newcommands in mathematical formulas are allowed, but not in
   the running text. Newcommands must be defined in files with names
   \texttt{newcommands*.tex}. Use \Verb!\newcommands! and not \Verb!\def!.
   Each newcommand must be defined on a single line.
   Use Mako functions if you need macros in the running text.

 \item Use labels and refer to them
   for sections, figures, movies, and equations only.
   MediaWiki (\texttt{mwiki}) does not support references to equations.

 \item Spaces are not allowed in labels.

 \item There is just one \texttt{ref} command (no \Verb!\eqref! for equations) and references to
   equations must use parentheses. Never use the tilde \texttt{~} (non-breaking
   space) character before references to figures, sections, etc., but
   tilde is allowed for references to equations.

 \item Never use \Verb!\pageref! as pages are not a concept in web documents
   (there is only a \texttt{ref} command in DocOnce and it refers to labels).

 \item Only figures and movies are floating elements in DocOnce, all other elements
   (code, tables, algorithms) must appear \emph{inline} without numbers or labels
   for reference\footnote{There is an exception: by using \emph{user-defined environments} within \Verb?!bu-name? and \Verb?!eu-name? directives, it is possible to label any type of text and refer to it. For example, one can have environments for examples, tables, code snippets, theorems, lemmas, etc. One can also use Mako functions to implement environments.} (refer to inline elements by a section label).
   The reason is that floating elements are in general
   not used in web documents, but we made an exception with figures
   and movies.

 \item Keep figure captions shorts as they are used as references in the
   Sphinx format. Avoid inline mathematics since Sphinx will strip it
   away in the figure reference.
   (Many writing styles encourage rich captions that
   explains everything about the figure; this work well
   only in the HTML and {\LaTeX} formats.)

 \item You cannot use \texttt{subfigure} to combine several image files in one
   figure, but you can combine the files into one file using
   the \Verb!doconce combine_images! tool. Refer to individual image files
   in the caption or text by (e.g.) ``left'' and ``right'', or
   ``upper left'', ``lower right'', etc.

 \item Footnotes can be used as usual in {\LaTeX}, but some HTML formats are not
   able to display mathematics or inline verbatim or other formatted
   code (emphasis, boldface, color) in footnotes - keep that in mind.

 \item Use plain \texttt{cite} for references (e.g., \Verb!\citeauthor! has no counterpart
   in DocOnce). The bibliography must be prepared in the Publish format,
   but import from (clean) \textsc{Bib}\negthinspace{\TeX} is possible.

 \item Use \texttt{idx} for index entries, but put the definitions between paragraphs,
   not inside them (required by Sphinx).

 \item Use the \Verb!\bm! command (from the \texttt{bm} package, always included by DocOnce)
   for boldface in mathematics.

 \item Make sure all ordinary text starts in column 1 on each line. Equations
   can be indented. The \Verb!\begin{}! and \Verb!\end{}! directives should start
   in column 1.

 \item If you depend on various {\LaTeX} environments for your writings, you have
   to give these up, or implement \emph{user-defined environments} in DocOnce.
   For instance, examples are normally typeset as subsections in DocOnce,
   but can also utilize a user-defined example environment.
   Learn about the exercise support in DocOnce for typesetting
   exercises, problems, and projects.

 \item Learn about the preprocessors Preprocess and Mako - these are smart
   tools for, e.g., commenting out/in large portions of text and creating
   macros.

 \item Use \emph{generalized references} when referring to companion documents
   that may later become part of this document (or migrated out of this document).

 \item Follow \href{{https://github.com/doconce/setup4book-doconce}}{recommendations for DocOnce books} if you plan to write a book.
\end{itemize}

\noindent

\begin{notice_mdfboxadmon}[Use the preprocessor to tailor output.]
If you really need special {\LaTeX} constructs in the {\LaTeX} output
from DocOnce, you may use use preprocessor if-tests on
the format (typically \Verb!#if FORMAT in ("latex", "pdflatex")!) to
include such special {\LaTeX} code. With an else clause you can easily
create corresponding constructions for other formats. This way
of using Preprocess or Mako
allows you to use advanced {\LaTeX} features (or HTML features for the HTML formats)
to fine tune the resulting
document. More tuning can be done by automatic editing of the
output file (e.g., \texttt{.tex} or \texttt{.html}) produced by DocOnce using
your own scripts or the \texttt{doconce replace} and \texttt{doconce subst} commands.
\end{notice_mdfboxadmon} % title: Use the preprocessor to tailor output.




\begin{notice_mdfboxadmon}[Autotranslation of {\LaTeX} to DocOnce?]
The tool \texttt{doconce latex2doconce} may help you translate {\LaTeX} files
to DocOnce syntax. However, if you use computer code in floating
list environments, special packages for typesetting algorithms,
example environments, \texttt{subfigure} in figures,
or a lot of newcommands in the running text, there will be need for
a lot of manual edits and adjustments.

For examples, figure environments can only be translated by
\texttt{doconce latex2doconce} if the label is inside the caption and
the figure is typeset like

\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=2mm]
\begin{figure}
  \centering
  \includegraphics[width=0.55\linewidth]{figs/myfig.pdf}
  \caption{This is a figure. \labe{myfig}}
\end{figure}
\end{Verbatim}
If the {\LaTeX} text is consistent with respect to the placement of the label, a
simple script can autoedit the label inside the caption, but many
{\LaTeX} writers put the label at different places in different figures,
and then it becomes more difficult to autoedit figures and translate
them to the DocOnce \texttt{FIGURE:} syntax.

Tables are hard to interpret and translate because headings and
caption can be typeset in many different ways. The type of table
that is recognized looks like

\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=2mm]
\begin{table}
\caption{Here goes the caption.}
\begin{tabular}{lr}
\hline
\multicolumn{1}{c}{$v_0$} & \multicolumn{1}{c}{$f_R(v_0)$}\\hline
1.2 & 4.2\1.1 & 4.0\0.9 & 3.7
\hline
\end{tabular}
\end{table}
\end{Verbatim}
Recall that table captions do not make sense in DocOnce since tables
must be inlined and explained in the surrounding text.

Footnotes are also problematic for \texttt{doconce latex2doconce} since DocOnce
footnotes must have the explanation outside the paragraph where the
footnote is used. This calls for manual work. The translator from
{\LaTeX} to DocOnce will insert \Verb!_PROBLEM_! and mark footnotes. One
solution is to avoid footnotes in the {\LaTeX} document if fully automatic
translation is desired.
\end{notice_mdfboxadmon} % title: Autotranslation of {\LaTeX} to DocOnce?




\subsection{Hyperlinks}

Links use either a link text or the raw URL:

\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=2mm]
Here is some "some link text": "http://some.net/address"
(as in "search google": "http://google.com")
or just the raw address: URL: "http://google.com".

Links to files typeset in verbatim mode applies backtics:
"`myfile.py`": "http://some.net/some/place/myfile.py".

Mail addresses works too: send problems to
"`hpl@simula.no`": "mailto:hpl@simula.no"
or just "send mail": "mailto:hpl@simula.no".
\end{Verbatim}

\subsection{Figures and Movies}

Figures and movies have almost equal syntax:
\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=2mm]
FIGURE: [relative/path/to/figurefile, width=500 frac=0.8] Here goes the caption which must be on a single line. label{some:fig:label}

MOVIE: [relative/path/to/moviefile, width=500] Here goes the caption which must be on a single line. 

\end{Verbatim}
Note three important syntax details:

\begin{enumerate}
 \item A mandatory comma after the figure/movie filename,

 \item no comments between \texttt{width}, \texttt{height}, and \texttt{frac} and no spaces
    around the \texttt{=} characters,

 \item all of the commands must appear on a single line,

 \item there must be a blank line after the command.
\end{enumerate}

\noindent
The figure file can be listed without extension. DocOnce will then find
the version of the file with the most appropriate extension for the chosen
output format. If not suitable version is found, DocOnce will convert
another format to the needed one.

The caption is optional. If omitted, the figure will be inlined (meaning
no use of any figure environment in HTML or {\LaTeX} formats). The \texttt{width}
and \texttt{height} parameters affect HTML formats (\texttt{html}, \texttt{rst}, \texttt{sphinx}),
while \texttt{frac} is the width of the image as a fraction of the total text
width in the \texttt{latex} and \texttt{pdflatex} formats.

The command-line options \Verb!--fig_prefix=...! and \Verb!--mov_prefix=...! can
be used to add a path (can be a URL) to all figure and movie files,
respectively.  This is useful when including DocOnce documents in
other DocOnce documents such that the text is compiled in different
directories (with different paths to the figure directory).

Movie files can either be a video or a wildcard expression for a
series of frames. In the latter case, a simple device in an HTML page
will display the individual frame files as a movie.

Combining several image files into one can be done by the
\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=2mm]
doconce combine_images image1 image2 ... output_image
\end{Verbatim}
This command applies \texttt{montage} or PDF-based tools to combine the images
to get the highest quality.

YouTube and Vimeo movies will be embedded in \texttt{html} and \texttt{sphinx} documents
and otherwise be represented by a link. The syntax is

\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=2mm]
MOVIE: [http://www.youtube.com/watch?v=_O7iUiftbKU, width=420 height=315] YouTube movie.

MOVIE: [http://vimeo.com/55562330, width=500 height=278] Vimeo movie.

\end{Verbatim}
The latter results in


\begin{doconce:movie}
\refstepcounter{doconce:movie:counter}
\begin{center}\href{{http://vimeo.com/55562330}}{\nolinkurl{http://vimeo.com/55562330}}\end{center}

\begin{center}  % movie caption
Movie \arabic{doconce:movie:counter}: Vimeo movie.
\end{center}
\end{doconce:movie}



\subsection{Tables}

The table in Section~\ref{quick:sections} was written with this
syntax:
\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=2mm]

|----------------c--------|------------------c--------------------|
|      Section type       |        Syntax                         |
|----------------l--------|------------------l--------------------|
| chapter                 | `========= Heading ========` (9 `=`)  |
| section                 | `======= Heading =======`    (7 `=`)  |
| subsection              | `===== Heading =====`        (5 `=`)  |
| subsubsection           | `=== Heading ===`            (3 `=`)  |
| paragraph               | `__Heading.__`               (2 `_`)  |
|-----------------------------------------------------------------|

\end{Verbatim}

Note that

\begin{itemize}
 \item Each line begins and ends with a vertical bar (pipe symbol).

 \item Column data are separated by a vertical bar (pipe symbol).

 \item There must be a blank line before and after the table.

 \item There may be horizontal rules, i.e., lines with dashes for
   indicating the heading and the end of the table, and these may
   contain characters 'c', 'l', or 'r' for how to align headings or
   columns. The first horizontal rule may indicate how to align
   headings (center, left, right), and the horizontal rule after the
   heading line may indicate how to align the data in the columns
   (center, left, right).
   One can also use \texttt{X} for potentially very wide text that must be
   wrapped and left-adjusted (will only affect \texttt{latex} and \texttt{pdflatex} where the
   \texttt{tabularx} package is then used; \texttt{X} means \texttt{l} in all other formats).

 \item If the horizontal rules are without alignment information there should
   be no vertical bar (pipe symbol) between the columns. Otherwise, such
   a bar indicates a vertical bar between columns in {\LaTeX}.

 \item Many output formats are so primitive that heading and column alignment
   have no effect.
\end{itemize}

\noindent
A quick way of generating tables is to place all the entries in a file
with comma as separator (a CSV file) and then run the utility
\texttt{doconce csv2table} to create a table in the DocOnce format.

The command-line option \texttt{--tables2csv} (to \texttt{doconce format})
makes DocOnce dump each table to CSV format in a file \Verb!table_X.csv!,
where \texttt{X} is the table number. This feature makes it easy to
load tables into spreadsheet programs for further analysis.

DocOnce tables can be efficiently made directly from data in CSV files.

\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=2mm]
Terminal> doconce csv2table mydata.csv > mydata_table.do.txt
\end{Verbatim}
Now we can do \Verb!# #include "mydata_table.do.txt"! in the DocOnce
source file or simply copy the table in \Verb!mydata_table.do.txt!
into the DocOnce file.

\subsection{Labels and References}

The notion of labels and references (as well as bibliography and index)
is adopted
from {\LaTeX} with a very similar syntax. As in {\LaTeX}, a label can be
inserted anywhere, using the syntax
\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=2mm]
label{name}
\end{Verbatim}
with no backslash
preceding the label keyword. It is common practice to choose \texttt{name}
as some hierarchical name, using a delimiter like \texttt{:} or \Verb!_! between
(e.g.) section, subsection, and topic.

A reference to the label \texttt{name} is written as
\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=2mm]
ref{name}
\end{Verbatim}
again with no backslash before \texttt{ref}.

Use labels for sections and equations only, and precede the reference
by "Section" or "Chapter", or in case of an equation, surround the
reference by parenthesis.


\subsection{Citations and Bibliography}

Single citations are written as
\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=2mm]
cite{name}
\end{Verbatim}
where \texttt{name} is a logical name
of the reference (again, {\LaTeX} writers must not insert a backslash).
Bibliography citations often have \texttt{name} on the form
\Verb!Author1_Author2_YYYY!, \Verb!Author_YYYY!, or \Verb!Author1_etal_YYYY!, where
\texttt{YYYY} is the year of the publication.
Multiple citations at once is possible by separating the logical names
by comma:
\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=2mm]
cite{name1,name2,name3}
\end{Verbatim}

The bibliography is specified by a line \texttt{BIBFILE: papers.pub},
where \texttt{papers.pub} is a publication database in the
\href{{https://github.com/doconce/publish}}{Publish} format.
\textsc{Bib}\negthinspace{\TeX} \texttt{.bib} files can easily be combined to a Publish database
(which DocOnce needs to create bibliographies in other formats
than {\LaTeX}).

\subsection{Generalized References}

There is a \emph{generalized referencing} feature in DocOnce that allows
a reference with \texttt{ref} to have one formulation if the label is
in the same document and another formulation if the reference is
to an item in an external document. This construction makes it easy
to work with many small, independent documents in parallel with
a book assembly of some of the small elements.
The syntax of a generalized reference is

\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=2mm]
ref[internal][cite][external]
\end{Verbatim}
with a specific example being

\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=2mm]
As explained in
ref[Section ref{subsec:ex}][in cite{testdoc:12}][a "section":
"testdoc.html#___sec2" in the document
"A Document for Testing DocOnce": "testdoc.html" cite{testdoc:12}],
DocOnce documents may include movies.
\end{Verbatim}
The output from a generalized reference is the text \texttt{internal} if all
references with \texttt{ref} in the text \texttt{internal} are references to labels
defined in the
present document. Otherwise, if \texttt{cite} is non-empty and the format is
\texttt{latex} or \texttt{pdflatex}, one assumes that the references in \texttt{internal}
are to external documents declared by a comment line
\Verb!# Externaldocuments: testdoc, mydoc! (usually after the title, authors,
and date). In this case the output text is \texttt{internal} followed by \texttt{cite},
and the
{\LaTeX} package \texttt{xr} is used to handle the labels in the external
documents.  If none of the two situations above applies, the
\texttt{external} text will be the output.

\subsection{Index of Keywords}

DocOnce supports creating an index of keywords. A certain keyword
is registered for the index by a syntax like (no
backslash!)
\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=2mm]
index{name}
\end{Verbatim}
It is recommended to place any index of this type outside
running text, i.e., after (sub)section titles and in the space between
paragraphs. Index specifications placed right before paragraphs also
gives the doconce source code an indication of the content in the
forthcoming text. The index is only produced for the \texttt{latex},
\texttt{pdflatex}, \texttt{rst}, and \texttt{sphinx} formats.

\subsection{Capabilities of The Program \texttt{doconce} }

The \texttt{doconce} program can be used for a number of purposes besides
transforming a \texttt{.do.txt} file to some format. Here is the
list of capabilities:

\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=2mm]
DocOnce version 1.5.4 (from /home/amarin/doconce/venv/lib/python3.6/site-packages/DocOnce-1.5.4-py3.6.egg/doconce)
Usage: doconce command [optional arguments]
commands: help format find subst replace remove spellcheck apply_inline_edits capitalize change_encoding clean combine_images csv2table diff expand_commands expand_mako extract_exercises find_nonascii_chars fix_bibtex4publish gitdiff grab grep guess_encoding gwiki_figsubst html2doconce html_colorbullets jupyterbook include_map insertdocstr ipynb2doconce latex2doconce latex_dislikes latex_exercise_toc latex_footer latex_header latex_problems latin2html lightclean linkchecker list_fig_src_files list_labels makefile md2html md2latex old2new_format ptex2tex pygmentize ref_external remove_exercise_answers remove_inline_comments replace_from_file slides_beamer slides_html slides_markdown sphinx_dir sphinxfix_localURLs split_html split_rst teamod

doconce format html|latex|pdflatex|rst|sphinx|plain|gwiki|mwiki|
               cwiki|pandoc|st|epytext dofile 
# transform doconce file to another format

doconce subst [-s -m -x --restore] regex-pattern \ 
        regex-replacement file1 file2 ... 
# substitute a phrase by another using regular expressions (in this example -s is the re.DOTALL modifier, -m is the re.MULTILINE modifier, -x is the re.VERBOSE modifier, --restore copies backup files back again)

doconce replace from-text to-text file1 file2 ...                      
# replace a phrase by another literally (exact text substitution)

doconce replace_from_file file-with-from-to-replacements file1 file2 ... 
# replace using from and to phrases from file

doconce find expression                                                
# search for a (regular) expression in all .do.txt files in the current directory tree (useful when removing compilation errors)

doconce include_map mydoc.do.txt                                       
# print an overview of how various files are included in the root doc

doconce expand_mako mako_code_file funcname file1 file2 ...            
# replace all mako function calls by the `results of the calls

doconce remove_inline_comments dofile                                  
# remove all inline comments in a doconce file

doconce apply_inline_edits                                             
# apply all edits specified through inline comments

doconce sphinx_dir copyright='John Doe' title='Long title' \
        short_title="Short title" version=0.1 intersphinx \
        /path/to/mylogo.png dofile 
# create a directory for the sphinx format (requires sphinx version >= 1.1)

doconce format sphinx complete_file 
doconce split_rst complete_file 
doconce sphinx_dir complete_file 
python automake_sphinx.py 
# split a sphinx/rst file into parts according to !split commands

doconce insertdocstr rootdir                                           
# walk through a directory tree and insert doconce files as docstrings in *.p.py files

doconce lightclean                                                     
# remove all redundant files (keep source .do.txt and results: .pdf, .html, sphinx- dirs, .mwiki, .ipynb, etc.)

doconce clean                                                          
# remove all files that the doconce can regenerate

doconce change_encoding utf-8 latin1 dofile                            
# change encoding

doconce guess_encoding filename                                        
# guess the encoding in a text

doconce find_nonascii_chars file1 file2 ...                            
# find non-ascii characters in a file

doconce split_html complete_file.html                                  
# split an html file into parts according to !split commands

doconce slides_html slide_type complete_file.html                      
# create HTML slides from a (doconce) html file

doconce slides_beamer complete_file.tex                                
# create LaTeX Beamer slides from a (doconce) latex/pdflatex file

doconce slides_markdown complete_file.md remark --slide_style=light    
# create Remark slides from Markdown

doconce html_colorbullets file1.html file2.html ...                    
# replace bullets in lists by colored bullets

doconce extract_exercises tmp_mako__mydoc                              
# extract all exercises (projects and problems too)

doconce grab --from[-] from-text [--to[-] to-text] file > result       
# grab selected text from a file

doconce remove --from[-] from-text [--to[-] to-text] file > result     
# remove selected text from a file

doconce grep FIGURE|MOVIE|CODE dofile                                  
# list all figure, movie or included code files

doconce spellcheck [-d .mydict.txt] *.do.txt                           
# run spellcheck on a set of files

doconce ptex2tex mydoc -DMINTED pycod=minted sys=Verbatim \
        dat=\begin{quote}\begin{verbatim};\end{verbatim}\end{quote} 
# transform ptex2tex files (.p.tex) to ordinary latex file and manage the code environments

doconce md2html file.md                                                
# make HTML file via pandoc from Markdown (.md) file

doconce md2latex file.md                                               
# make LaTeX file via pandoc from Markdown (.md) file

doconce combine_images image1 image2 ... output_file                   
# combine several images into one

doconce latex_problems mydoc.log [overfull-hbox-limit]                 
# report problems from a LaTeX .log file

doconce list_fig_src_files *.do.txt                                    
# list all figure files, movie files, and source code files needed

doconce list_labels myfile                                             
# list all labels in a document (for purposes of cleaning them up)

doconce ref_external mydoc [pubfile]                                   
# generate script for substituting generalized references

doconce linkchecker *.html                                             
# check all links in HTML files

doconce capitalize [-d .mydict.txt] *.do.txt                           
# change headings from "This is a Heading" to "This is a heading"

doconce latex2doconce latexfile                                        
# translate a latex document to doconce (requires usually manual fixing)

doconce latex_dislikes latexfile                                       
# check if there are problems with translating latex to doconce

doconce ipynb2doconce notebookfile                                     
# translate an IPython/Jupyter notebook to doconce

doconce pygmentize myfile [pygments-style]                             
# typeset a doconce document with pygments (for pretty print of doconce itself)

doconce makefile docname doconcefile [html sphinx pdflatex ...]        
# generate a make.py script for translating a doconce file to various formats

doconce diff file1.do.txt file2.do.txt [diffprog]                      
# find differences between two files (diffprog can be difflib, diff, pdiff, latexdiff, kdiff3, diffuse, ...)

doconce gitdiff file1 file2 file3 ...                                  
# find differences between the last two Git versions of several files

doconce csv2table somefile.csv                                         
# convert csv file to doconce table format

doconce sphinxfix_local_URLs file.rst                                  
# edit URLs to local files and place them in _static

doconce latin2html file.html                                           
# replace latex-1 (non-ascii) characters by html codes

doconce fix_bibtex4publish file1.bib file2.bib ...                     
# fix common problems in bibtex files for publish import

doconce latex_header                                                   
# print the header (preamble) for latex file

doconce latex_footer                                                   
# print the footer for latex files

doconce expand_commands file1 file2 ...                                
# expand short cut commands to full form in files

doconce latex_exercise_toc myfile                                      
# insert a table of exercises in a latex file myfile.p.tex
\end{Verbatim}

\subsection{Exercises}

DocOnce supports \emph{Exercise}, \emph{Problem}, \emph{Project}, and \emph{Example}.
These are typeset
as ordinary sections and referred to by their section labels.
Exercise, problem, project, or example sections contains certain \emph{elements}:

\begin{itemize}
  \item a headline at the level of a subsection
    containing one of the words "Exercise:", "Problem:",
    "Project:", or "Example:", followed by a title (required)

  \item a label (optional)

  \item a solution file (optional)

  \item name of file with a student solution (optional)

  \item main exercise text (required)

  \item a short answer (optional)

  \item a full solution (optional)

  \item one or more hints (optional)

  \item one or more subexercises (subproblems, subprojects), which can also
    contain a text, a short answer, a full solution, name student file
    to be handed in, and one or more hints (optional)
\end{itemize}

\noindent
A typical sketch of a a problem without subexercises goes as follows:
\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=2mm]
===== Problem: Derive the Formula for the Area of an Ellipse =====
label{problem:ellipsearea1}
file=ellipse_area.pdf
solution=ellipse_area1_sol.pdf

Derive an expression for the area of an ellipse by integrating
the area under a curve that defines half of the ellipse.
Show each step in the mathematical derivation.

!bhint
Wikipedia has the formula for the curve.
!ehint

!bhint
"Wolframalpha": "http://wolframalpha.com" can perhaps
compute the integral.
!ehint
\end{Verbatim}
If the exercise type (Exercise, Problem, Project, or Example)
is enclosed in braces, the type is left out of the title in the
output. For example, the if the title line above reads

\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=2mm]
===== {Problem}: Derive the Formula for the Area of an Ellipse =====
\end{Verbatim}
the title becomes just "Derive the ...".

An exercise with subproblems, answers and full solutions has this
setup-up:

\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=2mm]
===== Exercise: Determine the Distance to the Moon =====
label{exer:moondist}

Intro to this exercise. Questions are in subexercises below.

!bsubex
Subexercises are numbered a), b), etc.

file=subexer_a.pdf

!bans
Short answer to subexercise a).
!eans

!bhint
First hint to subexercise a).
!ehint

!bhint
Second hint to subexercise a).
!ehint
!esubex

!bsubex
Here goes the text for subexercise b).

file=subexer_b.pdf

!bhint
A hint for this subexercise.
!ehint

!bsol
Here goes the solution of this subexercise.
!esol
!esubex

!bremarks
At the very end of the exercise it may be appropriate to summarize
and give some perspectives. The text inside the `!bremarks` and `!eremarks`
directives is always typeset at the end of the exercise.
!eremarks

!bsol
Here goes a full solution of the whole exercise.
!esol

\end{Verbatim}
By default, answers, solutions, and hints are typeset as paragraphs.
The command-line arguments \Verb!--without_answers! and \Verb!--without_solutions!
turn off output of answers and solutions, respectively, except for examples. The command line options \Verb!--answers_at_end! and \Verb!--solutions_at_end! write all answers and solutions to exercises to a separate section at the end of the document, respectively. Combine with \Verb!--without_answers! and \Verb!--without_solutions! to remove answers and solutions from the main text.

The commands \Verb?!anshide? and \Verb?!solhide? can be used to hide from the main text answers and solutions, respectively, until the \Verb?!ansoff? and \Verb?!soloff? commands are encountered. Similarly, the \Verb?!ansdocend? and \Verb?!soldocend? commands move answers and solutions to the end of the book. 

\subsection{Environments}

DocOnce environments start with \Verb?!benvirname? and end with \Verb?!eenvirname?,
where \texttt{envirname} is the name of the environment. Here is a listing of
the environments:

\begin{itemize}
 \item \texttt{c}: computer code (or verbatim text)

 \item \texttt{t}: math blocks with {\LaTeX} syntax

 \item \texttt{subex}: sub-exercise

 \item \texttt{ans}: short answer to exercise or sub-exercise

 \item \texttt{sol}: full solution to exercise or sub-exercise

 \item \texttt{hint}: multiple help items in an exercise or sub-exercise

 \item \texttt{quote}: indented text

 \item \texttt{notice}, \texttt{summary}, \texttt{warning}, \texttt{question}: admonition boxes with
    custom title, special icon, and (sometimes) background color

 \item \texttt{block}, \texttt{box}: simpler boxes (\texttt{block} may have title but never any icon)

 \item \texttt{pop}: text to gradually pop up in slide presentations

 \item \texttt{slidecell}: indication of cells in a grid layout for elements on a
   slide
\end{itemize}

\noindent
In addition, the user can define new environments \Verb?!bc-name? as
explained in the \href{{http://doconce.github.io/doconce/doc/pub/manual/manual.html#manual:userdef:envir}}{manual}.

\subsection{Preprocessing}

DocOnce documents may utilize a preprocessor, either \texttt{preprocess} and/or
\texttt{mako}. The former is a C-style preprocessor that allows if-tests
and including other files (but not macros with arguments).
The \texttt{mako} preprocessor is much more advanced - it is actually a full
programming language, very similar to Python.

The command \texttt{doconce format} first runs \texttt{preprocess} and then \texttt{mako}.
Here is a typical example on utilizing \texttt{preprocess} to include another
document, ``comment out'' a large portion of text, and to write format-specific
constructions:

\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.95,xleftmargin=2mm]
# #include "myotherdoc.do.txt"

# #if FORMAT in ("latex", "pdflatex")
\begin{table}
\caption{Some words... label{mytab}}
\begin{tabular}{lrr}
\hline\noalign{\smallskip}
\multicolumn{1}{c}{time} & \multicolumn{1}{c}{velocity} & \multicolumn{1}{c}{acceleration} \\ 
\hline
0.0          & 1.4186       & -5.01        \\ 
2.0          & 1.376512     & 11.919       \\ 
4.0          & 1.1E+1       & 14.717624    \\ 
\hline
\end{tabular}
\end{table}
# #else
  |--------------------------------|
  |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    |
  |--------------------------------|
# #endif

# #ifdef EXTRA_MATERIAL
....large portions of text...
# #endif
\end{Verbatim}

With the \texttt{mako} preprocessor the if-else tests have slightly different syntax.
An \href{{http://doconce.github.com/bioinf-py/}}{example document} contains
some illustrations on how to utilize \texttt{mako} (clone the GitHub project and
examine the DocOnce source and the \texttt{doc/src/make.sh} script).

\subsection{Resources}

\begin{itemize}
 \item Excellent "Sphinx Tutorial" by C. Reller: "http://people.ee.ethz.ch/~creller/web/tricks/reST.html"
\end{itemize}

\noindent

% ------------------- end of main content ---------------

% #ifdef PREAMBLE
\end{document}
% #endif


************** File: quickref.rst *****************
.. Automatically generated reStructuredText file from DocOnce source
   (https://github.com/hplgit/doconce/)

.. |nbsp| unicode:: 0xA0
   :trim:

.. Document title:

DocOnce Quick Reference
=======================

:Authors: Hans Petter Langtangen
:Date: Jan 32, 2100

.. contents:: Table of contents
   :depth: 2

**WARNING: This quick reference is very incomplete!**

**Mission.**
Enable writing documentation with much mathematics and
computer code *once, in one place* and include it in traditional LaTeX
books, thesis, and reports, and, without extra efforts, also make
professional looking web versions with Sphinx or HTML. Other outlets
include Google's ``blogger.com``, Wikipedia/Wikibooks, IPython/Jupyter
notebooks, plus a wide variety of other formats for documents without
mathematics and code.

Supported Formats
-----------------

DocOnce currently translates files to the following formats:

 * LaTeX (format ``latex`` or ``pdflatex``)

 * HTML (format ``html``)

 * Sphinx (format ``sphinx``)

 * Pandoc-extended or GitHub-flavored Markdown (format ``pandoc``)

 * IPython notebook (format ``ipynb``)

 * Matlab notebook (format ``matlabnb``)

 * MediaWiki (format ``mwiki``)

 * Googlecode wiki (format ``gwiki``)

 * Creoloe wiki (format ``cwiki``)

 * reStructuredText (format ``rst``)

 * plain (untagged) ASCII (format ``plain``)

 * Epydoc (format ``epydoc``)

 * StructuredText (format ``st``)

For documents with much code and mathematics, the best (and most supported)
formats are ``latex``, ``pdflatex``, ``sphinx``, and ``html``; and to a slightly
less extent ``mwiki`` and ``pandoc``. The HTML format supports blog posts on
Google and Wordpress.


.. admonition:: Use a text editor with monospace font

   Some DocOnce constructions are sensitive to whitespace,
   so you *must* use a text editor with monospace font.




Emacs syntax support
--------------------

The file `.doconce-mode.el <https://github.com/doconce/doconce/blob/master/misc/.doconce-mode.el>`__
in the DocOnce source distribution gives a "DocOnce Editing Mode" in
Emacs. Store the raw version of the file in the home directory and add
``(load-file "~/.doconce-mode.el")`` to the ``.emacs`` file.

Besides syntax highlighting of DocOnce documents, this Emacs mode
provides a lot of shortcuts for setting up many elements in a document:

=============  ==========================================  
  Emacs key                      Action                    
=============  ==========================================  
Ctrl+c f       figure                                      
Ctrl+c v       movie/video                                 
Ctrl+c h1      heading level 1 (section/h1)                
Ctrl+c h2      heading level 2 (subsection/h2)             
Ctrl+c h3      heading level 2 (subsection/h3)             
Ctrl+c hp      heading for paragraph                       
Ctrl+c me      math environment: ``!bt`` equation ``!et``  
Ctrl+c ma      math environment: ``!bt`` align ``!et``     
Ctrl+c ce      code environment: ``!bc`` code ``!ec``      
Ctrl+c cf      code from file: ``@@@CODE``                 
Ctrl+c table2  table with 2 columns                        
Ctrl+c table3  table with 3 columns                        
Ctrl+c table4  table with 4 columns                        
Ctrl+c exer    exercise outline                            
Ctrl+c slide   slide outline                               
Ctrl+c help    print this table                            
=============  ==========================================  

Title, Authors, and Date
------------------------

A typical example of giving a title, a set of authors, a date,
and an optional table of contents
reads::

        TITLE: On an Ultimate Markup Language
        AUTHOR: H. P. Langtangen at Center for Biomedical Computing, Simula Research Laboratory & Dept. of Informatics, Univ. of Oslo
        AUTHOR: Kaare Dump Email: dump@cyb.space.com at Segfault, Cyberspace Inc.
        AUTHOR: A. Dummy Author
        DATE: today
        TOC: on

The entire title must appear on a single line.
The author syntax is::

        name Email: somename@adr.net at institution1 & institution2

where the email is optional, the "at" keyword is required if one or
more institutions are to be specified, and the ``&`` keyword
separates the institutions (the keyword ``and`` works too).
Each author specification must appear
on a single line.
When more than one author belong to the
same institution, make sure that the institution is specified in an identical
way for each author.

The date can be set as any text different from ``today`` if not the
current date is wanted, e.g., ``Jan 32, 2100``.

The table of contents is removed by writing ``TOC: off``.

Copyright
---------

.. Recall to ident AUTHOR commands to avoid interpretation

Copyright for selected authors and/or institutions are easy to insert as part
of the ``AUTHOR`` command. The copyright syntax is::

        {copyright,year1-year2|license}

and can be placed after the author or after an institution, e.g.::

         AUTHOR: name Email: somename@adr.net {copyright,2006-present} at inst1
         AUTHOR: name {copyright} at inst1 {copyright}

The first line gives ``name`` a copyright for 2006 up to the present year,
while the second line gives copyright to ``name`` and the institution ``inst1``
for the present year. The license can be any formulation, but there are
some convenient abbreviations for Creative Commons ("public domain")
licenses: ``CC BY`` for Creative Commons Attribution 4.0 license,
``CC BY-NC`` for Creative Commons Attribution-NonCommercial 4.0 license.
For example::

         AUTHOR: name1 {copyright|CC BY} at institution1
         AUTHOR: name2 {copyright|CC BY} at institution2

is a very common copyright for the present year with the Attribution license.
The copyright must be identical for all authors and institutions.

.. _quick:sections:

Section Types
-------------

=============  ===============================================  
 Section type                       Syntax                      
=============  ===============================================  
chapter        ``========= Heading ========`` (9 ``=``)         
section        ``======= Heading =======``    (7 ``=``)         
subsection     ``===== Heading =====``        (5 ``=``)         
subsubsection  ``=== Heading ===``            (3 ``=``)         
paragraph      ``__Heading.__``               (2 ``_``)         
abstract       ``__Abstract.__`` Running text...                
appendix       ``======= Appendix: heading =======`` (7 ``=``)  
appendix       ``===== Appendix: heading =====`` (5 ``=``)      
exercise       ``===== Exercise: heading =====`` (5 ``=``)      
=============  ===============================================  

Note that abstracts are recognized by starting with ``__Abstract.__`` or
``__Summary.__`` at the beginning of a line and ending with three or
more ``=`` signs of the next heading.

The ``Exercise:`` keyword can be substituted by ``Problem:`` or ``Project:``.
A recommended convention is that an exercise is tied to the text,
a problem can stand on its own, and a project is a comprehensive
problem.

Inline Formatting
-----------------

Words surrounded by ``*`` are emphasized: ``*emphasized words*`` becomes
*emphasized words*. Similarly, an underscore surrounds words that
appear in boldface: ``_boldface_`` becomes **boldface**. Colored words
are also possible: the text::

        `color{red}{two red words}`

becomes **two red words**.
(But colors do not work in format rst).

Quotations appear inside double backticks and double single quotes::

        This is a sentence with ``words to be quoted''.

A forced linebreak is specified by ``<linebreak>`` at the point where the
linebreak in the output is wanted.

Footnotes use a label in the text with the footnote text separate,
preferably after the paragraph where the footnote appears::

        Differentiating[^diff2] this equation leads
        to a new and much simpler equation.
        
        [^diff2]: More precisely, we apply the divergence
        $\nabla\cdot$ on both sides.
        
        Here comes a new paragraph...

Non-breaking space is inserted using the tilde character as in LaTeX::

        This distance corresponds to 7.5~km, which is traveled in $7.5/5$~s.

A horizontal rule for separating content vertically, like this:

---------

is typeset as four or more hyphens on a single line::

        ---------

The ``latex``, ``pdflatex``, ``sphinx``, and ``html`` formats support em-dash,
indicated by three hyphens: ``---``. Here is an example::

        The em-dash is used - without spaces - as alternative to hyphen with
        space around in sentences---this way, or in quotes:
        *Premature optimization is the root of all evil.*--- Donald Knuth.

This text is in the rst rendered as

The em-dash is used - without spaces - as alternative to hyphen with
space around in sentences---this way, or in quotes:
*Premature optimization is the root of all evil.*--- Donald Knuth.

The en-dash consists of two hyphens, either with blanks on both sides - for
something in the middle of a sentence - or in number ranges like 240 - 249.
LaTeX writes are used to and fond of en-dash.

An ampersand, as in Guns & Roses or Texas A&M, is written as a
plain ``&`` *with space(s) on both sides*. Single upper case letters on each
side of ``&``, as in ``Texas A & M``, remove the spaces and result in
Texas A&M, while words on both sides of ``&``, as in ``Guns & Roses``,
preserve the spaces: Guns & Roses. Failing to have spaces before and
after ``&`` will result in wrong typesetting of the ampersand in the ``html``,
``latex``, and ``pdflatex`` formats.

Emojis, as defined in `<http://www.emoji-cheat-sheet.com>`_, can be
inserted in the text, as (e.g.) ``:dizzy_face:`` with blank or newline
before or after :dizzy_face: Only the ``pdflatex``, ``html``, and ``pandoc`` output
formats translate emoji specifications to images, while all other
formats leave the textual specification in the document. The
command-line option ``--no_emoji`` removes all emojis from the output
document.

Lists
-----

There are three types of lists: *bullet lists*, where each item starts
with ``*``, *enumeration lists*, where each item starts with ``o`` and gets
consecutive numbers,
and *description* lists, where each item starts with ``-`` followed
by a keyword and a colon::

        Here is a bullet list:
        
         * item1
         * item2
          * subitem1 of item2
          * subitem2 of item2,
            second line of subitem2
         * item3
        
        Note that sublists are consistently indented by one or more blanks as
        shown: bullets must exactly match and continuation lines must start
        right below the line above.
        
        Here is an enumeration list:
        
         o item1
         o item2
           may appear on
           multiple lines
          o subitem1 of item2
          o subitem2 of item2
         o item3
        
        And finally a description list:
        
         - keyword1: followed by
           some text
           over multiple
           lines
         - keyword2:
           followed by text on the next line
         - keyword3: and its description may fit on one line

The code above follows.

Here is a bullet list:

 * item1

 * item2

  * subitem1 of item2

  * subitem2 of item2

 * item3

Note that sublists are consistently indented by one or more blanks as
shown: bullets must exactly match and continuation lines must start
right below the line above.

Here is an enumeration list:

1. item1

2. item2
   may appear on
   multiple lines

 a. subitem1 of item2

 b. subitem2 of item2

3. item3

And finally a description list:

 keyword1: 
   followed by
   some text
   over multiple
   lines

 keyword2: 
   followed by text on the next line

 keyword3: 
   and its description may fit on one line


.. admonition:: No indentation - except in lists

   DocOnce syntax is sensitive to whitespace.
   No lines should be indented, only lines belonging to lists.
   Indented lines may give strange output in some formats.




Comment lines
-------------

Lines starting with ``#`` are treated as comments in the document and
translated to the proper syntax for comments in the output
document. Such comment lines should not appear before LaTeX math
blocks, verbatim code blocks, or lists if the formats ``rst`` and
``sphinx`` are desired.

Comment lines starting with ``##`` are not propagated to the output
document and can be used for comments that are only of interest in
the DocOnce file.

Large portions of text can be left out using Preprocess. Just place
``# #ifdef EXTRA`` and ``# #endif`` around the text. The command line
option ``-DEXTRA`` will bring the text alive again.

When using the Mako preprocessor one can also place comments in
the DocOnce source file that will be removed by Mako before
DocOnce starts processing the file.

Inline comments
---------------

Inline comments meant as messages or notes, to authors during development
in particular,
are enabled by the syntax::

        [name: running text]

where ``name`` is the name or ID of an author or reader making the comment,
and ``running text`` is the comment. The name can contain upper and lower
case characters, digits, single quote, ``+`` and ``-``, as well
as space. Here goes an example::

        Some running text. [hpl: There must be a space after the colon,
        but the running text can occupy multiple lines.]

which is rendered as


..

    Some running text. **(**hpl 1**: There must be a space after the colon,
    but the running text can occupy multiple lines.**)



The inline comments have simple typesetting in most formats, typically
boldface name, a comment number, with everything surrounded by
parenthesis.  However, with LaTeX output and the ``--latex_todonotes``
option to ``doconce format``, colorful margin or inline boxes (using the
``todonotes`` package) make it very easy to spot the comments.

Running::

        doconce format html mydoc.do.txt --skip_inline_comments

removes all inline comments from the output. This feature makes it easy
to turn on and off notes to authors during the development of the document.

All inline comments to readers can also be physically
removed from the DocOnce source by::

        doconce remove_inline_comments mydoc.do.txt

Inline comments can also be used to markup edits. There are add, delete, and
replacement comments for editing::

        [add: ,]
        [add: .]
        [add: ;]
        [del: ,]
        [del: ,]
        [del: .]
        [del: ;]
        [add: some text]
        [del: some text]
        [edit: some text -> some replacement for text]
        [name: some text -> some replacement for text]

For example, the text::

        First consider a quantity $Q$. Without loss of generality, we assume
        $Q>0$. There are three, fundamental, basic property of $Q$.

can be edited as::

        First[add: ,] consider [edit: a quantity -> the flux]
        [del: $Q$. Without loss of generality,
        we assume] $Q>0$. There are three[del: ,] fundamental[del: , basic]
        [edit: property -> properties] of $Q$. [add: These are not
        important for the following discussion.]

which in the rst output format results in


..

    Firstcolor{red}{(**add 2**: ,}) consider **(**edit 3**: a quantity -> the flux**)
    **(**del 4**: Q. Without loss of generality,
    we assume**) Q>0. There are threecolor{red}{(**del 5**: ,}) fundamentalcolor{red}{(**del 6**: , basic})
    **(**edit 7**: property -> properties**) of Q. **(**add 8**: These are not
    important for the following discussion.**)



To implement these edits, run::

        Terminal> doconce apply_edit_comments mydoc.do.txt

Verbatim/Computer Code
----------------------

Inline verbatim code is typeset within back-ticks, as in::

        Some sentence with `words in verbatim style`.

resulting in Some sentence with ``words in verbatim style``.

Multi-line blocks of verbatim text, typically computer code, is typeset
in between ``!bc xxx`` and ``!ec`` directives, which must appear on the
beginning of the line. A specification ``xxx`` indicates what verbatim
formatting style that is to be used. Typical values for ``xxx`` are
nothing, ``cod`` for a code snippet, ``pro`` for a complete program,
``sys`` for a terminal session, ``dat`` for a data file (or output from a
program),
``Xpro`` or ``Xcod`` for a program or code snipped, respectively,
in programming ``X``, where ``X`` may be ``py`` for Python,
``cy`` for Cython, ``sh`` for Bash or other Unix shells,
``f`` for Fortran, ``c`` for C, ``cpp`` for C++, ``m`` for MATLAB,
``pl`` for Perl. For output in ``latex`` one can let ``xxx`` reflect any
defined verbatim environment in the ``ptex2tex`` configuration file
(``.ptex2tex.cfg``). For ``sphinx`` output one can insert a comment::

        # sphinx code-blocks: pycod=python cod=fortran cppcod=c++ sys=console

that maps environments (``xxx``) onto valid language types for
Pygments (which is what ``sphinx`` applies to typeset computer code).

The ``xxx`` specifier has only effect for ``latex`` and
``sphinx`` output. All other formats use a fixed monospace font for all
kinds of verbatim output.

Here is an example of computer code (see the source of this document
for exact syntax)::

        from numpy import sin, cos, exp, pi
        
        def f(x, y, z, t):
            return exp(-t)*sin(pi*x)*sin(pi*y)*cos(2*pi*z)

.. When showing copy from file in !bc envir, indent a character - otherwise

.. ptex2tex is confused and starts copying...

Computer code can also be copied from a file::

         @@@CODE doconce_program.sh
         @@@CODE doconce_program.sh  fromto: doconce clean@^doconce split_rst
         @@@CODE doconce_program.sh  from-to: doconce clean@^doconce split_rst
         @@@CODE doconce_program.sh  envir=shpro fromto: name=@

The ``@@@CODE`` identifier must appear at the very beginning of the line.
The first line copies the complete file ``doconce_program.sh``.
The second line copies from the first line matching the *regular
expression* ``doconce clean`` up to, but not including, the line
matching the *regular expression* ``^doconce split_rst``.
The third line behaves as the second, but the line matching
the first regular expression is not copied (this construction is often
used for copying text between begin-end comment pair in the file).

The copied lines from file are in this example put inside ``!bc shpro``
and ``!ec`` directives, if a complete file is copied, while the
directives become ``!bc shcod`` and ``!ec`` when a code snippet is copied
from a file. In general, for a filename extension ``.X``, the environment
becomes ``!bc Xpro`` or ``!bc Xcod`` for a complete program or snippet,
respectively. The enivorments (``Xcod`` and ``Xpro``) are only active for
``latex``, ``pdflatex``, html`, and ``sphinx`` output.  The fourth line
above specifies the code environment explicitly (``envir=shpro``) such
that it indicates a complete shell program (``shpro``) even if we copy a
part of the file (here from ``name=`` until the end of the file).
Copying a part of a file will by default lead to ``!bc shcod``, which indicates a
code snippet that normally needs more code to run properly.

The ``--code_prefix=text`` option adds a path ``text`` to the filename specified
in the ``@@@CODE`` command (URLs work). For example::

         @@@CODE src/myfile.py

and ``--code_prefix=http://some.place.net``, the file::

        http://some.place.net/src/myfile.py

will be included. If source files have a header with author, email, etc.,
one can remove this header by the option ``'--code_skip_until=# ---``.
The lines up to and including (the first) ``# ---`` will then be excluded.

Important warnings:

 * A code block must come after a plain sentence (at least for successful
   output in reStructredText), not directly after a section/paragraph heading,
   table, comment, figure, or movie.

 * Verbatim code blocks inside lists can be ugly when typeset in some
   output formats. A more robust approach is to replace the list with
   paragraphs that include headings.

LaTeX Mathematics
-----------------

DocOnce supports inline mathematics and blocks of mathematics, using
standard LaTeX syntax. The output formats ``html``, ``sphinx``, ``latex``,
pdflatex`, ``pandoc``, and ``mwiki`` work with this syntax while all other
formats will just display the raw LaTeX code.

Inline expressions are written in the standard
LaTeX way with the mathematics surrounded by dollar signs, as in
Ax=b. To help increase readability in other formats than ``sphinx``,
``latex``, and ``pdflatex``, inline mathematics may have a more human
readable companion expression. The syntax is like::

        $\sin(\norm{\bf u})$|$sin(||u||)$

That is, the LaTeX expression appears to the left of a vertical bar (pipe
symbol) and the more readable expression appears to the right. Both
expressions are surrounded by dollar signs.

Blocks of LaTeX mathematics are written within
``!bt``
and
``!et`` (begin/end TeX) directives starting on the beginning of a line::

        !bt
        \begin{align*}
        \nabla\cdot \pmb{u} &= 0,\\ 
        \nabla\times \pmb{u} &= 0.
        \end{align*}
        !et

This LaTeX code gets rendered as::

        \begin{align*}
        \nabla\cdot \pmb{u} &= 0,\\ 
        \nabla\times \pmb{u} &= 0.
        \end{align*}

Here is a single equation::

        !bt
        \[ \frac{\partial\pmb{u}}{\partial t} + \pmb{u}\cdot\nabla\pmb{u} = 0.\]
        !et

which results in::

        \[ \frac{\partial\pmb{u}}{\partial t} + \pmb{u}\cdot\nabla\pmb{u} = 0.\]

**LaTeX Newcommands.**
The author can define ``newcommand`` statements in files with names
``newcommands*.tex``. Such commands should only be used for mathematics
(other LaTeX constructions are only understood by LaTeX itself).
The convention is that ``newcommands_keep.tex``
contains the newcommands that are kept in the document, while
those in ``newcommands_replace.tex`` will be replaced by their full
LaTeX code. This conventions helps make readable documents in formats
without LaTeX support. For ``html``, ``sphinx``, ``latex``, ``pdflatex``,
``mwiki``, ``ipynb``, and ``pandoc``, the mathematics in newcommands is
rendered nicely anyway. If you desire ``newcommand`` outside LaTeX
mathematics, simply use a Mako variable or a Mako function (which
will be much more flexible and powerful).

.. include with mako must be in this root tree, so we need a link, see make.sh

.. _manual:latex:guide:

Writing Guidelines (Especially for LaTeX Users!)
------------------------------------------------

LaTeX writers often have their own writing habits and have preferred
LaTeX packages. DocOnce is a simpler format and
corresponds to writing in quite plain LaTeX and making the ascii text
look nice (be careful with the use of white space!). This means that
although DocOnce has borrowed a lot from LaTeX, there are a few points
LaTeX writers should pay attention to. Experience shows that these
points are so important that we list them *before* we list typical
DocOnce syntax!

Any LaTeX syntax in mathematical formulas is accepted when DocOnce
translates the text to LaTeX, but the following rules should be
followed when transalting the text to ``sphinx``, ``pandoc``,
``mwiki``, ``html``, or ``ipynb`` formats.

 * AMS LaTeX mathematics is supported, also for the ``html``, ``sphinx``,
   and ``ipynb`` formats.

 * If you want LaTeX math blocks to work with ``latex``, ``html``, ``sphinx``,
   ``markdown``, and ``ipynb``, only use
   the following equation environments: ``\[ ... \]``,
   ``equation*``, ``equation``, ``align*``, ``align``. ``alignat*``, ``alignat``.
   Other environments, such as ``split``, ``multiline``, ``gather`` are
   supported in modern MathJax in HTML and Sphinx, but may have
   rendering problems (to a larger extent than ``equation`` and ``align``).
   DocOnce performs extensions to ``sphinx``, ``ipynb``,
   and other formats such that
   labels in ``align`` and ``alignat`` environments work well.
   If you face problems with fancy LaTeX equation environments in
   web formats, try rewriting with plain ``align``, ``nonumber``, etc.

 * Do not use comments inside equations.

 * Newcommands in mathematical formulas are allowed, but not in
   the running text. Newcommands must be defined in files with names
   ``newcommands*.tex``. Use ``\newcommands`` and not ``\def``.
   Each newcommand must be defined on a single line.
   Use Mako functions if you need macros in the running text.

 * Use labels and refer to them
   for sections, figures, movies, and equations only.
   MediaWiki (``mwiki``) does not support references to equations.

 * Spaces are not allowed in labels.

 * There is just one ``ref`` command (no ``\eqref`` for equations) and references to
   equations must use parentheses. Never use the tilde `` |nbsp| `` (non-breaking
   space) character before references to figures, sections, etc., but
   tilde is allowed for references to equations.

 * Never use ``\pageref`` as pages are not a concept in web documents
   (there is only a ``ref`` command in DocOnce and it refers to labels).

 * Only figures and movies are floating elements in DocOnce, all other elements
   (code, tables, algorithms) must appear *inline* without numbers or labels
   for reference [#exception]_ (refer to inline elements by a section label).
   The reason is that floating elements are in general
   not used in web documents, but we made an exception with figures
   and movies.

 * Keep figure captions shorts as they are used as references in the
   Sphinx format. Avoid inline mathematics since Sphinx will strip it
   away in the figure reference.
   (Many writing styles encourage rich captions that
   explains everything about the figure; this work well
   only in the HTML and LaTeX formats.)

 * You cannot use ``subfigure`` to combine several image files in one
   figure, but you can combine the files into one file using
   the ``doconce combine_images`` tool. Refer to individual image files
   in the caption or text by (e.g.) "left" and "right", or
   "upper left", "lower right", etc.

 * Footnotes can be used as usual in LaTeX, but some HTML formats are not
   able to display mathematics or inline verbatim or other formatted
   code (emphasis, boldface, color) in footnotes - keep that in mind.

 * Use plain ``cite`` for references (e.g., ``\citeauthor`` has no counterpart
   in DocOnce). The bibliography must be prepared in the Publish format,
   but import from (clean) BibTeX is possible.

 * Use ``idx`` for index entries, but put the definitions between paragraphs,
   not inside them (required by Sphinx).

 * Use the ``\bm`` command (from the ``bm`` package, always included by DocOnce)
   for boldface in mathematics.

 * Make sure all ordinary text starts in column 1 on each line. Equations
   can be indented. The ``\begin{}`` and ``\end{}`` directives should start
   in column 1.

 * If you depend on various LaTeX environments for your writings, you have
   to give these up, or implement *user-defined environments* in DocOnce.
   For instance, examples are normally typeset as subsections in DocOnce,
   but can also utilize a user-defined example environment.
   Learn about the exercise support in DocOnce for typesetting
   exercises, problems, and projects.

 * Learn about the preprocessors Preprocess and Mako - these are smart
   tools for, e.g., commenting out/in large portions of text and creating
   macros.

 * Use *generalized references* when referring to companion documents
   that may later become part of this document (or migrated out of this document).

 * Follow `recommendations for DocOnce books <https://github.com/doconce/setup4book-doconce>`__ if you plan to write a book.

.. [#exception] There is an exception: by using *user-defined environments*
   within ``!bu-name`` and ``!eu-name`` directives, it is possible to
   label any type of text and refer to it. For example, one can have
   environments for examples, tables, code snippets, theorems, lemmas, etc.
   One can also use Mako functions to implement environments.


.. admonition:: Use the preprocessor to tailor output

   If you really need special LaTeX constructs in the LaTeX output
   from DocOnce, you may use use preprocessor if-tests on
   the format (typically ``#if FORMAT in ("latex", "pdflatex")``) to
   include such special LaTeX code. With an else clause you can easily
   create corresponding constructions for other formats. This way
   of using Preprocess or Mako
   allows you to use advanced LaTeX features (or HTML features for the HTML formats)
   to fine tune the resulting
   document. More tuning can be done by automatic editing of the
   output file (e.g., ``.tex`` or ``.html``) produced by DocOnce using
   your own scripts or the ``doconce replace`` and ``doconce subst`` commands.





.. admonition:: Autotranslation of LaTeX to DocOnce

   The tool ``doconce latex2doconce`` may help you translate LaTeX files
   to DocOnce syntax. However, if you use computer code in floating
   list environments, special packages for typesetting algorithms,
   example environments, ``subfigure`` in figures,
   or a lot of newcommands in the running text, there will be need for
   a lot of manual edits and adjustments.
   
   For examples, figure environments can only be translated by
   ``doconce latex2doconce`` if the label is inside the caption and
   the figure is typeset like::
   
           \begin{figure}
             \centering
             \includegraphics[width=0.55\linewidth]{figs/myfig.pdf}
             \caption{This is a figure. \labe{myfig}}
           \end{figure}
   
   If the LaTeX text is consistent with respect to the placement of the label, a
   simple script can autoedit the label inside the caption, but many
   LaTeX writers put the label at different places in different figures,
   and then it becomes more difficult to autoedit figures and translate
   them to the DocOnce ``FIGURE:`` syntax.
   
   Tables are hard to interpret and translate because headings and
   caption can be typeset in many different ways. The type of table
   that is recognized looks like::
   
           \begin{table}
           \caption{Here goes the caption.}
           \begin{tabular}{lr}
           \hline
           \multicolumn{1}{c}{$v_0$} & \multicolumn{1}{c}{$f_R(v_0)$}\\hline
           1.2 & 4.2\1.1 & 4.0\0.9 & 3.7
           \hline
           \end{tabular}
           \end{table}
   
   Recall that table captions do not make sense in DocOnce since tables
   must be inlined and explained in the surrounding text.
   
   Footnotes are also problematic for ``doconce latex2doconce`` since DocOnce
   footnotes must have the explanation outside the paragraph where the
   footnote is used. This calls for manual work. The translator from
   LaTeX to DocOnce will insert ``_PROBLEM_`` and mark footnotes. One
   solution is to avoid footnotes in the LaTeX document if fully automatic
   translation is desired.




Hyperlinks
----------

Links use either a link text or the raw URL::

        Here is some "some link text": "http://some.net/address"
        (as in "search google": "http://google.com")
        or just the raw address: URL: "http://google.com".
        
        Links to files typeset in verbatim mode applies backtics:
        "`myfile.py`": "http://some.net/some/place/myfile.py".
        
        Mail addresses works too: send problems to
        "`hpl@simula.no`": "mailto:hpl@simula.no"
        or just "send mail": "mailto:hpl@simula.no".

Figures and Movies
------------------

Figures and movies have almost equal syntax::

        FIGURE: [relative/path/to/figurefile, width=500 frac=0.8] Here goes the caption which must be on a single line. label{some:fig:label}
        
        MOVIE: [relative/path/to/moviefile, width=500] Here goes the caption which must be on a single line. 
        

Note three important syntax details:

 1. A mandatory comma after the figure/movie filename,

 2. no comments between ``width``, ``height``, and ``frac`` and no spaces
    around the ``=`` characters,

 3. all of the commands must appear on a single line,

 4. there must be a blank line after the command.

The figure file can be listed without extension. DocOnce will then find
the version of the file with the most appropriate extension for the chosen
output format. If not suitable version is found, DocOnce will convert
another format to the needed one.

The caption is optional. If omitted, the figure will be inlined (meaning
no use of any figure environment in HTML or LaTeX formats). The ``width``
and ``height`` parameters affect HTML formats (``html``, ``rst``, ``sphinx``),
while ``frac`` is the width of the image as a fraction of the total text
width in the ``latex`` and ``pdflatex`` formats.

The command-line options ``--fig_prefix=...`` and ``--mov_prefix=...`` can
be used to add a path (can be a URL) to all figure and movie files,
respectively.  This is useful when including DocOnce documents in
other DocOnce documents such that the text is compiled in different
directories (with different paths to the figure directory).

Movie files can either be a video or a wildcard expression for a
series of frames. In the latter case, a simple device in an HTML page
will display the individual frame files as a movie.

Combining several image files into one can be done by the::

        doconce combine_images image1 image2 ... output_image

This command applies ``montage`` or PDF-based tools to combine the images
to get the highest quality.

YouTube and Vimeo movies will be embedded in ``html`` and ``sphinx`` documents
and otherwise be represented by a link. The syntax is::

        MOVIE: [http://www.youtube.com/watch?v=_O7iUiftbKU, width=420 height=315] YouTube movie.
        
        MOVIE: [http://vimeo.com/55562330, width=500 height=278] Vimeo movie.
        

The latter results in

.. raw:: html
        
        <iframe width="500" height="278" src="https://player.vimeo.com/video/55562330" frameborder="0" allowfullscreen></iframe>
        
        <em>Vimeo movie.</em>
        

Tables
------

The table in the section `Section Types`_ was written with this
syntax::

        
        |----------------c--------|------------------c--------------------|
        |      Section type       |        Syntax                         |
        |----------------l--------|------------------l--------------------|
        | chapter                 | `========= Heading ========` (9 `=`)  |
        | section                 | `======= Heading =======`    (7 `=`)  |
        | subsection              | `===== Heading =====`        (5 `=`)  |
        | subsubsection           | `=== Heading ===`            (3 `=`)  |
        | paragraph               | `__Heading.__`               (2 `_`)  |
        |-----------------------------------------------------------------|
        

Note that

 * Each line begins and ends with a vertical bar (pipe symbol).

 * Column data are separated by a vertical bar (pipe symbol).

 * There must be a blank line before and after the table.

 * There may be horizontal rules, i.e., lines with dashes for
   indicating the heading and the end of the table, and these may
   contain characters 'c', 'l', or 'r' for how to align headings or
   columns. The first horizontal rule may indicate how to align
   headings (center, left, right), and the horizontal rule after the
   heading line may indicate how to align the data in the columns
   (center, left, right).
   One can also use ``X`` for potentially very wide text that must be
   wrapped and left-adjusted (will only affect ``latex`` and ``pdflatex`` where the
   ``tabularx`` package is then used; ``X`` means ``l`` in all other formats).

 * If the horizontal rules are without alignment information there should
   be no vertical bar (pipe symbol) between the columns. Otherwise, such
   a bar indicates a vertical bar between columns in LaTeX.

 * Many output formats are so primitive that heading and column alignment
   have no effect.

A quick way of generating tables is to place all the entries in a file
with comma as separator (a CSV file) and then run the utility
``doconce csv2table`` to create a table in the DocOnce format.

The command-line option ``--tables2csv`` (to ``doconce format``)
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.

DocOnce tables can be efficiently made directly from data in CSV files::

        Terminal> doconce csv2table mydata.csv > mydata_table.do.txt

Now we can do ``# #include "mydata_table.do.txt"`` in the DocOnce
source file or simply copy the table in ``mydata_table.do.txt``
into the DocOnce file.

Labels and References
---------------------

The notion of labels and references (as well as bibliography and index)
is adopted
from LaTeX with a very similar syntax. As in LaTeX, a label can be
inserted anywhere, using the syntax::

        label{name}

with no backslash
preceding the label keyword. It is common practice to choose ``name``
as some hierarchical name, using a delimiter like ``:`` or ``_`` between
(e.g.) section, subsection, and topic.

A reference to the label ``name`` is written as::

        ref{name}

again with no backslash before ``ref``.

Use labels for sections and equations only, and precede the reference
by "Section" or "Chapter", or in case of an equation, surround the
reference by parenthesis.

Citations and Bibliography
--------------------------

Single citations are written as::

        cite{name}

where ``name`` is a logical name
of the reference (again, LaTeX writers must not insert a backslash).
Bibliography citations often have ``name`` on the form
``Author1_Author2_YYYY``, ``Author_YYYY``, or ``Author1_etal_YYYY``, where
``YYYY`` is the year of the publication.
Multiple citations at once is possible by separating the logical names
by comma::

        cite{name1,name2,name3}

The bibliography is specified by a line ``BIBFILE: papers.pub``,
where ``papers.pub`` is a publication database in the
`Publish <https://github.com/doconce/publish>`__ format.
BibTeX ``.bib`` files can easily be combined to a Publish database
(which DocOnce needs to create bibliographies in other formats
than LaTeX).

Generalized References
----------------------

There is a *generalized referencing* feature in DocOnce that allows
a reference with ``ref`` to have one formulation if the label is
in the same document and another formulation if the reference is
to an item in an external document. This construction makes it easy
to work with many small, independent documents in parallel with
a book assembly of some of the small elements.
The syntax of a generalized reference is::

        ref[internal][cite][external]

with a specific example being::

        As explained in
        ref[Section ref{subsec:ex}][in cite{testdoc:12}][a "section":
        "testdoc.html#___sec2" in the document
        "A Document for Testing DocOnce": "testdoc.html" cite{testdoc:12}],
        DocOnce documents may include movies.

The output from a generalized reference is the text ``internal`` if all
references with ``ref`` in the text ``internal`` are references to labels
defined in the
present document. Otherwise, if ``cite`` is non-empty and the format is
``latex`` or ``pdflatex``, one assumes that the references in ``internal``
are to external documents declared by a comment line
``# Externaldocuments: testdoc, mydoc`` (usually after the title, authors,
and date). In this case the output text is ``internal`` followed by ``cite``,
and the
LaTeX package ``xr`` is used to handle the labels in the external
documents.  If none of the two situations above applies, the
``external`` text will be the output.

Index of Keywords
-----------------

DocOnce supports creating an index of keywords. A certain keyword
is registered for the index by a syntax like (no
backslash!)::

        index{name}

It is recommended to place any index of this type outside
running text, i.e., after (sub)section titles and in the space between
paragraphs. Index specifications placed right before paragraphs also
gives the doconce source code an indication of the content in the
forthcoming text. The index is only produced for the ``latex``,
``pdflatex``, ``rst``, and ``sphinx`` formats.

Capabilities of The Program ``doconce``
---------------------------------------

The ``doconce`` program can be used for a number of purposes besides
transforming a ``.do.txt`` file to some format. Here is the
list of capabilities::

        DocOnce version 1.5.4 (from /home/amarin/doconce/venv/lib/python3.6/site-packages/DocOnce-1.5.4-py3.6.egg/doconce)
        Usage: doconce command [optional arguments]
        commands: help format find subst replace remove spellcheck apply_inline_edits capitalize change_encoding clean combine_images csv2table diff expand_commands expand_mako extract_exercises find_nonascii_chars fix_bibtex4publish gitdiff grab grep guess_encoding gwiki_figsubst html2doconce html_colorbullets jupyterbook include_map insertdocstr ipynb2doconce latex2doconce latex_dislikes latex_exercise_toc latex_footer latex_header latex_problems latin2html lightclean linkchecker list_fig_src_files list_labels makefile md2html md2latex old2new_format ptex2tex pygmentize ref_external remove_exercise_answers remove_inline_comments replace_from_file slides_beamer slides_html slides_markdown sphinx_dir sphinxfix_localURLs split_html split_rst teamod
        
        doconce format html|latex|pdflatex|rst|sphinx|plain|gwiki|mwiki|
                       cwiki|pandoc|st|epytext dofile 
        # transform doconce file to another format
        
        doconce subst [-s -m -x --restore] regex-pattern \ 
                regex-replacement file1 file2 ... 
        # substitute a phrase by another using regular expressions (in this example -s is the re.DOTALL modifier, -m is the re.MULTILINE modifier, -x is the re.VERBOSE modifier, --restore copies backup files back again)
        
        doconce replace from-text to-text file1 file2 ...                      
        # replace a phrase by another literally (exact text substitution)
        
        doconce replace_from_file file-with-from-to-replacements file1 file2 ... 
        # replace using from and to phrases from file
        
        doconce find expression                                                
        # search for a (regular) expression in all .do.txt files in the current directory tree (useful when removing compilation errors)
        
        doconce include_map mydoc.do.txt                                       
        # print an overview of how various files are included in the root doc
        
        doconce expand_mako mako_code_file funcname file1 file2 ...            
        # replace all mako function calls by the `results of the calls
        
        doconce remove_inline_comments dofile                                  
        # remove all inline comments in a doconce file
        
        doconce apply_inline_edits                                             
        # apply all edits specified through inline comments
        
        doconce sphinx_dir copyright='John Doe' title='Long title' \
                short_title="Short title" version=0.1 intersphinx \
                /path/to/mylogo.png dofile 
        # create a directory for the sphinx format (requires sphinx version >= 1.1)
        
        doconce format sphinx complete_file 
        doconce split_rst complete_file 
        doconce sphinx_dir complete_file 
        python automake_sphinx.py 
        # split a sphinx/rst file into parts according to !split commands
        
        doconce insertdocstr rootdir                                           
        # walk through a directory tree and insert doconce files as docstrings in *.p.py files
        
        doconce lightclean                                                     
        # remove all redundant files (keep source .do.txt and results: .pdf, .html, sphinx- dirs, .mwiki, .ipynb, etc.)
        
        doconce clean                                                          
        # remove all files that the doconce can regenerate
        
        doconce change_encoding utf-8 latin1 dofile                            
        # change encoding
        
        doconce guess_encoding filename                                        
        # guess the encoding in a text
        
        doconce find_nonascii_chars file1 file2 ...                            
        # find non-ascii characters in a file
        
        doconce split_html complete_file.html                                  
        # split an html file into parts according to !split commands
        
        doconce slides_html slide_type complete_file.html                      
        # create HTML slides from a (doconce) html file
        
        doconce slides_beamer complete_file.tex                                
        # create LaTeX Beamer slides from a (doconce) latex/pdflatex file
        
        doconce slides_markdown complete_file.md remark --slide_style=light    
        # create Remark slides from Markdown
        
        doconce html_colorbullets file1.html file2.html ...                    
        # replace bullets in lists by colored bullets
        
        doconce extract_exercises tmp_mako__mydoc                              
        # extract all exercises (projects and problems too)
        
        doconce grab --from[-] from-text [--to[-] to-text] file > result       
        # grab selected text from a file
        
        doconce remove --from[-] from-text [--to[-] to-text] file > result     
        # remove selected text from a file
        
        doconce grep FIGURE|MOVIE|CODE dofile                                  
        # list all figure, movie or included code files
        
        doconce spellcheck [-d .mydict.txt] *.do.txt                           
        # run spellcheck on a set of files
        
        doconce ptex2tex mydoc -DMINTED pycod=minted sys=Verbatim \
                dat=\begin{quote}\begin{verbatim};\end{verbatim}\end{quote} 
        # transform ptex2tex files (.p.tex) to ordinary latex file and manage the code environments
        
        doconce md2html file.md                                                
        # make HTML file via pandoc from Markdown (.md) file
        
        doconce md2latex file.md                                               
        # make LaTeX file via pandoc from Markdown (.md) file
        
        doconce combine_images image1 image2 ... output_file                   
        # combine several images into one
        
        doconce latex_problems mydoc.log [overfull-hbox-limit]                 
        # report problems from a LaTeX .log file
        
        doconce list_fig_src_files *.do.txt                                    
        # list all figure files, movie files, and source code files needed
        
        doconce list_labels myfile                                             
        # list all labels in a document (for purposes of cleaning them up)
        
        doconce ref_external mydoc [pubfile]                                   
        # generate script for substituting generalized references
        
        doconce linkchecker *.html                                             
        # check all links in HTML files
        
        doconce capitalize [-d .mydict.txt] *.do.txt                           
        # change headings from "This is a Heading" to "This is a heading"
        
        doconce latex2doconce latexfile                                        
        # translate a latex document to doconce (requires usually manual fixing)
        
        doconce latex_dislikes latexfile                                       
        # check if there are problems with translating latex to doconce
        
        doconce ipynb2doconce notebookfile                                     
        # translate an IPython/Jupyter notebook to doconce
        
        doconce pygmentize myfile [pygments-style]                             
        # typeset a doconce document with pygments (for pretty print of doconce itself)
        
        doconce makefile docname doconcefile [html sphinx pdflatex ...]        
        # generate a make.py script for translating a doconce file to various formats
        
        doconce diff file1.do.txt file2.do.txt [diffprog]                      
        # find differences between two files (diffprog can be difflib, diff, pdiff, latexdiff, kdiff3, diffuse, ...)
        
        doconce gitdiff file1 file2 file3 ...                                  
        # find differences between the last two Git versions of several files
        
        doconce csv2table somefile.csv                                         
        # convert csv file to doconce table format
        
        doconce sphinxfix_local_URLs file.rst                                  
        # edit URLs to local files and place them in _static
        
        doconce latin2html file.html                                           
        # replace latex-1 (non-ascii) characters by html codes
        
        doconce fix_bibtex4publish file1.bib file2.bib ...                     
        # fix common problems in bibtex files for publish import
        
        doconce latex_header                                                   
        # print the header (preamble) for latex file
        
        doconce latex_footer                                                   
        # print the footer for latex files
        
        doconce expand_commands file1 file2 ...                                
        # expand short cut commands to full form in files
        
        doconce latex_exercise_toc myfile                                      
        # insert a table of exercises in a latex file myfile.p.tex

Exercises
---------

DocOnce supports *Exercise*, *Problem*, *Project*, and *Example*.
These are typeset
as ordinary sections and referred to by their section labels.
Exercise, problem, project, or example sections contains certain *elements*:

  * a headline at the level of a subsection
    containing one of the words "Exercise:", "Problem:",
    "Project:", or "Example:", followed by a title (required)

  * a label (optional)

  * a solution file (optional)

  * name of file with a student solution (optional)

  * main exercise text (required)

  * a short answer (optional)

  * a full solution (optional)

  * one or more hints (optional)

  * one or more subexercises (subproblems, subprojects), which can also
    contain a text, a short answer, a full solution, name student file
    to be handed in, and one or more hints (optional)

A typical sketch of a a problem without subexercises goes as follows::

        ===== Problem: Derive the Formula for the Area of an Ellipse =====
        label{problem:ellipsearea1}
        file=ellipse_area.pdf
        solution=ellipse_area1_sol.pdf
        
        Derive an expression for the area of an ellipse by integrating
        the area under a curve that defines half of the ellipse.
        Show each step in the mathematical derivation.
        
        !bhint
        Wikipedia has the formula for the curve.
        !ehint
        
        !bhint
        "Wolframalpha": "http://wolframalpha.com" can perhaps
        compute the integral.
        !ehint

If the exercise type (Exercise, Problem, Project, or Example)
is enclosed in braces, the type is left out of the title in the
output. For example, the if the title line above reads::

        ===== {Problem}: Derive the Formula for the Area of an Ellipse =====

the title becomes just "Derive the ...".

An exercise with subproblems, answers and full solutions has this
setup-up::

        ===== Exercise: Determine the Distance to the Moon =====
        label{exer:moondist}
        
        Intro to this exercise. Questions are in subexercises below.
        
        !bsubex
        Subexercises are numbered a), b), etc.
        
        file=subexer_a.pdf
        
        !bans
        Short answer to subexercise a).
        !eans
        
        !bhint
        First hint to subexercise a).
        !ehint
        
        !bhint
        Second hint to subexercise a).
        !ehint
        !esubex
        
        !bsubex
        Here goes the text for subexercise b).
        
        file=subexer_b.pdf
        
        !bhint
        A hint for this subexercise.
        !ehint
        
        !bsol
        Here goes the solution of this subexercise.
        !esol
        !esubex
        
        !bremarks
        At the very end of the exercise it may be appropriate to summarize
        and give some perspectives. The text inside the `!bremarks` and `!eremarks`
        directives is always typeset at the end of the exercise.
        !eremarks
        
        !bsol
        Here goes a full solution of the whole exercise.
        !esol
        

By default, answers, solutions, and hints are typeset as paragraphs.
The command-line arguments ``--without_answers`` and ``--without_solutions``
turn off output of answers and solutions, respectively, except for examples. The command line options ``--answers_at_end`` and ``--solutions_at_end`` write all answers and solutions to exercises to a separate section at the end of the document, respectively. Combine with ``--without_answers`` and ``--without_solutions`` to remove answers and solutions from the main text.

The commands ``!anshide`` and ``!solhide`` can be used to hide from the main text answers and solutions, respectively, until the ``!ansoff`` and ``!soloff`` commands are encountered. Similarly, the ``!ansdocend`` and ``!soldocend`` commands move answers and solutions to the end of the book. 

Environments
------------

DocOnce environments start with ``!benvirname`` and end with ``!eenvirname``,
where ``envirname`` is the name of the environment. Here is a listing of
the environments:

 * ``c``: computer code (or verbatim text)

 * ``t``: math blocks with LaTeX syntax

 * ``subex``: sub-exercise

 * ``ans``: short answer to exercise or sub-exercise

 * ``sol``: full solution to exercise or sub-exercise

 * ``hint``: multiple help items in an exercise or sub-exercise

 * ``quote``: indented text

 * ``notice``, ``summary``, ``warning``, ``question``: admonition boxes with
    custom title, special icon, and (sometimes) background color

 * ``block``, ``box``: simpler boxes (``block`` may have title but never any icon)

 * ``pop``: text to gradually pop up in slide presentations

 * ``slidecell``: indication of cells in a grid layout for elements on a
   slide

In addition, the user can define new environments ``!bc-name`` as
explained in the `manual <http://doconce.github.io/doconce/doc/pub/manual/manual.html#manual:userdef:envir>`__.

Preprocessing
-------------

DocOnce documents may utilize a preprocessor, either ``preprocess`` and/or
``mako``. The former is a C-style preprocessor that allows if-tests
and including other files (but not macros with arguments).
The ``mako`` preprocessor is much more advanced - it is actually a full
programming language, very similar to Python.

The command ``doconce format`` first runs ``preprocess`` and then ``mako``.
Here is a typical example on utilizing ``preprocess`` to include another
document, "comment out" a large portion of text, and to write format-specific
constructions::

        # #include "myotherdoc.do.txt"
        
        # #if FORMAT in ("latex", "pdflatex")
        \begin{table}
        \caption{Some words... label{mytab}}
        \begin{tabular}{lrr}
        \hline\noalign{\smallskip}
        \multicolumn{1}{c}{time} & \multicolumn{1}{c}{velocity} & \multicolumn{1}{c}{acceleration} \\ 
        \hline
        0.0          & 1.4186       & -5.01        \\ 
        2.0          & 1.376512     & 11.919       \\ 
        4.0          & 1.1E+1       & 14.717624    \\ 
        \hline
        \end{tabular}
        \end{table}
        # #else
          |--------------------------------|
          |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    |
          |--------------------------------|
        # #endif
        
        # #ifdef EXTRA_MATERIAL
        ....large portions of text...
        # #endif

With the ``mako`` preprocessor the if-else tests have slightly different syntax.
An `example document <http://doconce.github.com/bioinf-py/>`__ contains
some illustrations on how to utilize ``mako`` (clone the GitHub project and
examine the DocOnce source and the ``doc/src/make.sh`` script).

Resources
---------

 * Excellent "Sphinx Tutorial" by C. Reller: "http://people.ee.ethz.ch/~creller/web/tricks/reST.html"

************** File: quickref.sphinx.rst *****************
.. Automatically generated Sphinx-extended reStructuredText file from DocOnce source
   (https://github.com/hplgit/doconce/)

.. |nbsp| unicode:: 0xA0
   :trim:

.. Document title:

DocOnce Quick Reference
=======================

:Authors: Hans Petter Langtangen
:Date: Jan 32, 2100

**WARNING: This quick reference is very incomplete!**

**Mission.**
Enable writing documentation with much mathematics and
computer code *once, in one place* and include it in traditional LaTeX
books, thesis, and reports, and, without extra efforts, also make
professional looking web versions with Sphinx or HTML. Other outlets
include Google's ``blogger.com``, Wikipedia/Wikibooks, IPython/Jupyter
notebooks, plus a wide variety of other formats for documents without
mathematics and code.

Supported Formats
-----------------

DocOnce currently translates files to the following formats:

 * LaTeX (format ``latex`` or ``pdflatex``)

 * HTML (format ``html``)

 * Sphinx (format ``sphinx``)

 * Pandoc-extended or GitHub-flavored Markdown (format ``pandoc``)

 * IPython notebook (format ``ipynb``)

 * Matlab notebook (format ``matlabnb``)

 * MediaWiki (format ``mwiki``)

 * Googlecode wiki (format ``gwiki``)

 * Creoloe wiki (format ``cwiki``)

 * reStructuredText (format ``rst``)

 * plain (untagged) ASCII (format ``plain``)

 * Epydoc (format ``epydoc``)

 * StructuredText (format ``st``)

For documents with much code and mathematics, the best (and most supported)
formats are ``latex``, ``pdflatex``, ``sphinx``, and ``html``; and to a slightly
less extent ``mwiki`` and ``pandoc``. The HTML format supports blog posts on
Google and Wordpress.


.. admonition:: Use a text editor with monospace font

   Some DocOnce constructions are sensitive to whitespace,
   so you *must* use a text editor with monospace font.




Emacs syntax support
--------------------

The file `.doconce-mode.el <https://github.com/doconce/doconce/blob/master/misc/.doconce-mode.el>`__
in the DocOnce source distribution gives a "DocOnce Editing Mode" in
Emacs. Store the raw version of the file in the home directory and add
``(load-file "~/.doconce-mode.el")`` to the ``.emacs`` file.

Besides syntax highlighting of DocOnce documents, this Emacs mode
provides a lot of shortcuts for setting up many elements in a document:

=============  ==========================================  
  Emacs key                      Action                    
=============  ==========================================  
Ctrl+c f       figure                                      
Ctrl+c v       movie/video                                 
Ctrl+c h1      heading level 1 (section/h1)                
Ctrl+c h2      heading level 2 (subsection/h2)             
Ctrl+c h3      heading level 2 (subsection/h3)             
Ctrl+c hp      heading for paragraph                       
Ctrl+c me      math environment: ``!bt`` equation ``!et``  
Ctrl+c ma      math environment: ``!bt`` align ``!et``     
Ctrl+c ce      code environment: ``!bc`` code ``!ec``      
Ctrl+c cf      code from file: ``@@@CODE``                 
Ctrl+c table2  table with 2 columns                        
Ctrl+c table3  table with 3 columns                        
Ctrl+c table4  table with 4 columns                        
Ctrl+c exer    exercise outline                            
Ctrl+c slide   slide outline                               
Ctrl+c help    print this table                            
=============  ==========================================  

Title, Authors, and Date
------------------------

A typical example of giving a title, a set of authors, a date,
and an optional table of contents
reads

.. code-block:: doconce

    TITLE: On an Ultimate Markup Language
    AUTHOR: H. P. Langtangen at Center for Biomedical Computing, Simula Research Laboratory & Dept. of Informatics, Univ. of Oslo
    AUTHOR: Kaare Dump Email: dump@cyb.space.com at Segfault, Cyberspace Inc.
    AUTHOR: A. Dummy Author
    DATE: today
    TOC: on

The entire title must appear on a single line.
The author syntax is

.. code-block:: text

    name Email: somename@adr.net at institution1 & institution2

where the email is optional, the "at" keyword is required if one or
more institutions are to be specified, and the ``&`` keyword
separates the institutions (the keyword ``and`` works too).
Each author specification must appear
on a single line.
When more than one author belong to the
same institution, make sure that the institution is specified in an identical
way for each author.

The date can be set as any text different from ``today`` if not the
current date is wanted, e.g., ``Jan 32, 2100``.

The table of contents is removed by writing ``TOC: off``.

Copyright
---------

.. Recall to ident AUTHOR commands to avoid interpretation

Copyright for selected authors and/or institutions are easy to insert as part
of the ``AUTHOR`` command. The copyright syntax is

.. code-block:: doconce

    {copyright,year1-year2|license}

and can be placed after the author or after an institution, e.g.,

.. code-block:: doconce

     AUTHOR: name Email: somename@adr.net {copyright,2006-present} at inst1
     AUTHOR: name {copyright} at inst1 {copyright}

The first line gives ``name`` a copyright for 2006 up to the present year,
while the second line gives copyright to ``name`` and the institution ``inst1``
for the present year. The license can be any formulation, but there are
some convenient abbreviations for Creative Commons ("public domain")
licenses: ``CC BY`` for Creative Commons Attribution 4.0 license,
``CC BY-NC`` for Creative Commons Attribution-NonCommercial 4.0 license.
For example,

.. code-block:: doconce

     AUTHOR: name1 {copyright|CC BY} at institution1
     AUTHOR: name2 {copyright|CC BY} at institution2

is a very common copyright for the present year with the Attribution license.
The copyright must be identical for all authors and institutions.

.. _quick:sections:

Section Types
-------------

=============  ===============================================  
 Section type                       Syntax                      
=============  ===============================================  
chapter        ``========= Heading ========`` (9 ``=``)         
section        ``======= Heading =======``    (7 ``=``)         
subsection     ``===== Heading =====``        (5 ``=``)         
subsubsection  ``=== Heading ===``            (3 ``=``)         
paragraph      ``__Heading.__``               (2 ``_``)         
abstract       ``__Abstract.__`` Running text...                
appendix       ``======= Appendix: heading =======`` (7 ``=``)  
appendix       ``===== Appendix: heading =====`` (5 ``=``)      
exercise       ``===== Exercise: heading =====`` (5 ``=``)      
=============  ===============================================  

Note that abstracts are recognized by starting with ``__Abstract.__`` or
``__Summary.__`` at the beginning of a line and ending with three or
more ``=`` signs of the next heading.

The ``Exercise:`` keyword can be substituted by ``Problem:`` or ``Project:``.
A recommended convention is that an exercise is tied to the text,
a problem can stand on its own, and a project is a comprehensive
problem.

Inline Formatting
-----------------

Words surrounded by ``*`` are emphasized: ``*emphasized words*`` becomes
*emphasized words*. Similarly, an underscore surrounds words that
appear in boldface: ``_boldface_`` becomes **boldface**. Colored words
are also possible: the text

.. code-block:: text

    `color{red}{two red words}`

becomes **two red words**.
(But colors do not work in format sphinx).

Quotations appear inside double backticks and double single quotes:

.. code-block:: text

    This is a sentence with ``words to be quoted''.

A forced linebreak is specified by ``<linebreak>`` at the point where the
linebreak in the output is wanted.

Footnotes use a label in the text with the footnote text separate,
preferably after the paragraph where the footnote appears:

.. code-block:: text

    Differentiating[^diff2] this equation leads
    to a new and much simpler equation.
    
    [^diff2]: More precisely, we apply the divergence
    $\nabla\cdot$ on both sides.
    
    Here comes a new paragraph...

Non-breaking space is inserted using the tilde character as in LaTeX:

.. code-block:: text

    This distance corresponds to 7.5~km, which is traveled in $7.5/5$~s.

A horizontal rule for separating content vertically, like this:

---------

is typeset as four or more hyphens on a single line:

.. code-block:: text

    ---------

The ``latex``, ``pdflatex``, ``sphinx``, and ``html`` formats support em-dash,
indicated by three hyphens: ``---``. Here is an example:

.. code-block:: text

    The em-dash is used - without spaces - as alternative to hyphen with
    space around in sentences---this way, or in quotes:
    *Premature optimization is the root of all evil.*--- Donald Knuth.

This text is in the sphinx rendered as

The em-dash is used - without spaces - as alternative to hyphen with
space around in sentences---this way, or in quotes:
*Premature optimization is the root of all evil.*--- Donald Knuth.

The en-dash consists of two hyphens, either with blanks on both sides - for
something in the middle of a sentence - or in number ranges like 240 - 249.
LaTeX writes are used to and fond of en-dash.

An ampersand, as in Guns & Roses or Texas A&M, is written as a
plain ``&`` *with space(s) on both sides*. Single upper case letters on each
side of ``&``, as in ``Texas A & M``, remove the spaces and result in
Texas A&M, while words on both sides of ``&``, as in ``Guns & Roses``,
preserve the spaces: Guns & Roses. Failing to have spaces before and
after ``&`` will result in wrong typesetting of the ampersand in the ``html``,
``latex``, and ``pdflatex`` formats.

Emojis, as defined in `<http://www.emoji-cheat-sheet.com>`_, can be
inserted in the text, as (e.g.) ``:dizzy_face:`` with blank or newline
before or after :dizzy_face: Only the ``pdflatex``, ``html``, and ``pandoc`` output
formats translate emoji specifications to images, while all other
formats leave the textual specification in the document. The
command-line option ``--no_emoji`` removes all emojis from the output
document.

Lists
-----

There are three types of lists: *bullet lists*, where each item starts
with ``*``, *enumeration lists*, where each item starts with ``o`` and gets
consecutive numbers,
and *description* lists, where each item starts with ``-`` followed
by a keyword and a colon.

.. code-block:: text

    Here is a bullet list:
    
     * item1
     * item2
      * subitem1 of item2
      * subitem2 of item2,
        second line of subitem2
     * item3
    
    Note that sublists are consistently indented by one or more blanks as
    shown: bullets must exactly match and continuation lines must start
    right below the line above.
    
    Here is an enumeration list:
    
     o item1
     o item2
       may appear on
       multiple lines
      o subitem1 of item2
      o subitem2 of item2
     o item3
    
    And finally a description list:
    
     - keyword1: followed by
       some text
       over multiple
       lines
     - keyword2:
       followed by text on the next line
     - keyword3: and its description may fit on one line

The code above follows.

Here is a bullet list:

 * item1

 * item2

  * subitem1 of item2

  * subitem2 of item2

 * item3

Note that sublists are consistently indented by one or more blanks as
shown: bullets must exactly match and continuation lines must start
right below the line above.

Here is an enumeration list:

1. item1

2. item2
   may appear on
   multiple lines

 a. subitem1 of item2

 b. subitem2 of item2

3. item3

And finally a description list:

 keyword1: 
   followed by
   some text
   over multiple
   lines

 keyword2: 
   followed by text on the next line

 keyword3: 
   and its description may fit on one line


.. admonition:: No indentation - except in lists

   DocOnce syntax is sensitive to whitespace.
   No lines should be indented, only lines belonging to lists.
   Indented lines may give strange output in some formats.




Comment lines
-------------

Lines starting with ``#`` are treated as comments in the document and
translated to the proper syntax for comments in the output
document. Such comment lines should not appear before LaTeX math
blocks, verbatim code blocks, or lists if the formats ``rst`` and
``sphinx`` are desired.

Comment lines starting with ``##`` are not propagated to the output
document and can be used for comments that are only of interest in
the DocOnce file.

Large portions of text can be left out using Preprocess. Just place
``# #ifdef EXTRA`` and ``# #endif`` around the text. The command line
option ``-DEXTRA`` will bring the text alive again.

When using the Mako preprocessor one can also place comments in
the DocOnce source file that will be removed by Mako before
DocOnce starts processing the file.

Inline comments
---------------

Inline comments meant as messages or notes, to authors during development
in particular,
are enabled by the syntax

.. code-block:: text

    [name: running text]

where ``name`` is the name or ID of an author or reader making the comment,
and ``running text`` is the comment. The name can contain upper and lower
case characters, digits, single quote, ``+`` and ``-``, as well
as space. Here goes an example.

.. code-block:: text

    Some running text. [hpl: There must be a space after the colon,
    but the running text can occupy multiple lines.]

which is rendered as


..

    Some running text. [**hpl 1**: There must be a space after the colon, but the running text can occupy multiple lines.]



The inline comments have simple typesetting in most formats, typically
boldface name, a comment number, with everything surrounded by
parenthesis.  However, with LaTeX output and the ``--latex_todonotes``
option to ``doconce format``, colorful margin or inline boxes (using the
``todonotes`` package) make it very easy to spot the comments.

Running

.. code-block:: text

    doconce format html mydoc.do.txt --skip_inline_comments

removes all inline comments from the output. This feature makes it easy
to turn on and off notes to authors during the development of the document.

All inline comments to readers can also be physically
removed from the DocOnce source by

.. code-block:: text

    doconce remove_inline_comments mydoc.do.txt

Inline comments can also be used to markup edits. There are add, delete, and
replacement comments for editing:

.. code-block:: text

    [add: ,]
    [add: .]
    [add: ;]
    [del: ,]
    [del: ,]
    [del: .]
    [del: ;]
    [add: some text]
    [del: some text]
    [edit: some text -> some replacement for text]
    [name: some text -> some replacement for text]

For example, the text

.. code-block:: text

    First consider a quantity $Q$. Without loss of generality, we assume
    $Q>0$. There are three, fundamental, basic property of $Q$.

can be edited as

.. code-block:: text

    First[add: ,] consider [edit: a quantity -> the flux]
    [del: $Q$. Without loss of generality,
    we assume] $Q>0$. There are three[del: ,] fundamental[del: , basic]
    [edit: property -> properties] of $Q$. [add: These are not
    important for the following discussion.]

which in the sphinx output format results in


..

    First, (**edit 2: add comma**) consider (**edit 3: remove** a quantity) (**insert:**)the flux (**end insert**)
    (**edit 4**: **delete** :math:`Q`. Without loss of generality,
    we assume) :math:`Q>0`. There are three (**edit 5**: delete comma) fundamental(**edit 6**: **delete** , basic)
    (**edit 7: remove** property) (**insert:**)properties (**end insert**) of :math:`Q`.  (**edit 8: add**) These are not
    important for the following discussion. (**end add**)



To implement these edits, run

.. code-block:: text

    Terminal> doconce apply_edit_comments mydoc.do.txt

Verbatim/Computer Code
----------------------

Inline verbatim code is typeset within back-ticks, as in

.. code-block:: text

    Some sentence with `words in verbatim style`.

resulting in Some sentence with ``words in verbatim style``.

Multi-line blocks of verbatim text, typically computer code, is typeset
in between ``!bc xxx`` and ``!ec`` directives, which must appear on the
beginning of the line. A specification ``xxx`` indicates what verbatim
formatting style that is to be used. Typical values for ``xxx`` are
nothing, ``cod`` for a code snippet, ``pro`` for a complete program,
``sys`` for a terminal session, ``dat`` for a data file (or output from a
program),
``Xpro`` or ``Xcod`` for a program or code snipped, respectively,
in programming ``X``, where ``X`` may be ``py`` for Python,
``cy`` for Cython, ``sh`` for Bash or other Unix shells,
``f`` for Fortran, ``c`` for C, ``cpp`` for C++, ``m`` for MATLAB,
``pl`` for Perl. For output in ``latex`` one can let ``xxx`` reflect any
defined verbatim environment in the ``ptex2tex`` configuration file
(``.ptex2tex.cfg``). For ``sphinx`` output one can insert a comment

.. code-block:: text

    # sphinx code-blocks: pycod=python cod=fortran cppcod=c++ sys=console

that maps environments (``xxx``) onto valid language types for
Pygments (which is what ``sphinx`` applies to typeset computer code).

The ``xxx`` specifier has only effect for ``latex`` and
``sphinx`` output. All other formats use a fixed monospace font for all
kinds of verbatim output.

Here is an example of computer code (see the source of this document
for exact syntax):

.. code-block:: python

    from numpy import sin, cos, exp, pi
    
    def f(x, y, z, t):
        return exp(-t)*sin(pi*x)*sin(pi*y)*cos(2*pi*z)

.. When showing copy from file in !bc envir, indent a character - otherwise

.. ptex2tex is confused and starts copying...

Computer code can also be copied from a file:

.. code-block:: text

     @@@CODE doconce_program.sh
     @@@CODE doconce_program.sh  fromto: doconce clean@^doconce split_rst
     @@@CODE doconce_program.sh  from-to: doconce clean@^doconce split_rst
     @@@CODE doconce_program.sh  envir=shpro fromto: name=@

The ``@@@CODE`` identifier must appear at the very beginning of the line.
The first line copies the complete file ``doconce_program.sh``.
The second line copies from the first line matching the *regular
expression* ``doconce clean`` up to, but not including, the line
matching the *regular expression* ``^doconce split_rst``.
The third line behaves as the second, but the line matching
the first regular expression is not copied (this construction is often
used for copying text between begin-end comment pair in the file).

The copied lines from file are in this example put inside ``!bc shpro``
and ``!ec`` directives, if a complete file is copied, while the
directives become ``!bc shcod`` and ``!ec`` when a code snippet is copied
from a file. In general, for a filename extension ``.X``, the environment
becomes ``!bc Xpro`` or ``!bc Xcod`` for a complete program or snippet,
respectively. The enivorments (``Xcod`` and ``Xpro``) are only active for
``latex``, ``pdflatex``, html`, and ``sphinx`` output.  The fourth line
above specifies the code environment explicitly (``envir=shpro``) such
that it indicates a complete shell program (``shpro``) even if we copy a
part of the file (here from ``name=`` until the end of the file).
Copying a part of a file will by default lead to ``!bc shcod``, which indicates a
code snippet that normally needs more code to run properly.

The ``--code_prefix=text`` option adds a path ``text`` to the filename specified
in the ``@@@CODE`` command (URLs work). For example

.. code-block:: text

     @@@CODE src/myfile.py

and ``--code_prefix=http://some.place.net``, the file

.. code-block:: text

    http://some.place.net/src/myfile.py

will be included. If source files have a header with author, email, etc.,
one can remove this header by the option ``'--code_skip_until=# ---``.
The lines up to and including (the first) ``# ---`` will then be excluded.

Important warnings:

 * A code block must come after a plain sentence (at least for successful
   output in reStructredText), not directly after a section/paragraph heading,
   table, comment, figure, or movie.

 * Verbatim code blocks inside lists can be ugly when typeset in some
   output formats. A more robust approach is to replace the list with
   paragraphs that include headings.

LaTeX Mathematics
-----------------

DocOnce supports inline mathematics and blocks of mathematics, using
standard LaTeX syntax. The output formats ``html``, ``sphinx``, ``latex``,
pdflatex`, ``pandoc``, and ``mwiki`` work with this syntax while all other
formats will just display the raw LaTeX code.

Inline expressions are written in the standard
LaTeX way with the mathematics surrounded by dollar signs, as in
:math:`Ax=b`. To help increase readability in other formats than ``sphinx``,
``latex``, and ``pdflatex``, inline mathematics may have a more human
readable companion expression. The syntax is like

.. code-block:: text

    $\sin(\norm{\bf u})$|$sin(||u||)$

That is, the LaTeX expression appears to the left of a vertical bar (pipe
symbol) and the more readable expression appears to the right. Both
expressions are surrounded by dollar signs.

Blocks of LaTeX mathematics are written within
``!bt``
and
``!et`` (begin/end TeX) directives starting on the beginning of a line:

.. code-block:: text

    !bt
    \begin{align*}
    \nabla\cdot \pmb{u} &= 0,\\ 
    \nabla\times \pmb{u} &= 0.
    \end{align*}
    !et

This LaTeX code gets rendered as

.. math::
        \begin{align*}
        \nabla\cdot \pmb{u} &= 0,\\ 
        \nabla\times \pmb{u} &= 0.
        \end{align*}

Here is a single equation:

.. code-block:: text

    !bt
    \[ \frac{\partial\pmb{u}}{\partial t} + \pmb{u}\cdot\nabla\pmb{u} = 0.\]
    !et

which results in

.. math::
         \frac{\partial\pmb{u}}{\partial t} + \pmb{u}\cdot\nabla\pmb{u} = 0.

**LaTeX Newcommands.**
The author can define ``newcommand`` statements in files with names
``newcommands*.tex``. Such commands should only be used for mathematics
(other LaTeX constructions are only understood by LaTeX itself).
The convention is that ``newcommands_keep.tex``
contains the newcommands that are kept in the document, while
those in ``newcommands_replace.tex`` will be replaced by their full
LaTeX code. This conventions helps make readable documents in formats
without LaTeX support. For ``html``, ``sphinx``, ``latex``, ``pdflatex``,
``mwiki``, ``ipynb``, and ``pandoc``, the mathematics in newcommands is
rendered nicely anyway. If you desire ``newcommand`` outside LaTeX
mathematics, simply use a Mako variable or a Mako function (which
will be much more flexible and powerful).

.. include with mako must be in this root tree, so we need a link, see make.sh

.. _manual:latex:guide:

Writing Guidelines (Especially for LaTeX Users!)
------------------------------------------------

LaTeX writers often have their own writing habits and have preferred
LaTeX packages. DocOnce is a simpler format and
corresponds to writing in quite plain LaTeX and making the ascii text
look nice (be careful with the use of white space!). This means that
although DocOnce has borrowed a lot from LaTeX, there are a few points
LaTeX writers should pay attention to. Experience shows that these
points are so important that we list them *before* we list typical
DocOnce syntax!

Any LaTeX syntax in mathematical formulas is accepted when DocOnce
translates the text to LaTeX, but the following rules should be
followed when transalting the text to ``sphinx``, ``pandoc``,
``mwiki``, ``html``, or ``ipynb`` formats.

 * AMS LaTeX mathematics is supported, also for the ``html``, ``sphinx``,
   and ``ipynb`` formats.

 * If you want LaTeX math blocks to work with ``latex``, ``html``, ``sphinx``,
   ``markdown``, and ``ipynb``, only use
   the following equation environments: ``\[ ... \]``,
   ``equation*``, ``equation``, ``align*``, ``align``. ``alignat*``, ``alignat``.
   Other environments, such as ``split``, ``multiline``, ``gather`` are
   supported in modern MathJax in HTML and Sphinx, but may have
   rendering problems (to a larger extent than ``equation`` and ``align``).
   DocOnce performs extensions to ``sphinx``, ``ipynb``,
   and other formats such that
   labels in ``align`` and ``alignat`` environments work well.
   If you face problems with fancy LaTeX equation environments in
   web formats, try rewriting with plain ``align``, ``nonumber``, etc.

 * Do not use comments inside equations.

 * Newcommands in mathematical formulas are allowed, but not in
   the running text. Newcommands must be defined in files with names
   ``newcommands*.tex``. Use ``\newcommands`` and not ``\def``.
   Each newcommand must be defined on a single line.
   Use Mako functions if you need macros in the running text.

 * Use labels and refer to them
   for sections, figures, movies, and equations only.
   MediaWiki (``mwiki``) does not support references to equations.

 * Spaces are not allowed in labels.

 * There is just one ``ref`` command (no ``\eqref`` for equations) and references to
   equations must use parentheses. Never use the tilde `` |nbsp| `` (non-breaking
   space) character before references to figures, sections, etc., but
   tilde is allowed for references to equations.

 * Never use ``\pageref`` as pages are not a concept in web documents
   (there is only a ``ref`` command in DocOnce and it refers to labels).

 * Only figures and movies are floating elements in DocOnce, all other elements
   (code, tables, algorithms) must appear *inline* without numbers or labels
   for reference [#exception]_ (refer to inline elements by a section label).
   The reason is that floating elements are in general
   not used in web documents, but we made an exception with figures
   and movies.

 * Keep figure captions shorts as they are used as references in the
   Sphinx format. Avoid inline mathematics since Sphinx will strip it
   away in the figure reference.
   (Many writing styles encourage rich captions that
   explains everything about the figure; this work well
   only in the HTML and LaTeX formats.)

 * You cannot use ``subfigure`` to combine several image files in one
   figure, but you can combine the files into one file using
   the ``doconce combine_images`` tool. Refer to individual image files
   in the caption or text by (e.g.) "left" and "right", or
   "upper left", "lower right", etc.

 * Footnotes can be used as usual in LaTeX, but some HTML formats are not
   able to display mathematics or inline verbatim or other formatted
   code (emphasis, boldface, color) in footnotes - keep that in mind.

 * Use plain ``cite`` for references (e.g., ``\citeauthor`` has no counterpart
   in DocOnce). The bibliography must be prepared in the Publish format,
   but import from (clean) BibTeX is possible.

 * Use ``idx`` for index entries, but put the definitions between paragraphs,
   not inside them (required by Sphinx).

 * Use the ``\bm`` command (from the ``bm`` package, always included by DocOnce)
   for boldface in mathematics.

 * Make sure all ordinary text starts in column 1 on each line. Equations
   can be indented. The ``\begin{}`` and ``\end{}`` directives should start
   in column 1.

 * If you depend on various LaTeX environments for your writings, you have
   to give these up, or implement *user-defined environments* in DocOnce.
   For instance, examples are normally typeset as subsections in DocOnce,
   but can also utilize a user-defined example environment.
   Learn about the exercise support in DocOnce for typesetting
   exercises, problems, and projects.

 * Learn about the preprocessors Preprocess and Mako - these are smart
   tools for, e.g., commenting out/in large portions of text and creating
   macros.

 * Use *generalized references* when referring to companion documents
   that may later become part of this document (or migrated out of this document).

 * Follow `recommendations for DocOnce books <https://github.com/doconce/setup4book-doconce>`__ if you plan to write a book.

.. [#exception] There is an exception: by using *user-defined environments*
   within ``!bu-name`` and ``!eu-name`` directives, it is possible to
   label any type of text and refer to it. For example, one can have
   environments for examples, tables, code snippets, theorems, lemmas, etc.
   One can also use Mako functions to implement environments.


.. admonition:: Use the preprocessor to tailor output

   If you really need special LaTeX constructs in the LaTeX output
   from DocOnce, you may use use preprocessor if-tests on
   the format (typically ``#if FORMAT in ("latex", "pdflatex")``) to
   include such special LaTeX code. With an else clause you can easily
   create corresponding constructions for other formats. This way
   of using Preprocess or Mako
   allows you to use advanced LaTeX features (or HTML features for the HTML formats)
   to fine tune the resulting
   document. More tuning can be done by automatic editing of the
   output file (e.g., ``.tex`` or ``.html``) produced by DocOnce using
   your own scripts or the ``doconce replace`` and ``doconce subst`` commands.





.. admonition:: Autotranslation of LaTeX to DocOnce

   The tool ``doconce latex2doconce`` may help you translate LaTeX files
   to DocOnce syntax. However, if you use computer code in floating
   list environments, special packages for typesetting algorithms,
   example environments, ``subfigure`` in figures,
   or a lot of newcommands in the running text, there will be need for
   a lot of manual edits and adjustments.
   
   For examples, figure environments can only be translated by
   ``doconce latex2doconce`` if the label is inside the caption and
   the figure is typeset like
   
   .. code-block:: latex
   
       \begin{figure}
         \centering
         \includegraphics[width=0.55\linewidth]{figs/myfig.pdf}
         \caption{This is a figure. \labe{myfig}}
       \end{figure}
   
   If the LaTeX text is consistent with respect to the placement of the label, a
   simple script can autoedit the label inside the caption, but many
   LaTeX writers put the label at different places in different figures,
   and then it becomes more difficult to autoedit figures and translate
   them to the DocOnce ``FIGURE:`` syntax.
   
   Tables are hard to interpret and translate because headings and
   caption can be typeset in many different ways. The type of table
   that is recognized looks like
   
   .. code-block:: latex
   
       \begin{table}
       \caption{Here goes the caption.}
       \begin{tabular}{lr}
       \hline
       \multicolumn{1}{c}{$v_0$} & \multicolumn{1}{c}{$f_R(v_0)$}\\hline
       1.2 & 4.2\1.1 & 4.0\0.9 & 3.7
       \hline
       \end{tabular}
       \end{table}
   
   Recall that table captions do not make sense in DocOnce since tables
   must be inlined and explained in the surrounding text.
   
   Footnotes are also problematic for ``doconce latex2doconce`` since DocOnce
   footnotes must have the explanation outside the paragraph where the
   footnote is used. This calls for manual work. The translator from
   LaTeX to DocOnce will insert ``_PROBLEM_`` and mark footnotes. One
   solution is to avoid footnotes in the LaTeX document if fully automatic
   translation is desired.




Hyperlinks
----------

Links use either a link text or the raw URL:

.. code-block:: text

    Here is some "some link text": "http://some.net/address"
    (as in "search google": "http://google.com")
    or just the raw address: URL: "http://google.com".
    
    Links to files typeset in verbatim mode applies backtics:
    "`myfile.py`": "http://some.net/some/place/myfile.py".
    
    Mail addresses works too: send problems to
    "`hpl@simula.no`": "mailto:hpl@simula.no"
    or just "send mail": "mailto:hpl@simula.no".

Figures and Movies
------------------

Figures and movies have almost equal syntax:

.. code-block:: text

    FIGURE: [relative/path/to/figurefile, width=500 frac=0.8] Here goes the caption which must be on a single line. label{some:fig:label}
    
    MOVIE: [relative/path/to/moviefile, width=500] Here goes the caption which must be on a single line. 
    

Note three important syntax details:

 1. A mandatory comma after the figure/movie filename,

 2. no comments between ``width``, ``height``, and ``frac`` and no spaces
    around the ``=`` characters,

 3. all of the commands must appear on a single line,

 4. there must be a blank line after the command.

The figure file can be listed without extension. DocOnce will then find
the version of the file with the most appropriate extension for the chosen
output format. If not suitable version is found, DocOnce will convert
another format to the needed one.

The caption is optional. If omitted, the figure will be inlined (meaning
no use of any figure environment in HTML or LaTeX formats). The ``width``
and ``height`` parameters affect HTML formats (``html``, ``rst``, ``sphinx``),
while ``frac`` is the width of the image as a fraction of the total text
width in the ``latex`` and ``pdflatex`` formats.

The command-line options ``--fig_prefix=...`` and ``--mov_prefix=...`` can
be used to add a path (can be a URL) to all figure and movie files,
respectively.  This is useful when including DocOnce documents in
other DocOnce documents such that the text is compiled in different
directories (with different paths to the figure directory).

Movie files can either be a video or a wildcard expression for a
series of frames. In the latter case, a simple device in an HTML page
will display the individual frame files as a movie.

Combining several image files into one can be done by the

.. code-block:: text

    doconce combine_images image1 image2 ... output_image

This command applies ``montage`` or PDF-based tools to combine the images
to get the highest quality.

YouTube and Vimeo movies will be embedded in ``html`` and ``sphinx`` documents
and otherwise be represented by a link. The syntax is

.. code-block:: text

    MOVIE: [http://www.youtube.com/watch?v=_O7iUiftbKU, width=420 height=315] YouTube movie.
    
    MOVIE: [http://vimeo.com/55562330, width=500 height=278] Vimeo movie.
    

The latter results in

.. raw:: html
        
        <iframe width="500" height="278" src="https://player.vimeo.com/video/55562330" frameborder="0" allowfullscreen></iframe>
        
        <em>Vimeo movie.</em>
        

Tables
------

The table in the section :ref:`quick:sections` was written with this
syntax:

.. code-block:: text

    
    |----------------c--------|------------------c--------------------|
    |      Section type       |        Syntax                         |
    |----------------l--------|------------------l--------------------|
    | chapter                 | `========= Heading ========` (9 `=`)  |
    | section                 | `======= Heading =======`    (7 `=`)  |
    | subsection              | `===== Heading =====`        (5 `=`)  |
    | subsubsection           | `=== Heading ===`            (3 `=`)  |
    | paragraph               | `__Heading.__`               (2 `_`)  |
    |-----------------------------------------------------------------|
    

Note that

 * Each line begins and ends with a vertical bar (pipe symbol).

 * Column data are separated by a vertical bar (pipe symbol).

 * There must be a blank line before and after the table.

 * There may be horizontal rules, i.e., lines with dashes for
   indicating the heading and the end of the table, and these may
   contain characters 'c', 'l', or 'r' for how to align headings or
   columns. The first horizontal rule may indicate how to align
   headings (center, left, right), and the horizontal rule after the
   heading line may indicate how to align the data in the columns
   (center, left, right).
   One can also use ``X`` for potentially very wide text that must be
   wrapped and left-adjusted (will only affect ``latex`` and ``pdflatex`` where the
   ``tabularx`` package is then used; ``X`` means ``l`` in all other formats).

 * If the horizontal rules are without alignment information there should
   be no vertical bar (pipe symbol) between the columns. Otherwise, such
   a bar indicates a vertical bar between columns in LaTeX.

 * Many output formats are so primitive that heading and column alignment
   have no effect.

A quick way of generating tables is to place all the entries in a file
with comma as separator (a CSV file) and then run the utility
``doconce csv2table`` to create a table in the DocOnce format.

The command-line option ``--tables2csv`` (to ``doconce format``)
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.

DocOnce tables can be efficiently made directly from data in CSV files.

.. code-block:: text

    Terminal> doconce csv2table mydata.csv > mydata_table.do.txt

Now we can do ``# #include "mydata_table.do.txt"`` in the DocOnce
source file or simply copy the table in ``mydata_table.do.txt``
into the DocOnce file.

Labels and References
---------------------

The notion of labels and references (as well as bibliography and index)
is adopted
from LaTeX with a very similar syntax. As in LaTeX, a label can be
inserted anywhere, using the syntax

.. code-block:: text

    label{name}

with no backslash
preceding the label keyword. It is common practice to choose ``name``
as some hierarchical name, using a delimiter like ``:`` or ``_`` between
(e.g.) section, subsection, and topic.

A reference to the label ``name`` is written as

.. code-block:: text

    ref{name}

again with no backslash before ``ref``.

Use labels for sections and equations only, and precede the reference
by "Section" or "Chapter", or in case of an equation, surround the
reference by parenthesis.

Citations and Bibliography
--------------------------

Single citations are written as

.. code-block:: text

    cite{name}

where ``name`` is a logical name
of the reference (again, LaTeX writers must not insert a backslash).
Bibliography citations often have ``name`` on the form
``Author1_Author2_YYYY``, ``Author_YYYY``, or ``Author1_etal_YYYY``, where
``YYYY`` is the year of the publication.
Multiple citations at once is possible by separating the logical names
by comma:

.. code-block:: text

    cite{name1,name2,name3}

The bibliography is specified by a line ``BIBFILE: papers.pub``,
where ``papers.pub`` is a publication database in the
`Publish <https://github.com/doconce/publish>`__ format.
BibTeX ``.bib`` files can easily be combined to a Publish database
(which DocOnce needs to create bibliographies in other formats
than LaTeX).

Generalized References
----------------------

There is a *generalized referencing* feature in DocOnce that allows
a reference with ``ref`` to have one formulation if the label is
in the same document and another formulation if the reference is
to an item in an external document. This construction makes it easy
to work with many small, independent documents in parallel with
a book assembly of some of the small elements.
The syntax of a generalized reference is

.. code-block:: doconce

    ref[internal][cite][external]

with a specific example being

.. code-block:: doconce

    As explained in
    ref[Section ref{subsec:ex}][in cite{testdoc:12}][a "section":
    "testdoc.html#___sec2" in the document
    "A Document for Testing DocOnce": "testdoc.html" cite{testdoc:12}],
    DocOnce documents may include movies.

The output from a generalized reference is the text ``internal`` if all
references with ``ref`` in the text ``internal`` are references to labels
defined in the
present document. Otherwise, if ``cite`` is non-empty and the format is
``latex`` or ``pdflatex``, one assumes that the references in ``internal``
are to external documents declared by a comment line
``# Externaldocuments: testdoc, mydoc`` (usually after the title, authors,
and date). In this case the output text is ``internal`` followed by ``cite``,
and the
LaTeX package ``xr`` is used to handle the labels in the external
documents.  If none of the two situations above applies, the
``external`` text will be the output.

Index of Keywords
-----------------

DocOnce supports creating an index of keywords. A certain keyword
is registered for the index by a syntax like (no
backslash!)

.. code-block:: text

    index{name}

It is recommended to place any index of this type outside
running text, i.e., after (sub)section titles and in the space between
paragraphs. Index specifications placed right before paragraphs also
gives the doconce source code an indication of the content in the
forthcoming text. The index is only produced for the ``latex``,
``pdflatex``, ``rst``, and ``sphinx`` formats.

Capabilities of The Program ``doconce``
---------------------------------------

The ``doconce`` program can be used for a number of purposes besides
transforming a ``.do.txt`` file to some format. Here is the
list of capabilities:

.. code-block:: bash

    DocOnce version 1.5.4 (from /home/amarin/doconce/venv/lib/python3.6/site-packages/DocOnce-1.5.4-py3.6.egg/doconce)
    Usage: doconce command [optional arguments]
    commands: help format find subst replace remove spellcheck apply_inline_edits capitalize change_encoding clean combine_images csv2table diff expand_commands expand_mako extract_exercises find_nonascii_chars fix_bibtex4publish gitdiff grab grep guess_encoding gwiki_figsubst html2doconce html_colorbullets jupyterbook include_map insertdocstr ipynb2doconce latex2doconce latex_dislikes latex_exercise_toc latex_footer latex_header latex_problems latin2html lightclean linkchecker list_fig_src_files list_labels makefile md2html md2latex old2new_format ptex2tex pygmentize ref_external remove_exercise_answers remove_inline_comments replace_from_file slides_beamer slides_html slides_markdown sphinx_dir sphinxfix_localURLs split_html split_rst teamod
    
    doconce format html|latex|pdflatex|rst|sphinx|plain|gwiki|mwiki|
                   cwiki|pandoc|st|epytext dofile 
    # transform doconce file to another format
    
    doconce subst [-s -m -x --restore] regex-pattern \ 
            regex-replacement file1 file2 ... 
    # substitute a phrase by another using regular expressions (in this example -s is the re.DOTALL modifier, -m is the re.MULTILINE modifier, -x is the re.VERBOSE modifier, --restore copies backup files back again)
    
    doconce replace from-text to-text file1 file2 ...                      
    # replace a phrase by another literally (exact text substitution)
    
    doconce replace_from_file file-with-from-to-replacements file1 file2 ... 
    # replace using from and to phrases from file
    
    doconce find expression                                                
    # search for a (regular) expression in all .do.txt files in the current directory tree (useful when removing compilation errors)
    
    doconce include_map mydoc.do.txt                                       
    # print an overview of how various files are included in the root doc
    
    doconce expand_mako mako_code_file funcname file1 file2 ...            
    # replace all mako function calls by the `results of the calls
    
    doconce remove_inline_comments dofile                                  
    # remove all inline comments in a doconce file
    
    doconce apply_inline_edits                                             
    # apply all edits specified through inline comments
    
    doconce sphinx_dir copyright='John Doe' title='Long title' \
            short_title="Short title" version=0.1 intersphinx \
            /path/to/mylogo.png dofile 
    # create a directory for the sphinx format (requires sphinx version >= 1.1)
    
    doconce format sphinx complete_file 
    doconce split_rst complete_file 
    doconce sphinx_dir complete_file 
    python automake_sphinx.py 
    # split a sphinx/rst file into parts according to !split commands
    
    doconce insertdocstr rootdir                                           
    # walk through a directory tree and insert doconce files as docstrings in *.p.py files
    
    doconce lightclean                                                     
    # remove all redundant files (keep source .do.txt and results: .pdf, .html, sphinx- dirs, .mwiki, .ipynb, etc.)
    
    doconce clean                                                          
    # remove all files that the doconce can regenerate
    
    doconce change_encoding utf-8 latin1 dofile                            
    # change encoding
    
    doconce guess_encoding filename                                        
    # guess the encoding in a text
    
    doconce find_nonascii_chars file1 file2 ...                            
    # find non-ascii characters in a file
    
    doconce split_html complete_file.html                                  
    # split an html file into parts according to !split commands
    
    doconce slides_html slide_type complete_file.html                      
    # create HTML slides from a (doconce) html file
    
    doconce slides_beamer complete_file.tex                                
    # create LaTeX Beamer slides from a (doconce) latex/pdflatex file
    
    doconce slides_markdown complete_file.md remark --slide_style=light    
    # create Remark slides from Markdown
    
    doconce html_colorbullets file1.html file2.html ...                    
    # replace bullets in lists by colored bullets
    
    doconce extract_exercises tmp_mako__mydoc                              
    # extract all exercises (projects and problems too)
    
    doconce grab --from[-] from-text [--to[-] to-text] file > result       
    # grab selected text from a file
    
    doconce remove --from[-] from-text [--to[-] to-text] file > result     
    # remove selected text from a file
    
    doconce grep FIGURE|MOVIE|CODE dofile                                  
    # list all figure, movie or included code files
    
    doconce spellcheck [-d .mydict.txt] *.do.txt                           
    # run spellcheck on a set of files
    
    doconce ptex2tex mydoc -DMINTED pycod=minted sys=Verbatim \
            dat=\begin{quote}\begin{verbatim};\end{verbatim}\end{quote} 
    # transform ptex2tex files (.p.tex) to ordinary latex file and manage the code environments
    
    doconce md2html file.md                                                
    # make HTML file via pandoc from Markdown (.md) file
    
    doconce md2latex file.md                                               
    # make LaTeX file via pandoc from Markdown (.md) file
    
    doconce combine_images image1 image2 ... output_file                   
    # combine several images into one
    
    doconce latex_problems mydoc.log [overfull-hbox-limit]                 
    # report problems from a LaTeX .log file
    
    doconce list_fig_src_files *.do.txt                                    
    # list all figure files, movie files, and source code files needed
    
    doconce list_labels myfile                                             
    # list all labels in a document (for purposes of cleaning them up)
    
    doconce ref_external mydoc [pubfile]                                   
    # generate script for substituting generalized references
    
    doconce linkchecker *.html                                             
    # check all links in HTML files
    
    doconce capitalize [-d .mydict.txt] *.do.txt                           
    # change headings from "This is a Heading" to "This is a heading"
    
    doconce latex2doconce latexfile                                        
    # translate a latex document to doconce (requires usually manual fixing)
    
    doconce latex_dislikes latexfile                                       
    # check if there are problems with translating latex to doconce
    
    doconce ipynb2doconce notebookfile                                     
    # translate an IPython/Jupyter notebook to doconce
    
    doconce pygmentize myfile [pygments-style]                             
    # typeset a doconce document with pygments (for pretty print of doconce itself)
    
    doconce makefile docname doconcefile [html sphinx pdflatex ...]        
    # generate a make.py script for translating a doconce file to various formats
    
    doconce diff file1.do.txt file2.do.txt [diffprog]                      
    # find differences between two files (diffprog can be difflib, diff, pdiff, latexdiff, kdiff3, diffuse, ...)
    
    doconce gitdiff file1 file2 file3 ...                                  
    # find differences between the last two Git versions of several files
    
    doconce csv2table somefile.csv                                         
    # convert csv file to doconce table format
    
    doconce sphinxfix_local_URLs file.rst                                  
    # edit URLs to local files and place them in _static
    
    doconce latin2html file.html                                           
    # replace latex-1 (non-ascii) characters by html codes
    
    doconce fix_bibtex4publish file1.bib file2.bib ...                     
    # fix common problems in bibtex files for publish import
    
    doconce latex_header                                                   
    # print the header (preamble) for latex file
    
    doconce latex_footer                                                   
    # print the footer for latex files
    
    doconce expand_commands file1 file2 ...                                
    # expand short cut commands to full form in files
    
    doconce latex_exercise_toc myfile                                      
    # insert a table of exercises in a latex file myfile.p.tex

Exercises
---------

DocOnce supports *Exercise*, *Problem*, *Project*, and *Example*.
These are typeset
as ordinary sections and referred to by their section labels.
Exercise, problem, project, or example sections contains certain *elements*:

  * a headline at the level of a subsection
    containing one of the words "Exercise:", "Problem:",
    "Project:", or "Example:", followed by a title (required)

  * a label (optional)

  * a solution file (optional)

  * name of file with a student solution (optional)

  * main exercise text (required)

  * a short answer (optional)

  * a full solution (optional)

  * one or more hints (optional)

  * one or more subexercises (subproblems, subprojects), which can also
    contain a text, a short answer, a full solution, name student file
    to be handed in, and one or more hints (optional)

A typical sketch of a a problem without subexercises goes as follows:

.. code-block:: text

    ===== Problem: Derive the Formula for the Area of an Ellipse =====
    label{problem:ellipsearea1}
    file=ellipse_area.pdf
    solution=ellipse_area1_sol.pdf
    
    Derive an expression for the area of an ellipse by integrating
    the area under a curve that defines half of the ellipse.
    Show each step in the mathematical derivation.
    
    !bhint
    Wikipedia has the formula for the curve.
    !ehint
    
    !bhint
    "Wolframalpha": "http://wolframalpha.com" can perhaps
    compute the integral.
    !ehint

If the exercise type (Exercise, Problem, Project, or Example)
is enclosed in braces, the type is left out of the title in the
output. For example, the if the title line above reads

.. code-block:: text

    ===== {Problem}: Derive the Formula for the Area of an Ellipse =====

the title becomes just "Derive the ...".

An exercise with subproblems, answers and full solutions has this
setup-up:

.. code-block:: text

    ===== Exercise: Determine the Distance to the Moon =====
    label{exer:moondist}
    
    Intro to this exercise. Questions are in subexercises below.
    
    !bsubex
    Subexercises are numbered a), b), etc.
    
    file=subexer_a.pdf
    
    !bans
    Short answer to subexercise a).
    !eans
    
    !bhint
    First hint to subexercise a).
    !ehint
    
    !bhint
    Second hint to subexercise a).
    !ehint
    !esubex
    
    !bsubex
    Here goes the text for subexercise b).
    
    file=subexer_b.pdf
    
    !bhint
    A hint for this subexercise.
    !ehint
    
    !bsol
    Here goes the solution of this subexercise.
    !esol
    !esubex
    
    !bremarks
    At the very end of the exercise it may be appropriate to summarize
    and give some perspectives. The text inside the `!bremarks` and `!eremarks`
    directives is always typeset at the end of the exercise.
    !eremarks
    
    !bsol
    Here goes a full solution of the whole exercise.
    !esol
    

By default, answers, solutions, and hints are typeset as paragraphs.
The command-line arguments ``--without_answers`` and ``--without_solutions``
turn off output of answers and solutions, respectively, except for examples. The command line options ``--answers_at_end`` and ``--solutions_at_end`` write all answers and solutions to exercises to a separate section at the end of the document, respectively. Combine with ``--without_answers`` and ``--without_solutions`` to remove answers and solutions from the main text.

The commands ``!anshide`` and ``!solhide`` can be used to hide from the main text answers and solutions, respectively, until the ``!ansoff`` and ``!soloff`` commands are encountered. Similarly, the ``!ansdocend`` and ``!soldocend`` commands move answers and solutions to the end of the book. 

Environments
------------

DocOnce environments start with ``!benvirname`` and end with ``!eenvirname``,
where ``envirname`` is the name of the environment. Here is a listing of
the environments:

 * ``c``: computer code (or verbatim text)

 * ``t``: math blocks with LaTeX syntax

 * ``subex``: sub-exercise

 * ``ans``: short answer to exercise or sub-exercise

 * ``sol``: full solution to exercise or sub-exercise

 * ``hint``: multiple help items in an exercise or sub-exercise

 * ``quote``: indented text

 * ``notice``, ``summary``, ``warning``, ``question``: admonition boxes with
    custom title, special icon, and (sometimes) background color

 * ``block``, ``box``: simpler boxes (``block`` may have title but never any icon)

 * ``pop``: text to gradually pop up in slide presentations

 * ``slidecell``: indication of cells in a grid layout for elements on a
   slide

In addition, the user can define new environments ``!bc-name`` as
explained in the `manual <http://doconce.github.io/doconce/doc/pub/manual/manual.html#manual:userdef:envir>`__.

Preprocessing
-------------

DocOnce documents may utilize a preprocessor, either ``preprocess`` and/or
``mako``. The former is a C-style preprocessor that allows if-tests
and including other files (but not macros with arguments).
The ``mako`` preprocessor is much more advanced - it is actually a full
programming language, very similar to Python.

The command ``doconce format`` first runs ``preprocess`` and then ``mako``.
Here is a typical example on utilizing ``preprocess`` to include another
document, "comment out" a large portion of text, and to write format-specific
constructions:

.. code-block:: doconce

    # #include "myotherdoc.do.txt"
    
    # #if FORMAT in ("latex", "pdflatex")
    \begin{table}
    \caption{Some words... label{mytab}}
    \begin{tabular}{lrr}
    \hline\noalign{\smallskip}
    \multicolumn{1}{c}{time} & \multicolumn{1}{c}{velocity} & \multicolumn{1}{c}{acceleration} \\ 
    \hline
    0.0          & 1.4186       & -5.01        \\ 
    2.0          & 1.376512     & 11.919       \\ 
    4.0          & 1.1E+1       & 14.717624    \\ 
    \hline
    \end{tabular}
    \end{table}
    # #else
      |--------------------------------|
      |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    |
      |--------------------------------|
    # #endif
    
    # #ifdef EXTRA_MATERIAL
    ....large portions of text...
    # #endif

With the ``mako`` preprocessor the if-else tests have slightly different syntax.
An `example document <http://doconce.github.com/bioinf-py/>`__ contains
some illustrations on how to utilize ``mako`` (clone the GitHub project and
examine the DocOnce source and the ``doc/src/make.sh`` script).

Resources
---------

 * Excellent "Sphinx Tutorial" by C. Reller: "http://people.ee.ethz.ch/~creller/web/tricks/reST.html"

************** File: quickref.gwiki *****************
#summary DocOnce Quick Reference

By *Hans Petter Langtangen*
==== Jan 32, 2100 ====

<wiki: toc max_depth="2" />



*WARNING: This quick reference is very incomplete!*

*Mission.* Enable writing documentation with much mathematics and
computer code *once, in one place* and include it in traditional LaTeX
books, thesis, and reports, and, without extra efforts, also make
professional looking web versions with Sphinx or HTML. Other outlets
include Google's `blogger.com`, Wikipedia/Wikibooks, IPython/Jupyter
notebooks, plus a wide variety of other formats for documents without
mathematics and code.

==== Supported Formats ====

DocOnce currently translates files to the following formats:


 * LaTeX (format `latex` or `pdflatex`)
 * HTML (format `html`)
 * Sphinx (format `sphinx`)
 * Pandoc-extended or GitHub-flavored Markdown (format `pandoc`)
 * IPython notebook (format `ipynb`)
 * Matlab notebook (format `matlabnb`)
 * MediaWiki (format `mwiki`)
 * Googlecode wiki (format `gwiki`)
 * Creoloe wiki (format `cwiki`)
 * reStructuredText (format `rst`)
 * plain (untagged) ASCII (format `plain`)
 * Epydoc (format `epydoc`)
 * StructuredText (format `st`)

For documents with much code and mathematics, the best (and most supported)
formats are `latex`, `pdflatex`, `sphinx`, and `html`; and to a slightly
less extent `mwiki` and `pandoc`. The HTML format supports blog posts on
Google and Wordpress.

*Use a text editor with monospace font!* 
Some DocOnce constructions are sensitive to whitespace,
so you *must* use a text editor with monospace font.



==== Emacs syntax support ====

The file [https://github.com/doconce/doconce/blob/master/misc/.doconce-mode.el .doconce-mode.el]
in the DocOnce source distribution gives a "DocOnce Editing Mode" in
Emacs. Store the raw version of the file in the home directory and add
`(load-file "~/.doconce-mode.el")` to the `.emacs` file.

Besides syntax highlighting of DocOnce documents, this Emacs mode
provides a lot of shortcuts for setting up many elements in a document:


 ||    _Emacs key_     ||                  _Action_                   ||
 ||  Ctrl+c f          ||  figure                                     ||
 ||  Ctrl+c v          ||  movie/video                                ||
 ||  Ctrl+c h1         ||  heading level 1 (section/h1)               ||
 ||  Ctrl+c h2         ||  heading level 2 (subsection/h2)            ||
 ||  Ctrl+c h3         ||  heading level 2 (subsection/h3)            ||
 ||  Ctrl+c hp         ||  heading for paragraph                      ||
 ||  Ctrl+c me         ||  math environment: `!bt` equation `!et`     ||
 ||  Ctrl+c ma         ||  math environment: `!bt` align `!et`        ||
 ||  Ctrl+c ce         ||  code environment: `!bc` code `!ec`         ||
 ||  Ctrl+c cf         ||  code from file: `@@@CODE`                  ||
 ||  Ctrl+c table2     ||  table with 2 columns                       ||
 ||  Ctrl+c table3     ||  table with 3 columns                       ||
 ||  Ctrl+c table4     ||  table with 4 columns                       ||
 ||  Ctrl+c exer       ||  exercise outline                           ||
 ||  Ctrl+c slide      ||  slide outline                              ||
 ||  Ctrl+c help       ||  print this table                           ||


==== Title, Authors, and Date ====

A typical example of giving a title, a set of authors, a date,
and an optional table of contents
reads

{{{
TITLE: On an Ultimate Markup Language
AUTHOR: H. P. Langtangen at Center for Biomedical Computing, Simula Research Laboratory & Dept. of Informatics, Univ. of Oslo
AUTHOR: Kaare Dump Email: dump@cyb.space.com at Segfault, Cyberspace Inc.
AUTHOR: A. Dummy Author
DATE: today
TOC: on
}}}
The entire title must appear on a single line.
The author syntax is
{{{
name Email: somename@adr.net at institution1 & institution2
}}}
where the email is optional, the "at" keyword is required if one or
more institutions are to be specified, and the `&` keyword
separates the institutions (the keyword `and` works too).
Each author specification must appear
on a single line.
When more than one author belong to the
same institution, make sure that the institution is specified in an identical
way for each author.

The date can be set as any text different from `today` if not the
current date is wanted, e.g., `Jan 32, 2100`.

The table of contents is removed by writing `TOC: off`.

==== Copyright ====

<wiki:comment> Recall to ident AUTHOR commands to avoid interpretation </wiki:comment>

Copyright for selected authors and/or institutions are easy to insert as part
of the `AUTHOR` command. The copyright syntax is

{{{
{copyright,year1-year2|license}
}}}
and can be placed after the author or after an institution, e.g.,

{{{
 AUTHOR: name Email: somename@adr.net {copyright,2006-present} at inst1
 AUTHOR: name {copyright} at inst1 {copyright}
}}}
The first line gives `name` a copyright for 2006 up to the present year,
while the second line gives copyright to `name` and the institution `inst1`
for the present year. The license can be any formulation, but there are
some convenient abbreviations for Creative Commons ("public domain")
licenses: `CC BY` for Creative Commons Attribution 4.0 license,
`CC BY-NC` for Creative Commons Attribution-NonCommercial 4.0 license.
For example,

{{{
 AUTHOR: name1 {copyright|CC BY} at institution1
 AUTHOR: name2 {copyright|CC BY} at institution2
}}}
is a very common copyright for the present year with the Attribution license.
The copyright must be identical for all authors and institutions.


==== Section Types ====


 ||   _Section type_   ||                     _Syntax_                     ||
 ||  chapter           ||  `========= Heading ========` (9 `=`)            ||
 ||  section           ||  `======= Heading =======`    (7 `=`)            ||
 ||  subsection        ||  `===== Heading =====`        (5 `=`)            ||
 ||  subsubsection     ||  `=== Heading ===`            (3 `=`)            ||
 ||  paragraph         ||  `__Heading.__`               (2 `_`)            ||
 ||  abstract          ||  `__Abstract.__` Running text...                 ||
 ||  appendix          ||  `======= Appendix: heading =======` (7 `=`)     ||
 ||  appendix          ||  `===== Appendix: heading =====` (5 `=`)         ||
 ||  exercise          ||  `===== Exercise: heading =====` (5 `=`)         ||


Note that abstracts are recognized by starting with `__Abstract.__` or
`__Summary.__` at the beginning of a line and ending with three or
more `=` signs of the next heading.

The `Exercise:` keyword can be substituted by `Problem:` or `Project:`.
A recommended convention is that an exercise is tied to the text,
a problem can stand on its own, and a project is a comprehensive
problem.

==== Inline Formatting ====

Words surrounded by `*` are emphasized: `*emphasized words*` becomes
*emphasized words*. Similarly, an underscore surrounds words that
appear in boldface: `_boldface_` becomes *boldface*. Colored words
are also possible: the text

{{{
`color{red}{two red words}`
}}}
becomes <font color="red">two red words</font>.
(But colors do not work in format gwiki).

Quotations appear inside double backticks and double single quotes:

{{{
This is a sentence with ``words to be quoted''.
}}}

A forced linebreak is specified by `<linebreak>` at the point where the
linebreak in the output is wanted.

Footnotes use a label in the text with the footnote text separate,
preferably after the paragraph where the footnote appears:

{{{
Differentiating[^diff2] this equation leads
to a new and much simpler equation.

[^diff2]: More precisely, we apply the divergence
$\nabla\cdot$ on both sides.

Here comes a new paragraph...
}}}

Non-breaking space is inserted using the tilde character as in LaTeX:

{{{
This distance corresponds to 7.5~km, which is traveled in $7.5/5$~s.
}}}

A horizontal rule for separating content vertically, like this:

-----

is typeset as four or more hyphens on a single line:

{{{
---------
}}}

The `latex`, `pdflatex`, `sphinx`, and `html` formats support em-dash,
indicated by three hyphens: `---`. Here is an example:

{{{
The em-dash is used - without spaces - as alternative to hyphen with
space around in sentences---this way, or in quotes:
*Premature optimization is the root of all evil.*--- Donald Knuth.
}}}
This text is in the gwiki rendered as

The em-dash is used - without spaces - as alternative to hyphen with
space around in sentences---this way, or in quotes:
*Premature optimization is the root of all evil.*--- Donald Knuth.

The en-dash consists of two hyphens, either with blanks on both sides - for
something in the middle of a sentence - or in number ranges like 240 - 249.
LaTeX writes are used to and fond of en-dash.

An ampersand, as in Guns & Roses or Texas A&M, is written as a
plain `&` *with space(s) on both sides*. Single upper case letters on each
side of `&`, as in `Texas A & M`, remove the spaces and result in
Texas A&M, while words on both sides of `&`, as in `Guns & Roses`,
preserve the spaces: Guns & Roses. Failing to have spaces before and
after `&` will result in wrong typesetting of the ampersand in the `html`,
`latex`, and `pdflatex` formats.

Emojis, as defined in http://www.emoji-cheat-sheet.com, can be
inserted in the text, as (e.g.) `:dizzy_face:` with blank or newline
before or after :dizzy_face: Only the `pdflatex`, `html`, and `pandoc` output
formats translate emoji specifications to images, while all other
formats leave the textual specification in the document. The
command-line option `--no_emoji` removes all emojis from the output
document.

==== Lists ====

There are three types of lists: *bullet lists*, where each item starts
with `*`, *enumeration lists*, where each item starts with `o` and gets
consecutive numbers,
and *description* lists, where each item starts with `-` followed
by a keyword and a colon.
{{{
Here is a bullet list:

 * item1
 * item2
  * subitem1 of item2
  * subitem2 of item2,
    second line of subitem2
 * item3

Note that sublists are consistently indented by one or more blanks as
shown: bullets must exactly match and continuation lines must start
right below the line above.

Here is an enumeration list:

 o item1
 o item2
   may appear on
   multiple lines
  o subitem1 of item2
  o subitem2 of item2
 o item3

And finally a description list:

 - keyword1: followed by
   some text
   over multiple
   lines
 - keyword2:
   followed by text on the next line
 - keyword3: and its description may fit on one line
}}}
The code above follows.

Here is a bullet list:


 * item1
 * item2

  * subitem1 of item2
  * subitem2 of item2


 * item3

Note that sublists are consistently indented by one or more blanks as
shown: bullets must exactly match and continuation lines must start
right below the line above.

Here is an enumeration list:


# item1
# item2   may appear on   multiple lines

 # subitem1 of item2
 # subitem2 of item2


# item3

And finally a description list:


 * keyword1:  
   followed by   some text   over multiple   lines
 * keyword2:     followed by text on the next line
 * keyword3:  
   and its description may fit on one line

*No indentation - except in lists!* 
DocOnce syntax is sensitive to whitespace.
No lines should be indented, only lines belonging to lists.
Indented lines may give strange output in some formats.




==== Comment lines ====

Lines starting with `#` are treated as comments in the document and
translated to the proper syntax for comments in the output
document. Such comment lines should not appear before LaTeX math
blocks, verbatim code blocks, or lists if the formats `rst` and
`sphinx` are desired.

Comment lines starting with `##` are not propagated to the output
document and can be used for comments that are only of interest in
the DocOnce file.

Large portions of text can be left out using Preprocess. Just place
`# #ifdef EXTRA` and `# #endif` around the text. The command line
option `-DEXTRA` will bring the text alive again.

When using the Mako preprocessor one can also place comments in
the DocOnce source file that will be removed by Mako before
DocOnce starts processing the file.


==== Inline comments ====

Inline comments meant as messages or notes, to authors during development
in particular,
are enabled by the syntax
{{{
[name: running text]
}}}
where `name` is the name or ID of an author or reader making the comment,
and `running text` is the comment. The name can contain upper and lower
case characters, digits, single quote, `+` and `-`, as well
as space. Here goes an example.

{{{
Some running text. [hpl: There must be a space after the colon,
but the running text can occupy multiple lines.]
}}}
which is rendered as





The inline comments have simple typesetting in most formats, typically
boldface name, a comment number, with everything surrounded by
parenthesis.  However, with LaTeX output and the `--latex_todonotes`
option to `doconce format`, colorful margin or inline boxes (using the
`todonotes` package) make it very easy to spot the comments.

Running
{{{
doconce format html mydoc.do.txt --skip_inline_comments
}}}
removes all inline comments from the output. This feature makes it easy
to turn on and off notes to authors during the development of the document.

All inline comments to readers can also be physically
removed from the DocOnce source by
{{{
doconce remove_inline_comments mydoc.do.txt
}}}

Inline comments can also be used to markup edits. There are add, delete, and
replacement comments for editing:

{{{
[add: ,]
[add: .]
[add: ;]
[del: ,]
[del: ,]
[del: .]
[del: ;]
[add: some text]
[del: some text]
[edit: some text -> some replacement for text]
[name: some text -> some replacement for text]
}}}

For example, the text

{{{
First consider a quantity $Q$. Without loss of generality, we assume
$Q>0$. There are three, fundamental, basic property of $Q$.
}}}
can be edited as

{{{
First[add: ,] consider [edit: a quantity -> the flux]
[del: $Q$. Without loss of generality,
we assume] $Q>0$. There are three[del: ,] fundamental[del: , basic]
[edit: property -> properties] of $Q$. [add: These are not
important for the following discussion.]
}}}
which in the gwiki output format results in





To implement these edits, run

{{{
Terminal> doconce apply_edit_comments mydoc.do.txt
}}}

==== Verbatim/Computer Code ====

Inline verbatim code is typeset within back-ticks, as in
{{{
Some sentence with `words in verbatim style`.
}}}
resulting in Some sentence with `words in verbatim style`.

Multi-line blocks of verbatim text, typically computer code, is typeset
in between `!bc xxx` and `!ec` directives, which must appear on the
beginning of the line. A specification `xxx` indicates what verbatim
formatting style that is to be used. Typical values for `xxx` are
nothing, `cod` for a code snippet, `pro` for a complete program,
`sys` for a terminal session, `dat` for a data file (or output from a
program),
`Xpro` or `Xcod` for a program or code snipped, respectively,
in programming `X`, where `X` may be `py` for Python,
`cy` for Cython, `sh` for Bash or other Unix shells,
`f` for Fortran, `c` for C, `cpp` for C++, `m` for MATLAB,
`pl` for Perl. For output in `latex` one can let `xxx` reflect any
defined verbatim environment in the `ptex2tex` configuration file
(`.ptex2tex.cfg`). For `sphinx` output one can insert a comment
{{{
# sphinx code-blocks: pycod=python cod=fortran cppcod=c++ sys=console
}}}
that maps environments (`xxx`) onto valid language types for
Pygments (which is what `sphinx` applies to typeset computer code).

The `xxx` specifier has only effect for `latex` and
`sphinx` output. All other formats use a fixed monospace font for all
kinds of verbatim output.

Here is an example of computer code (see the source of this document
for exact syntax):

{{{
from numpy import sin, cos, exp, pi

def f(x, y, z, t):
    return exp(-t)*sin(pi*x)*sin(pi*y)*cos(2*pi*z)
}}}

<wiki:comment> When showing copy from file in !bc envir, indent a character - otherwise </wiki:comment>
<wiki:comment> ptex2tex is confused and starts copying... </wiki:comment>
Computer code can also be copied from a file:
{{{
 @@@CODE doconce_program.sh
 @@@CODE doconce_program.sh  fromto: doconce clean@^doconce split_rst
 @@@CODE doconce_program.sh  from-to: doconce clean@^doconce split_rst
 @@@CODE doconce_program.sh  envir=shpro fromto: name=@
}}}
The `@@@CODE` identifier must appear at the very beginning of the line.
The first line copies the complete file `doconce_program.sh`.
The second line copies from the first line matching the *regular
expression* `doconce clean` up to, but not including, the line
matching the *regular expression* `^doconce split_rst`.
The third line behaves as the second, but the line matching
the first regular expression is not copied (this construction is often
used for copying text between begin-end comment pair in the file).

The copied lines from file are in this example put inside `!bc shpro`
and `!ec` directives, if a complete file is copied, while the
directives become `!bc shcod` and `!ec` when a code snippet is copied
from a file. In general, for a filename extension `.X`, the environment
becomes `!bc Xpro` or `!bc Xcod` for a complete program or snippet,
respectively. The enivorments (`Xcod` and `Xpro`) are only active for
`latex`, `pdflatex`, html`, and `sphinx` output.  The fourth line
above specifies the code environment explicitly (`envir=shpro`) such
that it indicates a complete shell program (`shpro`) even if we copy a
part of the file (here from `name=` until the end of the file).
Copying a part of a file will by default lead to `!bc shcod`, which indicates a
code snippet that normally needs more code to run properly.

The `--code_prefix=text` option adds a path `text` to the filename specified
in the `@@@CODE` command (URLs work). For example

{{{
 @@@CODE src/myfile.py
}}}
and `--code_prefix=http://some.place.net`, the file

{{{
http://some.place.net/src/myfile.py
}}}
will be included. If source files have a header with author, email, etc.,
one can remove this header by the option `'--code_skip_until=# ---`.
The lines up to and including (the first) `# ---` will then be excluded.

Important warnings:


 * A code block must come after a plain sentence (at least for successful   output in reStructredText), not directly after a section/paragraph heading,   table, comment, figure, or movie.
 * Verbatim code blocks inside lists can be ugly when typeset in some   output formats. A more robust approach is to replace the list with   paragraphs that include headings.

==== LaTeX Mathematics ====

DocOnce supports inline mathematics and blocks of mathematics, using
standard LaTeX syntax. The output formats `html`, `sphinx`, `latex`,
pdflatex`, `pandoc`, and `mwiki` work with this syntax while all other
formats will just display the raw LaTeX code.

Inline expressions are written in the standard
LaTeX way with the mathematics surrounded by dollar signs, as in
`Ax=b`. To help increase readability in other formats than `sphinx`,
`latex`, and `pdflatex`, inline mathematics may have a more human
readable companion expression. The syntax is like
{{{
$\sin(\norm{\bf u})$|$sin(||u||)$
}}}
That is, the LaTeX expression appears to the left of a vertical bar (pipe
symbol) and the more readable expression appears to the right. Both
expressions are surrounded by dollar signs.

Blocks of LaTeX mathematics are written within
`!bt`
and
`!et` (begin/end TeX) directives starting on the beginning of a line:

{{{
!bt
\begin{align*}
\nabla\cdot \pmb{u} &= 0,\\ 
\nabla\times \pmb{u} &= 0.
\end{align*}
!et
}}}

This LaTeX code gets rendered as

{{{
\begin{align*}
\nabla\cdot \pmb{u} &= 0,\\ 
\nabla\times \pmb{u} &= 0.
\end{align*}
}}}
Here is a single equation:

{{{
!bt
\[ \frac{\partial\pmb{u}}{\partial t} + \pmb{u}\cdot\nabla\pmb{u} = 0.\]
!et
}}}
which results in

{{{
\[ \frac{\partial\pmb{u}}{\partial t} + \pmb{u}\cdot\nabla\pmb{u} = 0.\]
}}}


*LaTeX Newcommands.*
The author can define `newcommand` statements in files with names
`newcommands*.tex`. Such commands should only be used for mathematics
(other LaTeX constructions are only understood by LaTeX itself).
The convention is that `newcommands_keep.tex`
contains the newcommands that are kept in the document, while
those in `newcommands_replace.tex` will be replaced by their full
LaTeX code. This conventions helps make readable documents in formats
without LaTeX support. For `html`, `sphinx`, `latex`, `pdflatex`,
`mwiki`, `ipynb`, and `pandoc`, the mathematics in newcommands is
rendered nicely anyway. If you desire `newcommand` outside LaTeX
mathematics, simply use a Mako variable or a Mako function (which
will be much more flexible and powerful).

<wiki:comment> include with mako must be in this root tree, so we need a link, see make.sh </wiki:comment>

==== Writing Guidelines (Especially for LaTeX Users!) ====

LaTeX writers often have their own writing habits and have preferred
LaTeX packages. DocOnce is a simpler format and
corresponds to writing in quite plain LaTeX and making the ascii text
look nice (be careful with the use of white space!). This means that
although DocOnce has borrowed a lot from LaTeX, there are a few points
LaTeX writers should pay attention to. Experience shows that these
points are so important that we list them *before* we list typical
DocOnce syntax!

Any LaTeX syntax in mathematical formulas is accepted when DocOnce
translates the text to LaTeX, but the following rules should be
followed when transalting the text to `sphinx`, `pandoc`,
`mwiki`, `html`, or `ipynb` formats.


 * AMS LaTeX mathematics is supported, also for the `html`, `sphinx`,   and `ipynb` formats.
 * If you want LaTeX math blocks to work with `latex`, `html`, `sphinx`,   `markdown`, and `ipynb`, only use   the following equation environments: `\[ ... \]`,   `equation*`, `equation`, `align*`, `align`. `alignat*`, `alignat`.   Other environments, such as `split`, `multiline`, `gather` are   supported in modern MathJax in HTML and Sphinx, but may have   rendering problems (to a larger extent than `equation` and `align`).   DocOnce performs extensions to `sphinx`, `ipynb`,   and other formats such that   labels in `align` and `alignat` environments work well.   If you face problems with fancy LaTeX equation environments in   web formats, try rewriting with plain `align`, `nonumber`, etc.
 * Do not use comments inside equations.
 * Newcommands in mathematical formulas are allowed, but not in   the running text. Newcommands must be defined in files with names   `newcommands*.tex`. Use `\newcommands` and not `\def`.   Each newcommand must be defined on a single line.   Use Mako functions if you need macros in the running text.
 * Use labels and refer to them   for sections, figures, movies, and equations only.   MediaWiki (`mwiki`) does not support references to equations.
 * Spaces are not allowed in labels.
 * There is just one `ref` command (no `\eqref` for equations) and references to   equations must use parentheses. Never use the tilde ` ` (non-breaking   space) character before references to figures, sections, etc., but   tilde is allowed for references to equations.
 * Never use `\pageref` as pages are not a concept in web documents   (there is only a `ref` command in DocOnce and it refers to labels).
 * Only figures and movies are floating elements in DocOnce, all other elements   (code, tables, algorithms) must appear *inline* without numbers or labels   for reference[^exception] (refer to inline elements by a section label).   The reason is that floating elements are in general   not used in web documents, but we made an exception with figures   and movies.
 * Keep figure captions shorts as they are used as references in the   Sphinx format. Avoid inline mathematics since Sphinx will strip it   away in the figure reference.   (Many writing styles encourage rich captions that   explains everything about the figure; this work well   only in the HTML and LaTeX formats.)
 * You cannot use `subfigure` to combine several image files in one   figure, but you can combine the files into one file using   the `doconce combine_images` tool. Refer to individual image files   in the caption or text by (e.g.) "left" and "right", or   "upper left", "lower right", etc.
 * Footnotes can be used as usual in LaTeX, but some HTML formats are not   able to display mathematics or inline verbatim or other formatted   code (emphasis, boldface, color) in footnotes - keep that in mind.
 * Use plain `cite` for references (e.g., `\citeauthor` has no counterpart   in DocOnce). The bibliography must be prepared in the Publish format,   but import from (clean) BibTeX is possible.
 * Use `idx` for index entries, but put the definitions between paragraphs,   not inside them (required by Sphinx).
 * Use the `\bm` command (from the `bm` package, always included by DocOnce)   for boldface in mathematics.
 * Make sure all ordinary text starts in column 1 on each line. Equations   can be indented. The `\begin{}` and `\end{}` directives should start   in column 1.
 * If you depend on various LaTeX environments for your writings, you have   to give these up, or implement *user-defined environments* in DocOnce.   For instance, examples are normally typeset as subsections in DocOnce,   but can also utilize a user-defined example environment.   Learn about the exercise support in DocOnce for typesetting   exercises, problems, and projects.
 * Learn about the preprocessors Preprocess and Mako - these are smart   tools for, e.g., commenting out/in large portions of text and creating   macros.
 * Use *generalized references* when referring to companion documents   that may later become part of this document (or migrated out of this document).
 * Follow [https://github.com/doconce/setup4book-doconce recommendations for DocOnce books] if you plan to write a book.

[^exception]: There is an exception: by using *user-defined environments*
within `!bu-name` and `!eu-name` directives, it is possible to
label any type of text and refer to it. For example, one can have
environments for examples, tables, code snippets, theorems, lemmas, etc.
One can also use Mako functions to implement environments.

*Use the preprocessor to tailor output.* 
If you really need special LaTeX constructs in the LaTeX output
from DocOnce, you may use use preprocessor if-tests on
the format (typically `#if FORMAT in ("latex", "pdflatex")`) to
include such special LaTeX code. With an else clause you can easily
create corresponding constructions for other formats. This way
of using Preprocess or Mako
allows you to use advanced LaTeX features (or HTML features for the HTML formats)
to fine tune the resulting
document. More tuning can be done by automatic editing of the
output file (e.g., `.tex` or `.html`) produced by DocOnce using
your own scripts or the `doconce replace` and `doconce subst` commands.



*Autotranslation of LaTeX to DocOnce?* 
The tool `doconce latex2doconce` may help you translate LaTeX files
to DocOnce syntax. However, if you use computer code in floating
list environments, special packages for typesetting algorithms,
example environments, `subfigure` in figures,
or a lot of newcommands in the running text, there will be need for
a lot of manual edits and adjustments.

For examples, figure environments can only be translated by
`doconce latex2doconce` if the label is inside the caption and
the figure is typeset like

{{{
\begin{figure}
  \centering
  \includegraphics[width=0.55\linewidth]{figs/myfig.pdf}
  \caption{This is a figure. \labe{myfig}}
\end{figure}
}}}
If the LaTeX text is consistent with respect to the placement of the label, a
simple script can autoedit the label inside the caption, but many
LaTeX writers put the label at different places in different figures,
and then it becomes more difficult to autoedit figures and translate
them to the DocOnce `FIGURE:` syntax.

Tables are hard to interpret and translate because headings and
caption can be typeset in many different ways. The type of table
that is recognized looks like

{{{
\begin{table}
\caption{Here goes the caption.}
\begin{tabular}{lr}
\hline
\multicolumn{1}{c}{$v_0$} & \multicolumn{1}{c}{$f_R(v_0)$}\\hline
1.2 & 4.2\1.1 & 4.0\0.9 & 3.7
\hline
\end{tabular}
\end{table}
}}}
Recall that table captions do not make sense in DocOnce since tables
must be inlined and explained in the surrounding text.

Footnotes are also problematic for `doconce latex2doconce` since DocOnce
footnotes must have the explanation outside the paragraph where the
footnote is used. This calls for manual work. The translator from
LaTeX to DocOnce will insert `_PROBLEM_` and mark footnotes. One
solution is to avoid footnotes in the LaTeX document if fully automatic
translation is desired.




==== Hyperlinks ====

Links use either a link text or the raw URL:

{{{
Here is some "some link text": "http://some.net/address"
(as in "search google": "http://google.com")
or just the raw address: URL: "http://google.com".

Links to files typeset in verbatim mode applies backtics:
"`myfile.py`": "http://some.net/some/place/myfile.py".

Mail addresses works too: send problems to
"`hpl@simula.no`": "mailto:hpl@simula.no"
or just "send mail": "mailto:hpl@simula.no".
}}}

==== Figures and Movies ====

Figures and movies have almost equal syntax:
{{{
FIGURE: [relative/path/to/figurefile, width=500 frac=0.8] Here goes the caption which must be on a single line. label{some:fig:label}

MOVIE: [relative/path/to/moviefile, width=500] Here goes the caption which must be on a single line. 

}}}
Note three important syntax details:


 # A mandatory comma after the figure/movie filename,
 # no comments between `width`, `height`, and `frac` and no spaces    around the `=` characters,
 # all of the commands must appear on a single line,
 # there must be a blank line after the command.

The figure file can be listed without extension. DocOnce will then find
the version of the file with the most appropriate extension for the chosen
output format. If not suitable version is found, DocOnce will convert
another format to the needed one.

The caption is optional. If omitted, the figure will be inlined (meaning
no use of any figure environment in HTML or LaTeX formats). The `width`
and `height` parameters affect HTML formats (`html`, `rst`, `sphinx`),
while `frac` is the width of the image as a fraction of the total text
width in the `latex` and `pdflatex` formats.

The command-line options `--fig_prefix=...` and `--mov_prefix=...` can
be used to add a path (can be a URL) to all figure and movie files,
respectively.  This is useful when including DocOnce documents in
other DocOnce documents such that the text is compiled in different
directories (with different paths to the figure directory).

Movie files can either be a video or a wildcard expression for a
series of frames. In the latter case, a simple device in an HTML page
will display the individual frame files as a movie.

Combining several image files into one can be done by the
{{{
doconce combine_images image1 image2 ... output_image
}}}
This command applies `montage` or PDF-based tools to combine the images
to get the highest quality.

YouTube and Vimeo movies will be embedded in `html` and `sphinx` documents
and otherwise be represented by a link. The syntax is

{{{
MOVIE: [http://www.youtube.com/watch?v=_O7iUiftbKU, width=420 height=315] YouTube movie.

MOVIE: [http://vimeo.com/55562330, width=500 height=278] Vimeo movie.

}}}
The latter results in

Vimeo movie. `http://vimeo.com/55562330`: load [movie_player1.html `movie_player1.html`] into a browser


==== Tables ====

The table in the section [#Section_Types] was written with this
syntax:
{{{

|----------------c--------|------------------c--------------------|
|      Section type       |        Syntax                         |
|----------------l--------|------------------l--------------------|
| chapter                 | `========= Heading ========` (9 `=`)  |
| section                 | `======= Heading =======`    (7 `=`)  |
| subsection              | `===== Heading =====`        (5 `=`)  |
| subsubsection           | `=== Heading ===`            (3 `=`)  |
| paragraph               | `__Heading.__`               (2 `_`)  |
|-----------------------------------------------------------------|

}}}

Note that


 * Each line begins and ends with a vertical bar (pipe symbol).
 * Column data are separated by a vertical bar (pipe symbol).
 * There must be a blank line before and after the table.
 * There may be horizontal rules, i.e., lines with dashes for   indicating the heading and the end of the table, and these may   contain characters 'c', 'l', or 'r' for how to align headings or   columns. The first horizontal rule may indicate how to align   headings (center, left, right), and the horizontal rule after the   heading line may indicate how to align the data in the columns   (center, left, right).   One can also use `X` for potentially very wide text that must be   wrapped and left-adjusted (will only affect `latex` and `pdflatex` where the   `tabularx` package is then used; `X` means `l` in all other formats).
 * If the horizontal rules are without alignment information there should   be no vertical bar (pipe symbol) between the columns. Otherwise, such   a bar indicates a vertical bar between columns in LaTeX.
 * Many output formats are so primitive that heading and column alignment   have no effect.

A quick way of generating tables is to place all the entries in a file
with comma as separator (a CSV file) and then run the utility
`doconce csv2table` to create a table in the DocOnce format.

The command-line option `--tables2csv` (to `doconce format`)
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.

DocOnce tables can be efficiently made directly from data in CSV files.

{{{
Terminal> doconce csv2table mydata.csv > mydata_table.do.txt
}}}
Now we can do `# #include "mydata_table.do.txt"` in the DocOnce
source file or simply copy the table in `mydata_table.do.txt`
into the DocOnce file.

==== Labels and References ====

The notion of labels and references (as well as bibliography and index)
is adopted
from LaTeX with a very similar syntax. As in LaTeX, a label can be
inserted anywhere, using the syntax
{{{
label{name}
}}}
with no backslash
preceding the label keyword. It is common practice to choose `name`
as some hierarchical name, using a delimiter like `:` or `_` between
(e.g.) section, subsection, and topic.

A reference to the label `name` is written as
{{{
ref{name}
}}}
again with no backslash before `ref`.

Use labels for sections and equations only, and precede the reference
by "Section" or "Chapter", or in case of an equation, surround the
reference by parenthesis.


==== Citations and Bibliography ====

Single citations are written as
{{{
cite{name}
}}}
where `name` is a logical name
of the reference (again, LaTeX writers must not insert a backslash).
Bibliography citations often have `name` on the form
`Author1_Author2_YYYY`, `Author_YYYY`, or `Author1_etal_YYYY`, where
`YYYY` is the year of the publication.
Multiple citations at once is possible by separating the logical names
by comma:
{{{
cite{name1,name2,name3}
}}}

The bibliography is specified by a line `BIBFILE: papers.pub`,
where `papers.pub` is a publication database in the
[https://github.com/doconce/publish Publish] format.
BibTeX `.bib` files can easily be combined to a Publish database
(which DocOnce needs to create bibliographies in other formats
than LaTeX).

==== Generalized References ====

There is a *generalized referencing* feature in DocOnce that allows
a reference with `ref` to have one formulation if the label is
in the same document and another formulation if the reference is
to an item in an external document. This construction makes it easy
to work with many small, independent documents in parallel with
a book assembly of some of the small elements.
The syntax of a generalized reference is

{{{
ref[internal][cite][external]
}}}
with a specific example being

{{{
As explained in
ref[Section ref{subsec:ex}][in cite{testdoc:12}][a "section":
"testdoc.html#___sec2" in the document
"A Document for Testing DocOnce": "testdoc.html" cite{testdoc:12}],
DocOnce documents may include movies.
}}}
The output from a generalized reference is the text `internal` if all
references with `ref` in the text `internal` are references to labels
defined in the
present document. Otherwise, if `cite` is non-empty and the format is
`latex` or `pdflatex`, one assumes that the references in `internal`
are to external documents declared by a comment line
`# Externaldocuments: testdoc, mydoc` (usually after the title, authors,
and date). In this case the output text is `internal` followed by `cite`,
and the
LaTeX package `xr` is used to handle the labels in the external
documents.  If none of the two situations above applies, the
`external` text will be the output.

==== Index of Keywords ====

DocOnce supports creating an index of keywords. A certain keyword
is registered for the index by a syntax like (no
backslash!)
{{{
index{name}
}}}
It is recommended to place any index of this type outside
running text, i.e., after (sub)section titles and in the space between
paragraphs. Index specifications placed right before paragraphs also
gives the doconce source code an indication of the content in the
forthcoming text. The index is only produced for the `latex`,
`pdflatex`, `rst`, and `sphinx` formats.

==== Capabilities of The Program `doconce` ====

The `doconce` program can be used for a number of purposes besides
transforming a `.do.txt` file to some format. Here is the
list of capabilities:

{{{
DocOnce version 1.5.4 (from /home/amarin/doconce/venv/lib/python3.6/site-packages/DocOnce-1.5.4-py3.6.egg/doconce)
Usage: doconce command [optional arguments]
commands: help format find subst replace remove spellcheck apply_inline_edits capitalize change_encoding clean combine_images csv2table diff expand_commands expand_mako extract_exercises find_nonascii_chars fix_bibtex4publish gitdiff grab grep guess_encoding gwiki_figsubst html2doconce html_colorbullets jupyterbook include_map insertdocstr ipynb2doconce latex2doconce latex_dislikes latex_exercise_toc latex_footer latex_header latex_problems latin2html lightclean linkchecker list_fig_src_files list_labels makefile md2html md2latex old2new_format ptex2tex pygmentize ref_external remove_exercise_answers remove_inline_comments replace_from_file slides_beamer slides_html slides_markdown sphinx_dir sphinxfix_localURLs split_html split_rst teamod

doconce format html|latex|pdflatex|rst|sphinx|plain|gwiki|mwiki|
               cwiki|pandoc|st|epytext dofile 
# transform doconce file to another format

doconce subst [-s -m -x --restore] regex-pattern \ 
        regex-replacement file1 file2 ... 
# substitute a phrase by another using regular expressions (in this example -s is the re.DOTALL modifier, -m is the re.MULTILINE modifier, -x is the re.VERBOSE modifier, --restore copies backup files back again)

doconce replace from-text to-text file1 file2 ...                      
# replace a phrase by another literally (exact text substitution)

doconce replace_from_file file-with-from-to-replacements file1 file2 ... 
# replace using from and to phrases from file

doconce find expression                                                
# search for a (regular) expression in all .do.txt files in the current directory tree (useful when removing compilation errors)

doconce include_map mydoc.do.txt                                       
# print an overview of how various files are included in the root doc

doconce expand_mako mako_code_file funcname file1 file2 ...            
# replace all mako function calls by the `results of the calls

doconce remove_inline_comments dofile                                  
# remove all inline comments in a doconce file

doconce apply_inline_edits                                             
# apply all edits specified through inline comments

doconce sphinx_dir copyright='John Doe' title='Long title' \
        short_title="Short title" version=0.1 intersphinx \
        /path/to/mylogo.png dofile 
# create a directory for the sphinx format (requires sphinx version >= 1.1)

doconce format sphinx complete_file 
doconce split_rst complete_file 
doconce sphinx_dir complete_file 
python automake_sphinx.py 
# split a sphinx/rst file into parts according to !split commands

doconce insertdocstr rootdir                                           
# walk through a directory tree and insert doconce files as docstrings in *.p.py files

doconce lightclean                                                     
# remove all redundant files (keep source .do.txt and results: .pdf, .html, sphinx- dirs, .mwiki, .ipynb, etc.)

doconce clean                                                          
# remove all files that the doconce can regenerate

doconce change_encoding utf-8 latin1 dofile                            
# change encoding

doconce guess_encoding filename                                        
# guess the encoding in a text

doconce find_nonascii_chars file1 file2 ...                            
# find non-ascii characters in a file

doconce split_html complete_file.html                                  
# split an html file into parts according to !split commands

doconce slides_html slide_type complete_file.html                      
# create HTML slides from a (doconce) html file

doconce slides_beamer complete_file.tex                                
# create LaTeX Beamer slides from a (doconce) latex/pdflatex file

doconce slides_markdown complete_file.md remark --slide_style=light    
# create Remark slides from Markdown

doconce html_colorbullets file1.html file2.html ...                    
# replace bullets in lists by colored bullets

doconce extract_exercises tmp_mako__mydoc                              
# extract all exercises (projects and problems too)

doconce grab --from[-] from-text [--to[-] to-text] file > result       
# grab selected text from a file

doconce remove --from[-] from-text [--to[-] to-text] file > result     
# remove selected text from a file

doconce grep FIGURE|MOVIE|CODE dofile                                  
# list all figure, movie or included code files

doconce spellcheck [-d .mydict.txt] *.do.txt                           
# run spellcheck on a set of files

doconce ptex2tex mydoc -DMINTED pycod=minted sys=Verbatim \
        dat=\begin{quote}\begin{verbatim};\end{verbatim}\end{quote} 
# transform ptex2tex files (.p.tex) to ordinary latex file and manage the code environments

doconce md2html file.md                                                
# make HTML file via pandoc from Markdown (.md) file

doconce md2latex file.md                                               
# make LaTeX file via pandoc from Markdown (.md) file

doconce combine_images image1 image2 ... output_file                   
# combine several images into one

doconce latex_problems mydoc.log [overfull-hbox-limit]                 
# report problems from a LaTeX .log file

doconce list_fig_src_files *.do.txt                                    
# list all figure files, movie files, and source code files needed

doconce list_labels myfile                                             
# list all labels in a document (for purposes of cleaning them up)

doconce ref_external mydoc [pubfile]                                   
# generate script for substituting generalized references

doconce linkchecker *.html                                             
# check all links in HTML files

doconce capitalize [-d .mydict.txt] *.do.txt                           
# change headings from "This is a Heading" to "This is a heading"

doconce latex2doconce latexfile                                        
# translate a latex document to doconce (requires usually manual fixing)

doconce latex_dislikes latexfile                                       
# check if there are problems with translating latex to doconce

doconce ipynb2doconce notebookfile                                     
# translate an IPython/Jupyter notebook to doconce

doconce pygmentize myfile [pygments-style]                             
# typeset a doconce document with pygments (for pretty print of doconce itself)

doconce makefile docname doconcefile [html sphinx pdflatex ...]        
# generate a make.py script for translating a doconce file to various formats

doconce diff file1.do.txt file2.do.txt [diffprog]                      
# find differences between two files (diffprog can be difflib, diff, pdiff, latexdiff, kdiff3, diffuse, ...)

doconce gitdiff file1 file2 file3 ...                                  
# find differences between the last two Git versions of several files

doconce csv2table somefile.csv                                         
# convert csv file to doconce table format

doconce sphinxfix_local_URLs file.rst                                  
# edit URLs to local files and place them in _static

doconce latin2html file.html                                           
# replace latex-1 (non-ascii) characters by html codes

doconce fix_bibtex4publish file1.bib file2.bib ...                     
# fix common problems in bibtex files for publish import

doconce latex_header                                                   
# print the header (preamble) for latex file

doconce latex_footer                                                   
# print the footer for latex files

doconce expand_commands file1 file2 ...                                
# expand short cut commands to full form in files

doconce latex_exercise_toc myfile                                      
# insert a table of exercises in a latex file myfile.p.tex
}}}

==== Exercises ====

DocOnce supports *Exercise*, *Problem*, *Project*, and *Example*.
These are typeset
as ordinary sections and referred to by their section labels.
Exercise, problem, project, or example sections contains certain *elements*:


  * a headline at the level of a subsection    containing one of the words "Exercise:", "Problem:",    "Project:", or "Example:", followed by a title (required)
  * a label (optional)
  * a solution file (optional)
  * name of file with a student solution (optional)
  * main exercise text (required)
  * a short answer (optional)
  * a full solution (optional)
  * one or more hints (optional)
  * one or more subexercises (subproblems, subprojects), which can also    contain a text, a short answer, a full solution, name student file    to be handed in, and one or more hints (optional)

A typical sketch of a a problem without subexercises goes as follows:
{{{
===== Problem: Derive the Formula for the Area of an Ellipse =====
label{problem:ellipsearea1}
file=ellipse_area.pdf
solution=ellipse_area1_sol.pdf

Derive an expression for the area of an ellipse by integrating
the area under a curve that defines half of the ellipse.
Show each step in the mathematical derivation.

!bhint
Wikipedia has the formula for the curve.
!ehint

!bhint
"Wolframalpha": "http://wolframalpha.com" can perhaps
compute the integral.
!ehint
}}}
If the exercise type (Exercise, Problem, Project, or Example)
is enclosed in braces, the type is left out of the title in the
output. For example, the if the title line above reads

{{{
===== {Problem}: Derive the Formula for the Area of an Ellipse =====
}}}
the title becomes just "Derive the ...".

An exercise with subproblems, answers and full solutions has this
setup-up:

{{{
===== Exercise: Determine the Distance to the Moon =====
label{exer:moondist}

Intro to this exercise. Questions are in subexercises below.

!bsubex
Subexercises are numbered a), b), etc.

file=subexer_a.pdf

!bans
Short answer to subexercise a).
!eans

!bhint
First hint to subexercise a).
!ehint

!bhint
Second hint to subexercise a).
!ehint
!esubex

!bsubex
Here goes the text for subexercise b).

file=subexer_b.pdf

!bhint
A hint for this subexercise.
!ehint

!bsol
Here goes the solution of this subexercise.
!esol
!esubex

!bremarks
At the very end of the exercise it may be appropriate to summarize
and give some perspectives. The text inside the `!bremarks` and `!eremarks`
directives is always typeset at the end of the exercise.
!eremarks

!bsol
Here goes a full solution of the whole exercise.
!esol

}}}
By default, answers, solutions, and hints are typeset as paragraphs.
The command-line arguments `--without_answers` and `--without_solutions`
turn off output of answers and solutions, respectively, except for examples. The command line options `--answers_at_end` and `--solutions_at_end` write all answers and solutions to exercises to a separate section at the end of the document, respectively. Combine with `--without_answers` and `--without_solutions` to remove answers and solutions from the main text.

The commands `!anshide` and `!solhide` can be used to hide from the main text answers and solutions, respectively, until the `!ansoff` and `!soloff` commands are encountered. Similarly, the `!ansdocend` and `!soldocend` commands move answers and solutions to the end of the book. 

==== Environments ====

DocOnce environments start with `!benvirname` and end with `!eenvirname`,
where `envirname` is the name of the environment. Here is a listing of
the environments:


 * `c`: computer code (or verbatim text)
 * `t`: math blocks with LaTeX syntax
 * `subex`: sub-exercise
 * `ans`: short answer to exercise or sub-exercise
 * `sol`: full solution to exercise or sub-exercise
 * `hint`: multiple help items in an exercise or sub-exercise
 * `quote`: indented text
 * `notice`, `summary`, `warning`, `question`: admonition boxes with    custom title, special icon, and (sometimes) background color
 * `block`, `box`: simpler boxes (`block` may have title but never any icon)
 * `pop`: text to gradually pop up in slide presentations
 * `slidecell`: indication of cells in a grid layout for elements on a   slide

In addition, the user can define new environments `!bc-name` as
explained in the [http://doconce.github.io/doconce/doc/pub/manual/manual.html#manual:userdef:envir manual].

==== Preprocessing ====

DocOnce documents may utilize a preprocessor, either `preprocess` and/or
`mako`. The former is a C-style preprocessor that allows if-tests
and including other files (but not macros with arguments).
The `mako` preprocessor is much more advanced - it is actually a full
programming language, very similar to Python.

The command `doconce format` first runs `preprocess` and then `mako`.
Here is a typical example on utilizing `preprocess` to include another
document, "comment out" a large portion of text, and to write format-specific
constructions:

{{{
# #include "myotherdoc.do.txt"

# #if FORMAT in ("latex", "pdflatex")
\begin{table}
\caption{Some words... label{mytab}}
\begin{tabular}{lrr}
\hline\noalign{\smallskip}
\multicolumn{1}{c}{time} & \multicolumn{1}{c}{velocity} & \multicolumn{1}{c}{acceleration} \\ 
\hline
0.0          & 1.4186       & -5.01        \\ 
2.0          & 1.376512     & 11.919       \\ 
4.0          & 1.1E+1       & 14.717624    \\ 
\hline
\end{tabular}
\end{table}
# #else
  |--------------------------------|
  |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    |
  |--------------------------------|
# #endif

# #ifdef EXTRA_MATERIAL
....large portions of text...
# #endif
}}}

With the `mako` preprocessor the if-else tests have slightly different syntax.
An [http://doconce.github.com/bioinf-py/ example document] contains
some illustrations on how to utilize `mako` (clone the GitHub project and
examine the DocOnce source and the `doc/src/make.sh` script).

==== Resources ====

 * Excellent "Sphinx Tutorial" by C. Reller: "http://people.ee.ethz.ch/~creller/web/tricks/reST.html"



************** File: quickref.mwiki *****************
#TITLE (actually governed by the filename): DocOnce Quick Reference

By '''Hans Petter Langtangen'''
==== Jan 32, 2100 ====

__TOC__



'''WARNING: This quick reference is very incomplete!'''

''Mission.''
Enable writing documentation with much mathematics and
computer code ''once, in one place'' and include it in traditional LaTeX
books, thesis, and reports, and, without extra efforts, also make
professional looking web versions with Sphinx or HTML. Other outlets
include Google's <code>blogger.com</code>, Wikipedia/Wikibooks, IPython/Jupyter
notebooks, plus a wide variety of other formats for documents without
mathematics and code.

==== Supported Formats ====

DocOnce currently translates files to the following formats:


<ul>
 <li> LaTeX (format <code>latex</code> or <code>pdflatex</code>)
 <li> HTML (format <code>html</code>)
 <li> Sphinx (format <code>sphinx</code>)
 <li> Pandoc-extended or GitHub-flavored Markdown (format <code>pandoc</code>)
 <li> IPython notebook (format <code>ipynb</code>)
 <li> Matlab notebook (format <code>matlabnb</code>)
 <li> MediaWiki (format <code>mwiki</code>)
 <li> Googlecode wiki (format <code>gwiki</code>)
 <li> Creoloe wiki (format <code>cwiki</code>)
 <li> reStructuredText (format <code>rst</code>)
 <li> plain (untagged) ASCII (format <code>plain</code>)
 <li> Epydoc (format <code>epydoc</code>)
 <li> StructuredText (format <code>st</code>)
</ul>

For documents with much code and mathematics, the best (and most supported)
formats are <code>latex</code>, <code>pdflatex</code>, <code>sphinx</code>, and <code>html</code>; and to a slightly
less extent <code>mwiki</code> and <code>pandoc</code>. The HTML format supports blog posts on
Google and Wordpress.


{{mbox
| type = warning
| textstyle = font-size: 90%;
| text = '''Use a text editor with monospace font!''' Some DocOnce constructions are sensitive to whitespace,
so you ''must'' use a text editor with monospace font.
}}



==== Emacs syntax support ====

The file [https://github.com/doconce/doconce/blob/master/misc/.doconce-mode.el .doconce-mode.el]
in the DocOnce source distribution gives a "DocOnce Editing Mode" in
Emacs. Store the raw version of the file in the home directory and add
<code>(load-file "~/.doconce-mode.el")</code> to the <code>.emacs</code> file.

Besides syntax highlighting of DocOnce documents, this Emacs mode
provides a lot of shortcuts for setting up many elements in a document:

<table border="1">
<thead>
<tr><th align="center">  Emacs key  </th> <th align="center">                           Action                           </th> </tr>
</thead>
<tbody>
<tr><td align="left">   Ctrl+c f         </td> <td align="left">   figure                                                          </td> </tr>
<tr><td align="left">   Ctrl+c v         </td> <td align="left">   movie/video                                                     </td> </tr>
<tr><td align="left">   Ctrl+c h1        </td> <td align="left">   heading level 1 (section/h1)                                    </td> </tr>
<tr><td align="left">   Ctrl+c h2        </td> <td align="left">   heading level 2 (subsection/h2)                                 </td> </tr>
<tr><td align="left">   Ctrl+c h3        </td> <td align="left">   heading level 2 (subsection/h3)                                 </td> </tr>
<tr><td align="left">   Ctrl+c hp        </td> <td align="left">   heading for paragraph                                           </td> </tr>
<tr><td align="left">   Ctrl+c me        </td> <td align="left">   math environment: <code>!bt</code> equation <code>!et</code>    </td> </tr>
<tr><td align="left">   Ctrl+c ma        </td> <td align="left">   math environment: <code>!bt</code> align <code>!et</code>       </td> </tr>
<tr><td align="left">   Ctrl+c ce        </td> <td align="left">   code environment: <code>!bc</code> code <code>!ec</code>        </td> </tr>
<tr><td align="left">   Ctrl+c cf        </td> <td align="left">   code from file: <code>@@@CODE</code>                            </td> </tr>
<tr><td align="left">   Ctrl+c table2    </td> <td align="left">   table with 2 columns                                            </td> </tr>
<tr><td align="left">   Ctrl+c table3    </td> <td align="left">   table with 3 columns                                            </td> </tr>
<tr><td align="left">   Ctrl+c table4    </td> <td align="left">   table with 4 columns                                            </td> </tr>
<tr><td align="left">   Ctrl+c exer      </td> <td align="left">   exercise outline                                                </td> </tr>
<tr><td align="left">   Ctrl+c slide     </td> <td align="left">   slide outline                                                   </td> </tr>
<tr><td align="left">   Ctrl+c help      </td> <td align="left">   print this table                                                </td> </tr>
</tbody>
</table>
==== Title, Authors, and Date ====

A typical example of giving a title, a set of authors, a date,
and an optional table of contents
reads

<syntaxhighlight lang="text">
TITLE: On an Ultimate Markup Language
AUTHOR: H. P. Langtangen at Center for Biomedical Computing, Simula Research Laboratory & Dept. of Informatics, Univ. of Oslo
AUTHOR: Kaare Dump Email: dump@cyb.space.com at Segfault, Cyberspace Inc.
AUTHOR: A. Dummy Author
DATE: today
TOC: on
</syntaxhighlight>
The entire title must appear on a single line.
The author syntax is
<syntaxhighlight lang="text">
name Email: somename@adr.net at institution1 & institution2
</syntaxhighlight>
where the email is optional, the "at" keyword is required if one or
more institutions are to be specified, and the <code>&</code> keyword
separates the institutions (the keyword <code>and</code> works too).
Each author specification must appear
on a single line.
When more than one author belong to the
same institution, make sure that the institution is specified in an identical
way for each author.

The date can be set as any text different from <code>today</code> if not the
current date is wanted, e.g., <code>Jan 32, 2100</code>.

The table of contents is removed by writing <code>TOC: off</code>.

==== Copyright ====

<!-- Recall to ident AUTHOR commands to avoid interpretation -->

Copyright for selected authors and/or institutions are easy to insert as part
of the <code>AUTHOR</code> command. The copyright syntax is

<syntaxhighlight lang="text">
{copyright,year1-year2|license}
</syntaxhighlight>
and can be placed after the author or after an institution, e.g.,

<syntaxhighlight lang="text">
 AUTHOR: name Email: somename@adr.net {copyright,2006-present} at inst1
 AUTHOR: name {copyright} at inst1 {copyright}
</syntaxhighlight>
The first line gives <code>name</code> a copyright for 2006 up to the present year,
while the second line gives copyright to <code>name</code> and the institution <code>inst1</code>
for the present year. The license can be any formulation, but there are
some convenient abbreviations for Creative Commons ("public domain")
licenses: <code>CC BY</code> for Creative Commons Attribution 4.0 license,
<code>CC BY-NC</code> for Creative Commons Attribution-NonCommercial 4.0 license.
For example,

<syntaxhighlight lang="text">
 AUTHOR: name1 {copyright|CC BY} at institution1
 AUTHOR: name2 {copyright|CC BY} at institution2
</syntaxhighlight>
is a very common copyright for the present year with the Attribution license.
The copyright must be identical for all authors and institutions.


==== Section Types ====

<table border="1">
<thead>
<tr><th align="center"> Section type</th> <th align="center">                              Syntax                             </th> </tr>
</thead>
<tbody>
<tr><td align="left">   chapter          </td> <td align="left">   <code>========= Heading ========</code> (9 <code>=</code>)           </td> </tr>
<tr><td align="left">   section          </td> <td align="left">   <code>======= Heading =======</code>    (7 <code>=</code>)           </td> </tr>
<tr><td align="left">   subsection       </td> <td align="left">   <code>===== Heading =====</code>        (5 <code>=</code>)           </td> </tr>
<tr><td align="left">   subsubsection    </td> <td align="left">   <code>=== Heading ===</code>            (3 <code>=</code>)           </td> </tr>
<tr><td align="left">   paragraph        </td> <td align="left">   <code>__Heading.__</code>               (2 <code>_</code>)           </td> </tr>
<tr><td align="left">   abstract         </td> <td align="left">   <code>__Abstract.__</code> Running text...                           </td> </tr>
<tr><td align="left">   appendix         </td> <td align="left">   <code>======= Appendix: heading =======</code> (7 <code>=</code>)    </td> </tr>
<tr><td align="left">   appendix         </td> <td align="left">   <code>===== Appendix: heading =====</code> (5 <code>=</code>)        </td> </tr>
<tr><td align="left">   exercise         </td> <td align="left">   <code>===== Exercise: heading =====</code> (5 <code>=</code>)        </td> </tr>
</tbody>
</table>
Note that abstracts are recognized by starting with <code>__Abstract.__</code> or
<code>__Summary.__</code> at the beginning of a line and ending with three or
more <code>=</code> signs of the next heading.

The <code>Exercise:</code> keyword can be substituted by <code>Problem:</code> or <code>Project:</code>.
A recommended convention is that an exercise is tied to the text,
a problem can stand on its own, and a project is a comprehensive
problem.

==== Inline Formatting ====

Words surrounded by <code>*</code> are emphasized: <code>*emphasized words*</code> becomes
''emphasized words''. Similarly, an underscore surrounds words that
appear in boldface: <code>_boldface_</code> becomes '''boldface'''. Colored words
are also possible: the text

<syntaxhighlight lang="text">
`color{red}{two red words}`
</syntaxhighlight>
becomes <font color="red">two red words</font>.
(But colors do not work in format mwiki).

Quotations appear inside double backticks and double single quotes:

<syntaxhighlight lang="text">
This is a sentence with ``words to be quoted''.
</syntaxhighlight>

A forced linebreak is specified by <code><linebreak></code> at the point where the
linebreak in the output is wanted.

Footnotes use a label in the text with the footnote text separate,
preferably after the paragraph where the footnote appears:

<syntaxhighlight lang="text">
Differentiating[^diff2] this equation leads
to a new and much simpler equation.

[^diff2]: More precisely, we apply the divergence
$\nabla\cdot$ on both sides.

Here comes a new paragraph...
</syntaxhighlight>

Non-breaking space is inserted using the tilde character as in LaTeX:

<syntaxhighlight lang="text">
This distance corresponds to 7.5~km, which is traveled in $7.5/5$~s.
</syntaxhighlight>

A horizontal rule for separating content vertically, like this:

----

is typeset as four or more hyphens on a single line:

<syntaxhighlight lang="text">
---------
</syntaxhighlight>

The <code>latex</code>, <code>pdflatex</code>, <code>sphinx</code>, and <code>html</code> formats support em-dash,
indicated by three hyphens: <code>---</code>. Here is an example:

<syntaxhighlight lang="text">
The em-dash is used - without spaces - as alternative to hyphen with
space around in sentences---this way, or in quotes:
*Premature optimization is the root of all evil.*--- Donald Knuth.
</syntaxhighlight>
This text is in the mwiki rendered as

The em-dash is used - without spaces - as alternative to hyphen with
space around in sentences---this way, or in quotes:
''Premature optimization is the root of all evil.''--- Donald Knuth.

The en-dash consists of two hyphens, either with blanks on both sides - for
something in the middle of a sentence - or in number ranges like 240 - 249.
LaTeX writes are used to and fond of en-dash.

An ampersand, as in Guns & Roses or Texas A&M, is written as a
plain <code>&</code> ''with space(s) on both sides''. Single upper case letters on each
side of <code>&</code>, as in <code>Texas A & M</code>, remove the spaces and result in
Texas A&M, while words on both sides of <code>&</code>, as in <code>Guns & Roses</code>,
preserve the spaces: Guns & Roses. Failing to have spaces before and
after <code>&</code> will result in wrong typesetting of the ampersand in the <code>html</code>,
<code>latex</code>, and <code>pdflatex</code> formats.

Emojis, as defined in http://www.emoji-cheat-sheet.com, can be
inserted in the text, as (e.g.) <code>:dizzy_face:</code> with blank or newline
before or after :dizzy_face: Only the <code>pdflatex</code>, <code>html</code>, and <code>pandoc</code> output
formats translate emoji specifications to images, while all other
formats leave the textual specification in the document. The
command-line option <code>--no_emoji</code> removes all emojis from the output
document.

==== Lists ====

There are three types of lists: ''bullet lists'', where each item starts
with <code>*</code>, ''enumeration lists'', where each item starts with <code>o</code> and gets
consecutive numbers,
and ''description'' lists, where each item starts with <code>-</code> followed
by a keyword and a colon.
<syntaxhighlight lang="text">
Here is a bullet list:

 * item1
 * item2
  * subitem1 of item2
  * subitem2 of item2,
    second line of subitem2
 * item3

Note that sublists are consistently indented by one or more blanks as
shown: bullets must exactly match and continuation lines must start
right below the line above.

Here is an enumeration list:

 o item1
 o item2
   may appear on
   multiple lines
  o subitem1 of item2
  o subitem2 of item2
 o item3

And finally a description list:

 - keyword1: followed by
   some text
   over multiple
   lines
 - keyword2:
   followed by text on the next line
 - keyword3: and its description may fit on one line
</syntaxhighlight>
The code above follows.

Here is a bullet list:


<ul>
 <li> item1
 <li> item2

<ul>
  <li><li> subitem1 of item2
  <li><li> subitem2 of item2
</ul>

 <li> item3
</ul>

Note that sublists are consistently indented by one or more blanks as
shown: bullets must exactly match and continuation lines must start
right below the line above.

Here is an enumeration list:


<ol>
<li> item1
<li> item2
   may appear on
   multiple lines

<ol type="a">
 <li><li> subitem1 of item2
 <li><li> subitem2 of item2
</ol>

<li> item3
</ol>

And finally a description list:


<dl>
 <dt>keyword1:<dd> 
   followed by
   some text
   over multiple
   lines
 <dt>keyword2:<dd> 
   followed by text on the next line
 <dt>keyword3:<dd> 
   and its description may fit on one line
</dl>


{{mbox
| type = warning
| textstyle = font-size: 90%;
| text = '''No indentation - except in lists!''' DocOnce syntax is sensitive to whitespace.
No lines should be indented, only lines belonging to lists.
Indented lines may give strange output in some formats.
}}




==== Comment lines ====

Lines starting with <code>#</code> are treated as comments in the document and
translated to the proper syntax for comments in the output
document. Such comment lines should not appear before LaTeX math
blocks, verbatim code blocks, or lists if the formats <code>rst</code> and
<code>sphinx</code> are desired.

Comment lines starting with <code>##</code> are not propagated to the output
document and can be used for comments that are only of interest in
the DocOnce file.

Large portions of text can be left out using Preprocess. Just place
<code># #ifdef EXTRA</code> and <code># #endif</code> around the text. The command line
option <code>-DEXTRA</code> will bring the text alive again.

When using the Mako preprocessor one can also place comments in
the DocOnce source file that will be removed by Mako before
DocOnce starts processing the file.


==== Inline comments ====

Inline comments meant as messages or notes, to authors during development
in particular,
are enabled by the syntax
<syntaxhighlight lang="text">
[name: running text]
</syntaxhighlight>
where <code>name</code> is the name or ID of an author or reader making the comment,
and <code>running text</code> is the comment. The name can contain upper and lower
case characters, digits, single quote, <code>+</code> and <code>-</code>, as well
as space. Here goes an example.

<syntaxhighlight lang="text">
Some running text. [hpl: There must be a space after the colon,
but the running text can occupy multiple lines.]
</syntaxhighlight>
which is rendered as


{{quote box
| quote = Some running text. [hpl 1: There must be a space after the colon,
but the running text can occupy multiple lines.]
| textstyle = font-size: 90%;
}}



The inline comments have simple typesetting in most formats, typically
boldface name, a comment number, with everything surrounded by
parenthesis.  However, with LaTeX output and the <code>--latex_todonotes</code>
option to <code>doconce format</code>, colorful margin or inline boxes (using the
<code>todonotes</code> package) make it very easy to spot the comments.

Running
<syntaxhighlight lang="bash">
doconce format html mydoc.do.txt --skip_inline_comments
</syntaxhighlight>
removes all inline comments from the output. This feature makes it easy
to turn on and off notes to authors during the development of the document.

All inline comments to readers can also be physically
removed from the DocOnce source by
<syntaxhighlight lang="bash">
doconce remove_inline_comments mydoc.do.txt
</syntaxhighlight>

Inline comments can also be used to markup edits. There are add, delete, and
replacement comments for editing:

<syntaxhighlight lang="text">
[add: ,]
[add: .]
[add: ;]
[del: ,]
[del: ,]
[del: .]
[del: ;]
[add: some text]
[del: some text]
[edit: some text -> some replacement for text]
[name: some text -> some replacement for text]
</syntaxhighlight>

For example, the text

<syntaxhighlight lang="text">
First consider a quantity $Q$. Without loss of generality, we assume
$Q>0$. There are three, fundamental, basic property of $Q$.
</syntaxhighlight>
can be edited as

<syntaxhighlight lang="text">
First[add: ,] consider [edit: a quantity -> the flux]
[del: $Q$. Without loss of generality,
we assume] $Q>0$. There are three[del: ,] fundamental[del: , basic]
[edit: property -> properties] of $Q$. [add: These are not
important for the following discussion.]
</syntaxhighlight>
which in the mwiki output format results in


{{quote box
| quote = First[add 2: ,] consider [edit 3: a quantity -> the flux]
[del 4: <math>Q</math>. Without loss of generality,
we assume] <math>Q>0</math>. There are three[del 5: ,] fundamental[del 6: , basic]
[edit 7: property -> properties] of <math>Q</math>. [add 8: These are not
important for the following discussion.]
| textstyle = font-size: 90%;
}}



To implement these edits, run

<syntaxhighlight lang="bash">
Terminal> doconce apply_edit_comments mydoc.do.txt
</syntaxhighlight>

==== Verbatim/Computer Code ====

Inline verbatim code is typeset within back-ticks, as in
<syntaxhighlight lang="text">
Some sentence with `words in verbatim style`.
</syntaxhighlight>
resulting in Some sentence with <code>words in verbatim style</code>.

Multi-line blocks of verbatim text, typically computer code, is typeset
in between <code>!bc xxx</code> and <code>!ec</code> directives, which must appear on the
beginning of the line. A specification <code>xxx</code> indicates what verbatim
formatting style that is to be used. Typical values for <code>xxx</code> are
nothing, <code>cod</code> for a code snippet, <code>pro</code> for a complete program,
<code>sys</code> for a terminal session, <code>dat</code> for a data file (or output from a
program),
<code>Xpro</code> or <code>Xcod</code> for a program or code snipped, respectively,
in programming <code>X</code>, where <code>X</code> may be <code>py</code> for Python,
<code>cy</code> for Cython, <code>sh</code> for Bash or other Unix shells,
<code>f</code> for Fortran, <code>c</code> for C, <code>cpp</code> for C++, <code>m</code> for MATLAB,
<code>pl</code> for Perl. For output in <code>latex</code> one can let <code>xxx</code> reflect any
defined verbatim environment in the <code>ptex2tex</code> configuration file
(<code>.ptex2tex.cfg</code>). For <code>sphinx</code> output one can insert a comment
<syntaxhighlight lang="text">
# sphinx code-blocks: pycod=python cod=fortran cppcod=c++ sys=console
</syntaxhighlight>
that maps environments (<code>xxx</code>) onto valid language types for
Pygments (which is what <code>sphinx</code> applies to typeset computer code).

The <code>xxx</code> specifier has only effect for <code>latex</code> and
<code>sphinx</code> output. All other formats use a fixed monospace font for all
kinds of verbatim output.

Here is an example of computer code (see the source of this document
for exact syntax):

<syntaxhighlight lang="python">
from numpy import sin, cos, exp, pi

def f(x, y, z, t):
    return exp(-t)*sin(pi*x)*sin(pi*y)*cos(2*pi*z)
</syntaxhighlight>

<!-- When showing copy from file in !bc envir, indent a character - otherwise -->
<!-- ptex2tex is confused and starts copying... -->
Computer code can also be copied from a file:
<syntaxhighlight lang="text">
 @@@CODE doconce_program.sh
 @@@CODE doconce_program.sh  fromto: doconce clean@^doconce split_rst
 @@@CODE doconce_program.sh  from-to: doconce clean@^doconce split_rst
 @@@CODE doconce_program.sh  envir=shpro fromto: name=@
</syntaxhighlight>
The <code>@@@CODE</code> identifier must appear at the very beginning of the line.
The first line copies the complete file <code>doconce_program.sh</code>.
The second line copies from the first line matching the ''regular
expression'' <code>doconce clean</code> up to, but not including, the line
matching the ''regular expression'' <code>^doconce split_rst</code>.
The third line behaves as the second, but the line matching
the first regular expression is not copied (this construction is often
used for copying text between begin-end comment pair in the file).

The copied lines from file are in this example put inside <code>!bc shpro</code>
and <code>!ec</code> directives, if a complete file is copied, while the
directives become <code>!bc shcod</code> and <code>!ec</code> when a code snippet is copied
from a file. In general, for a filename extension <code>.X</code>, the environment
becomes <code>!bc Xpro</code> or <code>!bc Xcod</code> for a complete program or snippet,
respectively. The enivorments (<code>Xcod</code> and <code>Xpro</code>) are only active for
<code>latex</code>, <code>pdflatex</code>, html`, and <code>sphinx</code> output.  The fourth line
above specifies the code environment explicitly (<code>envir=shpro</code>) such
that it indicates a complete shell program (<code>shpro</code>) even if we copy a
part of the file (here from <code>name=</code> until the end of the file).
Copying a part of a file will by default lead to <code>!bc shcod</code>, which indicates a
code snippet that normally needs more code to run properly.

The <code>--code_prefix=text</code> option adds a path <code>text</code> to the filename specified
in the <code>@@@CODE</code> command (URLs work). For example

<syntaxhighlight lang="text">
 @@@CODE src/myfile.py
</syntaxhighlight>
and <code>--code_prefix=http://some.place.net</code>, the file

<syntaxhighlight lang="text">
http://some.place.net/src/myfile.py
</syntaxhighlight>
will be included. If source files have a header with author, email, etc.,
one can remove this header by the option <code>'--code_skip_until=# ---</code>.
The lines up to and including (the first) <code># ---</code> will then be excluded.

Important warnings:


<ul>
 <li> A code block must come after a plain sentence (at least for successful
   output in reStructredText), not directly after a section/paragraph heading,
   table, comment, figure, or movie.
 <li> Verbatim code blocks inside lists can be ugly when typeset in some
   output formats. A more robust approach is to replace the list with
   paragraphs that include headings.
</ul>

==== LaTeX Mathematics ====

DocOnce supports inline mathematics and blocks of mathematics, using
standard LaTeX syntax. The output formats <code>html</code>, <code>sphinx</code>, <code>latex</code>,
pdflatex`, <code>pandoc</code>, and <code>mwiki</code> work with this syntax while all other
formats will just display the raw LaTeX code.

Inline expressions are written in the standard
LaTeX way with the mathematics surrounded by dollar signs, as in
<math>Ax=b</math>. To help increase readability in other formats than <code>sphinx</code>,
<code>latex</code>, and <code>pdflatex</code>, inline mathematics may have a more human
readable companion expression. The syntax is like
<syntaxhighlight lang="text">
$\sin(\norm{\bf u})$|$sin(||u||)$
</syntaxhighlight>
That is, the LaTeX expression appears to the left of a vertical bar (pipe
symbol) and the more readable expression appears to the right. Both
expressions are surrounded by dollar signs.

Blocks of LaTeX mathematics are written within
<code>!bt</code>
and
<code>!et</code> (begin/end TeX) directives starting on the beginning of a line:

<syntaxhighlight lang="text">
!bt
\begin{align*}
\nabla\cdot \pmb{u} &= 0,\\ 
\nabla\times \pmb{u} &= 0.
\end{align*}
!et
</syntaxhighlight>

This LaTeX code gets rendered as

:<math>
\begin{align*}
\nabla\cdot \pmb{u} &= 0,\\ 
\nabla\times \pmb{u} &= 0.
\end{align*}
</math>
Here is a single equation:

<syntaxhighlight lang="text">
!bt
\[ \frac{\partial\pmb{u}}{\partial t} + \pmb{u}\cdot\nabla\pmb{u} = 0.\]
!et
</syntaxhighlight>
which results in

:<math>
 \frac{\partial\pmb{u}}{\partial t} + \pmb{u}\cdot\nabla\pmb{u} = 0.
</math>


''LaTeX Newcommands.''
The author can define <code>newcommand</code> statements in files with names
<code>newcommands*.tex</code>. Such commands should only be used for mathematics
(other LaTeX constructions are only understood by LaTeX itself).
The convention is that <code>newcommands_keep.tex</code>
contains the newcommands that are kept in the document, while
those in <code>newcommands_replace.tex</code> will be replaced by their full
LaTeX code. This conventions helps make readable documents in formats
without LaTeX support. For <code>html</code>, <code>sphinx</code>, <code>latex</code>, <code>pdflatex</code>,
<code>mwiki</code>, <code>ipynb</code>, and <code>pandoc</code>, the mathematics in newcommands is
rendered nicely anyway. If you desire <code>newcommand</code> outside LaTeX
mathematics, simply use a Mako variable or a Mako function (which
will be much more flexible and powerful).

<!-- include with mako must be in this root tree, so we need a link, see make.sh -->

==== Writing Guidelines (Especially for LaTeX Users!) ====

LaTeX writers often have their own writing habits and have preferred
LaTeX packages. DocOnce is a simpler format and
corresponds to writing in quite plain LaTeX and making the ascii text
look nice (be careful with the use of white space!). This means that
although DocOnce has borrowed a lot from LaTeX, there are a few points
LaTeX writers should pay attention to. Experience shows that these
points are so important that we list them ''before'' we list typical
DocOnce syntax!

Any LaTeX syntax in mathematical formulas is accepted when DocOnce
translates the text to LaTeX, but the following rules should be
followed when transalting the text to <code>sphinx</code>, <code>pandoc</code>,
<code>mwiki</code>, <code>html</code>, or <code>ipynb</code> formats.


<ul>
 <li> AMS LaTeX mathematics is supported, also for the <code>html</code>, <code>sphinx</code>,
   and <code>ipynb</code> formats.
 <li> If you want LaTeX math blocks to work with <code>latex</code>, <code>html</code>, <code>sphinx</code>,
   <code>markdown</code>, and <code>ipynb</code>, only use
   the following equation environments: <code>\[ ... \]</code>,
   <code>equation*</code>, <code>equation</code>, <code>align*</code>, <code>align</code>. <code>alignat*</code>, <code>alignat</code>.
   Other environments, such as <code>split</code>, <code>multiline</code>, <code>gather</code> are
   supported in modern MathJax in HTML and Sphinx, but may have
   rendering problems (to a larger extent than <code>equation</code> and <code>align</code>).
   DocOnce performs extensions to <code>sphinx</code>, <code>ipynb</code>,
   and other formats such that
   labels in <code>align</code> and <code>alignat</code> environments work well.
   If you face problems with fancy LaTeX equation environments in
   web formats, try rewriting with plain <code>align</code>, <code>nonumber</code>, etc.
 <li> Do not use comments inside equations.
 <li> Newcommands in mathematical formulas are allowed, but not in
   the running text. Newcommands must be defined in files with names
   <code>newcommands*.tex</code>. Use <code>\newcommands</code> and not <code>\def</code>.
   Each newcommand must be defined on a single line.
   Use Mako functions if you need macros in the running text.
 <li> Use labels and refer to them
   for sections, figures, movies, and equations only.
   MediaWiki (<code>mwiki</code>) does not support references to equations.
 <li> Spaces are not allowed in labels.
 <li> There is just one <code>ref</code> command (no <code>\eqref</code> for equations) and references to
   equations must use parentheses. Never use the tilde <code>&nbsp;</code> (non-breaking
   space) character before references to figures, sections, etc., but
   tilde is allowed for references to equations.
 <li> Never use <code>\pageref</code> as pages are not a concept in web documents
   (there is only a <code>ref</code> command in DocOnce and it refers to labels).
 <li> Only figures and movies are floating elements in DocOnce, all other elements
   (code, tables, algorithms) must appear ''inline'' without numbers or labels
   for reference[^exception] (refer to inline elements by a section label).
   The reason is that floating elements are in general
   not used in web documents, but we made an exception with figures
   and movies.
 <li> Keep figure captions shorts as they are used as references in the
   Sphinx format. Avoid inline mathematics since Sphinx will strip it
   away in the figure reference.
   (Many writing styles encourage rich captions that
   explains everything about the figure; this work well
   only in the HTML and LaTeX formats.)
 <li> You cannot use <code>subfigure</code> to combine several image files in one
   figure, but you can combine the files into one file using
   the <code>doconce combine_images</code> tool. Refer to individual image files
   in the caption or text by (e.g.) "left" and "right", or
   "upper left", "lower right", etc.
 <li> Footnotes can be used as usual in LaTeX, but some HTML formats are not
   able to display mathematics or inline verbatim or other formatted
   code (emphasis, boldface, color) in footnotes - keep that in mind.
 <li> Use plain <code>cite</code> for references (e.g., <code>\citeauthor</code> has no counterpart
   in DocOnce). The bibliography must be prepared in the Publish format,
   but import from (clean) BibTeX is possible.
 <li> Use <code>idx</code> for index entries, but put the definitions between paragraphs,
   not inside them (required by Sphinx).
 <li> Use the <code>\bm</code> command (from the <code>bm</code> package, always included by DocOnce)
   for boldface in mathematics.
 <li> Make sure all ordinary text starts in column 1 on each line. Equations
   can be indented. The <code>\begin{}</code> and <code>\end{}</code> directives should start
   in column 1.
 <li> If you depend on various LaTeX environments for your writings, you have
   to give these up, or implement ''user-defined environments'' in DocOnce.
   For instance, examples are normally typeset as subsections in DocOnce,
   but can also utilize a user-defined example environment.
   Learn about the exercise support in DocOnce for typesetting
   exercises, problems, and projects.
 <li> Learn about the preprocessors Preprocess and Mako - these are smart
   tools for, e.g., commenting out/in large portions of text and creating
   macros.
 <li> Use ''generalized references'' when referring to companion documents
   that may later become part of this document (or migrated out of this document).
 <li> Follow [https://github.com/doconce/setup4book-doconce recommendations for DocOnce books] if you plan to write a book.
</ul>

[^exception]: There is an exception: by using ''user-defined environments''
within <code>!bu-name</code> and <code>!eu-name</code> directives, it is possible to
label any type of text and refer to it. For example, one can have
environments for examples, tables, code snippets, theorems, lemmas, etc.
One can also use Mako functions to implement environments.


{{mbox
| type = notice
| textstyle = font-size: 90%;
| text = '''Use the preprocessor to tailor output.''' If you really need special LaTeX constructs in the LaTeX output
from DocOnce, you may use use preprocessor if-tests on
the format (typically <code>#if FORMAT in ("latex", "pdflatex")</code>) to
include such special LaTeX code. With an else clause you can easily
create corresponding constructions for other formats. This way
of using Preprocess or Mako
allows you to use advanced LaTeX features (or HTML features for the HTML formats)
to fine tune the resulting
document. More tuning can be done by automatic editing of the
output file (e.g., <code>.tex</code> or <code>.html</code>) produced by DocOnce using
your own scripts or the <code>doconce replace</code> and <code>doconce subst</code> commands.
}}




{{mbox
| type = notice
| textstyle = font-size: 90%;
| text = '''Autotranslation of LaTeX to DocOnce?''' The tool <code>doconce latex2doconce</code> may help you translate LaTeX files
to DocOnce syntax. However, if you use computer code in floating
list environments, special packages for typesetting algorithms,
example environments, <code>subfigure</code> in figures,
or a lot of newcommands in the running text, there will be need for
a lot of manual edits and adjustments.

For examples, figure environments can only be translated by
<code>doconce latex2doconce</code> if the label is inside the caption and
the figure is typeset like

<syntaxhighlight lang="text">
\begin{figure}
  \centering
  \includegraphics[width=0.55\linewidth]{figs/myfig.pdf}
  \caption{This is a figure. \labe{myfig}}
\end{figure}
</syntaxhighlight>
If the LaTeX text is consistent with respect to the placement of the label, a
simple script can autoedit the label inside the caption, but many
LaTeX writers put the label at different places in different figures,
and then it becomes more difficult to autoedit figures and translate
them to the DocOnce <code>FIGURE:</code> syntax.

Tables are hard to interpret and translate because headings and
caption can be typeset in many different ways. The type of table
that is recognized looks like

<syntaxhighlight lang="text">
\begin{table}
\caption{Here goes the caption.}
\begin{tabular}{lr}
\hline
\multicolumn{1}{c}{$v_0$} & \multicolumn{1}{c}{$f_R(v_0)$}\\hline
1.2 & 4.2\1.1 & 4.0\0.9 & 3.7
\hline
\end{tabular}
\end{table}
</syntaxhighlight>
Recall that table captions do not make sense in DocOnce since tables
must be inlined and explained in the surrounding text.

Footnotes are also problematic for <code>doconce latex2doconce</code> since DocOnce
footnotes must have the explanation outside the paragraph where the
footnote is used. This calls for manual work. The translator from
LaTeX to DocOnce will insert <code>_PROBLEM_</code> and mark footnotes. One
solution is to avoid footnotes in the LaTeX document if fully automatic
translation is desired.
}}




==== Hyperlinks ====

Links use either a link text or the raw URL:

<syntaxhighlight lang="text">
Here is some "some link text": "http://some.net/address"
(as in "search google": "http://google.com")
or just the raw address: URL: "http://google.com".

Links to files typeset in verbatim mode applies backtics:
"`myfile.py`": "http://some.net/some/place/myfile.py".

Mail addresses works too: send problems to
"`hpl@simula.no`": "mailto:hpl@simula.no"
or just "send mail": "mailto:hpl@simula.no".
</syntaxhighlight>

==== Figures and Movies ====

Figures and movies have almost equal syntax:
<syntaxhighlight lang="text">
FIGURE: [relative/path/to/figurefile, width=500 frac=0.8] Here goes the caption which must be on a single line. label{some:fig:label}

MOVIE: [relative/path/to/moviefile, width=500] Here goes the caption which must be on a single line. 

</syntaxhighlight>
Note three important syntax details:


<ol>
 <li> A mandatory comma after the figure/movie filename,
 <li> no comments between <code>width</code>, <code>height</code>, and <code>frac</code> and no spaces
    around the <code>=</code> characters,
 <li> all of the commands must appear on a single line,
 <li> there must be a blank line after the command.
</ol>

The figure file can be listed without extension. DocOnce will then find
the version of the file with the most appropriate extension for the chosen
output format. If not suitable version is found, DocOnce will convert
another format to the needed one.

The caption is optional. If omitted, the figure will be inlined (meaning
no use of any figure environment in HTML or LaTeX formats). The <code>width</code>
and <code>height</code> parameters affect HTML formats (<code>html</code>, <code>rst</code>, <code>sphinx</code>),
while <code>frac</code> is the width of the image as a fraction of the total text
width in the <code>latex</code> and <code>pdflatex</code> formats.

The command-line options <code>--fig_prefix=...</code> and <code>--mov_prefix=...</code> can
be used to add a path (can be a URL) to all figure and movie files,
respectively.  This is useful when including DocOnce documents in
other DocOnce documents such that the text is compiled in different
directories (with different paths to the figure directory).

Movie files can either be a video or a wildcard expression for a
series of frames. In the latter case, a simple device in an HTML page
will display the individual frame files as a movie.

Combining several image files into one can be done by the
<syntaxhighlight lang="bash">
doconce combine_images image1 image2 ... output_image
</syntaxhighlight>
This command applies <code>montage</code> or PDF-based tools to combine the images
to get the highest quality.

YouTube and Vimeo movies will be embedded in <code>html</code> and <code>sphinx</code> documents
and otherwise be represented by a link. The syntax is

<syntaxhighlight lang="text">
MOVIE: [http://www.youtube.com/watch?v=_O7iUiftbKU, width=420 height=315] YouTube movie.

MOVIE: [http://vimeo.com/55562330, width=500 height=278] Vimeo movie.

</syntaxhighlight>
The latter results in

Vimeo movie. <code>http://vimeo.com/55562330</code>: load [movie_player1.html <code>movie_player1.html</code>] into a browser


==== Tables ====

The table in the section [#Section_Types] was written with this
syntax:
<syntaxhighlight lang="text">

|----------------c--------|------------------c--------------------|
|      Section type       |        Syntax                         |
|----------------l--------|------------------l--------------------|
| chapter                 | `========= Heading ========` (9 `=`)  |
| section                 | `======= Heading =======`    (7 `=`)  |
| subsection              | `===== Heading =====`        (5 `=`)  |
| subsubsection           | `=== Heading ===`            (3 `=`)  |
| paragraph               | `__Heading.__`               (2 `_`)  |
|-----------------------------------------------------------------|

</syntaxhighlight>

Note that


<ul>
 <li> Each line begins and ends with a vertical bar (pipe symbol).
 <li> Column data are separated by a vertical bar (pipe symbol).
 <li> There must be a blank line before and after the table.
 <li> There may be horizontal rules, i.e., lines with dashes for
   indicating the heading and the end of the table, and these may
   contain characters 'c', 'l', or 'r' for how to align headings or
   columns. The first horizontal rule may indicate how to align
   headings (center, left, right), and the horizontal rule after the
   heading line may indicate how to align the data in the columns
   (center, left, right).
   One can also use <code>X</code> for potentially very wide text that must be
   wrapped and left-adjusted (will only affect <code>latex</code> and <code>pdflatex</code> where the
   <code>tabularx</code> package is then used; <code>X</code> means <code>l</code> in all other formats).
 <li> If the horizontal rules are without alignment information there should
   be no vertical bar (pipe symbol) between the columns. Otherwise, such
   a bar indicates a vertical bar between columns in LaTeX.
 <li> Many output formats are so primitive that heading and column alignment
   have no effect.
</ul>

A quick way of generating tables is to place all the entries in a file
with comma as separator (a CSV file) and then run the utility
<code>doconce csv2table</code> to create a table in the DocOnce format.

The command-line option <code>--tables2csv</code> (to <code>doconce format</code>)
makes DocOnce dump each table to CSV format in a file <code>table_X.csv</code>,
where <code>X</code> is the table number. This feature makes it easy to
load tables into spreadsheet programs for further analysis.

DocOnce tables can be efficiently made directly from data in CSV files.

<syntaxhighlight lang="bash">
Terminal> doconce csv2table mydata.csv > mydata_table.do.txt
</syntaxhighlight>
Now we can do <code># #include "mydata_table.do.txt"</code> in the DocOnce
source file or simply copy the table in <code>mydata_table.do.txt</code>
into the DocOnce file.

==== Labels and References ====

The notion of labels and references (as well as bibliography and index)
is adopted
from LaTeX with a very similar syntax. As in LaTeX, a label can be
inserted anywhere, using the syntax
<syntaxhighlight lang="text">
label{name}
</syntaxhighlight>
with no backslash
preceding the label keyword. It is common practice to choose <code>name</code>
as some hierarchical name, using a delimiter like <code>:</code> or <code>_</code> between
(e.g.) section, subsection, and topic.

A reference to the label <code>name</code> is written as
<syntaxhighlight lang="text">
ref{name}
</syntaxhighlight>
again with no backslash before <code>ref</code>.

Use labels for sections and equations only, and precede the reference
by "Section" or "Chapter", or in case of an equation, surround the
reference by parenthesis.


==== Citations and Bibliography ====

Single citations are written as
<syntaxhighlight lang="text">
cite{name}
</syntaxhighlight>
where <code>name</code> is a logical name
of the reference (again, LaTeX writers must not insert a backslash).
Bibliography citations often have <code>name</code> on the form
<code>Author1_Author2_YYYY</code>, <code>Author_YYYY</code>, or <code>Author1_etal_YYYY</code>, where
<code>YYYY</code> is the year of the publication.
Multiple citations at once is possible by separating the logical names
by comma:
<syntaxhighlight lang="text">
cite{name1,name2,name3}
</syntaxhighlight>

The bibliography is specified by a line <code>BIBFILE: papers.pub</code>,
where <code>papers.pub</code> is a publication database in the
[https://github.com/doconce/publish Publish] format.
BibTeX <code>.bib</code> files can easily be combined to a Publish database
(which DocOnce needs to create bibliographies in other formats
than LaTeX).

==== Generalized References ====

There is a ''generalized referencing'' feature in DocOnce that allows
a reference with <code>ref</code> to have one formulation if the label is
in the same document and another formulation if the reference is
to an item in an external document. This construction makes it easy
to work with many small, independent documents in parallel with
a book assembly of some of the small elements.
The syntax of a generalized reference is

<syntaxhighlight lang="text">
ref[internal][cite][external]
</syntaxhighlight>
with a specific example being

<syntaxhighlight lang="text">
As explained in
ref[Section ref{subsec:ex}][in cite{testdoc:12}][a "section":
"testdoc.html#___sec2" in the document
"A Document for Testing DocOnce": "testdoc.html" cite{testdoc:12}],
DocOnce documents may include movies.
</syntaxhighlight>
The output from a generalized reference is the text <code>internal</code> if all
references with <code>ref</code> in the text <code>internal</code> are references to labels
defined in the
present document. Otherwise, if <code>cite</code> is non-empty and the format is
<code>latex</code> or <code>pdflatex</code>, one assumes that the references in <code>internal</code>
are to external documents declared by a comment line
<code># Externaldocuments: testdoc, mydoc</code> (usually after the title, authors,
and date). In this case the output text is <code>internal</code> followed by <code>cite</code>,
and the
LaTeX package <code>xr</code> is used to handle the labels in the external
documents.  If none of the two situations above applies, the
<code>external</code> text will be the output.

==== Index of Keywords ====

DocOnce supports creating an index of keywords. A certain keyword
is registered for the index by a syntax like (no
backslash!)
<syntaxhighlight lang="text">
index{name}
</syntaxhighlight>
It is recommended to place any index of this type outside
running text, i.e., after (sub)section titles and in the space between
paragraphs. Index specifications placed right before paragraphs also
gives the doconce source code an indication of the content in the
forthcoming text. The index is only produced for the <code>latex</code>,
<code>pdflatex</code>, <code>rst</code>, and <code>sphinx</code> formats.

==== Capabilities of The Program <code>doconce</code> ====

The <code>doconce</code> program can be used for a number of purposes besides
transforming a <code>.do.txt</code> file to some format. Here is the
list of capabilities:

<syntaxhighlight lang="bash">
DocOnce version 1.5.4 (from /home/amarin/doconce/venv/lib/python3.6/site-packages/DocOnce-1.5.4-py3.6.egg/doconce)
Usage: doconce command [optional arguments]
commands: help format find subst replace remove spellcheck apply_inline_edits capitalize change_encoding clean combine_images csv2table diff expand_commands expand_mako extract_exercises find_nonascii_chars fix_bibtex4publish gitdiff grab grep guess_encoding gwiki_figsubst html2doconce html_colorbullets jupyterbook include_map insertdocstr ipynb2doconce latex2doconce latex_dislikes latex_exercise_toc latex_footer latex_header latex_problems latin2html lightclean linkchecker list_fig_src_files list_labels makefile md2html md2latex old2new_format ptex2tex pygmentize ref_external remove_exercise_answers remove_inline_comments replace_from_file slides_beamer slides_html slides_markdown sphinx_dir sphinxfix_localURLs split_html split_rst teamod

doconce format html|latex|pdflatex|rst|sphinx|plain|gwiki|mwiki|
               cwiki|pandoc|st|epytext dofile 
# transform doconce file to another format

doconce subst [-s -m -x --restore] regex-pattern \ 
        regex-replacement file1 file2 ... 
# substitute a phrase by another using regular expressions (in this example -s is the re.DOTALL modifier, -m is the re.MULTILINE modifier, -x is the re.VERBOSE modifier, --restore copies backup files back again)

doconce replace from-text to-text file1 file2 ...                      
# replace a phrase by another literally (exact text substitution)

doconce replace_from_file file-with-from-to-replacements file1 file2 ... 
# replace using from and to phrases from file

doconce find expression                                                
# search for a (regular) expression in all .do.txt files in the current directory tree (useful when removing compilation errors)

doconce include_map mydoc.do.txt                                       
# print an overview of how various files are included in the root doc

doconce expand_mako mako_code_file funcname file1 file2 ...            
# replace all mako function calls by the `results of the calls

doconce remove_inline_comments dofile                                  
# remove all inline comments in a doconce file

doconce apply_inline_edits                                             
# apply all edits specified through inline comments

doconce sphinx_dir copyright='John Doe' title='Long title' \
        short_title="Short title" version=0.1 intersphinx \
        /path/to/mylogo.png dofile 
# create a directory for the sphinx format (requires sphinx version >= 1.1)

doconce format sphinx complete_file 
doconce split_rst complete_file 
doconce sphinx_dir complete_file 
python automake_sphinx.py 
# split a sphinx/rst file into parts according to !split commands

doconce insertdocstr rootdir                                           
# walk through a directory tree and insert doconce files as docstrings in *.p.py files

doconce lightclean                                                     
# remove all redundant files (keep source .do.txt and results: .pdf, .html, sphinx- dirs, .mwiki, .ipynb, etc.)

doconce clean                                                          
# remove all files that the doconce can regenerate

doconce change_encoding utf-8 latin1 dofile                            
# change encoding

doconce guess_encoding filename                                        
# guess the encoding in a text

doconce find_nonascii_chars file1 file2 ...                            
# find non-ascii characters in a file

doconce split_html complete_file.html                                  
# split an html file into parts according to !split commands

doconce slides_html slide_type complete_file.html                      
# create HTML slides from a (doconce) html file

doconce slides_beamer complete_file.tex                                
# create LaTeX Beamer slides from a (doconce) latex/pdflatex file

doconce slides_markdown complete_file.md remark --slide_style=light    
# create Remark slides from Markdown

doconce html_colorbullets file1.html file2.html ...                    
# replace bullets in lists by colored bullets

doconce extract_exercises tmp_mako__mydoc                              
# extract all exercises (projects and problems too)

doconce grab --from[-] from-text [--to[-] to-text] file > result       
# grab selected text from a file

doconce remove --from[-] from-text [--to[-] to-text] file > result     
# remove selected text from a file

doconce grep FIGURE|MOVIE|CODE dofile                                  
# list all figure, movie or included code files

doconce spellcheck [-d .mydict.txt] *.do.txt                           
# run spellcheck on a set of files

doconce ptex2tex mydoc -DMINTED pycod=minted sys=Verbatim \
        dat=\begin{quote}\begin{verbatim};\end{verbatim}\end{quote} 
# transform ptex2tex files (.p.tex) to ordinary latex file and manage the code environments

doconce md2html file.md                                                
# make HTML file via pandoc from Markdown (.md) file

doconce md2latex file.md                                               
# make LaTeX file via pandoc from Markdown (.md) file

doconce combine_images image1 image2 ... output_file                   
# combine several images into one

doconce latex_problems mydoc.log [overfull-hbox-limit]                 
# report problems from a LaTeX .log file

doconce list_fig_src_files *.do.txt                                    
# list all figure files, movie files, and source code files needed

doconce list_labels myfile                                             
# list all labels in a document (for purposes of cleaning them up)

doconce ref_external mydoc [pubfile]                                   
# generate script for substituting generalized references

doconce linkchecker *.html                                             
# check all links in HTML files

doconce capitalize [-d .mydict.txt] *.do.txt                           
# change headings from "This is a Heading" to "This is a heading"

doconce latex2doconce latexfile                                        
# translate a latex document to doconce (requires usually manual fixing)

doconce latex_dislikes latexfile                                       
# check if there are problems with translating latex to doconce

doconce ipynb2doconce notebookfile                                     
# translate an IPython/Jupyter notebook to doconce

doconce pygmentize myfile [pygments-style]                             
# typeset a doconce document with pygments (for pretty print of doconce itself)

doconce makefile docname doconcefile [html sphinx pdflatex ...]        
# generate a make.py script for translating a doconce file to various formats

doconce diff file1.do.txt file2.do.txt [diffprog]                      
# find differences between two files (diffprog can be difflib, diff, pdiff, latexdiff, kdiff3, diffuse, ...)

doconce gitdiff file1 file2 file3 ...                                  
# find differences between the last two Git versions of several files

doconce csv2table somefile.csv                                         
# convert csv file to doconce table format

doconce sphinxfix_local_URLs file.rst                                  
# edit URLs to local files and place them in _static

doconce latin2html file.html                                           
# replace latex-1 (non-ascii) characters by html codes

doconce fix_bibtex4publish file1.bib file2.bib ...                     
# fix common problems in bibtex files for publish import

doconce latex_header                                                   
# print the header (preamble) for latex file

doconce latex_footer                                                   
# print the footer for latex files

doconce expand_commands file1 file2 ...                                
# expand short cut commands to full form in files

doconce latex_exercise_toc myfile                                      
# insert a table of exercises in a latex file myfile.p.tex
</syntaxhighlight>

==== Exercises ====

DocOnce supports ''Exercise'', ''Problem'', ''Project'', and ''Example''.
These are typeset
as ordinary sections and referred to by their section labels.
Exercise, problem, project, or example sections contains certain ''elements'':


<ul>
  <li> a headline at the level of a subsection
    containing one of the words "Exercise:", "Problem:",
    "Project:", or "Example:", followed by a title (required)
  <li> a label (optional)
  <li> a solution file (optional)
  <li> name of file with a student solution (optional)
  <li> main exercise text (required)
  <li> a short answer (optional)
  <li> a full solution (optional)
  <li> one or more hints (optional)
  <li> one or more subexercises (subproblems, subprojects), which can also
    contain a text, a short answer, a full solution, name student file
    to be handed in, and one or more hints (optional)
</ul>

A typical sketch of a a problem without subexercises goes as follows:
<syntaxhighlight lang="text">
===== Problem: Derive the Formula for the Area of an Ellipse =====
label{problem:ellipsearea1}
file=ellipse_area.pdf
solution=ellipse_area1_sol.pdf

Derive an expression for the area of an ellipse by integrating
the area under a curve that defines half of the ellipse.
Show each step in the mathematical derivation.

!bhint
Wikipedia has the formula for the curve.
!ehint

!bhint
"Wolframalpha": "http://wolframalpha.com" can perhaps
compute the integral.
!ehint
</syntaxhighlight>
If the exercise type (Exercise, Problem, Project, or Example)
is enclosed in braces, the type is left out of the title in the
output. For example, the if the title line above reads

<syntaxhighlight lang="text">
===== {Problem}: Derive the Formula for the Area of an Ellipse =====
</syntaxhighlight>
the title becomes just "Derive the ...".

An exercise with subproblems, answers and full solutions has this
setup-up:

<syntaxhighlight lang="text">
===== Exercise: Determine the Distance to the Moon =====
label{exer:moondist}

Intro to this exercise. Questions are in subexercises below.

!bsubex
Subexercises are numbered a), b), etc.

file=subexer_a.pdf

!bans
Short answer to subexercise a).
!eans

!bhint
First hint to subexercise a).
!ehint

!bhint
Second hint to subexercise a).
!ehint
!esubex

!bsubex
Here goes the text for subexercise b).

file=subexer_b.pdf

!bhint
A hint for this subexercise.
!ehint

!bsol
Here goes the solution of this subexercise.
!esol
!esubex

!bremarks
At the very end of the exercise it may be appropriate to summarize
and give some perspectives. The text inside the `!bremarks` and `!eremarks`
directives is always typeset at the end of the exercise.
!eremarks

!bsol
Here goes a full solution of the whole exercise.
!esol

</syntaxhighlight>
By default, answers, solutions, and hints are typeset as paragraphs.
The command-line arguments <code>--without_answers</code> and <code>--without_solutions</code>
turn off output of answers and solutions, respectively, except for examples. The command line options <code>--answers_at_end</code> and <code>--solutions_at_end</code> write all answers and solutions to exercises to a separate section at the end of the document, respectively. Combine with <code>--without_answers</code> and <code>--without_solutions</code> to remove answers and solutions from the main text.

The commands <code>!anshide</code> and <code>!solhide</code> can be used to hide from the main text answers and solutions, respectively, until the <code>!ansoff</code> and <code>!soloff</code> commands are encountered. Similarly, the <code>!ansdocend</code> and <code>!soldocend</code> commands move answers and solutions to the end of the book. 

==== Environments ====

DocOnce environments start with <code>!benvirname</code> and end with <code>!eenvirname</code>,
where <code>envirname</code> is the name of the environment. Here is a listing of
the environments:


<ul>
 <li> <code>c</code>: computer code (or verbatim text)
 <li> <code>t</code>: math blocks with LaTeX syntax
 <li> <code>subex</code>: sub-exercise
 <li> <code>ans</code>: short answer to exercise or sub-exercise
 <li> <code>sol</code>: full solution to exercise or sub-exercise
 <li> <code>hint</code>: multiple help items in an exercise or sub-exercise
 <li> <code>quote</code>: indented text
 <li> <code>notice</code>, <code>summary</code>, <code>warning</code>, <code>question</code>: admonition boxes with
    custom title, special icon, and (sometimes) background color
 <li> <code>block</code>, <code>box</code>: simpler boxes (<code>block</code> may have title but never any icon)
 <li> <code>pop</code>: text to gradually pop up in slide presentations
 <li> <code>slidecell</code>: indication of cells in a grid layout for elements on a
   slide
</ul>

In addition, the user can define new environments <code>!bc-name</code> as
explained in the [http://doconce.github.io/doconce/doc/pub/manual/manual.html#manual:userdef:envir manual].

==== Preprocessing ====

DocOnce documents may utilize a preprocessor, either <code>preprocess</code> and/or
<code>mako</code>. The former is a C-style preprocessor that allows if-tests
and including other files (but not macros with arguments).
The <code>mako</code> preprocessor is much more advanced - it is actually a full
programming language, very similar to Python.

The command <code>doconce format</code> first runs <code>preprocess</code> and then <code>mako</code>.
Here is a typical example on utilizing <code>preprocess</code> to include another
document, "comment out" a large portion of text, and to write format-specific
constructions:

<syntaxhighlight lang="text">
# #include "myotherdoc.do.txt"

# #if FORMAT in ("latex", "pdflatex")
\begin{table}
\caption{Some words... label{mytab}}
\begin{tabular}{lrr}
\hline\noalign{\smallskip}
\multicolumn{1}{c}{time} & \multicolumn{1}{c}{velocity} & \multicolumn{1}{c}{acceleration} \\ 
\hline
0.0          & 1.4186       & -5.01        \\ 
2.0          & 1.376512     & 11.919       \\ 
4.0          & 1.1E+1       & 14.717624    \\ 
\hline
\end{tabular}
\end{table}
# #else
  |--------------------------------|
  |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    |
  |--------------------------------|
# #endif

# #ifdef EXTRA_MATERIAL
....large portions of text...
# #endif
</syntaxhighlight>

With the <code>mako</code> preprocessor the if-else tests have slightly different syntax.
An [http://doconce.github.com/bioinf-py/ example document] contains
some illustrations on how to utilize <code>mako</code> (clone the GitHub project and
examine the DocOnce source and the <code>doc/src/make.sh</code> script).

==== Resources ====

<ul>
 <li> Excellent "Sphinx Tutorial" by C. Reller: "http://people.ee.ethz.ch/~creller/web/tricks/reST.html"
</ul>



************** File: quickref.cwiki *****************
#summary DocOnce Quick Reference
<wiki:toc max_depth="2" />
By **Hans Petter Langtangen**
=== Jan 32, 2100 ===

<<TableOfContents>>



**WARNING: This quick reference is very incomplete!**

//Mission.// Enable writing documentation with much mathematics and
computer code //once, in one place// and include it in traditional LaTeX
books, thesis, and reports, and, without extra efforts, also make
professional looking web versions with Sphinx or HTML. Other outlets
include Google's {{{blogger.com}}}, Wikipedia/Wikibooks, IPython/Jupyter
notebooks, plus a wide variety of other formats for documents without
mathematics and code.

== Supported Formats ==

DocOnce currently translates files to the following formats:


 * LaTeX (format {{{latex}}} or {{{pdflatex}}})
 * HTML (format {{{html}}})
 * Sphinx (format {{{sphinx}}})
 * Pandoc-extended or GitHub-flavored Markdown (format {{{pandoc}}})
 * IPython notebook (format {{{ipynb}}})
 * Matlab notebook (format {{{matlabnb}}})
 * MediaWiki (format {{{mwiki}}})
 * Googlecode wiki (format {{{gwiki}}})
 * Creoloe wiki (format {{{cwiki}}})
 * reStructuredText (format {{{rst}}})
 * plain (untagged) ASCII (format {{{plain}}})
 * Epydoc (format {{{epydoc}}})
 * StructuredText (format {{{st}}})

For documents with much code and mathematics, the best (and most supported)
formats are {{{latex}}}, {{{pdflatex}}}, {{{sphinx}}}, and {{{html}}}; and to a slightly
less extent {{{mwiki}}} and {{{pandoc}}}. The HTML format supports blog posts on
Google and Wordpress.

//Use a text editor with monospace font!// 
Some DocOnce constructions are sensitive to whitespace,
so you //must// use a text editor with monospace font.



== Emacs syntax support ==

The file [[https://github.com/doconce/doconce/blob/master/misc/.doconce-mode.el|.doconce-mode.el]]
in the DocOnce source distribution gives a "DocOnce Editing Mode" in
Emacs. Store the raw version of the file in the home directory and add
{{{(load-file "~/.doconce-mode.el")}}} to the {{{.emacs}}} file.

Besides syntax highlighting of DocOnce documents, this Emacs mode
provides a lot of shortcuts for setting up many elements in a document:


 | =Emacs key         | =Action                                             |
 |  Ctrl+c f          |  figure                                             |
 |  Ctrl+c v          |  movie/video                                        |
 |  Ctrl+c h1         |  heading level 1 (section/h1)                       |
 |  Ctrl+c h2         |  heading level 2 (subsection/h2)                    |
 |  Ctrl+c h3         |  heading level 2 (subsection/h3)                    |
 |  Ctrl+c hp         |  heading for paragraph                              |
 |  Ctrl+c me         |  math environment: {{{!bt}}} equation {{{!et}}}     |
 |  Ctrl+c ma         |  math environment: {{{!bt}}} align {{{!et}}}        |
 |  Ctrl+c ce         |  code environment: {{{!bc}}} code {{{!ec}}}         |
 |  Ctrl+c cf         |  code from file: {{{@@@CODE}}}                      |
 |  Ctrl+c table2     |  table with 2 columns                               |
 |  Ctrl+c table3     |  table with 3 columns                               |
 |  Ctrl+c table4     |  table with 4 columns                               |
 |  Ctrl+c exer       |  exercise outline                                   |
 |  Ctrl+c slide      |  slide outline                                      |
 |  Ctrl+c help       |  print this table                                   |


== Title, Authors, and Date ==

A typical example of giving a title, a set of authors, a date,
and an optional table of contents
reads

{{{
TITLE: On an Ultimate Markup Language
AUTHOR: H. P. Langtangen at Center for Biomedical Computing, Simula Research Laboratory & Dept. of Informatics, Univ. of Oslo
AUTHOR: Kaare Dump Email: dump@cyb.space.com at Segfault, Cyberspace Inc.
AUTHOR: A. Dummy Author
DATE: today
TOC: on
}}}
The entire title must appear on a single line.
The author syntax is
{{{
name Email: somename@adr.net at institution1 & institution2
}}}
where the email is optional, the "at" keyword is required if one or
more institutions are to be specified, and the {{{&}}} keyword
separates the institutions (the keyword {{{and}}} works too).
Each author specification must appear
on a single line.
When more than one author belong to the
same institution, make sure that the institution is specified in an identical
way for each author.

The date can be set as any text different from {{{today}}} if not the
current date is wanted, e.g., {{{Jan 32, 2100}}}.

The table of contents is removed by writing {{{TOC: off}}}.

== Copyright ==

<wiki:comment> Recall to ident AUTHOR commands to avoid interpretation </wiki:comment>

Copyright for selected authors and/or institutions are easy to insert as part
of the {{{AUTHOR}}} command. The copyright syntax is

{{{
{copyright,year1-year2|license}
}}}
and can be placed after the author or after an institution, e.g.,

{{{
 AUTHOR: name Email: somename@adr.net {copyright,2006-present} at inst1
 AUTHOR: name {copyright} at inst1 {copyright}
}}}
The first line gives {{{name}}} a copyright for 2006 up to the present year,
while the second line gives copyright to {{{name}}} and the institution {{{inst1}}}
for the present year. The license can be any formulation, but there are
some convenient abbreviations for Creative Commons ("public domain")
licenses: {{{CC BY}}} for Creative Commons Attribution 4.0 license,
{{{CC BY-NC}}} for Creative Commons Attribution-NonCommercial 4.0 license.
For example,

{{{
 AUTHOR: name1 {copyright|CC BY} at institution1
 AUTHOR: name2 {copyright|CC BY} at institution2
}}}
is a very common copyright for the present year with the Attribution license.
The copyright must be identical for all authors and institutions.


== Section Types ==



 | =Section type      | =Syntax                                                  |
 |  chapter           |  {{{========= Heading ========}}} (9 {{{=}}})            |
 |  section           |  {{{======= Heading =======}}}    (7 {{{=}}})            |
 |  subsection        |  {{{===== Heading =====}}}        (5 {{{=}}})            |
 |  subsubsection     |  {{{=== Heading ===}}}            (3 {{{=}}})            |
 |  paragraph         |  {{{__Heading.__}}}               (2 {{{_}}})            |
 |  abstract          |  {{{__Abstract.__}}} Running text...                     |
 |  appendix          |  {{{======= Appendix: heading =======}}} (7 {{{=}}})     |
 |  appendix          |  {{{===== Appendix: heading =====}}} (5 {{{=}}})         |
 |  exercise          |  {{{===== Exercise: heading =====}}} (5 {{{=}}})         |


Note that abstracts are recognized by starting with {{{__Abstract.__}}} or
{{{__Summary.__}}} at the beginning of a line and ending with three or
more {{{=}}} signs of the next heading.

The {{{Exercise:}}} keyword can be substituted by {{{Problem:}}} or {{{Project:}}}.
A recommended convention is that an exercise is tied to the text,
a problem can stand on its own, and a project is a comprehensive
problem.

== Inline Formatting ==

Words surrounded by {{{*}}} are emphasized: {{{*emphasized words*}}} becomes
//emphasized words//. Similarly, an underscore surrounds words that
appear in boldface: {{{_boldface_}}} becomes **boldface**. Colored words
are also possible: the text

{{{
`color{red}{two red words}`
}}}
becomes <font color="red">two red words</font>.
(But colors do not work in format cwiki).

Quotations appear inside double backticks and double single quotes:

{{{
This is a sentence with ``words to be quoted''.
}}}

A forced linebreak is specified by {{{<linebreak>}}} at the point where the
linebreak in the output is wanted.

Footnotes use a label in the text with the footnote text separate,
preferably after the paragraph where the footnote appears:

{{{
Differentiating[^diff2] this equation leads
to a new and much simpler equation.

[^diff2]: More precisely, we apply the divergence
$\nabla\cdot$ on both sides.

Here comes a new paragraph...
}}}

Non-breaking space is inserted using the tilde character as in LaTeX:

{{{
This distance corresponds to 7.5~km, which is traveled in $7.5/5$~s.
}}}

A horizontal rule for separating content vertically, like this:

----

is typeset as four or more hyphens on a single line:

{{{
---------
}}}

The {{{latex}}}, {{{pdflatex}}}, {{{sphinx}}}, and {{{html}}} formats support em-dash,
indicated by three hyphens: {{{---}}}. Here is an example:

{{{
The em-dash is used - without spaces - as alternative to hyphen with
space around in sentences---this way, or in quotes:
*Premature optimization is the root of all evil.*--- Donald Knuth.
}}}
This text is in the cwiki rendered as

The em-dash is used - without spaces - as alternative to hyphen with
space around in sentences---this way, or in quotes:
//Premature optimization is the root of all evil.//--- Donald Knuth.

The en-dash consists of two hyphens, either with blanks on both sides - for
something in the middle of a sentence - or in number ranges like 240 - 249.
LaTeX writes are used to and fond of en-dash.

An ampersand, as in Guns & Roses or Texas A&M, is written as a
plain {{{&}}} //with space(s) on both sides//. Single upper case letters on each
side of {{{&}}}, as in {{{Texas A & M}}}, remove the spaces and result in
Texas A&M, while words on both sides of {{{&}}}, as in {{{Guns & Roses}}},
preserve the spaces: Guns & Roses. Failing to have spaces before and
after {{{&}}} will result in wrong typesetting of the ampersand in the {{{html}}},
{{{latex}}}, and {{{pdflatex}}} formats.

Emojis, as defined in [[http://www.emoji-cheat-sheet.com]], can be
inserted in the text, as (e.g.) {{{:dizzy_face:}}} with blank or newline
before or after :dizzy_face: Only the {{{pdflatex}}}, {{{html}}}, and {{{pandoc}}} output
formats translate emoji specifications to images, while all other
formats leave the textual specification in the document. The
command-line option {{{--no_emoji}}} removes all emojis from the output
document.

== Lists ==

There are three types of lists: //bullet lists//, where each item starts
with {{{*}}}, //enumeration lists//, where each item starts with {{{o}}} and gets
consecutive numbers,
and //description// lists, where each item starts with {{{-}}} followed
by a keyword and a colon.
{{{
Here is a bullet list:

 * item1
 * item2
  * subitem1 of item2
  * subitem2 of item2,
    second line of subitem2
 * item3

Note that sublists are consistently indented by one or more blanks as
shown: bullets must exactly match and continuation lines must start
right below the line above.

Here is an enumeration list:

 o item1
 o item2
   may appear on
   multiple lines
  o subitem1 of item2
  o subitem2 of item2
 o item3

And finally a description list:

 - keyword1: followed by
   some text
   over multiple
   lines
 - keyword2:
   followed by text on the next line
 - keyword3: and its description may fit on one line
}}}
The code above follows.

Here is a bullet list:


 * item1
 * item2

  ** subitem1 of item2
  //* subitem2 of item2


 // item3

Note that sublists are consistently indented by one or more blanks as
shown: bullets must exactly match and continuation lines must start
right below the line above.

Here is an enumeration list:


# item1
# item2   may appear on   multiple lines

 ## subitem1 of item2
 ## subitem2 of item2


# item3

And finally a description list:


 * keyword1:  
   followed by   some text   over multiple   lines
 * keyword2:     followed by text on the next line
 * keyword3:  
   and its description may fit on one line

//No indentation - except in lists!// 
DocOnce syntax is sensitive to whitespace.
No lines should be indented, only lines belonging to lists.
Indented lines may give strange output in some formats.




== Comment lines ==

Lines starting with {{{#}}} are treated as comments in the document and
translated to the proper syntax for comments in the output
document. Such comment lines should not appear before LaTeX math
blocks, verbatim code blocks, or lists if the formats {{{rst}}} and
{{{sphinx}}} are desired.

Comment lines starting with {{{##}}} are not propagated to the output
document and can be used for comments that are only of interest in
the DocOnce file.

Large portions of text can be left out using Preprocess. Just place
{{{# #ifdef EXTRA}}} and {{{# #endif}}} around the text. The command line
option {{{-DEXTRA}}} will bring the text alive again.

When using the Mako preprocessor one can also place comments in
the DocOnce source file that will be removed by Mako before
DocOnce starts processing the file.


== Inline comments ==

Inline comments meant as messages or notes, to authors during development
in particular,
are enabled by the syntax
{{{
[name: running text]
}}}
where {{{name}}} is the name or ID of an author or reader making the comment,
and {{{running text}}} is the comment. The name can contain upper and lower
case characters, digits, single quote, {{{+}}} and {{{-}}}, as well
as space. Here goes an example.

{{{
Some running text. [hpl: There must be a space after the colon,
but the running text can occupy multiple lines.]
}}}
which is rendered as





The inline comments have simple typesetting in most formats, typically
boldface name, a comment number, with everything surrounded by
parenthesis.  However, with LaTeX output and the {{{--latex_todonotes}}}
option to {{{doconce format}}}, colorful margin or inline boxes (using the
{{{todonotes}}} package) make it very easy to spot the comments.

Running
{{{
doconce format html mydoc.do.txt --skip_inline_comments
}}}
removes all inline comments from the output. This feature makes it easy
to turn on and off notes to authors during the development of the document.

All inline comments to readers can also be physically
removed from the DocOnce source by
{{{
doconce remove_inline_comments mydoc.do.txt
}}}

Inline comments can also be used to markup edits. There are add, delete, and
replacement comments for editing:

{{{
[add: ,]
[add: .]
[add: ;]
[del: ,]
[del: ,]
[del: .]
[del: ;]
[add: some text]
[del: some text]
[edit: some text -> some replacement for text]
[name: some text -> some replacement for text]
}}}

For example, the text

{{{
First consider a quantity $Q$. Without loss of generality, we assume
$Q>0$. There are three, fundamental, basic property of $Q$.
}}}
can be edited as

{{{
First[add: ,] consider [edit: a quantity -> the flux]
[del: $Q$. Without loss of generality,
we assume] $Q>0$. There are three[del: ,] fundamental[del: , basic]
[edit: property -> properties] of $Q$. [add: These are not
important for the following discussion.]
}}}
which in the cwiki output format results in





To implement these edits, run

{{{
Terminal> doconce apply_edit_comments mydoc.do.txt
}}}

== Verbatim/Computer Code ==

Inline verbatim code is typeset within back-ticks, as in
{{{
Some sentence with `words in verbatim style`.
}}}
resulting in Some sentence with {{{words in verbatim style}}}.

Multi-line blocks of verbatim text, typically computer code, is typeset
in between {{{!bc xxx}}} and {{{!ec}}} directives, which must appear on the
beginning of the line. A specification {{{xxx}}} indicates what verbatim
formatting style that is to be used. Typical values for {{{xxx}}} are
nothing, {{{cod}}} for a code snippet, {{{pro}}} for a complete program,
{{{sys}}} for a terminal session, {{{dat}}} for a data file (or output from a
program),
{{{Xpro}}} or {{{Xcod}}} for a program or code snipped, respectively,
in programming {{{X}}}, where {{{X}}} may be {{{py}}} for Python,
{{{cy}}} for Cython, {{{sh}}} for Bash or other Unix shells,
{{{f}}} for Fortran, {{{c}}} for C, {{{cpp}}} for C++, {{{m}}} for MATLAB,
{{{pl}}} for Perl. For output in {{{latex}}} one can let {{{xxx}}} reflect any
defined verbatim environment in the {{{ptex2tex}}} configuration file
({{{.ptex2tex.cfg}}}). For {{{sphinx}}} output one can insert a comment
{{{
# sphinx code-blocks: pycod=python cod=fortran cppcod=c++ sys=console
}}}
that maps environments ({{{xxx}}}) onto valid language types for
Pygments (which is what {{{sphinx}}} applies to typeset computer code).

The {{{xxx}}} specifier has only effect for {{{latex}}} and
{{{sphinx}}} output. All other formats use a fixed monospace font for all
kinds of verbatim output.

Here is an example of computer code (see the source of this document
for exact syntax):

{{{
from numpy import sin, cos, exp, pi

def f(x, y, z, t):
    return exp(-t)*sin(pi*x)*sin(pi*y)*cos(2*pi*z)
}}}

<wiki:comment> When showing copy from file in !bc envir, indent a character - otherwise </wiki:comment>
<wiki:comment> ptex2tex is confused and starts copying... </wiki:comment>
Computer code can also be copied from a file:
{{{
 @@@CODE doconce_program.sh
 @@@CODE doconce_program.sh  fromto: doconce clean@^doconce split_rst
 @@@CODE doconce_program.sh  from-to: doconce clean@^doconce split_rst
 @@@CODE doconce_program.sh  envir=shpro fromto: name=@
}}}
The {{{@@@CODE}}} identifier must appear at the very beginning of the line.
The first line copies the complete file {{{doconce_program.sh}}}.
The second line copies from the first line matching the //regular
expression// {{{doconce clean}}} up to, but not including, the line
matching the //regular expression// {{{^doconce split_rst}}}.
The third line behaves as the second, but the line matching
the first regular expression is not copied (this construction is often
used for copying text between begin-end comment pair in the file).

The copied lines from file are in this example put inside {{{!bc shpro}}}
and {{{!ec}}} directives, if a complete file is copied, while the
directives become {{{!bc shcod}}} and {{{!ec}}} when a code snippet is copied
from a file. In general, for a filename extension {{{.X}}}, the environment
becomes {{{!bc Xpro}}} or {{{!bc Xcod}}} for a complete program or snippet,
respectively. The enivorments ({{{Xcod}}} and {{{Xpro}}}) are only active for
{{{latex}}}, {{{pdflatex}}}, html`, and {{{sphinx}}} output.  The fourth line
above specifies the code environment explicitly ({{{envir=shpro}}}) such
that it indicates a complete shell program ({{{shpro}}}) even if we copy a
part of the file (here from {{{name=}}} until the end of the file).
Copying a part of a file will by default lead to {{{!bc shcod}}}, which indicates a
code snippet that normally needs more code to run properly.

The {{{--code_prefix=text}}} option adds a path {{{text}}} to the filename specified
in the {{{@@@CODE}}} command (URLs work). For example

{{{
 @@@CODE src/myfile.py
}}}
and {{{--code_prefix=http://some.place.net}}}, the file

{{{
http://some.place.net/src/myfile.py
}}}
will be included. If source files have a header with author, email, etc.,
one can remove this header by the option {{{'--code_skip_until=# ---}}}.
The lines up to and including (the first) {{{# ---}}} will then be excluded.

Important warnings:


 * A code block must come after a plain sentence (at least for successful   output in reStructredText), not directly after a section/paragraph heading,   table, comment, figure, or movie.
 * Verbatim code blocks inside lists can be ugly when typeset in some   output formats. A more robust approach is to replace the list with   paragraphs that include headings.

== LaTeX Mathematics ==

DocOnce supports inline mathematics and blocks of mathematics, using
standard LaTeX syntax. The output formats {{{html}}}, {{{sphinx}}}, {{{latex}}},
pdflatex`, {{{pandoc}}}, and {{{mwiki}}} work with this syntax while all other
formats will just display the raw LaTeX code.

Inline expressions are written in the standard
LaTeX way with the mathematics surrounded by dollar signs, as in
{{{Ax=b}}}. To help increase readability in other formats than {{{sphinx}}},
{{{latex}}}, and {{{pdflatex}}}, inline mathematics may have a more human
readable companion expression. The syntax is like
{{{
$\sin(\norm{\bf u})$|$sin(||u||)$
}}}
That is, the LaTeX expression appears to the left of a vertical bar (pipe
symbol) and the more readable expression appears to the right. Both
expressions are surrounded by dollar signs.

Blocks of LaTeX mathematics are written within
{{{!bt}}}
and
{{{!et}}} (begin/end TeX) directives starting on the beginning of a line:

{{{
!bt
\begin{align*}
\nabla\cdot \pmb{u} &= 0,\\ 
\nabla\times \pmb{u} &= 0.
\end{align*}
!et
}}}

This LaTeX code gets rendered as

{{{
\begin{align*}
\nabla\cdot \pmb{u} &= 0,\\ 
\nabla\times \pmb{u} &= 0.
\end{align*}
}}}
Here is a single equation:

{{{
!bt
\[ \frac{\partial\pmb{u}}{\partial t} + \pmb{u}\cdot\nabla\pmb{u} = 0.\]
!et
}}}
which results in

{{{
\[ \frac{\partial\pmb{u}}{\partial t} + \pmb{u}\cdot\nabla\pmb{u} = 0.\]
}}}


//LaTeX Newcommands.//
The author can define {{{newcommand}}} statements in files with names
{{{newcommands*.tex}}}. Such commands should only be used for mathematics
(other LaTeX constructions are only understood by LaTeX itself).
The convention is that {{{newcommands_keep.tex}}}
contains the newcommands that are kept in the document, while
those in {{{newcommands_replace.tex}}} will be replaced by their full
LaTeX code. This conventions helps make readable documents in formats
without LaTeX support. For {{{html}}}, {{{sphinx}}}, {{{latex}}}, {{{pdflatex}}},
{{{mwiki}}}, {{{ipynb}}}, and {{{pandoc}}}, the mathematics in newcommands is
rendered nicely anyway. If you desire {{{newcommand}}} outside LaTeX
mathematics, simply use a Mako variable or a Mako function (which
will be much more flexible and powerful).

<wiki:comment> include with mako must be in this root tree, so we need a link, see make.sh </wiki:comment>

== Writing Guidelines (Especially for LaTeX Users!) ==


LaTeX writers often have their own writing habits and have preferred
LaTeX packages. DocOnce is a simpler format and
corresponds to writing in quite plain LaTeX and making the ascii text
look nice (be careful with the use of white space!). This means that
although DocOnce has borrowed a lot from LaTeX, there are a few points
LaTeX writers should pay attention to. Experience shows that these
points are so important that we list them //before// we list typical
DocOnce syntax!

Any LaTeX syntax in mathematical formulas is accepted when DocOnce
translates the text to LaTeX, but the following rules should be
followed when transalting the text to {{{sphinx}}}, {{{pandoc}}},
{{{mwiki}}}, {{{html}}}, or {{{ipynb}}} formats.


 * AMS LaTeX mathematics is supported, also for the {{{html}}}, {{{sphinx}}},   and {{{ipynb}}} formats.
 * If you want LaTeX math blocks to work with {{{latex}}}, {{{html}}}, {{{sphinx}}},   {{{markdown}}}, and {{{ipynb}}}, only use   the following equation environments: {{{\[ ... \]}}},   {{{equation*}}}, {{{equation}}}, {{{align*}}}, {{{align}}}. {{{alignat*}}}, {{{alignat}}}.   Other environments, such as {{{split}}}, {{{multiline}}}, {{{gather}}} are   supported in modern MathJax in HTML and Sphinx, but may have   rendering problems (to a larger extent than {{{equation}}} and {{{align}}}).   DocOnce performs extensions to {{{sphinx}}}, {{{ipynb}}},   and other formats such that   labels in {{{align}}} and {{{alignat}}} environments work well.   If you face problems with fancy LaTeX equation environments in   web formats, try rewriting with plain {{{align}}}, {{{nonumber}}}, etc.
 * Do not use comments inside equations.
 * Newcommands in mathematical formulas are allowed, but not in   the running text. Newcommands must be defined in files with names   {{{newcommands*.tex}}}. Use {{{\newcommands}}} and not {{{\def}}}.   Each newcommand must be defined on a single line.   Use Mako functions if you need macros in the running text.
 * Use labels and refer to them   for sections, figures, movies, and equations only.   MediaWiki ({{{mwiki}}}) does not support references to equations.
 * Spaces are not allowed in labels.
 * There is just one {{{ref}}} command (no {{{\eqref}}} for equations) and references to   equations must use parentheses. Never use the tilde {{{~}}} (non-breaking   space) character before references to figures, sections, etc., but   tilde is allowed for references to equations.
 * Never use {{{\pageref}}} as pages are not a concept in web documents   (there is only a {{{ref}}} command in DocOnce and it refers to labels).
 * Only figures and movies are floating elements in DocOnce, all other elements   (code, tables, algorithms) must appear //inline// without numbers or labels   for reference[^exception] (refer to inline elements by a section label).   The reason is that floating elements are in general   not used in web documents, but we made an exception with figures   and movies.
 * Keep figure captions shorts as they are used as references in the   Sphinx format. Avoid inline mathematics since Sphinx will strip it   away in the figure reference.   (Many writing styles encourage rich captions that   explains everything about the figure; this work well   only in the HTML and LaTeX formats.)
 * You cannot use {{{subfigure}}} to combine several image files in one   figure, but you can combine the files into one file using   the {{{doconce combine_images}}} tool. Refer to individual image files   in the caption or text by (e.g.) "left" and "right", or   "upper left", "lower right", etc.
 * Footnotes can be used as usual in LaTeX, but some HTML formats are not   able to display mathematics or inline verbatim or other formatted   code (emphasis, boldface, color) in footnotes - keep that in mind.
 * Use plain {{{cite}}} for references (e.g., {{{\citeauthor}}} has no counterpart   in DocOnce). The bibliography must be prepared in the Publish format,   but import from (clean) BibTeX is possible.
 * Use {{{idx}}} for index entries, but put the definitions between paragraphs,   not inside them (required by Sphinx).
 * Use the {{{\bm}}} command (from the {{{bm}}} package, always included by DocOnce)   for boldface in mathematics.
 * Make sure all ordinary text starts in column 1 on each line. Equations   can be indented. The {{{\begin{}}}} and {{{\end{}}}} directives should start   in column 1.
 * If you depend on various LaTeX environments for your writings, you have   to give these up, or implement //user-defined environments// in DocOnce.   For instance, examples are normally typeset as subsections in DocOnce,   but can also utilize a user-defined example environment.   Learn about the exercise support in DocOnce for typesetting   exercises, problems, and projects.
 * Learn about the preprocessors Preprocess and Mako - these are smart   tools for, e.g., commenting out/in large portions of text and creating   macros.
 * Use //generalized references// when referring to companion documents   that may later become part of this document (or migrated out of this document).
 * Follow [[https://github.com/doconce/setup4book-doconce|recommendations for DocOnce books]] if you plan to write a book.

[^exception]: There is an exception: by using //user-defined environments//
within {{{!bu-name}}} and {{{!eu-name}}} directives, it is possible to
label any type of text and refer to it. For example, one can have
environments for examples, tables, code snippets, theorems, lemmas, etc.
One can also use Mako functions to implement environments.

//Use the preprocessor to tailor output.// 
If you really need special LaTeX constructs in the LaTeX output
from DocOnce, you may use use preprocessor if-tests on
the format (typically {{{#if FORMAT in ("latex", "pdflatex")}}}) to
include such special LaTeX code. With an else clause you can easily
create corresponding constructions for other formats. This way
of using Preprocess or Mako
allows you to use advanced LaTeX features (or HTML features for the HTML formats)
to fine tune the resulting
document. More tuning can be done by automatic editing of the
output file (e.g., {{{.tex}}} or {{{.html}}}) produced by DocOnce using
your own scripts or the {{{doconce replace}}} and {{{doconce subst}}} commands.



//Autotranslation of LaTeX to DocOnce?// 
The tool {{{doconce latex2doconce}}} may help you translate LaTeX files
to DocOnce syntax. However, if you use computer code in floating
list environments, special packages for typesetting algorithms,
example environments, {{{subfigure}}} in figures,
or a lot of newcommands in the running text, there will be need for
a lot of manual edits and adjustments.

For examples, figure environments can only be translated by
{{{doconce latex2doconce}}} if the label is inside the caption and
the figure is typeset like

{{{
\begin{figure}
  \centering
  \includegraphics[width=0.55\linewidth]{figs/myfig.pdf}
  \caption{This is a figure. \labe{myfig}}
\end{figure}
}}}
If the LaTeX text is consistent with respect to the placement of the label, a
simple script can autoedit the label inside the caption, but many
LaTeX writers put the label at different places in different figures,
and then it becomes more difficult to autoedit figures and translate
them to the DocOnce {{{FIGURE:}}} syntax.

Tables are hard to interpret and translate because headings and
caption can be typeset in many different ways. The type of table
that is recognized looks like

{{{
\begin{table}
\caption{Here goes the caption.}
\begin{tabular}{lr}
\hline
\multicolumn{1}{c}{$v_0$} & \multicolumn{1}{c}{$f_R(v_0)$}\\hline
1.2 & 4.2\1.1 & 4.0\0.9 & 3.7
\hline
\end{tabular}
\end{table}
}}}
Recall that table captions do not make sense in DocOnce since tables
must be inlined and explained in the surrounding text.

Footnotes are also problematic for {{{doconce latex2doconce}}} since DocOnce
footnotes must have the explanation outside the paragraph where the
footnote is used. This calls for manual work. The translator from
LaTeX to DocOnce will insert {{{_PROBLEM_}}} and mark footnotes. One
solution is to avoid footnotes in the LaTeX document if fully automatic
translation is desired.




== Hyperlinks ==

Links use either a link text or the raw URL:

{{{
Here is some "some link text": "http://some.net/address"
(as in "search google": "http://google.com")
or just the raw address: URL: "http://google.com".

Links to files typeset in verbatim mode applies backtics:
"`myfile.py`": "http://some.net/some/place/myfile.py".

Mail addresses works too: send problems to
"`hpl@simula.no`": "mailto:hpl@simula.no"
or just "send mail": "mailto:hpl@simula.no".
}}}

== Figures and Movies ==

Figures and movies have almost equal syntax:
{{{
FIGURE: [relative/path/to/figurefile, width=500 frac=0.8] Here goes the caption which must be on a single line. label{some:fig:label}

MOVIE: [relative/path/to/moviefile, width=500] Here goes the caption which must be on a single line. 

}}}
Note three important syntax details:


 # A mandatory comma after the figure/movie filename,
 # no comments between {{{width}}}, {{{height}}}, and {{{frac}}} and no spaces    around the {{{=}}} characters,
 # all of the commands must appear on a single line,
 # there must be a blank line after the command.

The figure file can be listed without extension. DocOnce will then find
the version of the file with the most appropriate extension for the chosen
output format. If not suitable version is found, DocOnce will convert
another format to the needed one.

The caption is optional. If omitted, the figure will be inlined (meaning
no use of any figure environment in HTML or LaTeX formats). The {{{width}}}
and {{{height}}} parameters affect HTML formats ({{{html}}}, {{{rst}}}, {{{sphinx}}}),
while {{{frac}}} is the width of the image as a fraction of the total text
width in the {{{latex}}} and {{{pdflatex}}} formats.

The command-line options {{{--fig_prefix=...}}} and {{{--mov_prefix=...}}} can
be used to add a path (can be a URL) to all figure and movie files,
respectively.  This is useful when including DocOnce documents in
other DocOnce documents such that the text is compiled in different
directories (with different paths to the figure directory).

Movie files can either be a video or a wildcard expression for a
series of frames. In the latter case, a simple device in an HTML page
will display the individual frame files as a movie.

Combining several image files into one can be done by the
{{{
doconce combine_images image1 image2 ... output_image
}}}
This command applies {{{montage}}} or PDF-based tools to combine the images
to get the highest quality.

YouTube and Vimeo movies will be embedded in {{{html}}} and {{{sphinx}}} documents
and otherwise be represented by a link. The syntax is

{{{
MOVIE: [http://www.youtube.com/watch?v=_O7iUiftbKU, width=420 height=315] YouTube movie.

MOVIE: [http://vimeo.com/55562330, width=500 height=278] Vimeo movie.

}}}
The latter results in

Vimeo movie. {{{http://vimeo.com/55562330}}}: load [[movie_player1.html|{{{movie_player1.html}}}]] into a browser


== Tables ==

The table in the section [#Section_Types] was written with this
syntax:
{{{

|----------------c--------|------------------c--------------------|
|      Section type       |        Syntax                         |
|----------------l--------|------------------l--------------------|
| chapter                 | `========= Heading ========` (9 `=`)  |
| section                 | `======= Heading =======`    (7 `=`)  |
| subsection              | `===== Heading =====`        (5 `=`)  |
| subsubsection           | `=== Heading ===`            (3 `=`)  |
| paragraph               | `__Heading.__`               (2 `_`)  |
|-----------------------------------------------------------------|

}}}

Note that


 * Each line begins and ends with a vertical bar (pipe symbol).
 * Column data are separated by a vertical bar (pipe symbol).
 * There must be a blank line before and after the table.
 * There may be horizontal rules, i.e., lines with dashes for   indicating the heading and the end of the table, and these may   contain characters 'c', 'l', or 'r' for how to align headings or   columns. The first horizontal rule may indicate how to align   headings (center, left, right), and the horizontal rule after the   heading line may indicate how to align the data in the columns   (center, left, right).   One can also use {{{X}}} for potentially very wide text that must be   wrapped and left-adjusted (will only affect {{{latex}}} and {{{pdflatex}}} where the   {{{tabularx}}} package is then used; {{{X}}} means {{{l}}} in all other formats).
 * If the horizontal rules are without alignment information there should   be no vertical bar (pipe symbol) between the columns. Otherwise, such   a bar indicates a vertical bar between columns in LaTeX.
 * Many output formats are so primitive that heading and column alignment   have no effect.

A quick way of generating tables is to place all the entries in a file
with comma as separator (a CSV file) and then run the utility
{{{doconce csv2table}}} to create a table in the DocOnce format.

The command-line option {{{--tables2csv}}} (to {{{doconce format}}})
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.

DocOnce tables can be efficiently made directly from data in CSV files.

{{{
Terminal> doconce csv2table mydata.csv > mydata_table.do.txt
}}}
Now we can do {{{# #include "mydata_table.do.txt"}}} in the DocOnce
source file or simply copy the table in {{{mydata_table.do.txt}}}
into the DocOnce file.

== Labels and References ==

The notion of labels and references (as well as bibliography and index)
is adopted
from LaTeX with a very similar syntax. As in LaTeX, a label can be
inserted anywhere, using the syntax
{{{
label{name}
}}}
with no backslash
preceding the label keyword. It is common practice to choose {{{name}}}
as some hierarchical name, using a delimiter like {{{:}}} or {{{_}}} between
(e.g.) section, subsection, and topic.

A reference to the label {{{name}}} is written as
{{{
ref{name}
}}}
again with no backslash before {{{ref}}}.

Use labels for sections and equations only, and precede the reference
by "Section" or "Chapter", or in case of an equation, surround the
reference by parenthesis.


== Citations and Bibliography ==

Single citations are written as
{{{
cite{name}
}}}
where {{{name}}} is a logical name
of the reference (again, LaTeX writers must not insert a backslash).
Bibliography citations often have {{{name}}} on the form
{{{Author1_Author2_YYYY}}}, {{{Author_YYYY}}}, or {{{Author1_etal_YYYY}}}, where
{{{YYYY}}} is the year of the publication.
Multiple citations at once is possible by separating the logical names
by comma:
{{{
cite{name1,name2,name3}
}}}

The bibliography is specified by a line {{{BIBFILE: papers.pub}}},
where {{{papers.pub}}} is a publication database in the
[[https://github.com/doconce/publish|Publish]] format.
BibTeX {{{.bib}}} files can easily be combined to a Publish database
(which DocOnce needs to create bibliographies in other formats
than LaTeX).

== Generalized References ==

There is a //generalized referencing// feature in DocOnce that allows
a reference with {{{ref}}} to have one formulation if the label is
in the same document and another formulation if the reference is
to an item in an external document. This construction makes it easy
to work with many small, independent documents in parallel with
a book assembly of some of the small elements.
The syntax of a generalized reference is

{{{
ref[internal][cite][external]
}}}
with a specific example being

{{{
As explained in
ref[Section ref{subsec:ex}][in cite{testdoc:12}][a "section":
"testdoc.html#___sec2" in the document
"A Document for Testing DocOnce": "testdoc.html" cite{testdoc:12}],
DocOnce documents may include movies.
}}}
The output from a generalized reference is the text {{{internal}}} if all
references with {{{ref}}} in the text {{{internal}}} are references to labels
defined in the
present document. Otherwise, if {{{cite}}} is non-empty and the format is
{{{latex}}} or {{{pdflatex}}}, one assumes that the references in {{{internal}}}
are to external documents declared by a comment line
{{{# Externaldocuments: testdoc, mydoc}}} (usually after the title, authors,
and date). In this case the output text is {{{internal}}} followed by {{{cite}}},
and the
LaTeX package {{{xr}}} is used to handle the labels in the external
documents.  If none of the two situations above applies, the
{{{external}}} text will be the output.

== Index of Keywords ==

DocOnce supports creating an index of keywords. A certain keyword
is registered for the index by a syntax like (no
backslash!)
{{{
index{name}
}}}
It is recommended to place any index of this type outside
running text, i.e., after (sub)section titles and in the space between
paragraphs. Index specifications placed right before paragraphs also
gives the doconce source code an indication of the content in the
forthcoming text. The index is only produced for the {{{latex}}},
{{{pdflatex}}}, {{{rst}}}, and {{{sphinx}}} formats.

== Capabilities of The Program {{{doconce}}} ==

The {{{doconce}}} program can be used for a number of purposes besides
transforming a {{{.do.txt}}} file to some format. Here is the
list of capabilities:

{{{
DocOnce version 1.5.4 (from /home/amarin/doconce/venv/lib/python3.6/site-packages/DocOnce-1.5.4-py3.6.egg/doconce)
Usage: doconce command [optional arguments]
commands: help format find subst replace remove spellcheck apply_inline_edits capitalize change_encoding clean combine_images csv2table diff expand_commands expand_mako extract_exercises find_nonascii_chars fix_bibtex4publish gitdiff grab grep guess_encoding gwiki_figsubst html2doconce html_colorbullets jupyterbook include_map insertdocstr ipynb2doconce latex2doconce latex_dislikes latex_exercise_toc latex_footer latex_header latex_problems latin2html lightclean linkchecker list_fig_src_files list_labels makefile md2html md2latex old2new_format ptex2tex pygmentize ref_external remove_exercise_answers remove_inline_comments replace_from_file slides_beamer slides_html slides_markdown sphinx_dir sphinxfix_localURLs split_html split_rst teamod

doconce format html|latex|pdflatex|rst|sphinx|plain|gwiki|mwiki|
               cwiki|pandoc|st|epytext dofile 
# transform doconce file to another format

doconce subst [-s -m -x --restore] regex-pattern \ 
        regex-replacement file1 file2 ... 
# substitute a phrase by another using regular expressions (in this example -s is the re.DOTALL modifier, -m is the re.MULTILINE modifier, -x is the re.VERBOSE modifier, --restore copies backup files back again)

doconce replace from-text to-text file1 file2 ...                      
# replace a phrase by another literally (exact text substitution)

doconce replace_from_file file-with-from-to-replacements file1 file2 ... 
# replace using from and to phrases from file

doconce find expression                                                
# search for a (regular) expression in all .do.txt files in the current directory tree (useful when removing compilation errors)

doconce include_map mydoc.do.txt                                       
# print an overview of how various files are included in the root doc

doconce expand_mako mako_code_file funcname file1 file2 ...            
# replace all mako function calls by the `results of the calls

doconce remove_inline_comments dofile                                  
# remove all inline comments in a doconce file

doconce apply_inline_edits                                             
# apply all edits specified through inline comments

doconce sphinx_dir copyright='John Doe' title='Long title' \
        short_title="Short title" version=0.1 intersphinx \
        /path/to/mylogo.png dofile 
# create a directory for the sphinx format (requires sphinx version >= 1.1)

doconce format sphinx complete_file 
doconce split_rst complete_file 
doconce sphinx_dir complete_file 
python automake_sphinx.py 
# split a sphinx/rst file into parts according to !split commands

doconce insertdocstr rootdir                                           
# walk through a directory tree and insert doconce files as docstrings in *.p.py files

doconce lightclean                                                     
# remove all redundant files (keep source .do.txt and results: .pdf, .html, sphinx- dirs, .mwiki, .ipynb, etc.)

doconce clean                                                          
# remove all files that the doconce can regenerate

doconce change_encoding utf-8 latin1 dofile                            
# change encoding

doconce guess_encoding filename                                        
# guess the encoding in a text

doconce find_nonascii_chars file1 file2 ...                            
# find non-ascii characters in a file

doconce split_html complete_file.html                                  
# split an html file into parts according to !split commands

doconce slides_html slide_type complete_file.html                      
# create HTML slides from a (doconce) html file

doconce slides_beamer complete_file.tex                                
# create LaTeX Beamer slides from a (doconce) latex/pdflatex file

doconce slides_markdown complete_file.md remark --slide_style=light    
# create Remark slides from Markdown

doconce html_colorbullets file1.html file2.html ...                    
# replace bullets in lists by colored bullets

doconce extract_exercises tmp_mako__mydoc                              
# extract all exercises (projects and problems too)

doconce grab --from[-] from-text [--to[-] to-text] file > result       
# grab selected text from a file

doconce remove --from[-] from-text [--to[-] to-text] file > result     
# remove selected text from a file

doconce grep FIGURE|MOVIE|CODE dofile                                  
# list all figure, movie or included code files

doconce spellcheck [-d .mydict.txt] *.do.txt                           
# run spellcheck on a set of files

doconce ptex2tex mydoc -DMINTED pycod=minted sys=Verbatim \
        dat=\begin{quote}\begin{verbatim};\end{verbatim}\end{quote} 
# transform ptex2tex files (.p.tex) to ordinary latex file and manage the code environments

doconce md2html file.md                                                
# make HTML file via pandoc from Markdown (.md) file

doconce md2latex file.md                                               
# make LaTeX file via pandoc from Markdown (.md) file

doconce combine_images image1 image2 ... output_file                   
# combine several images into one

doconce latex_problems mydoc.log [overfull-hbox-limit]                 
# report problems from a LaTeX .log file

doconce list_fig_src_files *.do.txt                                    
# list all figure files, movie files, and source code files needed

doconce list_labels myfile                                             
# list all labels in a document (for purposes of cleaning them up)

doconce ref_external mydoc [pubfile]                                   
# generate script for substituting generalized references

doconce linkchecker *.html                                             
# check all links in HTML files

doconce capitalize [-d .mydict.txt] *.do.txt                           
# change headings from "This is a Heading" to "This is a heading"

doconce latex2doconce latexfile                                        
# translate a latex document to doconce (requires usually manual fixing)

doconce latex_dislikes latexfile                                       
# check if there are problems with translating latex to doconce

doconce ipynb2doconce notebookfile                                     
# translate an IPython/Jupyter notebook to doconce

doconce pygmentize myfile [pygments-style]                             
# typeset a doconce document with pygments (for pretty print of doconce itself)

doconce makefile docname doconcefile [html sphinx pdflatex ...]        
# generate a make.py script for translating a doconce file to various formats

doconce diff file1.do.txt file2.do.txt [diffprog]                      
# find differences between two files (diffprog can be difflib, diff, pdiff, latexdiff, kdiff3, diffuse, ...)

doconce gitdiff file1 file2 file3 ...                                  
# find differences between the last two Git versions of several files

doconce csv2table somefile.csv                                         
# convert csv file to doconce table format

doconce sphinxfix_local_URLs file.rst                                  
# edit URLs to local files and place them in _static

doconce latin2html file.html                                           
# replace latex-1 (non-ascii) characters by html codes

doconce fix_bibtex4publish file1.bib file2.bib ...                     
# fix common problems in bibtex files for publish import

doconce latex_header                                                   
# print the header (preamble) for latex file

doconce latex_footer                                                   
# print the footer for latex files

doconce expand_commands file1 file2 ...                                
# expand short cut commands to full form in files

doconce latex_exercise_toc myfile                                      
# insert a table of exercises in a latex file myfile.p.tex
}}}

== Exercises ==

DocOnce supports //Exercise//, //Problem//, //Project//, and //Example//.
These are typeset
as ordinary sections and referred to by their section labels.
Exercise, problem, project, or example sections contains certain //elements//:


  * a headline at the level of a subsection    containing one of the words "Exercise:", "Problem:",    "Project:", or "Example:", followed by a title (required)
  * a label (optional)
  * a solution file (optional)
  * name of file with a student solution (optional)
  * main exercise text (required)
  * a short answer (optional)
  * a full solution (optional)
  * one or more hints (optional)
  * one or more subexercises (subproblems, subprojects), which can also    contain a text, a short answer, a full solution, name student file    to be handed in, and one or more hints (optional)

A typical sketch of a a problem without subexercises goes as follows:
{{{
===== Problem: Derive the Formula for the Area of an Ellipse =====
label{problem:ellipsearea1}
file=ellipse_area.pdf
solution=ellipse_area1_sol.pdf

Derive an expression for the area of an ellipse by integrating
the area under a curve that defines half of the ellipse.
Show each step in the mathematical derivation.

!bhint
Wikipedia has the formula for the curve.
!ehint

!bhint
"Wolframalpha": "http://wolframalpha.com" can perhaps
compute the integral.
!ehint
}}}
If the exercise type (Exercise, Problem, Project, or Example)
is enclosed in braces, the type is left out of the title in the
output. For example, the if the title line above reads

{{{
===== {Problem}: Derive the Formula for the Area of an Ellipse =====
}}}
the title becomes just "Derive the ...".

An exercise with subproblems, answers and full solutions has this
setup-up:

{{{
===== Exercise: Determine the Distance to the Moon =====
label{exer:moondist}

Intro to this exercise. Questions are in subexercises below.

!bsubex
Subexercises are numbered a), b), etc.

file=subexer_a.pdf

!bans
Short answer to subexercise a).
!eans

!bhint
First hint to subexercise a).
!ehint

!bhint
Second hint to subexercise a).
!ehint
!esubex

!bsubex
Here goes the text for subexercise b).

file=subexer_b.pdf

!bhint
A hint for this subexercise.
!ehint

!bsol
Here goes the solution of this subexercise.
!esol
!esubex

!bremarks
At the very end of the exercise it may be appropriate to summarize
and give some perspectives. The text inside the `!bremarks` and `!eremarks`
directives is always typeset at the end of the exercise.
!eremarks

!bsol
Here goes a full solution of the whole exercise.
!esol

}}}
By default, answers, solutions, and hints are typeset as paragraphs.
The command-line arguments {{{--without_answers}}} and {{{--without_solutions}}}
turn off output of answers and solutions, respectively, except for examples. The command line options {{{--answers_at_end}}} and {{{--solutions_at_end}}} write all answers and solutions to exercises to a separate section at the end of the document, respectively. Combine with {{{--without_answers}}} and {{{--without_solutions}}} to remove answers and solutions from the main text.

The commands {{{!anshide}}} and {{{!solhide}}} can be used to hide from the main text answers and solutions, respectively, until the {{{!ansoff}}} and {{{!soloff}}} commands are encountered. Similarly, the {{{!ansdocend}}} and {{{!soldocend}}} commands move answers and solutions to the end of the book. 

== Environments ==

DocOnce environments start with {{{!benvirname}}} and end with {{{!eenvirname}}},
where {{{envirname}}} is the name of the environment. Here is a listing of
the environments:


 * {{{c}}}: computer code (or verbatim text)
 * {{{t}}}: math blocks with LaTeX syntax
 * {{{subex}}}: sub-exercise
 * {{{ans}}}: short answer to exercise or sub-exercise
 * {{{sol}}}: full solution to exercise or sub-exercise
 * {{{hint}}}: multiple help items in an exercise or sub-exercise
 * {{{quote}}}: indented text
 * {{{notice}}}, {{{summary}}}, {{{warning}}}, {{{question}}}: admonition boxes with    custom title, special icon, and (sometimes) background color
 * {{{block}}}, {{{box}}}: simpler boxes ({{{block}}} may have title but never any icon)
 * {{{pop}}}: text to gradually pop up in slide presentations
 * {{{slidecell}}}: indication of cells in a grid layout for elements on a   slide

In addition, the user can define new environments {{{!bc-name}}} as
explained in the [[http://doconce.github.io/doconce/doc/pub/manual/manual.html#manual:userdef:envir|manual]].

== Preprocessing ==

DocOnce documents may utilize a preprocessor, either {{{preprocess}}} and/or
{{{mako}}}. The former is a C-style preprocessor that allows if-tests
and including other files (but not macros with arguments).
The {{{mako}}} preprocessor is much more advanced - it is actually a full
programming language, very similar to Python.

The command {{{doconce format}}} first runs {{{preprocess}}} and then {{{mako}}}.
Here is a typical example on utilizing {{{preprocess}}} to include another
document, "comment out" a large portion of text, and to write format-specific
constructions:

{{{
# #include "myotherdoc.do.txt"

# #if FORMAT in ("latex", "pdflatex")
\begin{table}
\caption{Some words... label{mytab}}
\begin{tabular}{lrr}
\hline\noalign{\smallskip}
\multicolumn{1}{c}{time} & \multicolumn{1}{c}{velocity} & \multicolumn{1}{c}{acceleration} \\ 
\hline
0.0          & 1.4186       & -5.01        \\ 
2.0          & 1.376512     & 11.919       \\ 
4.0          & 1.1E+1       & 14.717624    \\ 
\hline
\end{tabular}
\end{table}
# #else
  |--------------------------------|
  |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    |
  |--------------------------------|
# #endif

# #ifdef EXTRA_MATERIAL
....large portions of text...
# #endif
}}}

With the {{{mako}}} preprocessor the if-else tests have slightly different syntax.
An [[http://doconce.github.com/bioinf-py/|example document]] contains
some illustrations on how to utilize {{{mako}}} (clone the GitHub project and
examine the DocOnce source and the {{{doc/src/make.sh}}} script).

== Resources ==


 * Excellent "Sphinx Tutorial" by C. Reller: "http://people.ee.ethz.ch/~creller/web/tricks/reST.html"



************** File: quickref.st *****************
TITLE: DocOnce Quick Reference
BY: Hans Petter Langtangen (Center for Biomedical Computing, Simula Research Laboratory, and Department of Informatics, University of Oslo)
DATE: Jan 32, 2100
**WARNING: This quick reference is very incomplete!**

*Mission.* Enable writing documentation with much mathematics and
computer code *once, in one place* and include it in traditional LaTeX
books, thesis, and reports, and, without extra efforts, also make
professional looking web versions with Sphinx or HTML. Other outlets
include Google's 'blogger.com', Wikipedia/Wikibooks, IPython/Jupyter
notebooks, plus a wide variety of other formats for documents without
mathematics and code.

Supported Formats

DocOnce currently translates files to the following formats:

 - LaTeX (format 'latex' or 'pdflatex')
 - HTML (format 'html')
 - Sphinx (format 'sphinx')
 - Pandoc-extended or GitHub-flavored Markdown (format 'pandoc')
 - IPython notebook (format 'ipynb')
 - Matlab notebook (format 'matlabnb')
 - MediaWiki (format 'mwiki')
 - Googlecode wiki (format 'gwiki')
 - Creoloe wiki (format 'cwiki')
 - reStructuredText (format 'rst')
 - plain (untagged) ASCII (format 'plain')
 - Epydoc (format 'epydoc')
 - StructuredText (format 'st')

For documents with much code and mathematics, the best (and most supported)
formats are 'latex', 'pdflatex', 'sphinx', and 'html'; and to a slightly
less extent 'mwiki' and 'pandoc'. The HTML format supports blog posts on
Google and Wordpress.

*Use a text editor with monospace font!* 
Some DocOnce constructions are sensitive to whitespace,
so you *must* use a text editor with monospace font.



Emacs syntax support

The file "https://github.com/doconce/doconce/blob/master/misc/.doconce-mode.el":.doconce-mode.el
in the DocOnce source distribution gives a "DocOnce Editing Mode" in
Emacs. Store the raw version of the file in the home directory and add
'(load-file "~/.doconce-mode.el")' to the '.emacs' file.

Besides syntax highlighting of DocOnce documents, this Emacs mode
provides a lot of shortcuts for setting up many elements in a document:

=============  ======================================  
  Emacs key                    Action                  
=============  ======================================  
Ctrl+c f       figure                                  
Ctrl+c v       movie/video                             
Ctrl+c h1      heading level 1 (section/h1)            
Ctrl+c h2      heading level 2 (subsection/h2)         
Ctrl+c h3      heading level 2 (subsection/h3)         
Ctrl+c hp      heading for paragraph                   
Ctrl+c me      math environment: '!bt' equation '!et'  
Ctrl+c ma      math environment: '!bt' align '!et'     
Ctrl+c ce      code environment: '!bc' code '!ec'      
Ctrl+c cf      code from file: '@@@CODE'               
Ctrl+c table2  table with 2 columns                    
Ctrl+c table3  table with 3 columns                    
Ctrl+c table4  table with 4 columns                    
Ctrl+c exer    exercise outline                        
Ctrl+c slide   slide outline                           
Ctrl+c help    print this table                        
=============  ======================================  

Title, Authors, and Date

A typical example of giving a title, a set of authors, a date,
and an optional table of contents
reads::

        TITLE: On an Ultimate Markup Language
        AUTHOR: H. P. Langtangen at Center for Biomedical Computing, Simula Research Laboratory & Dept. of Informatics, Univ. of Oslo
        AUTHOR: Kaare Dump Email: dump@cyb.space.com at Segfault, Cyberspace Inc.
        AUTHOR: A. Dummy Author
        DATE: today
        TOC: on

The entire title must appear on a single line.
The author syntax is::

        name Email: somename@adr.net at institution1 & institution2

where the email is optional, the "at" keyword is required if one or
more institutions are to be specified, and the '&' keyword
separates the institutions (the keyword 'and' works too).
Each author specification must appear
on a single line.
When more than one author belong to the
same institution, make sure that the institution is specified in an identical
way for each author.

The date can be set as any text different from 'today' if not the
current date is wanted, e.g., 'Jan 32, 2100'.

The table of contents is removed by writing 'TOC: off'.

Copyright

Copyright for selected authors and/or institutions are easy to insert as part
of the 'AUTHOR' command. The copyright syntax is::

        {copyright,year1-year2|license}

and can be placed after the author or after an institution, e.g.::

         AUTHOR: name Email: somename@adr.net {copyright,2006-present} at inst1
         AUTHOR: name {copyright} at inst1 {copyright}

The first line gives 'name' a copyright for 2006 up to the present year,
while the second line gives copyright to 'name' and the institution 'inst1'
for the present year. The license can be any formulation, but there are
some convenient abbreviations for Creative Commons ("public domain")
licenses: 'CC BY' for Creative Commons Attrib