Test slide features

Core Dump

Cyber Space Ltd

Mar 16, 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

  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: [../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 $$