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

Problems

RunestoneInteractive books has nice support for interactive code, but there are at present problems with the rendering in HTML.

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:

(codelens_1)

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 live code cell Sage Cell

     import random
     a = random.randint(1, 7)
     print a

(activecode_1)

We can even plot:

     from numpy import *
     from matplotlib.pyplot import *

     x = linspace(-2*pi, 2*pi, 801)
     y = exp(-0.1*x**2)*sin(4*x)
     plot(x, y)
     show()

(activecode_2)

RunestoneInteractive books have such interactive cells, but they do not seem to work well (?) yet, 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¶

Q-1: Does DocOnce feature multiple-choice questions or quizzes?

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

Remark

RunestoneInteractive books has nice support for quizzes, but mathematics and code blocks (or other types of advanced formatting) are not allowed in answers and feedbacks.

Q-2: 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 = ... \]

The typesetting of a quiz depends on the output format. One can 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?