Test slide features

Core Dump
Cyber Space Ltd

Jan 10, 2022



Table of contents


Scientific writing for the future needs to address many new media




The book will probably survive


The classical report will survive



Scope

  • Scope: documents with much math and computer code
  • Key question: What tools should I use for writing?
  • Default answer: LaTeX
  • Alternative: MS Word w/math
  • Recent popular alternative tools: HTML w/MathJax, Sphinx, Markdown, MediaWiki, IPython notebook







Scientific writing for the future needs to address many new media

Old days (1985-2005): LaTeX for BW paper output, but now

  1. BW books
  2. Colorful PDF books (printed and screen)
  3. Designed web pages
  4. Wikis
  5. Blog posts
  6. Next new fancy format (iBook w/LaTeX?)


Fundamental question

When I write some scientific material,

  • a LaTeX document,
  • a blog post (HTML),
  • some web pages (HTML),
  • a Sphinx document,
  • some Markdown files,

and later want to collect the pieces into a larger document, maybe some book, or one big web document, is that at all feasible?

Probably not, but I have a solution :-)

LaTeX is very rich; other tools support only some elements

  • LaTeX inline math: works with all (LaTeX, MathJax, Sphinx, Markdown, MediaWiki)
  • LaTeX equation math:
    • LaTeX: equation*, equation, align*, align + eqnarray, split, alignat, ... (numerous!)
    • MathJax: equation*, equation, align*, align
    • MediaWiki: equation*, equation, align*, align
    • Sphinx: equation*, equation, align*
    • Markdown: equation*, equation, eqnarray*, align* (but no labels)

LaTeX is very rich; other tools support only some elements

  • Figures: all
  • Subfigures: LaTeX (subfigure)
  • Movies: LaTeX (can run separately), just raw embedded HTML in others
  • Floating computer code: LaTeX
  • Fixed computer code: all
  • Floating tables: LaTeX; inline tables: all
  • Algorithms: LaTeX
  • Margin notes: LaTeX
  • Page references: LaTeX
  • Footnotes: LaTeX, Sphinx, reStructuredText, MediaWiki
  • Bibliography: LaTeX, Sphinx, reStructuredText, MediaWiki
  • Hyperlinks: all (but not on paper!)

Conclusion: Highly non-trivial to translate a LaTeX document into something based on HTML and vice versa.

DocOnce demo

https://hplgit.github.com/teamods/writing_reports/

A tour of DocOnce

DocOnce: title, authors, date, toc

TITLE: Some Title
AUTHOR: name1 at institution1, with more info & institution2
AUTHOR: name2 email:name2@web.com at institution
DATE: today

# A table of contents is optional:
TOC: on
Notice

Title and authors must have all information on a single line!

DocOnce: abstract

__Abstract.__
Here goes the abstract...

Or:

__Summary.__
Here goes the summary...

DocOnce: section headings

Headings are surrounded by = signs:

======= This is an H1/chapter heading =======

===== This is an H2/section heading =====

===== This is an H3/subsection heading =====

=== This is an H4/paragraph heading ===

__This is a paragraph heading.__

Result:

This is an H1/chapter heading

This is an H2/section heading

This is an H3/subsection heading

This is an H4/paragraph heading

This is a paragraph heading.

DocOnce: markup and lists

 * Bullet list items start with `*`
   and may span several lines
 * *Emphasized words* are possible
 * _Boldface words_ are also possible
 * color{red}{colored words} too
 * `inline verbatim code` is featured
   o and sublists with enumerated items starting with `o`
   o items are just indented as you would do in email

This gets rendered as

  • Bullet lists start with * and may span several lines
  • Emphasized words are possible
  • Boldface words are also possible
  • colored words too
  • inline verbatim code is featured

    1. and sublists with enumerated items starting with o
    2. items are just indented as you would do in email

DocOnce: labels, references, index items

# Insert index items in the source
idx{key word1} idx{key word2}

# Label
===== Some section =====
label{this:section}

# Make reference
As we saw in Section ref{this:section}, references, index
items and labels follow a syntax similar to LaTeX
but without backslashes.

# Make reference to equations
See \eqref{eq1}-\eqref{myeq}.

# Make hyperlink
"some link text": "https://github.com/doconce/doconce"

# Hyperlink with complete URL as link text
URL: "https://github.com/doconce/doconce"

DocOnce: figures and movies

Notice

Figure with HTML and LaTeX info, and caption, all on one line:

FIGURE: [figdir/myfig, width=300, frac=1.2] My caption. label{fig1}

# This figure will be 300 pixels wide in HTML and span 1.2 times
# the linewidth in LaTeX.

Movies are also supported:

