admon.do.txt

TITLE: Testing admons
AUTHOR: H. P. Langtangen {copyright}
DATE: today


!split
======= Introduction =======
First some ordinary text to compare font sizes in admonitions
and the surrounding text.

# #if FORMAT == "sphinx"
Note that `automake_sphinx.py` fixes the HTML file generated by Sphinx
so that all styles for admonitions have a colored background.
# #endif

===== Code =====

Need some code outside admons for color and font comparisons:

!bc pycod
def some_code(x):
    return sin(x)*exp(1-x)
!ec

And some plain text verbatim:

!bc
x=1.0 y=0.9 z=0.4
x=1.1 y=0.3 z=0.1
!ec

===== Quotes and boxes =====

Here is a plain quote environment.

!bquote
Sayre's law states that
``in any dispute the intensity of feeling is inversely
proportional to the value of the issues at stake.'' <linebreak>
By way of corollary, it adds: <linebreak>
``That is why academic politics are so bitter.'' <linebreak>
*Source*: "wikipedia": "https://en.wikipedia.org/wiki/Sayre's_law"
!equote

Does quotes with title also work? No...cannot work in LaTeX and HTML
and then it does not make sense to support it.

# #if FORMAT in ("sphinx", "rst")
!bwarning
The boxes below are shown without any extra formatting in reST
and Sphinx. We could use an admonition environment, but requires
a title.
!ewarning
# #endif

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:

!bbox
A generic equation

!bt
\[ f(x) = 0 \]
!et
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
!ebox
Now test a box with equation only (note that this line continues the
box, it is not a new paragraph):

!bbox
!bt
\begin{equation} f(x) = \sin(x)e^{1-x} \end{equation}
!et
!ebox

!bhint
Newton's method requires a good start vector to converge fast.
!ehint

Let's begin a new paragraph and show a box with code only:

!bbox
!bc pycod
def some_code(x):
    return sin(x)*exp(1-x)
!ec
!ebox



===== Admonitions =====

Let us start with a plain warning environment.

!bwarning
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.
!ewarning

Test warning with title:

!bwarning (large) Title ending with math $\sqrt{2}\approx 1.4$
And here comes some text with bad news in larger font.

Also some code:

!bc pycod
def f(x):
    return x
!ec
And a complete program

!bc pypro
print("Hello, World!")
!ec
!ewarning

Test warning with large title with math:
# #if FORMAT == "sphinx"
(we have no impact on the font size in the title in Sphinx)
# #endif

!bwarning (large) Watch out for $\nabla\cdot\bm{u}=0$ equations
Divergence freedom is often problematic from a numerical point
of view.
!ewarning

Then we test a block, which is guaranteed to never have any admon icon.

!bblock (small) 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.
!eblock

# #if FORMAT == "sphinx"
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:
# #endif

!bblock
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.
!eblock

# Note that the final ! does not appear in Sphinx and reST since
# those formats automatically add : to the admonition title.

!bnotice (illegal-size) 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}$:

!bt
\begin{align*}
\theta &= q^2,\\
\bm{r} &= \varrho\bm{i}
\end{align*}
!et
!enotice

# Test one word with a number

!bnotice Point1
Ah, we are soon close to the end.
!enotice

!bquestion
So, how many admonition environments does DocOnce support?
!equestion

!bquestion
  o Once more, how many admonition environments does DocOnce support?
!equestion

!bwarning Tip
It is of outmost important to

 o stay cool
 o read hints and tips carefully

Because here the thing is to do

!bc pycod
import urllib

def grab(url, filename):
    urllib.urlretrieve(url, filename=filename)
!ec
!ewarning

Next is a warning without a title ("none" implies no title).
# #if FORMAT == "sphinx"
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:"
# #endif

!bwarning none
And here comes some text with bad news.
!ewarning

===== Going deeper environments =====

Here is a long notice environment with a custom title and much
text, math and code.

!bnotice 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:

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

The implementation of such complicated equations in computer
code is task that this "Going deeper" environment targets.

!bc pycod
def Dudt(u):
    r = diff(u, t) + u*grad(u)
    return r

half = 0.5
x = 2*n
!ec
And some more text that can help going into the next page.
Longer computer code requires vertical space:

!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

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
!ec
And then we add a figure too.

FIGURE: [testfigs/wave1D, width=400, frac=0.7]
!enotice


===== The end =====

A bit of text before the summary, which we now call "Concluding remarks,
for the novice",
just because we can.

!bsummary 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.
!esummary

__Remark.__
The `remarks` and `hint` environments are not allowed outside
exercises (and problems and projects too).