Special features for teaching material

DocOnce offers some special features that can greatly aid development of effective teaching material:

fancy admonitions
simple boxes
interactive code blocks
hidden code blocks
exercises
multiple-choice questions or quizzes
movies
quotes

These are briefly exemplified below. If you are mainly interested in how to structure DocOnce-based books, you can safely jump to the section Assembling different pieces to a book.

Admonitions

Use admonitions! Need to notify, warn, summarize, ask a question, give a tip, dive into less important details, or really emphasize a result? DocOnce features special notice, warning, summary, and question boxes called admonitions. These can be typeset in a variety of versions, depending on the output format (check out doconce format --help and the many options with admon in the name).

Simple box

Put a box around something important:

$$ 1 + 1 = 2 $$

Embedded interactive code

The `pyoptpro` code environment

To illustrate program flow, you can step through code (as in a debugger, just more illustrative) using the pyoptpro code environment. Here is an example:

In HTML and Sphinx format this code can be stepped through in the browser, while in LaTeX one gets a link to a web page with this functionality.

The `pyscpro` code environment

The SageMathCell server enables live Python code in web documents. Using the pyscpro code environment, Python code can be embedded in a for interactive computing:

We can even plot:

HTML and Sphinx output has such interactive Sage Cells, while other output formats can just show the code.

Exercises

Exercise environments. DocOnce supports exercise subsections, which are subsections with some extra tagging for exercises. Important features are:

exercises can be divided into subexercises
one may specify filename(s) for delivering the answer to an exercise
one may specify filename(s) for the solution of an exercise
one may specify a remark (fun facts, comments)
one or more hints can be given to an exercise or subexercise (can be hidden in certain output formats)
any exercise or subexercise can have a solution field
any exercise or subexercise can have an answer field (very condensed solution)
solutions and answers can be removed from the document at compile time
exercises can have one of four titles: Exercise, Project, Problem, or Example

Quote

There is also a quote environment (invisible box with larger margins).

We're programmers. Programmers are, in their hearts, architects, and the first thing they want to do when they get to a site is to bulldoze the place flat and build something grand. We're not excited by incremental renovation: tinkering, improving, planting flower beds.
There's a subtle reason that programmers always want to throw away the code and start over. The reason is that they think the old code is a mess. And here is the interesting observation: they are probably wrong. The reason that they think the old code is a mess is because of a cardinal, fundamental law of programming: It's harder to read code than to write it. This is why code reuse is so hard. This is why everybody on your team has a different function they like to use for splitting strings into arrays of strings. They write their own function because it's easier and more fun than figuring out how the old function works.
Joel Spolsky, 2000

Quiz

Question: Does DocOnce feature multiple-choice questions or quizzes?

Choice A: Yes.

See the quiz manual.

Choice B: No.

Wrong!

Quite often we need mathematics and computer code in questions and answers.

Question: Compute the integral $$ \int_0^{2\pi} e^{-x}\sin^2 x\,dx $$ and report the formula in verbatim LaTeX code,

\[ \int_0^{2\pi} e^{-x}\sin^2 x\,dx = ... \]

Choice A: There is no closed-form formula for this integral.

Maybe you fiddled around with pen and paper the wrong way... Try sympy!

Choice B:

>>> from sympy import *
>>> x = symbols('x')
>>> F = integrate(exp(-x)*sin(x)**2, (x, 0, 2*pi))
>>> F
-2*exp(-2*pi)/5 + 2/5
>>> latex(F)
'- \\frac{2}{5 e^{2 \\pi}} + \\frac{2}{5}'

so the answer is

\[ \int_0^{2\pi} e^{-x}\sin^2 x\,dx =
- \frac{2}{5 e^{2 \pi}} + \frac{2}{5} \]

Correct!

Choice C:

\[ \int_0^{2\pi} e^{-x}\sin^2 x\,dx =
- \frac{3}{4 e^{2 \pi}} + \frac{3}{4} \]

Something went wrong here with the fractions...

Choice D:

\[ \int_0^{2\pi} e^{-x}\sin^2 x\,dx =
- {2\over5}{5 exp^{2 pi}} + \frac{2}{5} \]

Well, the math is correct, but the LaTeX code lacks two backslashes, and \over is old-fashioned, use \frac{}{} in 2015.

The typesetting of a quiz depends on the output format. One can output in plain HTML and Sphinx formats, hover over the choice and get a pop-up tooltip with the right answer and an explanation (if defined). The explanation can only show plain text, so it is empty if it contains math or code blocks, or figures. With HTML Bootstrap styles one can click on a symbol to open up the answer and the explanation. RunestoneInteractive books (Sphinx) offers a button for the same purpose, but the explanation can only be plain text so any math or code block makes the explanation empty. LaTeX output can feature the choices only (no answer, no explanation: --without_solutions --without_answers), the short answer only (--without_solutions) or both the answer and all explanations (the case in this demo).

What about a video lecture?

Question. Can you think of applications of the above mentioned features?

References

H. P. Langtangen. Debugging in Python, \emphhttp://hplgit.github.io/primer.html/doc/pub/debug, http://hplgit.github.io/primer.html/doc/pub/debug.
H. P. Langtangen. A Primer on Scientific Programming With Python, fourth edition, Texts in Computational Science and Engineering, Springer, 2014.
H. P. Langtangen. Some document, \emphhttp://hplgit.github.io/setup4book-doconce/doc/pub/fake/html, http://hplgit.github.io/setup4book-doconce/doc/pub/fake/html.