MOVIE: [https://www.youtube.com/embed/P8VcZzgdfSc, width=420, height=315]

and rendered as

DocOnce: math

Inline math as in LaTeX:

...where $a=\int_{\Omega}fdx$ is an integral.

gets rendered as ...where \( a=\int_{\Omega}fdx \) is an integral.

An equation environment is surrounded by !bt and !et tags, the rest is plain LaTeX:

!bt
\begin{align}
\frac{\partial u}{\partial t} &= \nabla^2 u,
label{a:eq}\\
\nabla\cdot\pmb{v} & = 0
label{b:eq}
\end{align}
!et

which is rendered as

 
$$ \begin{align} \frac{\partial u}{\partial t} &= \nabla^2 u, \tag{1}\\ \nabla\cdot\pmb{v} & = 0 \tag{2} \end{align} $$

 

DocOnce: displaying code

Code is enclosed in !bc and !ec tags:

!bc pycod
def solver(I, a, T, dt, theta):
    """Solve u'=-a*u, u(0)=I, for t in (0,T] with steps of dt."""
    dt = float(dt)           # avoid integer division
    N = int(round(T/dt))     # no of time intervals
    T = N*dt                 # adjust T to fit time step dt
    u = zeros(N+1)           # array of u[n] values
    t = linspace(0, T, N+1)  # time mesh

    u[0] = I                 # assign initial condition
    for n in range(0, N):    # n=0,1,...,N-1
        u[n+1] = (1 - (1-theta)*a*dt)/(1 + theta*dt*a)*u[n]
    return u, t
!ec

This gets rendered as

def solver(I, a, T, dt, theta):
    """Solve u'=-a*u, u(0)=I, for t in (0,T] with steps of dt."""
    dt = float(dt)           # avoid integer division
    N = int(round(T/dt))     # no of time intervals
    T = N*dt                 # adjust T to fit time step dt
    u = zeros(N+1)           # array of u[n] values
    t = linspace(0, T, N+1)  # time mesh

    u[0] = I                 # assign initial condition
    for n in range(0, N):    # n=0,1,...,N-1
        u[n+1] = (1 - (1-theta)*a*dt)/(1 + theta*dt*a)*u[n]
    return u, t
Language-dependent typesetting of code:

The !bc command can be followed by a specification of the computer language: pycod for Python code snippet, pypro for complete Python program, fcod for Fortran snippet, fpro for Fortran program, and so forth (c for C, cpp for C++, sh for Unix shells, m for Matlab).

DocOnce: displaying interactive demo code

With !bc pyoptpro or a file *.pyopt, the code applies the Online Python Tutor for displaying program flow and state of variables:

DocOnce: exercises

DocOnce offers a special format for exercises, problems, projects, and examples:

===== Problem: Flip a Coin =====
label{demo:ex:1}

files = flip_coin.py, flip_coin.pdf
solutions = mysol.txt, mysol_flip_coin.py
keywords = random numbers; Monte Carlo simulation

!bsubex
Make a program that simulates flipping a coin $N$ times.

!bhint
Use `r = random.random()` and define head as `r <= 0.5`.
!ehint
!esubex

!bsubex
Compute the probability of getting heads.

!bans
A short answer: 0.5.
!eans

!bsol
A full solution to this subexercise can go here.
!esol
!esubex

!bsubex
Make another program that computes the probability
of getting at least three heads out of 5 throws.
!esubex

Solutions/answers can easily be left out of the document.

DocOnce: exercises

Last page gets rendered as follows:

Problem 1: Flip a Coin

a) Make a program that simulates flipping a coin \( N \) times.

Hint. Use r = random.random() and define head as r <= 0.5.

b) Compute the probability of getting heads.

Answer. A short answer: 0.5.

Solution. A full solution to this subexercise can go here.

c) Make another program that computes the probability of getting at least three heads out of 5 throws.

Filenames: flip_coin.py, flip_coin.pdf.

DocOnce: example on slide code

!split
===== Headline =====

 * Key point 1
 * Key point 2
 * Key point 3 takes very much more text to explain because
   this point is really comprehensive, and although long
   bullet points are not recommended in general, we need
   it here for demonstration purposes

FIGURE: [testfigs/teacher1, width=100]

Key equation:

!bt
\[ -\nabla^2 u = f \quad\hbox{in }\Omega \]
!et

And maybe a final comment?

!split
===== Next slide... =====

DocOnce: example on slide code

Last page gets rendered to

Headline

  • Key point 1
  • Key point 2


Key equation:

 
$$ -\nabla^2 u = f \quad\hbox{in }\Omega $$

 

And maybe a final comment?

DocOnce: example on slide code with cells

One can introduce a table-like layout with MxN cells and put slide elements in various cell. A cell with position MN is surrounded by !bslidecell MN and !eslidecell tags. Below is an example with a bullet list to the left and a figure to the right (two cells, numbered 00 and 01).

!split
===== Headline =====

!bslidecell 00
!bpop
 * Key point 1
 * Key point 2
 * Key point 3 takes very much more text to explain because
   this point is really comprehensive, and although long
   bullet points are not recommended in general, we need
   it here for demonstration purposes
!epop

!bpop
!bt
\[ -\nabla^2 u = f \quad\hbox{in }\Omega \]
!et
!epop

!eslidecell

!bslidecell 01
FIGURE: [testfigs/broken_pen_and_paper, width=400, frac=0.8]
!eslidecell

!split
===== Next slide... =====

DocOnce: example on slide code

Last page gets rendered to

Headline

  • Key point 1
  • Key point 2
  • Key point 3 takes very much more text to explain because this point is really comprehensive, and although long bullet points are not recommended in general, we need it here for demonstration purposes

 
$$ -\nabla^2 u = f \quad\hbox{in }\Omega $$