Keywords: key word1,key word2

# Test slide features

Core Dump

Cyber Space Ltd

#### Mar 1, 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
Scientific writing for the future needs to address many new media
Fundamental question
LaTeX is very rich; other tools support only some elements
LaTeX is very rich; other tools support only some elements
DocOnce demo
A tour of DocOnce
DocOnce: title, authors, date, toc
DocOnce: abstract
DocOnce: section headings
This is an H1/chapter heading
This is an H2/section heading
This is an H3/subsection heading
DocOnce: markup and lists
DocOnce: labels, references, index items
DocOnce: figures and movies
DocOnce: math
DocOnce: displaying code
DocOnce: displaying interactive demo code
DocOnce: exercises
DocOnce: exercises
Problem 1: Flip a Coin
DocOnce: example on slide code
DocOnce: example on slide code
Headline
DocOnce: example on slide code with cells
DocOnce: example on slide code
Headline

## 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: [../doc/src/slides/fig/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: [../doc/src/slides/fig/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 $$ |