Keywords: key word1,key word2

# Test slide features

Core Dump
Cyber Space Ltd

#### Apr 15, 2021

# 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 BW books Colorful PDF books (printed and screen) Designed web pages Wikis Blog posts 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/`

- LaTeX-based PDF for screen, for printing, for phone

- Plain HTML or with a template or another template or solarized

- Sphinx: agni, pyramid, classy, fenics, redcloud

- HTML for Google or Wordpress blog posts

- MediaWiki (Wikipedia, Wikibooks, etc)

- DocOnce source code and manual

# 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

- and sublists with enumerated items starting with `o`

- 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 $$ |