The format of this document is plain, homemade HTML (from DocOnce).

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
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 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 (12) is fine. Eq. (12) too. Even Equation (12) without the tilde. This equation appears in another part if this document is split.

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 red color, and links as well as math: \( 1+1=2 \).

Test also that emphasize at the end of line, and bold works, as well as color and links2 and verbatim as well.

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,

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
      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,

1
2
3
4
5
6
7
8
      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):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
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:

1
2
3
4
!bc pycod
def f(x):
    return x+1
!ec

which gets rendered as

1
2
def f(x):
    return x+1

Test paragraph and subsubsection headings before before code.

Paragraph heading before code.

1
2
import sys
sys.path.insert(0, os.pardir)

Subsubsection heading before code

1
2
def h(z):
    return z+1

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

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

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

Standard Python shell sessions:

1
2
3
4
5
6
7
8
>>> 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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
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.

1
2
3
4
5
6
7
8
>>> 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++:

1
2
3
4
5
6
7
#include <iostream>

int main()
{
   std::cout << "Sample output" << std::endl;
   return 0
}

And a little bit of Fortran:

1
2
3
4
5
6
7
8
!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

1
2
3
4
5
6
      subroutine midpt(x, length, a, b)
      real*8 a, b, x
      x = (a + b)/2
      length = b - a
      return
      end

HTML:

1
2
3
4
5
<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:

1
2
3
4
5
% 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:

1
2
3
4
5
Terminal> mkdir test
Terminal> cd test
Terminal> myprog -f
output1
output2

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

1
2
3
4
5
6
7
!bc restructuredtext
=======
Heading
=======

Some text.
!ec

results in

1
2
3
4
5
=======
Heading
=======

Some text.

Finally, !bc do supports highlighting of DocOnce source:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
======= 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}.

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

1
2
3
4
5
Terminal> python -c 'print("Testing\noutput\nfrom\nPython.")'
Testing
output
from
Python.

Footnotes

Here is a test of footnotes [1], 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 \) [2]
and code h[i] += 1 [3] (must have space between inline code and footnote!)
and links [4]

which gives flexibility in writing. This is the third [5] example.

1: 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.

2: Math footnotes can be dangerous since it interferes with an exponent.

3: One-line footnote.

4: 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, 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 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 1 in which there is a flow.


Figure 1: Visualization of a wave.

Figures without captions are allowed and will be inlined.





Here is figure 2 with a long (illegal) multi-line caption containing inline verbatim text:


Figure 2: 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} \).

Test URL as figure name:





Test SVG figure:





HTML output may feature Bokeh plots:





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 \):

1
2
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} \tag{1}\\ \frac{1}{2}\pmb{x} &= \pmb{n} \tag{2} \end{align} $$

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

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

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

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 (10)-(11).

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. \( \Diamond \)

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

1
2
3
4
5
6
7
  |--------------------------------|
  |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.

\( \mathcal{L}=0 \)
\( a=b \)
\( \nabla\cdot\boldsymbol{u} =0 \)

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.

1
2
# 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.

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.

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.

1
2
3
4
5
6
7
8
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, 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. Can test spaces with the link with word too: hpl or hpl. Also file:/// works: 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: hpl@simula.no, or just a mail link, or a raw mailto:hpl@simula.no.

Here are some tough tests of URLs, especially for the latex format: Newton-Cotes formulas and a 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 decay_mod, ball1.py, and ball2.py.

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

\
« Previous
\
Next »