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

Note: Simple boxes are not supported in format sphinx.

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.

? #

Choice B: No.

?

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.

? #

Choice B: .. code-block:: python

>>> 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} \]

?

Choice C: .. code-block:: latex

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

? #

Choice D: .. code-block:: latex

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

? #

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

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