# DocOnce Description¶

Authors: Hans Petter Langtangen, Kristian Gregorius Hustad Mar 13, 2017

Warning

Some parts of this manual may be outdated. Please create an issue at https://github.com/hplgit/doconce to report errors.

## What Is DocOnce?¶

DocOnce is a very simple and minimally tagged markup language that looks like ordinary ASCII text, much like what you would use in an email, but the text can be transformed to numerous other formats, including HTML, Sphinx, LaTeX, PDF, reStructuredText (reST), Markdown, MediaWiki, Creole wiki, blogger.com, wordpress.com, Epytext, and also plain (untagged) text for email. From reST or Markdown you can go to XML, OpenOffice, MS Word, HTML, LaTeX, PDF, DocBook, GNU Texinfo, and more.

DocOnce supports a working strategy of never duplicating information. Text is written in a single place and then transformed to a number of different destinations of diverse type: scientific reports, software manuals, books, thesis, software source code, wikis, blog posts, emails, etc. The slogan is: “Document once, include anywhere”.

Here are some DocOnce features:

• DocOnce addresses small and large documents containing text with much computer source code and LaTeX mathematics, where the output is desired in different formats such as LaTeX, pdfLaTeX, Sphinx, HTML, MediaWiki, blogger.com, and wordpress.com. A piece of DocOnce text can enter (e.g.) a classical science book, an ebook, a web document, and a blog post.
• DocOnce offers a range of HTML designs, including many Bootstrap and Sphinx styles and solarized color schemes. A special feature is the many styles for admonitions (boxes for warning, notice, question, etc.) in HTML and LaTeX.
• DocOnce targets in particular large book projects where many different pieces of text and software can be assembled in different ways and published in different formats for different devices (see example).
• DocOnce enables authors who write for many types of media (blog posts, wikis, LaTeX manuscripts, Sphinx, HTML) to use a common source language such that lots of different pieces can easily be brought together later to form a coherent (big) document.
• DocOnce has good support for copying computer code directly from the source code files via regular expressions for the start and end lines.
• DocOnce first runs two preprocessors (Preprocess and Mako), which allow programming constructs (includes, if-tests, function calls, variables) as part of the text. This feature makes it easy to write one text with different flavors: long vs short text, Python vs Matlab code examples, experimental vs mature content.
• DocOnce can be converted to plain untagged text, often desirable for email and computer code documentation.
• DocOnce markup does include tags, so the format is more tagged than Markdown, but less than reST, and very much less than LaTeX and HTML.
• Compared to the related tools Sphinx and Markdown, DocOnce allows more types of equations (especially systems of equations with references), has more flexible inclusion of source code, integrates preprocessors, has special support for exercises, and produces cleaner LaTeX and HTML output.

History. The DocOnce development started in 2006 at a time when most popular markup languages used quite some tagging (LaTeX, reStructuredText, HTML). Later, almost untagged markup languages became popular, especially Markdown and its sisters MultiMarkdown, Pandoc-extended Markdown, and Markua. DocOnce looks much like Markdown and is in particular close to the functionality and nature of MultiMarkdown. The advantage of DocOnce, however, is a series of features for supporting both small and large documents (books in particular) with much mathematics and computer code. While Markdown tools are heavily geared toward HTML, DocOnce has strong support for LaTeX since this is the dominating format for books and articles on mathematical subjects. DocOnce can also output Sphinx (not supported by Pandoc or MultiMarkdown), a format that is very attractive for presenting scientific material and software documentation on the web. (DocOnce allows basic Markdown syntax as input, extended with DocOnce syntax as you like.)

Disclaimer. DocOnce applies text transformations, mostly via regular expressions. This is not a fool-proof method of translation compared to real parsing. Moreover, the possibility for tweaking the layout in the DocOnce document is obviously limited (at least compared to LaTeX and HTML) since the text can go to all sorts of markup languages. This disadvantage can be quite easily compensated, however, by clever use of the programmable Mako preprocessor used by DocOnce and by automatic editing of the generated output (e.g., via regular expressions).

DocOnce has been used as writing platform for several books:

### Demos and Documentation¶

This guide is for the experienced DocOnce writer

Do not read the detailed descriptions of DocOnce syntax that follows (this is a manual!) before you have read the tutorial and played a little around with a simple document.

The primary demo for what can be achieved as output from DocOnce documents regards a little scientific report that is compiled to a range of various output documents. A version of that web page contains the specific compilation commands to create each of the output demonstrations.

There is also a demo on the many different ways one can create slides.

Write DocOnce documents in a text editor with monospace font

Some DocOnce constructions are sensitive to whitespace (indentation in lists is a primary example), so you must use a text editor with monospace font (also known as verbatim text). Never use fonts like Arial or Helvetica. (Other popular markup languages such as Sphinx and Markdown are also sensitive to whitespace and require a monospace font in the text editor.)

A lot of tips and problems have over the years been collected in the Troubleshooting and FAQ document, available in Sphinx, HTML, and PDF. The FAQ and this manual are the two key references for how to make use of DocOnce.

The DocOnce tutorial (available in Sphinx, HTML, and PDF formats) has its source code in the GitHub repository for DocOnce, more precisely in the file

doc/src/tutorial/tutorial.do.txt


One can compare this source with the output in HTML, Sphinx, and PDF. The make.sh script in the same directory tells in detail how the various versions were compiled.

The DocOnce source of the current manual is also found at the GitHub repository for DocOnce, in the file

doc/src/manual/manual.do.txt


You can compare this source with the available output in HTML, Sphinx, and PDF.

## Markup Based on Special Lines¶

The DocOnce markup language has a concept called special lines. Such lines starts with a markup at the very beginning of the line and are used to mark document title, authors, date, sections, subsections, paragraphs, figures, movies, lists, etc.

### Heading with title and author(s)¶

Lines starting with TITLE:, AUTHOR:, and DATE: are optional and used to identify a title of the document, the authors, and the date. The title is treated as the rest of the line, so is the date, but the author text consists of the name and associated institution(s) with the syntax

AUTHOR: name at institution1 and institution2 and institution3


The at with surrounding spaces is essential for adding information about institution(s) to the author name, and the and with surrounding spaces is essential as delimiter between different institutions. An email address can optionally be included, using the syntax

AUTHOR: name Email: somename@site.net at institution1 and institution2


Multiple authors require multiple AUTHOR: lines. All information associated with TITLE: and AUTHOR: keywords must appear on a single line. Here is an example:

TITLE: On an Ultimate Markup Language
AUTHOR: H. P. Langtangen at Center for Biomedical Computing, Simula Research Laboratory & Dept. of Informatics, Univ. of Oslo
AUTHOR: Kaare Dump Email: dump@cyb.space.com at Segfault, Cyberspace Inc.
AUTHOR: A. Dummy Author
DATE: November 9, 2016


Note how one can specify a single institution, multiple institutions (with & as separator between institutions), and no institution. In some formats (including rst and sphinx) only the author names appear. Some formats have “intelligence” in listing authors and institutions, e.g., the plain text format:

Hans Petter Langtangen [1, 2]
Kaare Dump  (dump@cyb.space.com) [3]
A. Dummy Author

[1] Center for Biomedical Computing, Simula Research Laboratory
[2] Department of Informatics, University of Oslo
[3] Segfault, Cyberspace Inc.


Similar typesetting is done for LaTeX and HTML formats.

The current date can be specified as today.

TOC: on


This line is usually placed after the DATE: line. The value off turns off the table of contents.

The depth of the table of contents is dictated by the command-line option --toc_depth=, which is 2 by default, meaning that sections and subsections are included, but not subsubsections. When making Sphinx documents, toc_depth= is a command-line option for for the doconce sphinx_dir command (and not doconce format).

Section headings are recognized by being surrounded by equal signs (=) or underscores before and after the text of the headline. Different section levels are recognized by the associated number of underscores or equal signs (=):

• 9 = characters for chapters
• 7 for sections
• 5 for subsections
• 3 for subsubsections
• 2 underscores (only! - it looks best) for paragraphs (paragraph heading will be inlined)

Headings can be surrounded by as many blanks as desired, but the first = must start in column 1 and there must one blank on each side of the heading, between the heading and the = signs. Here are examples on headings:

======= Example on a Section Heading =======

The running text goes here.

===== Example on a Subsection Heading =====

The running text goes here.

=== Example on a Subsubsection Heading ===

The running text goes here.

__A Paragraph.__ The running text goes here.


### Abstract¶

DocOnce also supports abstracts. The syntax is like an ordinary paragraph with heading Abstract, Summary, or Preface, but the text *must be followed by a

• table of contents (TOC:)
• date (DATE:)

Everything up to the first heading, table of contents, or date is taken as the abstract. For articles, the abstract is placed after the date, but before the table of contents or the first ordinary heading. For books one may insert the abstract before the date to make appear on the first page.

__Abstract.__ This abstract
lasts up to the section heading.

======= Here Is the First Section Heading =======

# or

__Summary.__
This is
a summary.

Even with two paragraphs. It lasts

TOC: on

# In books we may place the summary before DATE

TITLE: Some Title
AUTHOR: Some Author

__Summary.__ Here is the backmatter
promotion text for this book, appearing
on the front page...

DATE: today


### Appendix¶

Appendix is supported too: just let the heading start with “Appendix: ” This affects only latex output, where the appendix formatting is used - all other formats just leave the heading as it is written.

### Figures¶

#### Basic syntax¶

Figures are recognized by the special line syntax

FIGURE:[filename, width=600 frac=0.8] caption


The filename can be without extension, and DocOnce will search for an appropriate file with the right extension. If the extension is wrong, say .pdf when requesting an HTML format, DocOnce tries to find another file, and if not, the given file is converted to a proper format (using ImageMagick’s convert utility).

Warning

Note the comma between the filename and the figure size specifications and that there should be no space around the = sign. This syntax must be strictly followed.

Note also that, like for TITLE: and AUTHOR: lines, all information related to a figure line must be written on the same line. Introducing newlines in a long caption will destroy the formatting (only the part of the caption appearing on the same line as FIGURE: will be included in the formatted caption).

The height, width, and frac keywords can be included if desired and may have effect for some formats: the height and width are used for output in the formats html, rst, sphinx, while the frac specification is used for latex and pdflatex to specify the width of the image as a fraction of the text width.

#### Figure Placement¶

In web formats (html, sphinx, ipynb, matlabnb, wikis), the FIGURE: command is replaced by an img tag exactly where the FIGURE: appears in the document. LaTeX, however, will normally place the figure at a different location. The generated LaTeX code applies

\begin{figure}[!ht] % my:fig


i..e, we use the “here” option [!ht] to recommend a placement as near the FIGURE: command as possible. One can autoedit the .tex file and modify the figure environment options, e.g.,

Terminal> doconce replace '{figure}[!ht]' '{figure}[t]' mydoc.tex


The above command will change all [!ht] options to [t] (top). A specific figure can also be edited, using the fact that the label is printed at the same line as \begin{figure}:

Terminal> doconce subst '{figure}[!ht] .+my:fig' \
'{figure}[!h] % my:fig' mydoc.tex


Of greater influence than options like [ht], [h], etc., is the LaTeX code found in the preamble:

\setcounter{topnumber}{2}
\setcounter{bottomnumber}{2}
\setcounter{totalnumber}{4}
\renewcommand{\topfraction}{0.95}
\renewcommand{\bottomfraction}{0.95}
\renewcommand{\textfraction}{0}
\renewcommand{\floatpagefraction}{0.75}
% floatpagefraction must always be less than topfraction!
\usepackage[section]{placeins}  % flush all figs before next section


These values can be manipulated to fine-tune how LaTeX places figures.

#### Figure References¶

Suppose we have the DocOnce code

The results are presented in Figure ref{myfig}.

FIGURE:[myfigfile, width=400 frac=0.8] Results for $a=2$. label{myfig}


Different formats will display the figure reference differently. In LaTeX, DocOnce generates the code ... in Figure |nbsp| :ref:myfig”, which reads ... in Figure 5” (article) or ”... in Figure 5.2” (book). Requesting the varioref package (with --latex_packages=varioref) makes DocOnce emit \vref references and then the above reference becomes in Figure |nbsp| v:ref:myfig”, which reads ... in Figure 5 on page 67”. However, if Figure 5 appears on the present page where the reference is done, the page reference is left out, and one can read just “in Figure 5”.

Sphinx applies the caption as name of the figure, so the reference reads ”... in Figure Results for .”, and the caption/name is a link to the figure. Note that Sphinx strips off the mathematics from the caption. In HTML, figures are given numbers, so the reference reads ”... in Figure 3”, with the figure number as a link to the place in the document where the FIGURE: command was located. The IPython notebook format makes a Markdown link: ... in [Figure](#myfig), where myfig is an anchor such one can click on Figure. The plain text format displays the reference as ”... in Figure myfig.”. Wiki formats show ”... in Figure myfig.”. So to summarize, figure references work best in LaTeX, HTML, and Sphinx. Other formats should avoid figure references with labels.

#### Inline Figures¶

The figure caption is optional. If omitted, the figure appears “inline” in the text without any figure environment in LaTeX formats or HTML.

An inline figure is handy in LaTeX since it appears exactly where the FIGURE: command appears (figures with captions are encapsulated in the LaTeX figure environment and become floating objects whose placement is up to LaTeX do decide).

Tip: use linebreak to insert space around inline figures

Sometimes inline figures (FIGURE line without caption) get squeezed into the text. You can add vertical space in LaTeX and HTML by inserting several lines with <linebreak>.

#### Choosing the Figure Format¶

For each output format, there is a preference which type of graphics file that is preferred. That is, for HTML, for instance, we can accept many types of graphics formats. If we specify the extension as part of the filename, DocOnce will try to find that specific format. If not found, it will convert whatever can be used to some format suitable for HTML. It is highly recommended to prepare figures in different formats manually and not rely on automatic conversion by DocOnce - that gives the best quality. For example, plots should always be prepared in both PDF and PNG formats.

If we just specify the filestem of the figure file, DocOonce will pick the most appropriate version of the file for given output format. For HTML there is a preference for .svg, thereafter comes .html (typically Bokeh plots), then .png, then gif, then .jpg. Here is the preference list for the various formats:

• latex: .eps, .ps
• pdflatex: .pgf, .tikz, .pdf, .png, .jpg, .jpeg
• html: .svg, .html, .png, .gif, .jpg, .jpeg
• sphinx: .png, .gif, .jpg, .jpeg
• pandoc: .png, .gif, .jpg, .jpeg, .tif, .tiff, .pdf

Other formats, which can display graphics, will prefer .png files.

#### Handling Variable Figure Paths¶

Figure files are usually located in some directory. Sometimes one needs to compile the DocOnce source file(s) from different directories, and then the path to figure files changes. For example, think of a master DocOnce file that includes different sections whose DocOnce source files are located in different directories. If you want to compile a section as stand-alone document, you have to do that from the subdirectory for that section. The path to a common directory for figures may then be like ../fig/myfig.png, while for the master document in the parent directory, the corresponding path is fig/myfig.png.

The simplest way out of this problem is to use the --fig_prefix= command-line option to set a path prefix for the figure filename. When compiling a section in a subdirectory one sets --fig_prefix=../fig while in the parent directory one needs --fig_prefix=fig to compile the master document. In the DocOnce source file one has FIGURE: [myfig, width=...].

A more manual method is to introduce a Mako variable FIGPREFIX that is set on the command line as part of the doconce format command. The FIGPREFIX variable holds a prefix for the path to the figure. In our example one writes

FIGURE: [{FIGPREFIX}/myfig, width=500 frac=0.8] caption label{my:fig}  and set FIGPREFIX=../fig after the doconce format ... command if one compiles a section, while FIGPREFIX=fig is the appropriate value of the path when compiling the master document. #### Figures with Subfigures¶ Combining several image files into one, in a table fashion, can be done by the montage program from the ImageMagick suite: montage -background white -geometry 100% -tile 2x \ file1.png file2.png ... file4.png result.png  The option -tile XxY gives X figures in the horizontal direction and Y in the vertical direction (tile 2x means two figures per row and -tile x2 means two rows). The montage program is only appropriate for bitmap images (PNG, JPEG, GIF, TIFF). Images in the PDF format should be mounted together using pdftk (to combine images to one file), pdfnup (to align them in tabular format), and pdfcrop (to remove surrounding whitespace): Terminal> pdftk file1.pdf file2.pdf ... file4.pdf output tmp.pdf Terminal> pdfnup --nup 2x2 tmp.pdf # output in tmp-nup.pdf Terminal> pdfcrop tmp-nup.pdf result.png # output in FE1.png  Instead of using montage, pdftk, etc., one can rely on the convenient command doconce combine_images: Terminal> doconce combine_images pdf -2 fig1 fig2 fig3 fig4 fig  This command will combine fig1.pdf, fig2.pdf, fig3.pdf, and fig4.pdf with two images per row (-2 option) and place the result in fig.pdf. By just changing the pdf option to png, the same will happen with fig1.png, fig2.png, fig3.png, and fig4.png, resulting in fig.png. The tool employs the technique above for PNG and PDF files to produce ultimate quality of the combined image. One can also run doconce combine_images with filenames with extension, e.g., Terminal> doconce combine_images myfig1.png myfig2.png fig2.png  Here, myfig1,png and myfig2.png are placed next to each other in a new figure file fig2.png. #### Sidecaption in LaTeX and HTML¶ The figure caption can be placed on the (right) side of figures by using the sidecap feature as figure option, e.g., FIGURE: [myfig, width=500 frac=0.5 sidecap=True]. The generated latex and pdflatex output then uses the sidecap package and the SCfigure environment to typeset the figure. Remember to use a quite low frac value for figures with sidecaption (0.5 for instance). A table is used for typesetting a figure with sidecaption in HTML, and a low width value is recommended. The sidecap=True figure option has no impact on other formats. #### TikZ Figures¶ Many LaTeX writers are dependent upon TikZ figures, and these can be used in DocOnce documents, see the demo document. #### Plot Files in LaTeX¶ Users who applies Matplotlib to make figures get plots with fonts that differ from the rest of a LaTeX document. A blog post describes techniques for overcoming this problem. The plotfile is then a .pgf file and one must use the pgf LaTeX package. DocOnce supports .pgf plot files for the pdflatex output format and will make use of such files if they exist. These are included by a simple \input{file.pgf}. If no .pgf file is found, the pdflatex output format will apply .pdf, .png, or .jpg file, in that order of preference. #### Interactive Bokeh Plots for HTML¶ Fancy interactive plots for data exploration can be made with the Bokeh library. Such plots reside in an HTML file. DocOnce will for the HTML output format detect files of this type and use the HTML code in the file to embed the plot(s) in the generated output document. Below is a complete example on creating a grid of interactive plots where the horizontal axes are coupled to each other. Panning the graph in one plot automatically moves all the other graphs. In this way, one can scroll through a long time series simultaneously for many plots. Our demo looks as follows in a browser: Such a figure is specified the normal way: if the HTML code for the figure is in myfig.html, write FIGURE: [myfig] caption  Options like width are ignored for Bokeh plots, unless you have other versions of the figure (myfig.png, for instance, see the box below) where such options may be useful for some formats. Make alternatives to Bokeh plots Note that Bokeh plots have only meaning when DocOnce translates the document to HTML. For other formats, one needs to supply figure files that those formats can accept (PNG, PDF, etc.). Suppose you have made a Bokeh plot in myfig.html. Either you have to embed the FIGURE command inside a preprocessor test that the FORMAT == 'html' or you must provide alternatives like myfig.png. A Bokeh plot will often have a save button that can be used to save the plot to PNG format. This can be used for Sphinx, wikis, and pdfLaTeX (although the latter would appreciate real vector graphics in a PDF plot). The plot example above is so advanced that there is no natural counterpart in a static PNG or PDF plot. Tip: reduce the size of Bokeh HTML files When making Bokeh plots in Python programs, we recommend to use the mode='cdn' option in the call output_file. This argument leads to links to Bokeh tools in the resulting HTML file. Without the argument, Bokeh embeds long HTML code for its tools into the file. DocOnce issues a warning in this case and recommends the mode argument. Note that with mode='cdn' the HTML code for the plot requires Internet access. An interactive plot like the one shown above, stored in a file tmp.html, can be made by the code below (download file): from __future__ import division from builtins import range from past.utils import old_div def bokeh_plot(u, t, legends, u_e, t_e, I, w, t_range, filename): """ Make plots for u vs t using the Bokeh library. u and t are lists (several experiments can be compared). legends contain legend strings for the various u,t pairs. Each plot has u vs t and the exact solution u_e vs t_e. """ import numpy as np import bokeh.plotting as plt plt.output_file(filename, mode='cdn', title='Comparison') # Assume that all t arrays have the same range t_fine = np.linspace(0, t[0][-1], 1001) # fine mesh for u_e tools = 'pan,wheel_zoom,box_zoom,reset,'\ 'save,box_select,lasso_select' u_range = [-1.2*I, 1.2*I] font_size = '8pt' p = [] # list of all individual plots p_ = plt.figure( width=300, plot_height=250, title=legends[0], x_axis_label='t', y_axis_label='u', x_range=t_range, y_range=u_range, tools=tools, title_text_font_size=font_size) p_.xaxis.axis_label_text_font_size=font_size p_.yaxis.axis_label_text_font_size=font_size p_.line(t[0], u[0], line_color='blue') p_.line(t_e, u_e, line_color='red', line_dash='4 4') p.append(p_) for i in range(1, len(t)): p_ = plt.figure( width=300, plot_height=250, title=legends[i], x_axis_label='t', y_axis_label='u', x_range=p[0].x_range, y_range=p[0].y_range, tools=tools, title_text_font_size=font_size) p_.xaxis.axis_label_text_font_size=font_size p_.yaxis.axis_label_text_font_size=font_size p_.line(t[i], u[i], line_color='blue') p_.line(t_e, u_e, line_color='red', line_dash='4 4') p.append(p_) # Arrange in grid with 3 plots per row grid = [[]] for i, p_ in enumerate(p): grid[-1].append(p_) if (i+1) % 3 == 0: # New row grid.append([]) plot = plt.gridplot(grid, toolbar_location='left') plt.save(plot) plt.show(plot) def demo_bokeh(): """Plot numerical and exact solution of sinousoidal shape.""" import numpy as np def u_exact(t): return I*np.cos(w*t) def u_numerical(t): w_tilde = (old_div(2.,dt))*np.arcsin(w*dt/2.) return I*np.cos(w_tilde*t) I = 1 # Amplitude w = 1.0 # Angular frequency P = 2*np.pi/w # Period of signal num_steps_per_period = [5, 10, 20, 40, 80] num_periods = 40 T = num_periods*P # End time of signal t_e = np.linspace(0, T, 1001) # Fine mesh for u_exact u_e = u_exact(t_e) u = [] t = [] legends = [] # Make a series of numerical solutions with different time steps for n in num_steps_per_period: dt = old_div(P,n) # Time step length t_ = np.linspace(0, T, num_periods*n+1) u_ = u_numerical(t_) u.append(u_) t.append(t_) legends.append('# time steps per period: %d' % n) bokeh_plot(u, t, legends, u_e, t_e, I=1, w=w, t_range=[0, 4*P], filename='tmp.html') demo_bokeh()  #### Converting Matplotlib Plots to Bokeh¶ Most Python users apply Matplotlib to create line drawings. Bokeh has a conversion utility from Matplotlib to Bokeh that works well for standard curve plots. The script below demonstrates how to generate a plot in Matplotlib and convert it to a Bokeh tmp.html file. import numpy as np import matplotlib.pyplot as plt x = np.linspace(0, 2*np.pi, 1001) y1 = np.exp(-x)*np.sin(2*x) y2 = np.exp(-0.5*x)*np.sin(2*x) plt.plot(x, y1, 'r-', x, y2, 'b--') plt.xlabel('x'); plt.ylabel('y') # legends do not work in Bokeh #plt.legend([r'e^{-x}\sin 2x$', r'$e^{-\frac{1}{2}x}\sin 2x$']) plt.title('Damped sine functions') plt.savefig('tmp.pdf'); plt.savefig('tmp.png') # Convert to Bokeh import bokeh.mpl, bokeh.plotting as bpl p = bokeh.mpl.to_bokeh(notebook=False, xkcd=False) #p = bokeh.mpl.to_bokeh() bpl.output_file('tmp.html', mode='cdn') bpl.save(p) #bpl.show(p) plt.show()  ### Movies¶ Movies/videos are inserted using the MOVIE: keyword. This feature works well for the latex, html, rst, and sphinx formats. Other formats try to generate some HTML file and link to that file for showing the movie. If such a link is not appropriate and one wants a figure instead of the movie, use the preprocessor as explained in the box Recommendations below. #### The Basic Command¶ As with FIGURE, the MOVIE command expands just one line and is of the form MOVIE: [filename, height=xxx width=yyy] possible caption  Note that there must be a blank line after every MOVIE: command. The width and height parameters are not required, but leaving them out may lead to movie sizes you do not want. Here is a movie in the Ogg format: A movie in Ogg format. realized by the command MOVIE: [mov/wave.igg, width=600] A movie in Ogg format.  A URL works too as movie address: MOVIE: [http://hplgit.github.io/animate/doc/pub/mov-animate/demo.ogg] Ogg movie in cyberspace.  Ogg movie in cyberspace. Important Movies will not work properly in sphinx format unless they are located in a directory (tree) with a name starting with mov. Make it a habit to place figures in fig-X and movies in mov-X directories, where X is a short logical name for the current document (or let the names of the directories be just fig and mov). #### MP4, WebM, and Ogg Movies in HTML¶ If a movie is in Ogg, MP4, or WebM format, and the output format is html, DocOnce will check if the movie file is also in the other formats among Ogg, MP4, and WebM, and include these as well such that the movie has backup formats in case the browser does not support a particular format. Providing a movie in Ogg, MP4, and WebM format is therefore the safest way to ensure that the movie can be played in any browser on any device. Note If you specify a movie in Ogg or WebM format and it also exists in MP4 format, the MP4 format will be loaded first. To avoid having alternative movie formats in HTML, use the --no_mp4_webm_ogg_alternatives command-line option when running doconce format. #### Movie Handling in Various Formats¶ Movies are easiest shown in the HTML format. The reST and Sphinx formats apply the same raw HTML code as the HTML format and therefore have the same capabilities. The LaTeX format supports different methods for embedding movies via the option -latex_movie=.... Proper values are listed below. 1. href: the h:ref:run:file{link} is used for all movies (default), typeset in a one-line quote environment with the movie caption (if present) and a movie counter. 2. media9: the media9 package is used for Flash and MP4 movies, movie15 for MPEG and AVI files, and a simple h:ref:run:file{link} command for other formats. Only Acrobat Reader supports displaying these type of movies. 3. multimedia: the \movie command (known from LaTeX Beamer) is used for movies. 4. movie15: the old movie15 package is used. Where to put the movie file for a PDF document A major concern when using the default (href) link to a movie in a PDF document, is where to store the movie file. If your document is in a repository at GitHub or Bitbucket, one can use this address for the movie file. However, for the HTML and Sphinx formats, we would like to use some short, local address mov/mymovie.ogg. For LaTeX PDF we can then use the command-line option --prefix_movie= to prefix the local address with the proper address in the repository in the cloud. Suppose the mov directory is found in https://github.com/n/p/blob/master/doc/mov  We need, however, the raw movie file, which has the address https://raw.githubusercontent.com/n/p/master/doc/mov/m.ogg  We can then use the line MOVIE: [mov/m.ogg]  in the document, but compile to LaTeX with the command-line option --movie_prefix=https://raw.githubusercontent.com/n/p/master/doc/  All links to movies in the PDF file will then be links to the repository file in the cloud while for HTML and Sphinx we link to the local movie files that are stored together with the .html files for the document. For all other formats, an HTML file that acts as a movie player is generated and linked from the output document. This movie player has essentially the same code as the HTML format would have, except that the video tag is not used, only the embed tag. Some wiki types do have support for videos, e.g., Wikipedia can work with Ogg files, but DocOnce has not yet implemented robust schemes for anything but LaTeX, HTML, and Sphinx output. #### YouTube and Vimeo Movies¶ Many publish their scientific movies on YouTube or Vimeo, and DocOnce recognizes YouTube and Vimeo URLs as movies. When the output from DocOnce is an HTML file, the movie will be embedded, otherwise a URL to the YouTube or Vimeo page is inserted. You should equip the MOVIE: command with the right width and height of embedded YouTube and Vimeo movies. The recipe goes as follows: 1. click on Share (and on YouTube then Embed) 2. note the height and width of the embedded movie A typical MOVIE command with a YouTube movie is then MOVIE: [http://www.youtube.com/watch?v=sI2uCHH3qIM, width=420 height=315] MOVIE: [http://vimeo.com/55562330, width=500 height=278] CFD.  #### Animation Based on Filename Generators¶ It is possible to define a movie from a set of files, usually plot files, which can be shown in sequence to create an animation. If the files are local on the computer, one can specify them by a simple Unix wildcard notation, as in MOVIE: [../experiments/frame_*.png]  Output in the HTML, reST, and Sphinx formats will make use of inline JavaScript code to show the frames in sequence. LaTeX employs the animate package for the same purpose. Other formats generates a file (movie_playerX.py, where X is a number) containing the HTML code with JavaScript to show and control the animation. The DocOnce document has a link to this movie viewer. There is an alternative syntax to the Unix wildcard notation: MOVIE: [../experiments/frame_%04d.png:0->320]  The filename is specified via printf syntax (typically the same syntax as used to generate the individual frame files). The postfix :0->320 specifies the lower and upper limit of the counter that is used in the printf specification %04d. This latter syntax must be used if the plot files reside on some web server, e.g., MOVIE: [http://some.where.net/experiments/frame_%04d.png:0->320]  Here is an example: Recommendations It is challenging to write robust DocOnce code with movies. The recommended formats in HTML are MP4, WebM, and Ogg. One should preferably make all three. These also works in reST and Sphinx. The filename generation works very well in LaTeX, while true movie formats pose big challenges. On Linux systems, the media9 does not work well because a proper Flash player for embedding in the PDF file is not always available. The movie15 package also leads to problems because Acrobat Reader depends on an external player to show the files, and the correct plugins to launch players with support for a given format are not trivial to install. Even the plain h:ref:run:file” command relies on an external player and not all formats will be supported on a given computer. To have really robust code, use filename generators and not movie files. MOVIE: [../experiments/frame_*.png]  One can write flexible DocOnce code and decide at run time if HTML output should have movie files or filename generators. A relevant snippet using Mako and a user-defined variable HTMLMOVIE is % FORMAT in ("latex", "pdflatex") or HTMLMOVIE == "files": MOVIE: [../experiments/frame_*.png] % else: MOVIE: [../experiments/movie.ogg] % endif  With the -DHTMLMOVIE=files flag, animation of individual files will be performed, while any other value than files leads to use of the movie.ogg in all but LaTeX formats. In HTML one will try to load movie.mp4 (if it exists) and then movie.webm (if it exists) and then finally movie.ogg. There is no way to control the number of frames per second in LaTeX animations based on filename generators such as myframes*.png. However, with a little auto editing in a script one can control the frame rates of the various movies. The rate is specified as 2 in lines on the form \begin{animateinline}[controls,loop]{2} % frames: f000.png -> f098.png  Setting the rate to 12 instead for this particular movie based on the f%03.png files, the following doconce subst command does the job in a script: doconce subst ',loop]{2}( .+: f000)' ',loop{12}\g<1>' mydoc.do.txt  Sometimes it is desired to use true movies in web formats and a figure in LaTeX, e.g., a figure with four snapshots from the movie combined into a single figure file with doconce combine_images. A preprocessor test is appropriate for this: % if FORMAT in ("latex", "pdflatex"): FIGURE: [myfig, frac=1] caption % else: MOVIE: [mymov] caption % endif  If you encounter a large number of such if-else statements, it is advantageous to write a Mako function in Python: <% def figmov(figfile, movfile, caption): if FORMAT in ("latex", "pdflatex"): return "FIGURE: [%s, frac=1] %s" % (figfile, caption) % else: return "MOVIE: [%s] %s" % (movfile, caption) % endif %>  The one can avoid if-else tests in the running code and instead write just ${figmov('myfig', 'mymov', 'caption')}


to insert a movie or figure file, depending on the output format.

### Copying Computer Code from Source Files¶

Another type of special lines starts with @@@CODE and enables copying of computer code from a file directly into a verbatim environment, see the section Blocks of Verbatim Computer Code below.

### Inserting the Output from Operating System Commands¶

When DocOnce is used to document computer program and results from computer code it is important to ensure that the document contains the latest version of the code and the corresponding output. The former is handled by the @@@CODE directive, while the latter has its own directive @@@OSCMD. The syntax reads

@@@OSCMD cmd


where cmd is any text that can be run in the operating system. The output is copied into the DocOnce source. For example,

@@@OSCMD python -c 'print "Hello,\nWorld!"'


results in

Terminal> python -c 'print "Hello,\nWorld!"'
Hello,
World!


There is a command-line option --os_prompt= that can be used to set the (terminal) prompt that prefixes the command:

• --os_prompt=None results in no prompt, just the command.
• --os_prompt=nocmd results in no prompt and no command, just the output.
• --os_prompt=Terminal> is the default setting (as in the example above).

Comments intended to be (sometimes) visible in the output document and read by readers are known as inline comments in DocOnce and described in the section Inline Tagging.

Here we address comments in the DocOnce source file that are not intended to be visible in the output document. Basic comment lines start with the hash #:

#
# Here are some comment lines that do not affect any formatting.
# These lines are converted to comments in the output format.
#


Such comment lines may have some side effects in the rst and sphinx formats because following lines are taken as part of the comment if there is not a blank line after the comment.

The Mako preprocessor supports comments that are filtered out before DocOnce starts translating the document. Such comments are very valuable as they will never interfere with the output format and they are only present in the DocOnce source. Mako has two types of comments: lines starting with a double hash ## and multiple lines enclosed by the <%doc> (beginning) and <%doc/> (closing) tags.

If you need a lot of comments in the DocOnce file, consider using Mako comments instead of the single hash, unless you want the comments to be in the source code of the output document.

To comment out or remove large sections, consider using the Preprocess preprocessor and an if-else block with a variable that is undefined (typically something like a test # #ifdef EXTRA in Preprocess, or the Mako equivalent % if EXTRA:).

### Tables¶

#### Basic Syntax¶

A table like

time velocity acceleration
0.0 1.4186 -5.01
2.0 1.376512 11.919
4.0 1.1E+1 14.717624

is built up of pipe symbols and dashes:

   |--------------------------------|
|time  | velocity | acceleration |
|--r--------r-----------r--------|
| 0.0  | 1.4186   | -5.01        |
| 2.0  | 1.376512 | 11.919       |
| 4.0  | 1.1E+1   | 14.717624    |
|--------------------------------|

* The pipes and column values do not need to be aligned (but why write
the DocOnce source in an ugly way?).

* In the line below the heading,
one can insert the characters c, r, or l to specify the
alignment of the columns (centered, right, or left, respectively).
One can also use X for potentially very wide text that must be
wrapped and left-adjusted (will only affect latex and pdflatex where the
tabularx package is then used; X means l in all other formats).

* Similar character can be inserted in the line above the header to

* There must be a blank line before and after the table.

* Tables are *inlined* in the text, without numbers or labels for reference.

* Some CSS files used by some HTML styles may overrule the alignment
characters c, r, and l and, e.g., center all text.

* For output in LaTeX one can control certain aspects of the typesetting
of tables: the text size (--latex_table_format=), the color of every
two rows (--latex_colored_table_rows=), and the space between
rows (--latex_table_row_sep=).


Here is an example with centered headings (which is default anyway), and the numbers are left-adjusted in the first column and right-adjusted in the two others.

|--c--------c-----------c--------|
|time  | velocity | acceleration |
|--l--------r-----------r--------|
| 0.0  | 1.4186   | -5.01        |
| 2.0  | 1.376512 | 11.919       |
| 4.0  | 1.1E+1   | 14.717624    |
|--------------------------------|


Typeset result:

time velocity acceleration
0.0 1.4186 -5.01
2.0 1.376512 11.919
4.0 1.1E+1 14.717624

Pipes | can also be inserted to indicate vertical rules in LaTeX tables (they are ignored for other formats):

|--------------------------------|
|time  | velocity | acceleration |
|--l---|----r-----|-----r--------|
| 0.0  | 1.4186   | -5.01        |
| 2.0  | 1.376512 | 11.919       |
| 4.0  | 1.1E+1   | 14.717624    |
|--------------------------------|


Note

• Not all formats offer alignment of heading or entries in tables (rst and sphinx are examples).
• DocOnce tables are very simple: neither entries nor headings can span several columns or rows. When that functionality is needed, one can make use of the preprocessor and if-tests on the format and insert format-specific code for tables.

#### Quick way of creating tables¶

It takes some efforts to put the pipes and dashes correctly in the table format. A quick way of generating a DocOnce table is to first put the table entries in a file with comma between the entries. This is essentially a file in the famous CSV format. Data in CSV format can be transformed to DocOnce table format by the doconce csv2table utility:

Terminal> doconce csv2table somefile.csv > table.do.txt


For example, we can write a text file tmp.csv with

time, velocity, acceleration
0.0, 1.4186, -5.01
2.0, 1.376512, 11.919
4.0, 1.1E+1, 14.717624


Running doconce csv2table tmp.csv creates the table

|------c--------------c--------------c-------|
| time         | velocity     | acceleration |
|------c--------------c--------------c-------|
| 0.0          | 1.4186       | -5.01        |
| 2.0          | 1.376512     | 11.919       |
| 4.0          | 1.1E+1       | 14.717624    |
|--------------------------------------------|


If the output from doconce csv2table is redirected to a file:

Terminal> doconce csv2table data.csv > mytable.do.txt


one can easily include this file by # #include "mytable.do.txt" in the DocOnce source file. This is an efficient method for generating DocOnce tables directly from data.

#### Tables from DocOnce to CSV Data Files¶

The command-line option --tables2csv (to doconce format) makes DocOnce dump each table to CSV format in a file table_X.csv, where X is a generated table number. This feature makes it easy to load tables from DocOnce documents into spreadsheet programs for further analysis.

### Lists¶

An unordered bullet list makes use of the * as bullet sign and is consistently indented by some chosen spaces as follows

* item 1
* item 2
* subitem 1, if there are more
lines, each line must
be exactly intended as shown here
(i.e., start in the same column)
* subitem 2,
also spans two lines
* item 3


This list gets typeset as

• item 1
• item 2
• subitem 1, if there are more lines, each line must be exactly intended as shown here (i.e., start in the same column)
• subitem 2, also spans two lines
• item 3

In an ordered list, each item starts with an o (as the first letter in ordered):

o item 1
o item 2
* subitem 1
* subitem 2
o item 3


resulting in

1. item 1
2. item 2
• subitem 1
• subitem 2
3. item 3

Ordered lists cannot have an ordered sublist, i.e., the ordering applies to the outer list only.

In a description list, each item is recognized by a dash followed by a keyword followed by a colon:

- keyword1: explanation of keyword1

- keyword2: explanation
of keyword2 (remember to indent properly
if there are multiple
lines)


The result becomes

keyword1:
explanation of keyword1
keyword2:
explanation of keyword2 (remember to indent properly if there are multiple lines)

No indentation - except in lists

DocOnce syntax is sensitive to whitespace! No lines should be indented, only lines belonging to lists. Indented lines may give strange output in some formats. Also note that extra whitespace after item" indicators (*, o, or -) in lists may give strange behavior.

## Inline Tagging¶

DocOnce supports tags for emphasized phrases, boldface phrases, and verbatim text (also called type writer text, for inline code), plus LaTeX/TeX inline mathematics, such as $$\nu = \sin(x)$$. Links are easy to define, either with a text or just a plain http://google.com. Also a non-breaking space (to avoid linebreak), linebreak,

m-dash (as in m—dash), and horizontal rule can be specified (below).

Limitation of inline tagging

Since DocOnce applies regular expressions to recognize inline tagging, there might be cases where the tags are not correctly interpreted and translated. Fortunately, most such pitfalls are easily circumvented. The troubleshooting document shows some examples.

### Emphasized Words¶

Emphasized text is typeset inside a pair of asterisk, and there should be no spaces between an asterisk and the emphasized text, as in

*emphasized words*


Boldface font is recognized by an underscore instead of an asterisk:

_several words in boldface_ followed by *emphasized text*.


The line above gets typeset as several words in boldface followed by emphasized text. One should only have pure text (no mathematical formulas) between the boldface or emphasize markers, and no leading or trailing blanks (with such blanks, the text will not be recognized as boldface or emphasize).

Colored text is formatted as

some text color{red}{more text in red}


The current output format does not support colors, however.

### Inline Verbatim Text¶

Verbatim text, typically used for short inline code, is typeset between backticks:

call myroutine(a, b) looks like a Fortran call
while void myfunc(double *a, double *b) must be C.


The typesetting result looks like this: call myroutine(a, b) looks like a Fortran call while void myfunc(double *a, double *b) must be C. Note that there must be no leading or trailing spaces inside the backticks.

It is recommended to have inline verbatim text on the same line in the DocOnce file, because some formats (LaTeX in combination with the ptex2tex program (but not doconce pretex)) will have problems with inline verbatim text that is split over two lines.

Note

Watch out for mixing backticks and asterisk (i.e., verbatim and emphasized code): the DocOnce interpreter is not very smart in detecting such errors. A missing backtick will also quickly create strange output. If you suspect inline code to be the source of problems in the final format, examine the DocOnce source and the output.

### Quotes¶

Quotations employ either the emphasized font or double quotation marks. In the latter case, one should not use the character " but rather the (LaTeX-inspired) construction with double backticks and two single quotes:

This is a sentence with words to be quoted''.


To candidates for find double quotes that should be transferred to the above type of quotation (which is a common mistake), one can run a regular expression search like

Terminal> find . -name '*.do.txt' -exec grep -E \
'[^("]"[A-Za-z0-9 ,]+" *[^:)"]' {} \; -print


This search may give many false hits as double quotes are frequently used in computer code and preprocessor instructions (URLs and hyperlinks should not give hits in the above regular expressions).

### Non-Breaking Space¶

The non-breaking space character is tilde:

Here comes a long line with a specification of a number with unit at the end,
which is an example that requires a "non-breaking space character":
"http://en.wikipedia.org/wiki/Non-breaking_space": 7.4~km is traveled
in~$7.4/5.5\approx 1.345$~s. (Computer code, where the tilde has a
meaning, as in y = ~x, is not affected. The non-breaking character only
works between characters, numbers, and the math dollar sign.)


This is rendered as

Here comes a long line with a specification of a number with unit at the end, which is an example that requires a non-breaking space character: 7.4 km is traveled in $$7.4/5.5\approx 1.345$$ s. (Computer code, where the tilde has a meaning, as in y = ~x, is not affected. The non-breaking character only works between characters, numbers, and the math dollar sign.)

### Horizontal rule¶

A horizontal rule for separating content vertically, like this:

is typeset as four or more hyphens on a single line:

---------


### Em-dash¶

The latex, pdflatex, sphinx, html, pandoc, and ipynb formats support em-dash, indicated by three hyphens: ---. Other formats print just the three hyphens. The em-dash has two applications:

• as alternative to an ordinary single hyphen (with space around) in a sentence—except that there are no spaces around the em-dash (this is common, cf. Wikipedia), and
• origin of quotes (where there is no space between the end of the quote and the m-dash):
Premature optimization is the root of all evil.—Donald Knuth.

!bquote
*Premature optimization is the root of all evil.*---Donald Knuth.
!equote


### En-dash¶

The en-dash constists of two hyphens, as in --, and can be used instead of a single hyphen to get a slightly longer hyphen (LaTeX writers are especially used to this). Common applications are

• hyphen in compound words as the Navier - Stokes equations (here written as Navier - Stokes)
• hyphen in number ranges like 1 - 9
• hyphen around a sentence in sentence: To be precise - but not to detailed - we should ... (here the hyphen is written as --), as an alternative to em-dash (see section above)

The latex, pdflatex, sphinx, html, pandoc, and ipynb formats support en-dash (basically this means that HTML output has &ndash and LaTeX output is not altered). Other formats just show the raw double hyphen.

### Ampersand¶

An ampersand, as in Guns & Roses or Texas A&M, is written as a plain & with space(s) on both sides. Single upper case letters on each side of &, as in Texas A & M, remove the spaces and result in Texas A&M, while words on both sides of &, as in Guns & Roses, preserve the spaces: Guns & Roses. Failing to have spaces before and after & will result in wrong typesetting of the ampersand in the html, latex, and pdflatex formats. If special quoting of the ampersand is undesired, e.g., when one has inserted native LaTeX code for tables, the command-line option --no_ampersand_quote for doconce format turns off the ampersand treatment for all formats.

### Footnotes¶

Typesetting of footnotes employs a common email or Extended Markdown syntax:

Footnotes are typeset according to the output format[^typesetting].
The syntax is optional spaces, opening bracket, hat, a footnote name
without spaces[^remedy-for-name-with-spaces], and closing bracket. The
logical name of the footnote is not used in LaTeX, HTML,
reStructuredText, or Sphinx, because these languages employ numbered
footnotes. Other formats employ the logical name.

[^typesetting]: Typesetting of the footnote depends on the format.
Plain text does nothing, LaTeX removes the definition and inserts the
footnote as part of the LaTeX text.  reStructuredText and Sphinx
employ a similar type of typesetting as Extended Markdown and DocOnce,
and in HTML we keep the same syntax, just displayed properly in HTML.

Footnotes are preferably defined after the paragraph they are used.
The definition is the footnote syntax (some optional space, bracket,
hat, name, bracket) followed by colon and a text.
A new paragraph marks the end of a footnote.

[^remedy-for-name-with-spaces]: Just put in dashes or underscores in
case of spaces.


The text above looks as follows.

Footnotes are typeset according to the output format [1]. The syntax is optional spaces, opening bracket, hat, a footnote name without spaces [2], and closing bracket. The logical name of the footnote is not used in LaTeX, HTML, reStructuredText, or Sphinx, because these languages employ numbered footnotes. Other formats employ the logical name.

 [1] Typesetting of the footnote depends on the format. Plain text does nothing, LaTeX removes the definition and inserts the footnote as part of the LaTeX text. reStructuredText and Sphinx employ a similar type of typesetting as Extended Markdown and DocOnce, and in HTML we keep the same syntax, just displayed properly in HTML.

Footnotes are preferably defined after the paragraph they are used. The definition is the footnote syntax (some optional space, bracket, hat, name, bracket) followed by colon and a text. A new paragraph marks the end of a footnote.

 [2] Just put in dashes or underscores in case of spaces.

DocOnce also supports inline comments in the text:

[name: comment]


where name is (e.g.) the name of the author of the comment, and comment is a plain text text. Note that there must be a space after the colon, otherwise the comment is not recognized. The name can contain upper and lower case characters, digits, single quote, + and -, as well as space. Next is an example. [hpl’s comment 1: Inline comments can span several lines, if desired.]

The name and comment are visible in the output unless doconce format is run with a command-line argument --skip_inline_comments (see the section From DocOnce to Other Formats for an example). Inline comments are helpful during development of a document since different authors and readers can comment on formulations, missing points, etc. All such comments can easily be removed from the .do.txt file by doconce remove_inline_comments (see the section From DocOnce to Other Formats).

Inline comments are typeset in a simple way: boldface name, a numbering of the comment, and then the comment, all in red and in parenthesis. However, with the --latex_todonotes option, LaTeX will apply the todonotespackage to typeset the comments in very visible color boxes.

Note

The inline editing syntax in DocOnce was implemented before the invention of CriticMarkup. Now it would make sense to use the CriticMarkup syntax and associated tools. (DocOnce needs proper rendering of CriticMarkup

Inline comments can also be used to markup editing of the text. The following syntax is supported:

[add: ,]
[del: ,]
[del: ,]
[del: .]
[del: ;]
[del: some text]
[edit: some text -> some replacement for text]
[name: some text -> some replacement for text]


That is, one can add, delete, and replace text, and adding or deleting a comma, period, or semicolon leads to special typesetting where such a small edit is highlighted. Below is an example of a text with inline editing.

Originally, we have the text

First consider a quantity $Q$. Without loss of generality, we assume
$Q>0$. There are three, fundamental, basic property of $Q$.


Then, some reader wants to change this text and explicitly demonstrate what is deleted, added, and replaced (as when using track changes in Microsoft Word). The use of the add, del, and replacement construction with -> may look as follows.

First[add: ,] consider [edit: a quantity -> the flux]
[del: $Q$. Without loss of generality,
we assume] $Q>0$. There are three[del: ,] fundamental[del: , basic]
[edit: property -> properties] of $Q$. [add: These are not
important for the following discussion.]


The text gets rendered as

First, (edit 2: add comma) consider (edit 3: remove a quantity) (insert:)the flux (end insert) (edit 4: delete $$Q$$. Without loss of generality, we assume) $$Q>0$$. There are three (edit 5: delete comma) fundamental(edit 6: delete , basic) (edit 7: remove property) (insert:)properties (end insert) of $$Q$$. (edit 8: add) These are not important for the following discussion. (end add)

Such inline comments with edits are only given special typesetting in the output formats latex, pdflatex, html, and sphinx. Otherwise, just the DocOnce syntax is shown (but that is also quite readable as edit instructions.)

The editing implied by the edit comments can be implemented in the DocOnce file by the command

Terminal> doconce apply_edit_comments mydoc.do.txt


### Forced Line Breaks¶

By ending a line in the DocOnce file with <linebreak> the output format has a forced linebreak at this point. This can be used to typeset poems, songs (if not in a verbatim block), or the origin of quotes. Here is an example:

!bquote
*Program writing is substantially more demanding than book
writing. Why is it so? I think the main reason is that a larger
attention span is needed when working on a large computer program
than when doing other intellectual tasks.* <linebreak>
Donald Knuth cite[p. 18]{Knuth85}, computer scientist, 1938-.
!equote


is rendered as

Program writing is substantially more demanding than book writing. Why is it so? I think the main reason is that a larger attention span is needed when working on a large computer program than when doing other intellectual tasks.

Donald Knuth [Ref1] (p. 18), computer scientist, 1938-.

The <linebreak> is a newline in LaTeX if it has preceding text, otherwise it is a \vspace{3mm}. In HTML, <linebreak> is <br>. Both constructions can be used to either force a linebreak or add vertical space.

Tip on using forced linebreaks

The <linebreak> tag is often useful in slides to avoid overfull lines in bullet lists, portion such lines into separate lines, or to insert vertical space. It can be used in admonitions too to get more space between the title and the text. Remember to have <linebreak> at the end of the line.

### Inline Mathematics¶

Inline mathematics is written as in LaTeX, i.e., inside dollar signs. Many formats leave this syntax as it is (including the two dollar signs), hence nice math formatting is only obtained in LaTeX, HTML, MediaWiki, and Sphinx (Epytext has some inline math support that is utilized).

The following text

Let $a=\sin(x) + \cos(x)$. Then $a^2 = 2\sin(x)\cos(x)$
because $\sin^2x + \cos^2x = 1$.


is rendered as “Let $$a=\sin(x) + \cos(x)$$. Then $$a^2 = 2\sin(x)\cos(x)$$ because $$\sin^2x + \cos^2x = 1$$.”

Mathematical expressions in LaTeX syntax often contains special formatting commands, which may appear annoying in plain text. DocOnce therefore supports an extended inline math syntax where the writer can provide an alternative syntax suited for formats close to plain ASCII:

Here is an example on a linear system
${\bf A}{\bf x} = {\bf b}$|$Ax=b$,
where $\bf A$|$A$ is an $n\times n$|$nxn$ matrix, and
$\bf x$|$x$ and $\bf b$|$b$ are vectors of length $n$|$n$.


That is, we provide two alternative expressions, both enclosed in dollar signs and separated by a pipe symbol, the expression to the left is used in formats with LaTeX support (latex, pdflatex, html, sphinx, mwiki), while the expression to the right is used for all other formats. The above text is typeset as “Here is an example on a linear system $${\bf A}{\bf x} = {\bf b}$$, where $$\bf A$$ is an $$n\times n$$ matrix, and $$\bf x$$ and $$\bf b$$ are vectors of length $$n$$.”

### Cross-Referencing¶

References and labels are supported. The syntax is simple:

label{section:verbatim}   # defines a label


The DocOnce label syntax is close that that of labels and cross-references in LaTeX, but note that labels cannot contain whitespace and cannot have a backslash.

When the label is placed after a section or subsection heading, the plain text, epytext, and st formats will simply replace the reference by the title of the (sub)section. All labels will become invisible, except those in math environments. (In the rst and sphinx formats, the end effect is the same, but the label and ref commands are first translated to the proper reST commands by doconce format.) In the html, ipynb, and wiki formats, labels become anchors and references become links, and with LaTeX label and ref are just equipped with backslashes so these commands work as usual in LaTeX.

Since references to sections appear differently in different formats, we provide an example.

..., we refer to Section ref{sec:theory}.

======= Basic Theory =======
label{sec:theory}

A first discovery was that 1+1 is 2.


The reference appears as follows in various output formats:

• latex and pdflatex: “we refer to Section 2.3” with LaTeX code
we refer to Section :ref:sec:theory”
• html: we refer to the section Basic Theory” with the HTML code
we refer to the section <a href="#sec:theory">Basic Theory</a>
• rst, sphinx: “we refer to the section Basic Theory”
• plain: “we refer to the section “Basic Theory”“
• ipynb: “we refer to the section Basic Theory” with Markdown code
we refer to the section [Basic Theory](#sec:theory)
• mwiki: “we refer to the section Basic Theory” with MediaWiki code
We refer to the section [#Basic_Theory]

Labels and references should only be used for (sub)sections, equations, figures, and movies (since DocOnce does not support references to tables and algorithms, for instance). By the way, here is an example on referencing Figure A wave. Additional references to the sections LaTeX Blocks of Mathematical Text and Macros (Newcommands) are nice to demonstrate, as well as a reference to equations, say (1)-(2).

References to equations must be in parentheses

LaTeX writers who are used to \eqref{} should observe that there is only one type of reference syntax in DocOnce, ref, without backslash, and that references to an equation with label my:special:eq must feature parentheses and look like

..., see (ref{my:special:eq}).


Hyperlinks to files or web addresses are handled as explained in the section Inline Tagging.

References to equations and sections in other documents can be done by the generalized cross-referencing syntax explained in the next section. However, sometimes one wants in an HTML document or notebook to make references to equations and sections in a LaTeX textbook. This is not well handled by the generalized cross-referencing technique, but DocOnce has a special option for this feature: --replace_ref_by_latex_auxno=../book.aux will read the label and numbering information from ../book.aux and replace all references (ref) by the corresponding number found in the ../book.aux file. Sometimes one wants to use this feature for selected references. In that case, use refaux instead of ref. If there one or more refaux commands in the DocOnce source, only refaux references will be replaced by numbers from the .aux file. Otherwise, all ref commands corresponding to labels in the .aux file will be replaced. In any case, the --replace_ref_by_latex_auxno= option is needed to specify one .aux file.

### Generalized Cross-Referencing¶

Sometimes a series of individual documents may be assembled to one large document, typically a book. In the book one wants to make cross references between chapters and sections, while these become references to external documents when the chapters (or sections) are compiled as stand-alone documents. For example, one can in a DocOnce file file1.do.txt have text like

...as shown in Section ref{sec:eqs}.


with the label sec:eqs defined in another file file2.do.txt. If file1.do.txt and file2.do.txt are combined to a single document, the reference is treated correctly, but if file1.do.txt is compiled as a single document, the label sec:eqs becomes undefined. Then one would instead write

...as shown in the document "Mathematical Equations":
"http://some.net/doc/matheqs.html" cite{math_eqs_2020}.


LaTeX has functionality for referring to labels in external documents. One must use the xr package and list external documents with a command \externaldocument{name} such that LaTeX can extract label information from the name.aux file. We are then able to write the above reference as

\externaldocument{file2}
...
...as shown in Section ref{sec:eqs} in cite{math_eqs_2020}.


and get output like ”...as shown in Section 3.4 in [12].” When the numbering of sections in file2.tex changes later, the output from the shown line in file1.tex will automatically be changed if file2.aux is recently compiled (so file2.aux with the mapping from labels to section numbers is updated).

#### Generalized References¶

DocOnce mimics a generalization of the LaTeX functionality in the xr package such that one can refer to external documents in other formats than LaTeX (HTML, Sphinx, IPython notebooks, wikis, etc.). This feature is called a generalized reference and involves a reference with three values. The syntax of generalized references reads

ref[internal][cite][external]


If all references in the text internal are to labels defined in the present DocOnce document, the generalized reference becomes the text internal. If one or more references in internal are not labels present in the document and latex or pdflatex is the output format, the generalized reference becomes the text internal followed by cite, while for all other formats the text in external is used.

The example above can now be written as the generalized reference

...as shown in ref[Section ref{sec:eqs}][ in cite{math_eqs_2020}][
the document "Mathematical Equations":
"http://some.net/doc/matheqs.html" cite{math_eqs_2020}].


(Note that there must be no spaces between closing and opening brackets: ][.) When the label sec:eqs is found in the current DocOnce document, this generalized reference becomes

Section ref{sec:eqs}


If not, and latex or pdflatex is the output format, the reference becomes

Section ref{sec:eqs}] in cite{math_eqs_2020}


while in all other cases the reference becomes

the document "Mathematical Equations":
"http://some.net/doc/matheqs.html" cite{math_eqs_2020}


For the reference to a label in an external document to work in the LaTeX case it is required to list this document in the DocOnce file as

# Externaldocuments: file2


Several external documents can be listed with comma as delimiter:

# Externaldocuments: file2, file3, myfile


on a single line. The Externaldocuments comment leads to use of the xr package and insertion of \externaldocument{file2} in the .tex output file. It is a good habit to place the Externaldocument comment after the title, author, and date.

External documents must be recently compiled

When compiling DocOnce documents with generalized references to latex or pdflatex, all documents listed in the Externaldocuments comment must have been recently compiled such that their .aux files are available and updated.

Note that cleaning (doconce clean) of the directory holding an external document will destroy the .aux file, and latex or pdflatex may then complain that a file listed as \externaldocument{} has no .aux file. This is just a warning - the result is question marks in the PDF document.

#### Generalized References to Chapters¶

A reference to a chapter in a book becomes just a reference to a complete stand-alone document if chapters are compiled individually. Here is an example:

...as shown in Chapter ref{ch:model}.


This reference works fine if the present document is a book and ch:model is a label of a chapter in the book. However, if the chapter with label ch:model is compiled separately, we would rather write

...as shown in cite{math_eqs_2020}.


where math_eqs_2020 is the citation label for the external document as listed in the Publish database. Or if the output format supports hyperlinks, we would perhaps add such a link:

the document "Mathematical Equations":
"http://some.net/doc/matheqs.html" cite{math_eqs_2020}.


Such references to chapters or complete documents are very much like the previously generalized references, but written with refch instead of ref:

refch[internal][cite][external]


The only difference between refch and ref is that the former, for latex and pdflatex output, just use the cite text and not internal if the labels in the internal text are not found in the document. To be precise, the reference

...as shown in refch[Chapter ref{ch:eqs}][cite{eqs_doc_2008}][
the document "Some Equations": "http://some.net/someeqs/"].


will be

...as shown in Chapter ref{ch:eqs}.


if ch:eqs is a label defined in the present document. It becomes

...as shown in Chapter cite{eqs_doc_2008}.


if ch:eqs is not found in the present document and the output format is latex or pdflatex. In all other cases the result becomes

...as shown in
the document "Some Equations": "http://some.net/someeqs/"].


#### Generalized References to LaTeX Documents¶

It is difficult in the [external] part of the generalized reference to refer to equation numbers in an external document. If one wants to refer to a LaTeX document, say a textbook, from some HTML or notebook, then one can use the refaux reference and an .aux file as explained at the end of the previous section on Cross-Referencing. Here is one example:

From ref[(ref{eq1})][ in cite{Langtangen_2045}][
equation (refaux{eq1}) in cite{Langtangen_2045}], we realize that...


For LaTeX output, the reference to eq1 will remain, but for other formats

(refaux{eq1})


will be replaced by (say) (1.5) if we provide the option --replace_ref_by_latex_auxno=mybook.aux and mybook.aux defines label eq1 to have number 1.5. Replacing refaux by ref above will lead to hardcoding of :ref:eq1” as 1.5 also in LaTeX output (which is okay, the xr package and giving Externaldocuments: mybook results in the same).

The example above is particularly relevant if one writes exercises that are to be filtered out as notebooks. The notebooks can then refer to a LaTeX book, while in the LaTeX version of the document, the exercises make references to the LaTeX book via the xr package the usual way.

Sometimes one does not want to refer to a LaTeX document in the [external] part of a generalized reference, but to a web document. Then the text must be written in a different way if one has equation or section references. For example,

From ref[(ref{eq1})][ in cite{Langtangen_2045}][
the differential equation for $u(t)$ in the section
"Setting up the model": "http://some.where.net/doc#model"
in cite{Langtangen_2045}], we realize that...


#### Tool for Generating Generalized References¶

The doconce ref_external command will read all the labels in the external documents listed in the Externaldocuments: comment and use the Publish database file of the current document (specified by BIBFILE:) to automatically generate substitution commands that translate ordinary LaTeX-style internal references to generalized references in DocOnce syntax. For example, doconce ref_external file1 will find the reference

......as shown in Section ref{sec:eqs}.


as a reference to a label sec:eqs defined in file2, grab the title of file2.do.txt, find the bibliographic data in the Publish file, and make a substitution command

### The Basics of Mako¶

Just a preliminary sketch of some Mako code (next example is better!):

# Define variables
<%
mycounter = 1
mydict = {}
%>

# Assume MYVAR is given on the command line as MYVAR=mytext (e.g.)
% if MYVAR is not UNDEFINED:
The value of MYVAR is ${MYVAR}. % endif <% ## Manipulation of variables mycounter += 1 %> % if MYVAR in (2,4,6): MYVAR is even integer in [2,6]. % elif MYVAR > 1000000: MYVAR is big. % else: MYVAR=${MYVAR}, mycounter=${mycounter}. % endif # Function <% # Define Python function: FORMAT and DEVICE # are always defined def link(filename): url = "https://github.com/some/path/to/' + filename + '"' if DEVICE == 'screen': # make link to url return '"filename":' + url elif DEVICE == 'paper': # write URL explicit on paper return 'URL:' + url %> <%doc> This is a block comment in Mako. <%doc/>  ### Debugging Python code in Mako¶ Although it is easy to put in Python code inside <% and %> directives, it may quickly become a nightmare to debug the Python code. If Mako reports a syntax error in the Python code, it is recommended to debug the Python code outside of Mako. That is, copy all Python code to a separate file and run it as standard Python code. This will give much more precise (and familiar) error messages. A setup that is easy for developing and maintaining the Python code used in Mako goes as follows. Different pieces of Python code in Mako is placed in separate files and included via the Preprocess preprocessor in the DocOnce document. For instance, ## Define Mako variables and basic functions <% # #include "variables.py" # #include "basic_functions.py" %> Some DocOnce text .... ## Define more functions <% # #include "more_functions.py" %>  Here, we have separated the Python code in Mako into three files: variables.py, basic_functions.py, and more_functions.py. With the # #include statements, Mako sees the .py files inserted as text inside the <% and %> directives (check the file tmp_preprocess__mydoc.do.txt for the result of running Preprocess and the complete DocOnce file that Mako sees). To debug the .py files, collect all their text in one single .py file and run it. The recommended way is to use Preprocess to copy all the text in the .py files into a single file, named (say) all_code.p.py: # --*-- coding: utf-8 -*- # (Encoding info cannot be in mako code, but required here # in Python code if we use non-ascii characters) # #include "variables.py" # #include "basic_functions.py" # #include "more_functions.py" # Test the code included above from __future__ import print_function print(some_func(1, 'arg'))  Note that after including the .py files one can insert calls to functions, print variables, etc., as desired to debug and experiment. Run Preprocess on all_code.p.py to produce an ordinary Python file all_code.py and run that code to test and debug. A little shell script all_code.sh doing both these things is convenient: #!/bin/sh preprocess all_code.p.py > all_code.py python all_code.py  Especially when the Python code in Mako grows and becomes non-trivial, this setup for having the code external to the DocOnce document is very effective. Things to remember when programming Mako • Do not use continuation character (backslash) in Python code. • When a Mako error refers to a line in the text, invoke the file that Mako sees: tmp_preprocess__mydoc.do.txt if the DocOnce file has name mydoc.do.txt. • Use double ## (Mako comment) to comment out Mako calls of the form ${name...}.

And to be repeated: keep the Python code in separate files!

One can use Mako to extend the DocOnce syntax. Four examples are given next.

### Example: Nomenclature functionality¶

LaTeX has a package for nomenclatures (see documentation) that allows a user to issue a simple command

\nomenclature{symbol}{definition}


to add a symbol and its definition to a nomenclature. The command \printglossary inserts the nomenclature table in the document.

We can easily create something similar in DocOnce with the aid of Mako. Here are the basic ideas:

• Collect the nomenclature definitions in a table in a file .nomenclature.do.txt.
• Introduce a command ${insert_nomenclature()} to make a fresh .nomenclature.do.txt file and return a @@@CODE command for inserting the nomenclature table. • Introduce a command ${nomenclature(symbol, definition)} for adding a new line in the nomenclature table in the file.
• Introduce a command ${end_nomenclature()} to finish the nomenclature table, i.e., insert the last table line. The Mako functions are defined by <% # Nomenclature functionality def insert_nomenclature(): # Make new file with open('.nomenclature.do.txt', 'w') as f: f.write("""\ |---------------------------------| | symbol | definition | |---l---------l-------------------| """) # Use envir=None to make plain include return '@@@CODE .nomenclature.do.txt envir=None' def nomenclature(symbol, definition): with open('.nomenclature.do.txt', 'a') as f: f.write('| ' + symbol + ' | ' + definition + ' |\n') return '' def end_nomenclature(): with open('.nomenclature.do.txt', 'a') as f: f.write('|---------------------------------|\n') return '' %>  The typical application in a DocOnce document is TITLE: ... AUTHOR: ... DATE: today !split TOC: on !split${insert_nomenclature()}

# Here comes a lot of text...

The equation becomes

!bt
$\nabla\cdot\sigma = \varrho f,$
!et
where $\sigma$ is the stress tensor, $\varrho$ is the density,
and $f$ is a body force.
${nomenclature(r'$\sigma$', 'stress tensor')}${nomenclature(r'$\varrho$', 'density')}
${nomenclature(r'$f$', 'body force')} ## More text.... ## At the end:${end_nomenclature()}


Make it a habit to use raw strings r"..." for the symbol in ${nomenclature(r"...", .... (sometimes backslashes enter the definition too and raw strings are required). Here is the resulting DocOnce after mako is run (found in tmp_mako__mydoc.do.txt if mydoc.do.txt is the file above): TITLE: Test AUTHOR: HPL DATE: today !split TOC: on !split @@@CODE .nomenclature.do.txt envir=None # Here comes a lot of text... The equation becomes !bt $\nabla\cdot\sigma = \varrho f,$ !et where$\sigma$is the stress tensor,$\varrho$is the density, and$f$is a body force.  The file .nomenclature.do.txt reads |---------------------------------| | symbol | definition | |---l---------l-------------------| |$\sigma$| stress tensor | |$\varrho$| density | |$f$| body force | |---------------------------------|  ### Example: Executing Python and using SymPy Objects in LaTeX¶ Here is an example where we want to illustrate how to calculate a double integral. All mathematics is to be done in SymPy, and results are supposed to be embedded in the document’s text. We can include Python code to be executed, anywhere in the document, and a variable var in the Python code is reached by ${var}. Here, we run SymPy and use SymPy’s LaTeX converter to make LaTeX code out of computed SymPy expressions:

# Execute Python code
<%
import sympy as sm
x, y, a = sm.symbols('x y a')
f = a*x + sm.sin(y)
step1 = sm.Integral(f, x, y)
step2 = sm.Integral(sm.Integralf, x).doit(), y)
step3 = step2.doit()
%>

# Make use of results in the above block when writing LaTeX math
!bt
\begin{align*}
${sm.latex(step1)} &=${sm.latex(step2)}\\
&= {sm.latex(step3)} \end{align*} !et  The result of the LaTeX block above, after Mako is run, becomes \begin{align*} \iint a x + y^{2} \sin{\left (y \right )}\, dx\, dy &= \int \frac{a x^{2}}{2} + x y^{2} \sin{\left (y \right )}\, dy\\ &= \frac{a y}{2} x^{2} + x \left(- y^{2} \cos{\left (y \right )} + 2 y \sin{\left (y \right )} + 2 \cos{\left (y \right )}\right) \end{align*}  Debugging Python code in Mako is less convenient than debugging Python files directly, so one may prefer to just include the Python code that Mako is supposed to run by <% # #include "src/ex1.py" %>  This is the recommended way to make use of SymPy to automate the mathematical derivations: first develop and test the SymPy code files, include the files in the document inside Mako’s Python code environment. Remark. Executing Python code inside the DocOnce document is closely related to literate programming. Tools supporting creating a document while running a Python programming cover Pweave, Python literate, PyWebTool, Antiweb, Literate Programming in Python, Pyreport, and also IPython notebooks. ### Example: Extending Tables to Handle Figures¶ DocOnce tables cannot contain figures, since figures must appear on a single line with the special syntax FIGURE: [file, ...]. What if you want a table of thumbnail figures with hyperlinks? #### Solution for LaTeX and HTML¶ We first restrict the attention to LaTeX and HTML. In those cases we can create an ordinary table and insert a call to a Mako function in cells in the table to return the proper LaTeX or HTML code for displaying a figure. The Mako call syntax in a cell is decided to be {tfig('080')}, which insert the figure mov/wave_frames/frame_0080.png. A 3x3 table of figures then look like

|-------------------------------------------------|
|               |                |                |
|-------c---------------c----------------c--------|
|${tfig('080')} |${tfig('085')} | ${tfig('090')} | |${tfig('095')} | ${tfig('100')} |${tfig('105')} |
|${tfig('110')} |${tfig('115')} | ${tfig('120')} | |-------------------------------------------------|  We do not want a heading, just a grid of figures, but a heading is required in DocOnce figures, so the solution is to provide empty column names in the heading. This solution gives acceptable results in HTML and LaTeX. The Mako function can be a plain Python function: <% def tfig(fileno): p = 'mov/wave_frames/frame_0' + fileno + '.png' # path if FORMAT in ("latex", "pdflatex"): text = r'\includegraphics[width=2cm]{%s}' % p elif FORMAT == "html": text = '<a href="%s"><img src="%s" width="300"></a>' % (p, p) else: text = '"%s": "%s"' % (fileno, p) # plain link return text %>  Note that for other formats than LaTeX and HTML we just return a link to the figure. Note A corresponding solution for Sphinx will not work because inline figures in Sphinx has a syntax with pipe symbols (‘|’) that interfere with the column separator in tables in DocOnce. Returning the HTML code in case of Sphinx will just display that HTML code in the cells, not the rendered HTML code. A solution that includes Sphinx is provided later. The resulting table is displayed below. 085 090 100 105 115 120 #### Generating the Entire Table¶ The specific structure of this table also suggest using Mako to generate the entire table: <% def generate_table(start, end, step, no_of_columns): # Heading text = '' horizontal_rule = '|----|\n' text += horizontal_rule text += '| '*no_of_columns + '|\n' text += horizontal_rule fig_counter = 0 for counter in range(start, end+1, step): fig_counter += 1 text += '| ' + tfig('%03d' % counter) + ' ' if fig_counter % no_of_columns == 0: text += '|\n' text += horizontal_rule return text %>${generate_table(80, 120, 5, 3)}


The result is a table like the one above, except that the horizontal rules and the heading are very short lines (but this is legal syntax - it just does not look appealing in the DocOnce source).

#### Generating the Entire Table in a Native Format via Mako¶

To allow Sphinx and other formats, it is best to generate the entire table. This can be done either by a Mako function or as a post process after DocOnce has created the output file. We show the Mako solution here.

Tip

A pure Python function Mako is easiest to develop in a separate Python program file because Python has better error messages than Mako. Also, Python has debugging facilities that make the development of the code much more efficient than writing in Mako. When the Python function works, it can be inserted in the DocOnce file inside the Mako directives <% and %>.

The Mako function for generating the entire table in LaTeX, HTML, and Sphinx format goes as follows.

<%
def generate_native_table(start, end, step, no_of_columns):
text = ''
if FORMAT in ("latex", "pdflatex"):
text += r"""\begin{quote}\begin{tabular}{%s}
\hline
\\
\hline
""" % ('c'*no_of_columns)
elif FORMAT in ("sphinx", "rst", "html"):
text += '<p><table border="1">\n<tr>'
fig_counter = 0
latex_columns = []
for counter in range(start, end+1, step):
fig_counter += 1
if FORMAT in ("latex", "pdflatex"):
latex_columns.append(r'\includegraphics[width=2cm]'\
'{mov/wave_frames/frame_%04d.png}\n' % counter)
elif FORMAT in ("sphinx", "rst", "html"):
text += '<td align="center"> '\
'<a href="mov/wave_frames/frame_%04d.png">'\
'<img src="mov/wave_frames/frame_%04d.png" width="300">'\
'</a> </td>\n' % (counter, counter)

if fig_counter % no_of_columns == 0:  # new row
if FORMAT in ("latex", "pdflatex"):
text += '   ' + ' & '.join(latex_columns)
if counter != end:
text += r'\\' + '\n'
latex_columns = []
elif FORMAT in ("sphinx", "rst", "html"):
text += '</tr>\n'
if counter != end:
text += '<tr>\n'  # begin new row
# Footer
if FORMAT in ("latex", "pdflatex"):
text += r"""\hline
\end{tabular}\end{quote}
"""
elif FORMAT in ("sphinx", "rst", "html"):
text += '</table>\n'
if FORMAT in ("sphinx", "rst"):
# Wrap raw HTML code
lines = text.splitlines()
text = '\n.. raw:: html\n\n'
for line in lines:
text += '    ' + line + '\n'
text += '\n'
return text
%>

## Example on call in DocOnce source
${generate_native_table(80, 120, 5, 3)}  One can easily add support for various other formats, such as pandoc, gwiki, mwiki, etc. The output in the current format is shown below. #### Generating the Entire Table in a Native Format as a Post Process¶ Instead of using Mako as shown above, we can invent our own syntax line for the table with figures and apply a script to the DocOnce output file to replace the special line with proper native code. We use the same generate_native_table function as above, but this time in a Python script. In the DocOnce source we place a line @@@FIGTABLE 80 120 5 3  which is meant to generate a table with figures where the numbers correspond to arguments in the generative_native_table function. Suppose we have run Terminal> doconce format sphinx mydoc  In the resulting mydoc.rst file we have the magic line @@@FIGTABLE .... Such lines can now be processed in our Python script: # read mydoc.rst into the string filestr pattern = r'@@@FIGTABLE (.+)' def replacement(m): # m is a MatchObject args = m.group(1) # Convert args to a tuple of words with right type args = [eval(arg) for arg in args.split()] text = generate_native_table(*args) filestr = re.sub(pattern, filestr, replacement) # write filestr back to manual.rst  This code makes use of a function for creating the replacement string for the re.sub command and demands a knowledge of regular expression syntax and the workings or re.sub. A more plain Python version goes like this: # read mydoc.rst into the string filestr lines = filestr.splitsplines() for i in range(len(lines)): if lines[i].startswith('@@@FIGTABLE'): args = lines[i][10:].strip() # Convert args to a tuple of words with right type args = [eval(arg) for arg in args.split()] text = generate_native_table(*args) lines[i] = text filestr = '\n'.join(lines) # make one string from all separate lines # write filestr back to manual.rst  Recommendation This latter way of inserting specialized native text after DocOnce has generated the output file is easier than using Mako and usually also safer. Lesson Learned The above examples show different techniques for extending the DocOnce capabilities. The ideas are not restricted to DocOnce: using Mako as a preprocessing step or inserting “magic” lines that you can later substitute by a script is possible in all types of ASCII-based documents, e.g., LaTeX, Sphinx, and Markdown. ### Example: Defining a Theorem Environment¶ DocOnce supports only basic formatting elements (headings, paragraphs, lists, etc.), while LaTeX users are used to fancy environments for, e.g., theorems. A flexible strategy is to typeset theorems using paragraph headings, which will look satisfactorily in all formats, but add comment lines that can be replaced by LaTeX environments via doconce replace. Theorems can be numbered using a variable in Mako. Here is an example on raw DocOnce code: <% theorem_counter = 4 %> # begin theorem label{theorem:fundamental1} <% theorem_counter += 1 theorem_fundamental1 = theorem_counter %> __Theorem${theorem_counter}.__
Let $a=1$ and $b=2$. Then $c=3$.
# end theorem

# begin proof
__Proof.__
Since $c=a+b$, the result follows from straightforward addition.
$\Diamond$|$END$
# end proof

As we see, the proof of Theorem ${theorem_counter} is a modest achievement.  The .p.tex output file now reads % begin theorem label{theorem:fundamental1} \paragraph{Theorem 5.} Let$a=1$and$b=2$. Then$c=3$. % end theorem % begin proof \paragraph{Proof.} Since$c=a+b$, the result follows from straightforward addition.$\Diamond$% end proof As we see, the proof of Theorem 5 is a modest achievement.  Note that with Mako variables we can easily create our own counters, and this works in any format. In LaTeX we can use both the generated numbers from Mako variables or we can use the labels. The next step is to replace the % begin ... and % end ... lines with the proper LaTeX expressions in the .p.tex file. Moreover, we need to remove the paragraphs with Theorem. The following Bash script does the job: file=mydoc.p.tex thpack='\\usepackage{theorem}\n\\newtheorem{theorem}{Theorem}[section]' doconce subst '% insert custom LaTeX commands\.\.\.'$thpack $file doconce subst '\\paragraph\{Theorem \d+\.\}' ''$file
doconce replace '% begin theorem' '\begin{theorem}' $file doconce replace '% end theorem' '\end{theorem}'$file


More heavy editing is better done in a Python script that reads the mydoc.p.tex file and performs string substitutions and regex substitutions as needed.

The resulting mydoc.tex file now becomes

\usepackage{theorem}
\newtheorem{theorem}{Theorem}[section]

...

\begin{theorem}
\label{theorem:fundamental1}

Let $a=1$ and $b=2$. Then $c=3$.
\end{theorem}

% begin proof
\paragraph{Proof.}
Since $c=a+b$, the result follows from straightforward addition.
$\Diamond$
% end proof

As we see, the proof of Theorem 5 is a modest
achievement.


Even better, HTML output looks nice as well.

Note that DocOnce supports fancy environments for verbatim code via the ptex2tex program with all its flexibility for choosing environments. Also doconce ptex2tex has quite some flexibility for typesetting computer code.

### Tools for Writing DocOnce Documents¶

• Emacs (with the modest DocOnce syntax highlighting), Vim, Gedit, etc.
• TeXMaker and Kile can in theory be adapted to handle DocOnce compilation and maybe even DocOnce constructs.

### Debugging¶

Given a problem, extract a small portion of text surrounding the problematic area and debug that small piece of text. DocOnce does a series of transformations of the text. The effect of each of these transformation steps are dumped to a logfile, named _doconce_debugging.log, if the to doconce format after the filename is debug. The logfile is intended for the developers of DocOnce, but may still give some idea of what is wrong. The section “Basic Parsing Ideas” explains how the DocOnce text is transformed into a specific format, and you need to know these steps to make use of the logfile.

## From DocOnce to Other Formats¶

Transformation of a DocOnce document mydoc.do.txt to various other formats is done with the script doconce format:

Terminal> doconce format formatname mydoc.do.txt


or just drop the extension:

Terminal> doconce format formatname mydoc


### Writing a Makefile¶

Producing HTML, Sphinx, and in particular LaTeX documents from DocOnce sources requires a few commands. Often you want to produce several different formats. The relevant commands should then be placed in a script that acts as a “makefile”.

We here show how to make a Bash script. Alternatively, scripts can be coded in Python or Perl, for instance. Below is the skeleton of a typical Bash script, called make.sh and run as bash make.sh in a Terminal application on Mac or any of the many terminal or console applications on Linux. On Windows you normally cannot run Bash scripts, so you should go for Python instead (maybe as the language in Windows Script Host).

#!/bin/bash
set -x  # write out all commands prior to execution

function system {
# Run operating system command and if failure, report and abort

"$@" if [$? -ne 0 ]; then
echo "make.sh: unsuccessful command $@" echo "abort!" exit 1 fi } # Do a hard clean (remove all files that can be regenerated) doconce clean # Do a soft clean (keep compiled files) #doconce lightclean # Run spellcheck system doconce spellcheck -d .dict4spell.txt *.do.txt name=mydoc # name of DocOnce master document # Compile to PDF system doconce pdflatex$name --latex_code_style=pyg  # + more options
system pdflatex -shell-escape $name system bibtex$name
system makeindex $name pdflatex -shell-escape$name
pdflatex -shell-escape $name # Compile to HTML (two different styles) styles="bootstrap solarized3" for style in$styles; do
system doconce format html $name --html_style=$style \
--html_output=${name}-${style}
system doconce split_html ${name}-${style}  # split at !split commands
done

# Compile to Sphinx
system doconce format sphinx $name system doconce sphinx_dir theme=alabaster$name
python automake_sphinx.py


In addition, you are strongly encouraged to make a clean script. Here is a quick Bash version, called clean.sh:

#!/bin/sh
doconce clean
rm -f *.html
rm -rf Trash
rm -f automake_sphinx.py


If you host your files in a Git repository, you should also have a .gitignore file in the root directory of the repository:

*~
.*~
tmp*
temp*
.#*
\#*
# DocOnce files
.*_html_file_collection
*.p.tex
.*.exerinfo
.*.quiz
.*.quiz.html
automake_sphinx.py
Trash
# LaTeX files:
*.log
*.dvi
*.aux
*.blg
*.idx
*.nav
*.out
*.toc
*.snm
*.vrb


If you host your files on GitHub and use a gh-pages branch to publish your documents, make sure you have an empty file called .nojeykyll in the root directory or the repository and that this file is present in the gh-pages branch. Without .nojekyll, GitHub will not display files starting with an underscore or dot, with the result that HTML and Sphinx documents are not rendered correctly.

### Generating a Makefile¶

The doconce makefile can be used to automatically generate such a makefile, more precisely a Python script make.py, which carries out the commands explained below. If our DocOnce source is in main_myproj.do.txt, we run

doconce makefile main_myproj html pdflatex sphinx


to produce the necessary output for generating HTML, pdfLaTeX, and Sphinx. Usually, you need to edit make.py to really fit your needs. Some examples lines are inserted as comments to show various options that can be added to the basic commands. A handy feature of the generated make.py script is that it inserts checks for successful runs of the many doconce commands, and if something goes wrong, the script aborts.

### Spell checking¶

Despite not being a part of compiling DocOnce to some format, spell checking is often the first task done in a make.sh or make.py file. DocOnce comes with a convenient support for spell checking, doconce spellcheck, where all code and mathematics are stripped from the document, as well as all inline verbatim expressions, comments, etc. Then the program ispell is run on the stripped document, and a list of misspellings is reported.

Any DocOnce document has its own set of “legal words” (approved by the authors) in the file .dict4spell.txt. When doconce spellcheck reports new misspellings, some are corrected and some are added to .dict4spell.txt. The spell checker applies an American dictionary and the user’s custom dictionary in .dict4spell.txt.

The work flow is simple:

1. Run doconce spellcheck -d .dict4spell.txt *.do.txt
2. Examine misspellings.txt  for misspellings and make corrections in the source files.
3. Rerun doconce spellcheck and repeat the procedure.
4. When all words in misspellings.txt |nbsp|  are acceptable, add these to the current custom dictionary by cp new_dictionary.txt~ .dict4spell.txt.

Run doconce spellcheck without any arguments to get more description of what kind of files that are produced. For example, the text in mydoc.do.txt, stripped for math, code, and other special constructions, is available in tmp_stripped_mydoc.do.txt and can be copied into (e.g.) Microsoft Word for grammar check.

### Preprocessing¶

The preprocess and mako programs are used to preprocess the file. The DocOnce program detects whether preprocess and/or mako statements are present and runs the corresponding programs, first preprocess and then mako.

Variables to preprocess and/or mako can be added after the filename with the syntax -DMYVAR, -DMYVAR=val or MYVAR=val.

• The form -DMYVAR defines the variable MYVAR for preprocess (like the same syntax for the C preprocessor - MYVAR is defined, but has not specific value). When running mako, -DMYVAR means that MYVAR has the (Python) value True. You can test for # #ifdef MYVAR in Preprocess and % if MYVAR: in Mako.
• The expressions -DMYVAR=val and MYVAR=val are equivalent. When running preprocess, MYVAR is defined and has the value val (# #ifdef MYVAR and # #if MYVAR == "val" are both true tests), while for mako, MYVAR exists as variable and has the value val (% if MYVAR == "val" is true).

Note that MYVAR=False defines MYVAR in preprocess and any test # #ifdef MYVAR is always true, regardless of the value one has set MYVAR to, so a better test is # #if MYVAR == True. In general, it is recommended to go with preprocess directives if the tests are very simple, as in # #ifdef MYVAR or # #if FORMAT == "latex", otherwise use only mako syntax like % if MYVAR or YOURVAR: to incorporate if tests in the preprocessor phases.

Two examples on defining preprocessor variables are

Terminal> doconce format sphinx mydoc -Dextra_sections -DVAR1=5
Terminal> doconce format sphinx mydoc extra_sections=True VAR1=5


The variable FORMAT is always defined as the current format when running preprocess or mako. That is, in the above examples, FORMAT is defined as sphinx. Inside the DocOnce document one can then perform format specific actions through tests like #if FORMAT == "sphinx" (for preprocess) or % if FORMAT == "sphinx": (for mako).

The result of running preprocess on a DocOnce file mydoc.do.txt is available in a file tmp_preprocess__mydoc.do.txt. Similarly, the result of running mako is available in tmp_mako__mydoc.do.txt. By examining these files one can see exactly what the preprocessors have done.

The command-line arguments --no_preprocess and --no_mako turn off running preprocess and mako, respectively.

#### Variable Substition with Preprocessors¶

A variable VAR=value given on the command line (or -DVar=value) can be used in Preprocess and Mako tests. With Mako, the variable can also be used inside text, as ${VAR}, and Mako will substitute the variable by its value. Preprocess can also substitute a variable by its value, but this is (on DocOnce’s use of Preprocess) restricted to filenames in #include statements. With the command-line option --preprocess_include_subst, any -DVAR=value variable will lead to a susbtitution of VAR by value in included filenames. For example, # #include "MYDIR/myfile.do.txt" and -DMYDIR=RN2 will lead to inclusion of the file RN2/myfile.do.txt. Note that for this Preprocess substitution, the variable in the filename must be MYDIR, not ${MYDIR} as with Mako.

Inline comments (inside square brackets) in the text are removed from the output by

Terminal> doconce format latex mydoc --skip_inline_comments


One can also remove all such comments from the original DocOnce file by running:

Terminal> doconce remove_inline_comments mydoc


This action is convenient when a DocOnce document reaches its final form and comments by different authors should be removed.

### Notes¶

DocOnce does not have a tag for longer notes, because implementation of a “notes feature” is so easy using the preprocess or mako programs. Just introduce some variable, say NOTES, that you define through -DNOTES (or not) when running doconce format .... Inside the document you place your notes between # #ifdef NOTES and # #endif preprocess tags. Alternatively you use % if NOTES: and % endif that mako will recognize. In the same way you may encapsulate unfinished material, extra material to be removed for readers but still nice to archive as part of the document for future revisions.

### Demo of Different Formats¶

A simple scientific report is available in a lot of different formats. How to create the different formats is explained in more depth in the coming sections.

### Tweaking the DocOnce Output¶

Occasionally, one would like to tweak the output in a certain format from DocOnce. One example is figure filenames when transforming DocOnce to reStructuredText. Since DocOnce does not know if the .rst file is going to be filtered to LaTeX or HTML, it cannot know if .eps or .png is the most appropriate image filename. The solution is to use a text substitution command or code with, e.g., sed, perl, python, or scitools subst, to automatically edit the output file from DocOnce. It is then wise to run DocOnce and the editing commands from a script to automate all steps in going from DocOnce to the final format(s). The make.sh files in docs/manual and docs/tutorial constitute comprehensive examples on how such scripts can be made.

### Useful Options for doconce format¶

The doconce format command used to translate a DocOnce document to an output format performs some syntax check and to notify the user about common problems. There are some useful options for turning on additional checks:

• --labelcheck=on (or off) to check that every ref reference has a corresponding label definition within the document (this check may lead to wrong diagnostics, e.g., when a label is defined in an external document and referred via generalized references, so the check must be used with care)
• --urlcheck checks that all URLs referred to in the document are valid.

Other useful options are

• --os_prompt=PROMPT> sets the prompt, here PROMPT>, as terminal prompt in output from running OS commands with the @@@OSCMD instruction. The value None gives no prompt.
• --code_prefix=X prefixes all @@@CODE imports with some path X (if the source files are located in some other directory)
• --figure_prefix=X and --movie_prefix=X prefix figure/movie file names with a path or URL
• --sections_down and --sections_up move all sections down or up (e.g., sections become subsections or chapters).
• --tables2csv translates each table to a CSV file.
• --short_title=X sets a short title X for the document.
• --toc_depth=X: controls the depth of the table of contents in documents. Default value of X is 3, meaning chapters, sections, and subsections. X as 0 gives the table of contents as a nested list in Bootstrap styles.

Many more options, depending on the output format, are listed in the following sections. A list of all options is otbained by running doconce format --help (or preferably doconce format --help | less since the output is extensive).

## HTML¶

### Basic HTML Output¶

Making an HTML version of a DocOnce file mydoc.do.txt is performed by

Terminal> doconce format html mydoc


The resulting file mydoc.html can be loaded into any web browser for viewing.

### Typesetting of Code¶

If the Pygments package (including the pygmentize program) is installed, code blocks are typeset with aid of this package. The command-line argument --no_pygments_html turns off the use of Pygments and makes code blocks appear with plain (pre) HTML tags. The option --pygments_html_linenos turns on line numbers in Pygments-formatted code blocks. A specific Pygments style is set by --pygments_html_style=style, where style can be default, emacs, perldoc, and other valid names for Pygments styles.

### Handling of Movies¶

MP4, WebM, and Ogg movies are typeset with the HTML5 video tag and the HTML code tries to load as many versions among MP4, WebM, and Ogg as exist (and the files are loaded in the mentioned order). If just the specified file is to be loaded, use the --no_mp4_webm_ogg_alternatives command-line option. Other movie formats, e.g., .flv, .mpeg and .avi, are embedded via the older embed tag.

### HTML Styles¶

The HTML style can be defined either in the header of the HTML file, using a named built-in style; in an external CSS file; or in a template file.

An external CSS file filename used by setting the command-line argument --css=filename. There available built-in styles are specified as --html_style=name, where name can be

• solarized: the famous solarized style (yellowish),
• blueish: a simple style with blue headings (default),
• blueish2: a variant of bluish,
• bloodish: as bluish, but dark read as color,
• bootstrap* or bootswatch* in a lot of variants, see doconce format --help for a list of all styles.

There is a comprehensive demonstration of almost all available styles!

Using --css=filename where filename is a non-existing file makes DocOnce write the built-in style to that file. Otherwise the HTML links to the CSS stylesheet in filename. Several stylesheets can be specified: --ccs=file1.css,file2.css,file3.css.

### HTML templates¶

Templates are HTML files with ready-made headers, footers, and style specifications where plain HTML text can be inserted in “slots” in the template file. Typically, there is a slot %(main)s for the main body of text, %(title)s for the title, and %(date)s for the date. Templates are designed beforehand and doconce format puts the translated HTML text into the template to form the complete HTML document.

DocOnce comes with a few ready-made HTML templates. The usage of templates is described in a separate document. That document describes how you your DocOnce-generated HTML file can have any specified layout.

The HTML file can be embedded in a template with your own tailored design, see a tutorial on this topic. The template file must contain valid HTML code and can have three “slots”: %(title)s for a title, %(date)s for a date, and %(main)s for the main body of text. The latter is the DocOnce document translated to HTML. The title becomes the first heading in the DocOnce document, or the title (but a title is not recommended when using templates). The date is extracted from the DATE: line. With the template feature one can easily embed the text in the look and feel of a website. DocOnce comes with two templates in bundled/html_styles. Just copy the directory containing the template and the CSS and JavaScript files to your document directory, edit the template as needed (also check that paths to the css and js subdirectories are correct - according to how you store the template files), and run

Terminal> doconce format html mydoc --html_template=mytemplate.html


The template in style_vagrant also needs an extra option --html_style=bootstrap.

### Splitting HTML documents¶

The !split instruction (on separate lines) signifies a pagebreak. A command doconce split_html is needed after doconce format to actually perform the split. The doconce split_html command has several options for setting the type of splitting, type of navigation buttons, etc. Just type doconce split_html to see the options. Here is an example with separate links for each page (pagination) at the top and bottom of each page:

Terminal> doconce format html mydoc --html_style=bootswatch_journal
Terminal> doconce split_html mydoc --nav_buttontop+bottom --pagination


#### The HTML File Collection¶

There are usually a range of files needed for an HTML document arising from a DocOnce source. The needed files are listed in .basename_html_file_collection, where basename is the filestem of the DocOnce file (i.e., the DocOnce source is in basename.do.txt).

#### Filenames¶

An HTML version of a DocOnce document is often made in different styles, calling for a need to rename the HTML output file. This is conveniently done by the --html_output=mydoc option, where mydoc is the filestem of the associated HTML files. The .mydoc_html_file_collection file lists all the needed files for the HTML document. Here is an example on making three versions of the HTML document: mydoc_bloodish.html, mydoc_solarized, and mydoc_vagrant.

Terminal> doconce format html mydoc --html_style=bloodish \
--html_output=mydoc_bloodish
Terminal> doconce split_html mydoc_bloodish.html
Terminal> doconce format html mydoc --html_style=solarized \
--html_output=mydoc_solarized \
Terminal> doconce format html mydoc --html_style=vagrant \
--html_output=mydoc_vagrant --pygments_html_style=default \
Terminal> doconce split_html mydoc_vagrant.html


### URL to files hosted on GitHub¶

The generated HTML code will have URLs to files in the DocOnce repo at GitHub. The type of URL is set with the --html_raw_github_url=... option:

• --html_raw_github_url=safe or --html_raw_github_url=cdn.rawgit: safe URL for high traffic production sites (default)
• --html_raw_github_url=test or --html_raw_github_url=rawgit: recommended URL for low traffic development sites - use this when developing HTML pages and the DocOnce GitHub links in the HTML files are also developed and subject to changes
• --html_raw_github_url=github or --html_raw_github_url=raw.github: URL directly to the raw GitHub file (https://raw.github.com/hplgit/doconce/...) that may fail to load properly in (e.g.) Internet explorer
• --html_raw_github_url=githubusercontent or --html_raw_github_url=raw.githubusercontent: as the one above, but using https://raw.githubusercontent.com instead

### Other HTML options¶

The Bootstrap family of styles have become very popular since they provide responsive pages for phones and small tablets. There are several specific options for Bootstrap styles:

• --html_code_style=on,off,inherit,transparent: control the style of inline verbatim code code tags. With off, inherit, or transparent the verbatim text inherits foreground and background color from its surroundings, while on (default) means that the typesetting is css-specified. This option is most relevant for Bootstrap styles to avoid the redish typesetting of inline verbatim text.
• --html_pre_style=on,off,inherit,transparent: control the style of code blocks in pre tags. With off, inherit, or transparent the code blocks inherit foreground and background color from their surroundings, while on (default) means that code block colors are css-specified. This option is most relevant for Bootstrap styles to avoid white background in code blocks inside colorful admons.
• --html_bootstrap_navbar=on,off: turn the Bootstrap navigation bar on or off.
• --html_bootstrap_jumbotron=on,off,h2: turn the jumbotron intro on or off, and govern the size of the document title. Default is on, while h2 means a jumbotron with h2 (section) size of the title (normally the jumbotron has huge heading fonts so some jumbotrons look better with h2 typesetting of the document title).
• --html_quiz_button_text=X: set a text on the answer button for Bootstrap-style quizzes. Without this option a small icon is used.

Other options:

• --html_share=http://... makes sharing buttons at the end of the document: email, Facebook, Google+, LinkedIn, Twitter, and print by default. --html_share=http://...,twitter,linkedin will make just to sharing buttons for Twitter and LinkedIn. Sites are separated by comma and valid names are email, facebook, google+, linkedin, twitter, and print. The URL http://... must be the URL where the document is published.
• --html_toc_indent=X: indent sections/subsections X spaces in the table of contents.
• --html_body_font=: specify font for text body. The value ? lists available fonts.
• --html_heading_font=: specify font for headings. The value ? lists available fonts.
• --html_video_autoplay=True,False: let videos play automatically (True, default) or not (False) when the HTML page is loaded.
• --html_admon=X: specify typesetting of admonitions. Values of X are colors, gray, yellow, apricot, lyx, paragraph. For Bootstrap styles only to other values are legal: botstrap_panel or bootstrap_alert. See demos for how these look like.
• --html_admon_bg_color=X: set the background color in admonitions.
• --html_admon_bd_color=X: set the boundary color in admonitions.
• --html_admon_shadow: add a shadow effect in admonitions.
• --html_box_shadow: add a shadow effect in box environments (!bbox).
• --html_exercise_icon=X: specify an icon to more easily notify exercises. X can be any filename question_*.png in the bundled/html_images directory in the DocOnce repo. With X as default, a default icon choice is made, based on the current style.
• --html_exercise_icon_width=X: set the width of the exercise icon image to X pixels.
• --exercise_numbering=absolute, chapter
• --html_DOCTYPE: insert <!DOCTYPE HTML> at the top of the HTML output file. This is normally recommended, but malformed CSS files will then not be loaded (so by default, the doctype is not specified). This option is necessary for correct rendering of Bootstrap styles in Internet Explorer.
• --html_links_in_new_window: open all links as new tabs.
• --html_figure_hrule=X: control the use of horizontal rules in figures. X is top by default; other values are none (no rules), bottom and top+bottom.
• --allow_refs_to_external_docs (do not abort if there are references whose labels are not found)

### Blog Posts¶

DocOnce can be used for writing blog posts provided the blog site accepts raw HTML code. Google’s Blogger service (blogger.com or blogname.blogspot.com) is particularly well suited since it also allows extensive LaTeX mathematics via MathJax.

1. Write the text of the blog post as a DocOnce document without any title, author, and date.
2. Generate HTML as described above.
3. Copy the text and paste it into the text area in the blog post (just delete the HTML code that initially pops up in the text area). Make sure the input format is HTML.

See a simple blog example and a scientific report for demonstrations of blog posts at blogspot.no.

Warning

The comment field after the blog post does not recognize MathJax (LaTeX) mathematics or code with indentation. However, using a MathJax bookmarklet, e.g., at http://checkmyworking.com/misc/mathjax-bookmarklet/, one can get the mathematics properly rendered. The comment fields are not suitable for computer code, though, as HTML tags are not allowed.

Note

Figure files must be uploaded to some web site and the local filenames name must be replaced by the relevant URL. This is usually done by using the --figure_prefix=http://project.github.io/... option to give some URL as prefix to all figure names (a similar --movie_prefix= option exists as well).

Changing figure names in a blog post can also be done “manually” by some editing code in the script that compiles the DocOnce document to HTML format:

cp mydoc.do.txt mydoc2.do.txt
url="https//raw.github.com/someuser/someuser.github.com"
dir="master/project/dir1/dir2"
for figname in fig1 fig2 fig3; do
doconce replace "[$figname," "[$site/$dir/$figname.png," \
mydoc2.do.txt
done
doconce format html mydoc2
# Paste mydoc2.html into a new blog post page


Blog posts at Google can also be published automatically through email. A Python program can send the contents of the HTML file to the blog site’s email address using the packages smtplib and email.

WordPress (wordpress.com) allows raw HTML code in blogs, but has very limited LaTeX support, basically only formulas. The --wordpress option to doconce modifies the HTML code such that all equations are typeset in a way that is acceptable to WordPress. Look at a simple doconce example and a scientific report to see blog posts with mathematics and code on WordPress.

Speaking of WordPress, the related project http://pressbooks.com can take raw HTML code (from DocOnce, for instance, but use the --wordpress option) and produce very nice-looking books. There is support for LaTeX mathematics as in WordPress blog posts, meaning that one cannot refer to equations.

[[[

## Pandoc and Markdown¶

Output in Pandoc’s extended Markdown format results from

Terminal> doconce format pandoc mydoc


or (equivalent)

Terminal> doconce format markdown mydoc


Test on FORMAT == 'pandoc' for Markdown

Note that even though it works to write doconce format markdown, the FORMAT variable that is defined in all DocOnce documents has the value pandoc for all the Markdown formats. A test like FORMAT == 'markdown' will not work!

The name of the output file is mydoc.md. There are four supported dialects of Markdown (see sections below for more information):

• Pandoc-extended Markdown
• GitHub-flavored Markdown
• MultiMarkdown
• Strict Markdown

From the Markdown format one can go to numerous other formats using the pandoc program:

Terminal> pandoc -R -t mediawiki -o mydoc.mwk --toc mydoc.md


Pandoc supports latex, html, odt (OpenOffice), docx (Microsoft Word), rtf, texinfo, to mention some. The -R option makes Pandoc pass raw HTML or LaTeX to the output format instead of ignoring it, while the --toc option generates a table of contents. See the Pandoc documentation for the many features of the pandoc program.

### Markdown to HTML conversion¶

The HTML output from pandoc needs adjustments to provide full support for MathJax LaTeX mathematics, and for this purpose one should use doconce md2html:

Terminal> doconce format pandoc mydoc
Terminal> doconce md2html mydoc


The result mydoc.html can be viewed in a browser.

### Strict Markdown¶

The option --strict_markdown_output generates plain or strict Markdown without the many extension that Pandoc accepts in Markdown syntax.

### GitHub-flavored Markdown¶

Adding the command-line option github-md turns on the GutHub-flavored Markdown dialect, which is used for the issue tracker on GitHub. A special feature is the support of task lists: unnumbered lists with [x] (task done) or [ ] (task not done). (Tables get typeset directly as HTML and the syntax for code highlighting is different from Pandoc extended Markdown.) Below is a typical response in a GitHub issue tracker where one first quotes the issue and then provides an answer:

!bquote
===== Problems with a function =====

There is a problem with the f(x) function

!bc pycod
def f(x):
return 1 + x
!ec
!equote

OK, this is fixed:

!bc pycod
def f(x, a=1, b=1, c=1):
return a*x**2 + b*x + c
!ec

* [x] Offer an f(x) function
* [ ] Extension to cubic functions
* [x] Allowing general coefficient in the quadratic function

=== Remaining functionality ===

|---------------------------------------------------------------|
| function | purpose                        | state |
|----l-----------l------------------------------l---------------|
|  g(x)  | Compute the Gaussian function. | Formula ready. |
|  h(x)  | Heaviside function.            | Formula ready. |
|  I(x)  | Indicator function.            | Nothing done yet. |
|---------------------------------------------------------------|


Say this text is stored in a file mycomments.do.txt. Running

Terminal> doconce format pandoc mycomments --github_md


produces the Markdown file mycomments.md, which can be pasted into the Write field of the GitHub issue tracker. Turning on Preview shows the typesetting of the quote, compute code, inline verbatim, headings, the task list, and the table.

### MultiMarkdown¶

The option --multimarkdown_output generates the MultiMarkdown version of Markdown (as opposed to Pandoc-extended Markdown (default), strict Markdown, or GitHub-flavored Markdown).

### Strapdown rendering of Markdown text¶

Strapdown is a tool that can render Markdown text nicely in a web browser by just inserting an HTML header and footer in the Markdown file and load the file into a browser. The option --strapdown outputs the relevant header and footer. The output file must be renamed such that it gets the extension .html:

Terminal> doconce format pandoc mydoc --strict_markdown_output \
--strapdown --bootstrap_bootwatch_theme=slate
Terminal> mv mydoc.md mydoc.html


The --bootstrap_bootwatch_theme=theme option is used to choose a Bootswatch theme whose names are found on the Strapdown page.

### Using Pandoc to go from LaTeX to MS Word or HTML¶

Pandoc is useful to go from LaTeX mathematics to, e.g., HTML or MS Word. There are two ways (experiment to find the best one for your document): doconce format pandoc and then translating using doconce md2latex (which runs pandoc), or doconce format latex, and then going from LaTeX to the desired format using pandoc. Here is an example on the latter strategy:

Terminal> doconce format latex mydoc
Terminal> doconce ptex2tex mydoc
Terminal> doconce replace '\Verb!' '\verb!' mydoc.tex
Terminal> pandoc -f latex -t docx -o mydoc.docx mydoc.tex


When we go through pandoc, only single equations, align, or align* environments are well understood for output to HTML.

Note that DocOnce applies the Verb macro from the fancyvrb package while pandoc only supports the standard verb construction for inline verbatim text. Moreover, quite some additional doconce replace and doconce subst edits might be needed on the .mkd or .tex files to successfully have mathematics that is well translated to MS Word. Also when going to reStructuredText using Pandoc, it can be advantageous to go via LaTeX.

## LaTeX¶

Note

XeLaTeX and pdfLaTeX are used very much in the same way as standard LaTeX. The minor differences are described in separate sections of the documentation of the DocOnce to LaTeX translation.

### Overview¶

Making a LaTeX file mydoc.tex from mydoc.do.txt can be done in two ways:

1. direct translation to a .tex file
2. translation to a .p.tex file

In the latter case, one must apply the ptex2tex program or the simplified doconce ptex2tex program to translate the .p.tex file to a plain .tex file. This step involves the specification of how blocks of verbatim code should be typeset in LaTeX. Before 2015, DocOnce always translated to the .p.tex syntax and required the use of ptex2tex or doconce ptex2tex. Now, one can choose a direct translation, which is simpler and actually more versatile than even using the ptex2tex program.

Direct translation is specified by the --latex_code_style= command-line option. A separate document, Demonstration of DocOnce support for LaTeX code block environments, describes how this option is used and the demonstrates many possibilities that are available. One popular choice is

default:lst[style=blue1_bluegreen]@dat:lst[style=gray]@sys:vrb


This value gives syntax-highlighted blue-green code on a blue background and sets data files with gray background.

The --latex_code_style= option makes the use of ptex2tex or doconce ptex2tex redundant.

### The old ptex2tex step¶

Here, we describe the old translation via a .p.tex file. New users should jump over this information and use the --latex_code_style= option to specify verbatim code environments.

First we compile the DocOnce source to the ptex2tex format, and then we compile the ptex2tex format to standard LaTeX. The ptex2tex format can be viewed as an extended LaTeX. For DocOnce users, the ptex2tex format essentially means that the file consists of

1. if-else statements for the preprocess processor such that LaTeX constructions can be activated or deactivated, and
2. all code environments can be typeset according to a .ptex2tex.cfg configuration file.

Point 2 is only of interest if you aim to use a special computer code formatting that requires you to use a configuration file and the ptex2tex program.

The reason for generating ptex2tex and not standard LaTeX directly from DocOnce was that the ptex2tex format shows a range of possible LaTeX constructions for controlling the layout. It can be instructive for LaTeX users to look at this code before choosing specific parts for some desired layout. Experts may also want to edit this code (which should be automated by a script such that the edits can be repeated when the DocOnce source is modified, see Step 2b below). (Direct control of the LaTeX layout in the doconce format program would not spit out alternative LaTeX constructs as is now done through the ptex2tex step.)

Going from ptex2tex format to standard LaTeX format is enabled by either the ptex2tex program or DocOnce’s (simplified) version of it: doconce ptex2tex.

Inline verbatim tries to use texttt and not Verb if possible

Inline verbatim code, typeset with backticks in DocOnce, is translated to

\Verb!text!


or similar constructions with other delimiters if the pipe is used in text. Thereafter, if text does not contain illegal characters for the \texttt command, the latter is used instead since then LaTeX can insert linebreaks in the inline verbatim text and hence avoid overfull hboxes.

### LaTeX-PDF: Generate LaTeX (Step 1)¶

#### The translation command¶

Filter the doconce text directly to valid LaTeX using the --latex_code_style= option:

Terminal> doconce format pdflatex mydoc --latex_code_style=vrb


Without --latex_code_style=, the output will be a mydoc.p.tex file that has to be converted to a standard mydoc.tex LaTeX file via the programs ptex2tex or doconce ptex2tex.

#### Newcommands¶


#### Output for paper vs screen¶

An option --device=paper makes some adjustments for documents aimed at being printed. For example, links to web resources are associated with a footnote listing the complete web address (URL). (Very long URLs in footnotes can be shortened using services such as http://goo.gl/, http://tinyurl.com/, and https://bitly.com/.) The default, --device=screen, creates a PDF file for reading on a screen where links are just clickable.

#### Command-line options¶

There are many additional options (run doconce format --help and look for options starting with --latex to get a more verbose description):

• --latex_code_style=lst,vrb,pyg,any
• --latex_font=helvetica,palatino
• --latex_papersize=a4,a6
• --latex_bibstyle=plain (name of BibTeX style)
• --latex_title_layout=titlepage, std, beamer, doconce_heading, Springer_collection
• --latex_style=std, Springer_sv, Springer_lncse, Springer_llncs, Springer_lnup, Springer_T2, Springer_T4, siamltex, siamltexmm, elsevier
• --latex_packages=package1,package2,package3 (list of extra packages to be included [5])
• --draft (turns on draft mode in documentclass, otherwise final mode)
• --latex_copyright=everypage,titlepages (copyright on every page or on titlepage and chapter pages)
• --latex_list_of_exercises=loe,toc,none (LaTeX list of exercises, integrated into the table of contents, or no list)
• --latex_fancy_header (chapter/section headings at top of pages, style depends on value of --latex_section_headings)
• --latex_section_headings=std,blue,bookblue,strongblue,gray,gray-wide (standard LaTeX, blue headings, blue headings for books, strong blue headings, white in gray box, white in gray box that fills the page width)
• --latex_table_format=quote, center, footnotesize, tiny (environment around tables)
• --latex_colored_table_rows=blue, gray, no (color of every two lines in tables)
• --latex_table_row_sep=1.5 (increase the separation between table (and matrix) rows by a factor 1.5)
• --latex_todonotes (inline comments typeset as “bubbles”)
• --latex_double_spacing (to ease hand-writing between the lines)
• --latex_line_numbers (to ease references to sentences)
• --latex_labels_in_margin (name of section, equation, citation labels in the margin)
• --latex_preamble=filename (user-specific preamble)
• --latex_admon=mdfbox, graybox2, grayicon, yellowicon, paragraph, colors1, colors2
• --latex_admon_color=0.34,0.02,0.8 (background color in admons)
• --latex_admon_envir_map=2 (code environment names in admons)
• --exercise_numbering=absolute, chapter
• --latex_movie=media9, href, multimedia, movie15 (control typesetting of movies)
• --latex_movie_controls=on
• --latex_external_movie_viewer (for movie15 package)
• --xelatex (prepare for XeLaTeX)

The overall LaTeX style is much governed by --latex_title_layout and --latex_style. For the former, titlepage gives a separate title page; std is just standard LaTeX handling of title, author, and date; doconce_heading is a more modern heading, Springer_collection is used with --latex_style=Springer_lncse for an edited book; beamer is needed if the DocOnce document is to be translated to LaTeX Beamer slides. For --latex_style, std gives standard LaTeX behavior; Springer_lncse is for Springer’s LNCSE book series style (to be used with --latex_title_layout=Springer_collection if the book is an edited book); Springer_llncs is for Springer’s Lecture Notes in Computer Science series (normally an edited book that also requres --latex_title_layout=Springer_collection); Springer_lnup for Springer’s Lecture Notes for Undergraduate Physics books, Springer_T2 for Springer’s T2 book layout, siamltex, for the LaTeX style of papers in standard SIAM journals (also used far beyond SIAM journals and requires the stylefiles siamltex.cls and siam10.clo), siamltexmm for the new multimedia SIAM journal style (requires siamltex.cls and siam10.clo), elsevier for the style of papers to be submitted to Elsevier journals (--latex_elsevier_journal= can be used to set the journal name, and the style requires elsarticle.cls and elsarticle-num.bst).

 [5] Listing varioref in as package automatically leads to references with page numbers, if the element referred to is not on the same page. This is often very helpful, e.g., “see Figure 5.3 on page 67”.

#### Syntax highlighting¶

The style of verbatim blocks of computer code is specified by --latex_code_style=X, where X can be set in a very flexible way. There are three main values, corresponding to three LaTeX tools for verbatim type setting:

• vrb for plain Verbatim style (fancyvrb LaTeX package)
• pyg for the Pygments style (mintex LaTeX package)
• lst for the Listings styles (listingsutf8 LaTeX package)
• any for any environment named any from any package

A separate demo explains the many possible settings of X. Popular choices are minimalistic plain verbatim,

--latex_code_style=vrb


maybe with an added light blue background color,

--latex_code_style=vrb-blue1


or the default Pygments style,

--latex_code_style=pyg


or the Listings-based style with yellow background color

--latex_code_style=lst-yellow2


It is easy to specify different styles for different code environments, say blue background with plain verbatim style for code but a special terminal window for the sys environment:

"--latex_code_style=default:vrb-blue1@
sys:vrb[frame=lines,label=\\fbox{{\tiny Terminal}},
framesep=2.5mm,framerule=0.7pt,fontsize=\fontsize{9pt}{9pt}]"


(but no linebreaks, as here, they are for formatting this document only).

#### Drafts¶

During development of a manuscript, may prefer line numbers, double line spacing, frequent use of inline comments, and label names printed in the margin. This is enabled by the options --latex_line_numbers --latex_double_spacing --latex_todonotes --latex_labels_in_margin. One may also (automatically) edit the final argument in the documentclass heading to draft as this will mark overful lines (hboxes).

#### Potential problems with ampersand¶

Another useful option for LaTeX documents is --no_ampersand_quote, which prevents ampersands from getting a backskash. This is necessary if one inserts native latex code for tables inside % if FORMAT in ('latex', 'pdflatex'): (or similar preprocess syntax) tests.

#### Part 2 of Step 1 (outdated)¶

In case you did not specify the --latex_code_style= option, you must run ptex2tex (if you have installed the Python ptex2tex package) to make a standard LaTeX file,

Terminal> ptex2tex mydoc


If you do not have ptex2tex, or do not bother to make the required configuration file for ptex2tex (you may of course rely on the default file), a (simplified) version of ptex2tex that comes with DocOnce can be run:

Terminal> doconce ptex2tex mydoc


The ptex2tex command can set two preprocessor variables:

• PREAMBLE to turn the LaTeX preamble on or off (i.e., complete document or document to be included elsewhere - and note that the preamble is only included if the document has a title, author, and date)
• MINTED for inclusion of the minted package for typesetting of code with the Pygments tool (which requires latex or pdflatex to be run with the -shell-escape option); not used for doconce ptex2tex only in the ptex2tex program

If you are not satisfied with the generated DocOnce preamble, you can provide your own preamble by adding the command-line option --latex_preamble=myfile. In case myfile contains a documentclass definition, DocOnce assumes that the file contains the complete preamble you want (not that all the packages listed in the default preamble are required and must be present in myfile). Otherwise, myfile is assumed to contain additional LaTeX code to be added to the DocOnce default preamble.

The ptex2tex tool makes it possible to easily switch between many different fancy formattings of computer code in LaTeX documents. After any !bc command in the DocOnce source you can insert verbatim block styles as defined in your .ptex2tex.cfg file, e.g., !bc sys for a terminal session, where sys is set to a certain environment in .ptex2tex.cfg (e.g., CodeTerminal). There are about 40 styles to choose from, and you can easily add new ones.

The doconce ptex2tex allows specifications of code environments as well. Here is an example:

Terminal> doconce ptex2tex mydoc \
"sys=\begin{quote}\begin{verbatim}@\end{verbatim}\end{quote}" \
fpro=minted fcod=minted shcod=Verbatim envir=ans:nt


Note that @ must be used to separate the begin and end LaTeX commands, unless only the environment name is given (such as minted above, which implies \begin{minted}{fortran} and \end{minted} as begin and end for blocks inside !bc fpro and !ec). Specifying envir=ans:nt means that all other environments are typeset with the anslistings.sty package, e.g., !bc cppcod will then result in \begin{c++}. A predefined shortcut as in shcod=Verbatim-0.85 results in denser vertical spacing (baselinestretch 0.85 in LaTeX terminology), and shcod=Verbatim-indent implies indentation of the verbatim text. Alternatively, one can provide all desired parameters \begin{Verbatim} instruction using the syntax illustrated for the sys environments above.

If no environments like sys, fpro, or the common envir are defined on the command line, the plain \begin{Verbatim} and \end{Verbatim} instructions are used.

### LaTeX-PDF: Edit the LaTeX File (Step 2, Optional)¶

You can edit the mydoc.tex file to your needs. For example, you may want to substitute section by section* to avoid numbering of sections, you may want to insert linebreaks (and perhaps space) in the title, etc. This can be automatically edited with the aid of the doconce replace and doconce subst commands. The former works with substituting text directly, while the latter performs substitutions using regular expressions. You will use doconce replace to edit section{ to section*{:

Terminal> doconce replace 'section{' 'section*{' mydoc.tex


For fixing the line break of a title, you may pick a word in the title, say “Using”, and insert a break after than word. With doconce subst this is easy employing regular expressions with a group before “Using” and a group after:

Terminal> doconce subst 'title\{(.+)Using (.+)\}' \
'title{\g<1> \\\\ [1.5mm] Using \g<2>' mydoc.tex


A lot of tailored fixes to the LaTeX document can be done by an appropriate set of text replacements and regular expression substitutions. You are anyway encourged to make a script for generating PDF from the LaTeX file so the doconce subst or doconce replace commands can be put inside the script.

### LaTeX-PDF: Generate PDF (Step 3)¶

Compile mydoc.tex and create the PDF file, using pdflatex:

Terminal> pdflatex mydoc
Terminal> pdflatex mydoc
Terminal> makeindex mydoc   # if index
Terminal> bibtex mydoc      # if bibliography
Terminal> pdflatex mydoc


One can also compile mydoc the “old way” with latex and dvipdf. Use doconce format latex in that case and proceed with latex mydoc.

If the minted style is used, latex, pdflatex, or xelatex must be run with the -shell-escape option:

Terminal> pdflatex -shell-escape mydoc
Terminal> pdflatex -shell-escape mydoc
Terminal> makeindex mydoc   # if index
Terminal> bibtex mydoc      # if bibliography
Terminal> pdflatex -shell-escape mydoc


### XeLaTeX¶

XeLaTeX is an alternative to pdfLaTeX and is run in almost the same way, except for the --xelatex flag to doconce format:

Terminal> doconce format pdflatex mydoc --xelatex \
--latex_code_style=lst
Terminal> xelatex mydoc


### From PDF to e-book formats¶

PDF (as generated from LaTeX above) can be read on most devices today. However, for Kindle and other devices specialized for e-books you need to convert to ePub or MOBI. The Calibre program can produce epub, mobi, and other e-book formats from PDF, see a description. Unfortunately, Calibre cannot deal satisfactory with LaTeX math so the usefulness for DocOnce writers is limited. See the section LaTeX Blocks of Mathematical Text for more information on how to generate ePub.

### Microsoft Word or LibreOffice¶

Transforming DocOnce files to Word format is best done with the aid of pandoc. A standard way is to first generate the Markdown format (doconce format pandoc) and then use pandoc to generate a .docx file:

Terminal> doconce format pandoc mydoc
Terminal> pandoc -t docx -o mydoc.docx mydoc.md


The transformation works well for simple text files, but LaTeX mathematics does not work.

## Jupyter (IPython) Notebooks¶

DocOnce can generate json files for the Jupyter Notebook:

Terminal> doconce format ipynb mydoc  # results in mydoc.ipynb


### Hidden code blocks¶

It is no guarantee that the notebook can be executed. For example, having the code

print sys.version


will not execute unless sys is imported. While a book may show such code and skip (potentially tedious) initializing statements, they must be present in the notebook. To this end, use the !bc *hid environment for hidden code. In the present example, we use !bc pyhid to specify Python code that needs to be executed, but that should normally be hidden (other formats, with the exception of certain interactive Sphinx documents, will hide such code).

!bc pyhid
import sys
!ec


The notebook will feature the import sys statement in a cell prior to the print sys.version cell, and the latter will work.

Similarly, if you import from your own modules, say from mymod import hello, the mymod.py must be accessible for the notebook. Suppose this file is in src-test/mymod.py. Then you need to add src-test to sys.path for the import statement to work:

!bc pyhid
sys.path.append('src-test')
!ec


### Displaying code as plain text instead of executable cells¶

Some code blocks may just be there for explanation and are not meant to be executed. These can be marked by !bc pycod-t (or !bc Xcod-t for any supported programming language X):

!bc pycod-t
if isinstance(myvar, float):
raise TypeError('myvar must be array, not %s' % type(myvar))
!ec


The code segment above will then be typeset as verbatim text and not an executable cell, and there is no need to worry about a missing definition of myvar (which would cause problems in an executable cell).

Interactive sessions with the pyshell or ipy environment will by default be broken up into many cells such that each output command ends a cell. By executing the cells, the input and output from the session is recovered. This is usually the behavior that is wanted, but there is an option --ipynb_split_pyshell=off that can be used to typeset the entire session with all input but no output in one cell (print statements will lead to output, but plain dumping of a variable will not lead to output like it does in a Python shell).

To have an interactive session typeset with input and output in plain text, use the -t extension to the environment: pyshell-t and ipy-t.

### Figures¶

As with HTML files, you need to ensure that the notebook has access to figures and source code as requested.

Figures in notebooks can be typeset in various ways, specified by the --ipynb_figure= option, with the following values:

• md: plain Markdown syntax for a figure, with no possibility to adjust the size (default)
• imgtag: <img ...> tag in HTML taking the specified width into account
• Image: Python notebook cell with Image object

### Movies¶

Typesetting of movies is specified by --ipynb_movie=, and valid options are

• md: raw HTML code with iframe tag - not relevant for the notebook
• HTML: raw HTML code with iframe tag
embedded in the HTML object from the notebook (default)
• HTML-YouTube: as HTML but use an IPython.display.YouTubeVideo object to display YouTube videos
• ipynb: use IPython.display.YouTubeVideo object for YouTube videos, and use an HTML object with video tag for local movies

Typesetting of admonition is rather primitive in notebooks. We offer these different choices, set by the option --ipynb_admon=:

• quote: typeset admon as Markdown quote (special font and gray vertical bar on the left)
• paragraph: typeset admon as a plain paragraph with a heading if any (default)
• hrule: use a horozontal rule to surround the heading and the text

Note that quotes in !bc quote environments are always typeset as Markdown quotes.

### References to an External Textbook¶

Sometimes one wants to refer to equations and sections in an external LaTeX book where a book.aux file is available. The references in the notebook to the LaTeX book can then be hardcoded from the book.aux file with this construction:

Terminal> doconce format ipynb mydoc \
--replace_ref_by_latex_auxno=book.aux


### Conversion from Notebook Back to DocOnce¶

A notebook generated from DocOnce can be converted back to DocOnce format again, even after being annotated in a web browser. Here is a trivial example:

Here is a code:

!bc pypro
a = 1
b = 2
print a + b
!ec


We translate this DocOnce document to a notebook:

Terminal> doconce format ipynb mydoc


We load mydoc.ipynb into the notebook application and add a code cell

print "Hello, World!"


before the original code cell. After executing the cells we download the new notebook as the file mydoc2.ipynb. We can then generate the corresponding DocOnce document mydoc2.do.txt:

Terminal> ipynb2doconce mydoc2.ipynb


Title, author, and other information in DocOnce that does not have a corresponding syntax in the notebook are stored as special comments in the generated .ipynb file so that DocOnce can retrieve this information when running the doconce ipynb2doconce conversion command.

## Matlab Notebooks¶

The Matlab publish format is aimed at notebooks, but the markup is quite primitive, so only a small subset of DocOnce markup can translate successfully to the Matlab publish format. However, if you write within that subset, it is easy to create notebooks in DocOnce that can translate both to Python and Matlab (use preprocessor directives or Mako functions to include Matlab or Python code, depending on the output format).

The Matlab publish format is called matlabnb:

Terminal> doconce format matlabnb mydoc


The --replace_ref_by_latex_auxno= option for referring to equations and sections in a textbook, as explained at the end of the section on Jupyter/IPython notebooks, also works with Matlab notebooks (and for any other output format):

Terminal> doconce format matlabnb mydoc \
--replace_ref_by_latex_auxno=book.aux


## Plain ASCII Text¶

We can go from DocOnce “back to” plain untagged text suitable for viewing in terminal windows, inclusion in email text, or for insertion in computer source code:

Terminal> doconce format plain mydoc.do.txt  # results in mydoc.txt


## reStructuredText¶

Going from DocOnce to reStructuredText gives a lot of possibilities to go to other formats. First we filter the DocOnce text to a reStructuredText file mydoc.rst:

Terminal> doconce format rst mydoc.do.txt


We may now produce various other formats:

Terminal> rst2html.py  mydoc.rst > mydoc.html # html
Terminal> rst2latex.py mydoc.rst > mydoc.tex  # latex
Terminal> rst2xml.py   mydoc.rst > mydoc.xml  # XML
Terminal> rst2odt.py   mydoc.rst > mydoc.odt  # OpenOffice


The OpenOffice file mydoc.odt can be loaded into OpenOffice and saved in, among other things, the RTF format or the Microsoft Word format. However, it is more convenient to use the program unoconv to convert between the many formats OpenOffice supports on the command line. Run

Terminal> unoconv --show


to see all the formats that are supported. For example, the following commands take mydoc.odt to Microsoft Office Open XML format, classic MS Word format, and PDF:

Terminal> unoconv -f ooxml mydoc.odt
Terminal> unoconv -f doc mydoc.odt
Terminal> unoconv -f pdf mydoc.odt


Remark about Mathematical Typesetting. At the time of this writing, there is no easy way to go from DocOnce and LaTeX mathematics to reST and further to OpenOffice and the “MS Word world”. Mathematics is only fully supported by latex as output and to a wide extent also supported by the sphinx output format. Some links for going from LaTeX to Word are listed below.

## Sphinx¶

### The Basic Steps¶

Sphinx documents demand quite some steps in their creation. We have automated most of the steps through the doconce sphinx_dir command:

Terminal> doconce sphinx_dir version=1.0 dirname=sphinxdir \
theme=sometheme mydoc short_title="short title" mydoc


The author, title, and copyright information needed by Sphinx is taken from the DocOnce file mydoc.do.txt. By default, version is 1.0 and dirname is sphinx-rootdir. The theme keyword is used to set the theme for design of HTML output from Sphinx (the default theme is classic).

There are more options for the sphinx_dir command: --runestone for Runestone Interactive books, toc_depth= for setting the depth of the table of contents, intersphinx for allowing the document to link automatically to other Sphinx documents, conf.py= for specifying a tailored conf.py file, logo= and favicon= for specifying logo and favicon files.

One often just runs the simple command

Terminal> doconce sphinx_dir mydoc


which creates the Sphinx directory sphinx-rootdir with relevant files.

The doconce sphinx_dir command generates a script automake_sphinx.py for compiling the Sphinx document into an HTML document. Run

Terminal> python automake_sphinx.py


As the output also tells, you can see the Sphinx HTML version of the document by running

Terminal> google-chrome sphinx-rootdir/_build/html/index.html


or loading the index.html file manually into your favorite web browser.

If you cycle through editing the DocOnce file and watching the HTML output, you should observe that automake_sphinx.py does not recompile the DocOnce file if the Sphinx .rst version already exists. In each edit-and-watch cycle do

Terminal> rm mydoc.rst; python automake_sphinx.py


Tip

If you are new to Sphinx and end up producing quite some Sphinx documents, you are encouraged to read the Sphinx documentation and study the automake_sphinx.py file. Maybe you want to do things differently.

The following paragraphs describes the many possibilities for steering the Sphinx output.

### Themes¶

DocOnce comes with a rich collection of HTML themes for Sphinx documents, much larger than what is found in the standard Sphinx distribution. Additional themes include agni, alabaster, basic, basicstrap, bootstrap, cloud, epub, fenics, fenics_minimal, flask, haiku, jal, pylons, pyramid, redcloud, scipy_lectures, scrolls, slim-agogo, sphinx_rtd_theme, and vlinux-theme. Some of the themes come with basic Sphinx, while others must be installed separately, see the bundled/README_sphinx_themes.do.txt file in the DocOnce source code tree for installation instructions.

The doconce sphinx_dir insert lots of extra code in the conf.py file to enable easy specification of information and, in particular,customization of themes. For example, modules are loaded for the additional themes that come with DocOnce, code is inserted to allow customization of the look and feel of themes, etc.

#### Using a Your Own Configuration File¶

The conf.py file is a good starting point for fine-tuning your favorite theme, and your own myconf.py file can later be supplied and used when running doconce sphinx_dir: simply add the command-line option conf.py=myconf.py. If you leave the project and copyright variables as empty strings in your own myconf.py file, DocOnce will automatically edit a copy (conf.py) of myconf.py in the sphinx root directory so that project becomes the title of the DocOnce source file, and copyright is based on the author or copyright information in the source file. Other variables in myconf.py depending on title, author, and copyright information will also be edited. In this way, you can have your tailored conf.py file, and be sure that it is always compatible with title, author, and copyright information in the underlying DocOnce source.

If a short title is desired, use the short_title= option as part of the doconce sphinx_dir command. This will propagate the short title to your tailored conf.py file regardless of what the short title in that file is.

It is recommended to leave the variables latex_documents, man_pages, and texinfo_documents as empty lists: [] in a tailored conf.py file.

Tip: Error messages from conf.py

When you have edited a conf.py file and supplied it as part of a doconce sphinx_dir command through the conf.py=myconf.py option, it is a danger that python automake_sphinx.py will abort with an error message because of a problem with your configuration file. Note that the error message refers to a line in the conf.py in the Sphinx root directory (sphinx-rootdir by default) and not the configuration file myconf.py you created yourself (so make sure you search in sphinx-rootdir/conf.py for the error). If the error comes from some wrong manual editing, make sure you correct the error in myconf.py.

#### Compiling Multiple Themes¶

A script make-themes.sh can make HTML documents with one or more themes. For example, to realize the themes fenics, pyramid, and pylon one writes

Terminal> ./make-themes.sh fenics pyramid pylon


The resulting directories with HTML documents are _build/html_fenics and _build/html_pyramid, respectively. Without arguments, make-themes.sh makes all available themes (!). With make-themes.sh it is easy to check out various themes to find the one that is most attractive for your document.

You may supply your own theme and avoid copying all the themes that come with DocOnce into the Sphinx directory. Just specify theme_dir=path on the command line, where path is the relative path to the directory containing the Sphinx theme. You must also specify a configure file by conf.py=path, where path is the relative path to your conf.py file.

#### Example¶

Say you like the scipy_lectures theme, but you want a table of contents to appear to the right, much in the same style as in the default or classic themes (where the table of contents is to the left). You can then run doconce sphinx_dir, invoke a text editor with the conf.py file, find the line html_theme == 'scipy_lectures', edit the following nosidebar to false and rightsidebar to true. Alternatively, you may write a little script using doconce replace to replace a portion of text in conf.py by a new one:

doconce replace "elif html_theme == 'scipy_lectures':
html_theme_options = {
'nosidebar': 'true',
'rightsidebar': 'false',
'sidebarbgcolor': '#f2f2f2',
'sidebartextcolor': '#20435c',
'footerbgcolor': '#000000',
'relbarbgcolor': '#000000',
}" "elif html_theme == 'scipy_lectures':
html_theme_options = {
'nosidebar': 'false',
'rightsidebar': 'true',
'sidebarbgcolor': '#f2f2f2',
'sidebartextcolor': '#20435c',
'footerbgcolor': '#000000',
'relbarbgcolor': '#000000',
}" conf.py


Obviously, we could also have changed colors in the edit above. The final alternative is to save the edited conf.py file somewhere and reuse it the next time doconce sphinx_dir is run

doconce sphinx_dir theme=scipy_lectures \
conf.py=../some/path/conf.py mydoc


### RunestoneInteractive books¶

The doconce format sphinx command accepts an option --runestone for generating RunestoneInteractive books (which build on Sphinx). You must run the generated automake_sphinx.py also with a --runestone option to generate these type of documents.

### The manual Sphinx procedure¶

If it is not desirable to use the autogenerated scripts explained above, here is the complete manual procedure of generating a Sphinx document from a file mydoc.do.txt.

Step 1. Translate DocOnce into the Sphinx format:

Terminal> doconce format sphinx mydoc


Step 2. Create a Sphinx root directory either manually or by using the interactive sphinx-quickstart program. Here is a scripted version of the steps with the latter:

mkdir sphinx-rootdir
sphinx-quickstart <<EOF
sphinx-rootdir
n
_
Name of My Sphinx Document
Author
version
version
.rst
index
n
y
n
n
n
n
y
n
n
y
y
y
EOF


The autogenerated conf.py file may need some edits if you want to specific layout (Sphinx themes) of HTML pages. The doconce sphinx_dir generator makes an extended conv.py file where, among other things, several useful Sphinx extensions are included.

Step 3. Copy the mydoc.rst file to the Sphinx root directory:

Terminal> cp mydoc.rst sphinx-rootdir


If you have figures in your document, the relative paths to those will be invalid when you work with mydoc.rst in the sphinx-rootdir directory. Either edit mydoc.rst so that figure file paths are correct, or simply copy your figure directories to sphinx-rootdir. Links to local files in mydoc.rst must be modified to links to files in the _static directory, see comment above.

Step 4. Edit the generated index.rst file so that mydoc.rst is included, i.e., add mydoc to the toctree section so that it becomes

.. toctree::
:maxdepth: 2

mydoc


(The spaces before mydoc are important!)

Step 5. Generate, for instance, an HTML version of the Sphinx source:

make clean   # remove old versions
make html


Sphinx can generate a range of different formats: standalone HTML, HTML in separate directories with index.html files, a large single HTML file, JSON files, various help files (the qthelp, HTML, and Devhelp projects), epub, LaTeX, PDF (via LaTeX), pure text, man pages, and Texinfo files.

Step 6. View the result:

Terminal> firefox _build/html/index.html


Note that verbatim code blocks can be typeset in a variety of ways depending the argument that follows !bc: cod gives Python (code-block:: python in Sphinx syntax) and cppcod gives C++, but all such arguments can be customized both for Sphinx and LaTeX output.

## Wiki Formats¶

There are many different wiki formats, but DocOnce only supports three: Googlecode wiki, MediaWiki, and Creole Wiki. These formats are called gwiki, mwiki, and cwiki, respectively. Transformation from DocOnce to these formats is done by

Terminal> doconce format gwiki mydoc.do.txt
Terminal> doconce format mwiki mydoc.do.txt
Terminal> doconce format cwiki mydoc.do.txt


The produced MediaWiki can be tested in the sandbox of wikibooks.org. The format works well with Wikipedia, Wikibooks, and ShoutWiki, but not always well elsewhere (see this example).

Large MediaWiki documents can be made with the Book creator. From the MediaWiki format one can go to other formats with aid of mwlib. This means that one can easily use DocOnce to write Wikibooks and publish these in PDF and MediaWiki format, while at the same time, the book can also be published as a standard LaTeX book, a Sphinx web document, or a collection of HTML files.

The Googlecode wiki document, mydoc.gwiki, is most conveniently stored in a directory which is a clone of the wiki part of the Googlecode project. This is far easier than copying and pasting the entire text into the wiki editor in a web browser. Note that Google decided to close down its Googlecode service in 2015.

When the DocOnce file contains figures, each figure filename must in the .gwiki file be replaced by a URL where the figure is available. There are instructions in the file for doing this. Usually, one performs this substitution automatically (see next section).

Google Docs are normally made online in the interactive editor. However, you may upload a DocOnce document to Google Docs. This requires transforming the DocOnce document to one of the accepted formats for Google Docs:

• OpenOffice: doconce format rst and then run rst2odt (or rst2odt.py). Upload the .odt file, click Open... in Google Drive and choose Google Docs as viewer.
• MS Word: doconce format pandoc and then run pandoc to produce a .docx file that can be uploaded to Google Drive and opened in Google Docs.
• RTF: doconce format pandoc and then run pandoc to produce a .rtf file that can be uploaded to Google Drive and opened. Another possibility is to run doconce format latex and then latex2rtf (the support of mathematics has gotten worse).
• Plain text: doconce format plain. Upload the .txt file to Google Drive and open in Google Docs.
• HTML: doconce format html. Upload the .html file and open in Google Docs. Complicated HTML files can be misinterpreted by Google Docs.

This is not yet much tested. It remains to see how code becomes in Google Docs. Support for mathematics is probably impossible until Google Docs can import LaTeX files, but LaTeX mathematics can be embedded in Google Docs and the googledoc2latex script can convert a Google document to LaTeX.

## Options for the doconce commands¶

### doconce format command-line options¶

The transformation of a DocOnce source to various format is done with the doconce format command, which has a lot of command-line options. These are printed out by doconce format --help. The output is listed here for convenience.

Terminal> doconce format --help

doconce format X doconcefile

where X can be any of the formats
html, latex, pdflatex, rst, sphinx, plain, gwiki, mwiki, cwiki,
pandoc, epytext.

--help

Print all options to the doconce program.

--debug

Write a debugging file _doconce_debugging.log with lots
of intermediate results

--no_abort

Do not abort the execution if syntax errors are found.

--verbose=...

Write progress of intermediate steps if they take longer than X seconds.
0: X=15
1: X=5
2: 0.5

--language=...

Native language to be used: English (default), Norwegian,

--preprocess_include_subst

Turns on variable substitutions in # #include paths when running Preprocess:
preprocess -i -DMYDIR=rn1
will lead to the string "MYDIR" being replaced by the value "rn1"
in # #include "..." statements.

--syntax_check=...

Values: on/off. Turns on/off fix of illegal constructions and the syntax check
(may be time consuming for large books).

Remove all inline comments of the form [ID: comment].

--draft

Indicates draft (turns on draft elements in LaTeX, otherwise no effect).

Template wording for Creative Commons licenses.
Default: "Released under CC %s 4.0 license."
Example: "This worsk is released under the Creative Commons %s 4.0 license"
CC license is specified as a part of the copyright syntax, e.g.,
AUTHOR: Kaare Dump {copyright|CC BY} at BSU & Some Company Ltd.
AUTHOR: Kaare Dump at BSU & Some Company Ltd. {copyright,2005-present|CC BY-NC}

--align2equations

Rewrite align/alignat math environments to separate equation environments.
Sometimes needed for proper MathJax rendering (e.g., remark slides).
Sphinx requires such rewrite and will do it regardless of this option.

--force_tikz_conversion

Force generation SVG/HTML versions of tikz figures, overwriting any previously generated SVG/HTML files (applies to all formats except LaTeX)

--IBPLOT

automagic translation of IBPLOT commands.

--exercise_numbering=...

absolute: exercises numbered as 1, 2, ... (default)
chapter: exercises numbered as 1.1, 1.2, ... , 3.1, 3.2, ..., B.1, B.2, etc.
with a chapter or appendix prefix.

--exercises_in_zip

Place each exercises as an individual DocOnce file in a zip archive.

--exercises_in_zip_filename=...

Filenames of individual exercises in zip archive.
logical: use the (first) logical filename specified by file=...
number:  use either absolute exercise number or chapter.localnumber.

--toc_depth=...

chapters, sections, and subsections. Set to 1 to exclude subsections.
Applies to all formats, except sphinx: for sphinx, set toc_depth=... as
part of the command doconce sphinx_dir.

--encoding=...

Specify encoding (e.g., latin1 or utf-8).

--no_ampersand_quote

Turn off special treatment of ampersand (&). Needed, e.g., when native latex code for tables are inserted in the document.

--no_mako

Do not run the Mako preprocessor program.

--no_preprocess

Do not run the Preprocess preprocessor program.

--mako_strict_undefined

Make Mako report on undefined variables.

Do not include header and footer in (LaTeX and HTML) documents.

--no_emoji

Remove all emojis.

--siunits

Allow siunitx MathJax/LaTeX package for support of SI units in various formats

--allow_refs_to_external_docs

Do not abort translation if ref{...} to labels not defined in this document.

--runestone

Make a RunestoneInteractive version of a Sphinx document.

--max_bc_linelength=...

Strip lines in !bc environments that are longer than specified
(to prevent too long lines). Default: None (no length restriction).

--replace_ref_by_latex_auxno=...

Replace all ref{...} by hardcoded numbers from a latex .aux file.
Makes it possible for a notebook or html page to refer to a latex textbook.
Recommended syntax: see (ref{my:eq1}) in cite{MyBook}, or see
Section ref{my:sec2} in cite{MyBook}.

--keep_pygments_html_bg

Do not allow change of background in code blocks in HTML.

--minted_latex_style=...

Specify the minted style to be used for typesetting code in LaTeX.
See pygmetize -L styles for legal names.

--pygments_html_style=...

Specify the minted/pygments style to be used for typesetting code
in HTML.
Default: default (other values: monokai, manni, rrt, perldoc,
borland, colorful, murphy, trac, tango, fruity, autumn, emacs,
vim, pastie, friendly, native, see pygmentize -L styles).
none, no, off: turn off pygments to typeset computer code in HTML,
use plain <pre> tags.
highlight.js: use highlight.js syntax highlighting, not pygments.

--pygments_html_linenos

Turn on line numbers in pygmentized computer code in HTML.
(In LaTeX line numbers can be added via doconce subst or
doconce replace such that the verbatim environments get
the linenos=true parameter.)

--xhtml

Use BeautifulSoap to try to produce XHTML output. It inserts end tags (e.g. </p>) and guesses where to do it.

--html_output=...

Alternative basename of files associated with the HTML format.

--html_style=...

Name of theme for HTML style:
plain, blueish, blueish2, bloodish, tactile-black, tactile-red, rossant
solarized, solarized2_light, solarized2_dark,
bootstrap, bootswatch,
bootstrap_X,  X=bloodish, blue, bluegray, brown, cbc, FlatUI, red,
bootswatch_X, X=cerulean, cosmo, flatly, journal, lumen, readable,
simplex, spacelab, united, yeti
(dark:) amelia, cyborg, darkly, slate, spruce,
superhero (demos at bootswatch.com)

--html_template=...

Specify an HTML template with header/footer in which the doconce
document is embedded. (Often preferred to run with --no_title)

--no_title

Comment out TITLE, AUTHOR, DATE.
Often used with HTML templates.

--html_code_style=...

off, inherit, or transparent: enable normal inline verbatim font
where foreground and background color is inherited from the
surroundnings. off, inherit and transparent are just synonyms for
inheriting color from the text and make the background color transparent
(use e.g. --html_code_style=inherit to avoid the red Boostrap color).
Default: on (use the css-specified typesetting of <pre> tags).
NOTE: the naming "html_code_style" is not optimal: it has nothing
to do with code block style, but the <code> tag for inline verbatim text
in the context of bootstrap css styles.

--html_pre_style=...

off, inherit, or transparent: let code blocks inside <pre> tags have
foreground and background color inherited from the surroundnings.
Default: on (use the css-specified typesetting of <pre> tags).
This option is most relevant for Bootstrap styles to
avoid white background in code blocks inside colorful admons.

--html_toc_indent=...

No of spaces for indentation of subsections in the table of
contents in HTML output. Default: 3 (0 gives toc as nested list
in Bootstrap-based styles).

--html_body_style=...

Override elements in the <body> style css.
Used to enlargen bootswatch fonts, for instance:
"--html_body_style=font-size:20px;line-height:1.5"

--html_body_font=...

Specify HTML font for text body. =? lists available fonts.

Specify HTML font for headings. =? lists available fonts.

--html_video_autoplay=...

True for autoplay when HTML is loaded, otherwise False (default).

colors, gray, yellow, apricot, lyx, paragraph.
For html_style=bootstrap*,bootswatch*,
the two legal values are boostrap_panel, bootstrap_alert.

Background color of admon in HTML.

Boundary color of admon in HTML.

--css=...

Specify a .css style file for HTML output.
If the file does not exist, the default or specified style
(--html_style=) is written to it.

--html_share=...

at the end of the HTML document.

--html_exercise_icon=...

Specify a question icon (as a filename in the bundled/html_images
directory in the doconce repo) for being inserted to the right in exercises.
default: turn on predefined question icons according to the chosen style.
none: no icons (this is the default value).

--html_exercise_icon_width=...

Width of the icon image in pixels (must be used with --html_exercise_icon).

--html_raw_github_url=...

URLs to files hosted on the doconce github account.
Internet Explorer (and perhaps other browsers) will not show raw.github.com
files. Instead on should use rawgit.com. For development of HTML sites
in Safari and Chrome and can use rawgit.com.

Values of --html_raw_github_url=:
safe or cdn.rawgit: use this for ready-made sites with potentially some traffic.
The URL becomes https://cdn.rawgit.com/hplgit/doconce/...

test or rawgit: use this for test purposes and development with low traffic.
The URL becomes https://rawgit.com/hplgit/doconce/...

github or raw.github: the URL becomes https://raw.github.com and may fail to

githubusercontent or raw.githubusercontent: The URL becomes
https://raw.githubusercontent.com and may fail to load properly.

--html_DOCTYPE

Insert <!DOCTYPE HTML> in the top of the HTML file.
This is required for Internet Explorer and Mozilla.
However, some of the CSS files used by DocOnce may not load properly if
they are not well formed. That is why no doctype is default in the
generated HTML files.

Open HTML links in a new window/tab.

--html_quiz_button_text=...

Text on buttons for collapsing/expanding answers and explanations
in quizzes (with bootstrap styles).
Default: Empty (just pencil glyphion).

--html_bootstrap_navbar=...

Turns the Bootstrap navigation bar on/off. Default: on.

--html_bootstrap_jumbotron=...

Turns the Bootstrap jumbotron intro on/off and governs the
size of the document title. Default: on. Other values: h2, off

Example:

--html_figure_caption=...

Placement of figure caption: top (default) or bottom.
(sidecap=True is another option, this can be set for individual figures, while
--html_figure_caption controls the general caption placement of all figures.

--html_figure_hrule=...

Set horizontal rule(s) above and/or below a figure.
none, off: no rules
top: rule at top (default)
bottom: rule at bottom
top+bottom: rule at top and bottom

Controls where to put copyright statements.
everypage: in the footer of every page
titlepages or titlepage: in the footer of the titlepage only (default).

--cite_doconce

Adds a citation to the DocOnce web page if copyright statements are present.

--device=...

Set device to paper, screen, or other (paper impacts LaTeX output).

--number_all_equations

Switch latex environments such that all equations get a number.

--denumber_all_equations

Switch latex environments such no equations get a number (useful for removing equation labels in slides). Error messages are issued about references to numbered equations in the text.

--latex_style=...

LaTeX style package used for the document.
std: standard LaTeX article or book style,
Springer_sv: Springer's svmono class (the new standard for all Springer books),
Springer_T2: Springer's T2 book style,
Springer_T4: Springer's T4 book style (smaller pagesize than T2),
Springer_lncse: Springer's Lecture Notes in Computational Science and
Engineering (LNCSE) style,
Springer_llncs: Springer's Lecture Notes in Computer Science style,
Springer_lnup:  Springer's Lecture Notes in University Physics,
Springer_collection: Springer's style for chapters in LNCSE proceedings,
tufte-book: use of tufte-book.cls for E. Tufte-inspired layout,
Koma_Script: Koma Script style,
siamltex: SIAM's standard LaTeX style for papers,
siamltexmm: SIAM's extended (blue) multimedia style for papers.

--latex_font=...

LaTeX font choice: helvetica, palatino, utopia, std (Computer Modern, default).

--latex_code_style=...

Typesetting of code blocks.
pyg: use pygments (minted), style is set with --minted_latex_style=
lst: use lstlistings
vrb: use Verbatim (default)

Specifications across languages:
pyg-blue1
lst, lst-yellowgray[style=redblue]
vrb[frame=lines,framesep=2.5mm,framerule=0.7pt]

Detailed specification for each language:
default:vrb-red1[frame=lines]@pycod:lst[style=redblue]@pypro:lst-blue1[style=default]@sys:vrb[frame=lines,label=\fbox{{\tiny Terminal}},framesep=2.5mm,framerule=0.7pt]

Here, Verbatim[frame=lines] is used for all code environments, except
pycod, pypro and sys, which have their own specifications.
pycod: lst package with redblue style (and white background)
pypro: lst package with default style and blue1 background
style, sys: Verbatim with the specified arguments and white background.

(Note: @ is delimiter for the language specifications, syntax is
envir:package-background[style parameters]@)

--latex_code_leftmargin=...

Sets the left margin in code blocks. Default: 7 (mm).

--latex_code_bg=...

Background color code blocks. Default: white.

Vertical padding of background. Has only effect for vrb/pyg-bgcolor styles (not lst!).

--latex_code_lststyles=...

Filename with LaTeX definitions of lst styles.

Controls where to put copyright statements.
everypage: in the footer of every page
titlepages: in the footer of the titlepage and chapter pages (for books) only (default).

--latex_bibstyle=...

LaTeX bibliography style. Default: plain.

--section_numbering=...

Turn section numbering on/off. Default: off for all formats except latex and pdflatex (on for those).

--latex_table_format=...

Default: quote. Other values: left, center, footnotesize, tiny.

--latex_table_row_sep=...

Row separation factor in tables (command \renewcommand{\arraystretch}{<factor>}. Default: 1.0

--latex_title_layout=...

Layout of the title, authors, and date:
titlepage: separate page,
doconce_heading (default): authors with "footnotes" for institutions,
beamer: layout for beamer slides.

Color used in hyperlinks. Default is dark blue if --device=screen,
or black if --device=paper (invisible in printout or special blue
Values are specified either as comma-separated rgb tuples or as

--latex_title_reference=...

latex code placed in a footnote for the title,
typically used for acknowledging publisher/source of original
version of the document.

--latex_encoding=...

Encoding for \usepackage[encoding]{inputenc}.
Values: utf8 (default) or latin1.

--latex_packages=...

Comma-separated list of latex packages to be included in \usepackage commands..

--latex_papersize=...

Geometry of page size: a6, a4, std (default).

--latex_list_of_exercises=...

LaTeX typesetting of list of exercises:
loe: special, separate list of exercises,
none (default): no list of exercises.

--latex_movie=...

Specify package for handling movie/video content.
Default: href (hyperlink to movie file).
Other options: media9, movie15, multimedia (Beamer's \movie command).

--latex_movie_controls=...

Specify control panel for movies. Default: on. Other options: off.

--latex_external_movie_viewer

Allow external movie viewer for movie15 package.

Typesetting of headers on each page:
If article: section name to the left and page number to the right
on even page numbers, the other way around on odd page numners.
If book: section name to the left and page numner to the right
on even page numbers, chapter name to the right and page number to
the left on odd page numbers.

std (default): standard LaTeX,
blue: gray blue color,
strongblue: stronger blue color,
gray: white text on gray background, fit to heading width,
gray-wide: white text on gray background, wide as the textwidth.

--latex_colored_table_rows=...

Colors on every two line in tables: no (default), gray, blue.

--latex_line_numbers

Include line numbers for the running text (only active if there

--latex_todonotes

Use the todonotes package to typeset inline comments.
Gives colored bubbles in the margin for small inline comments and
in the text for larger comments.

--latex_double_spacing

Sets the LaTeX linespacing to 1.5 (only active if there are

--latex_labels_in_margin

Print equation, section and other LaTeX labels in the margin.

--latex_index_in_margin

Place entries in the index also in the margin.

--latex_preamble=...

User-provided LaTeX preamble file, either complete or additions
to the doconce-generated preamble.

If --device=paper, this option removes footnotes with links to
computer programs.

colors1:
(inspired by the NumPy User Guide) applies different colors
for the different admons with an embedded icon,

colors2:
like colors1 but the text is wrapped around the icon,

mdfbox:
rounded boxes with a optional title and no icon (default),

graybox2:
box with square corners, gray background, and narrower
than mdfbox, if code it reduces to something like mdfbox
(mdframed based); the summary admon is in case of A4 format
only half of the text width with text wrapped around
(effective for proposals and articles),

grayicon:
box with gray icons and a default light gray background,

yellowicon:
box yellow icons and a default light yellow background,

paragraph:  plain paragraph with boldface heading.

Note: the colors in mdfbox and other boxes can customized.

The color to be used as background in admonitions.
A single value applies to all admons:
Either rgb tuple or saturated color a la yellow!5:
Note the quotes, needed for bash, in the latter example.

Multiple values can be assigned, one for each admon (all admons must
be specified):

If --latex_admon=mdfbox, the specification above with color1!X!color2
will automatically trigger 2*X as the background color of the frametitle.

There are predefined multiple values, e.g.,
gives red warnings, blue notice, orange questions, green summaries and
yellow blocks, automatically adjusted with darker frametitles for

If --latex_admon=mdfbox, the background of the title and
the color of the border of box can also be customized by
direct editing. For example, a dark blue border and light
blue title background is obtained by editing the .tex file as

doconce replace 'linecolor=black,' 'linecolor=darkblue,' mydoc.tex
doconce subst 'frametitlebackgroundcolor=.*?,' 'frametitlebackgroundcolor=blue!5,' mydoc.tex

Actually, this particular (and common) edit is automatically done by the option
(the latter has color yellow!5 instead and yellow!20 for the border)

By default, a period is added to title admons that do not have a period, question mark, or similar. This option prevents adding a period such that the title acts like a heading.

Mapping of code envirs to new envir names inside admons, e.g.,
to get a different code typesetting inside admons. This is useful
if admons have a special color and the color background of code
blocks does not fit will with the color background inside admons.
Then it is natural to use a different verbatim code style inside
If specifying a number, say 2, as in --latex_admon_envir_map=2,
an envir like pycod gets the number appended: pycod2. One can
then in --latex_code_style= or in doconce ptex2tex or ptex2tex
specify the typesetting of pycod2 environments.
Otherwise the specification must be a mapping for each envir
that should be changed inside the admons:
(from-to,from-to,... syntax).

Default: ).
Gives headers a), b), etc. Can be set to period, colon, etc.

--xelatex

--latex_double_hyphen

Replace single dash - by double dash -- in LaTeX output.
Somewhat intelligent, but may give unwanted edits. Use with great care!

--latex_elsevier_journal=...

Sets the journal name for the --latex_style=elsevier style.
Default: none (no journal name).

--ipynb_version=...

ipynb version 3 (default) or 4.

--ipynb_split_pyshell=...

Split interactive sessions into multiple cells after each output.
Applies to pyshell and ipy code environments.
on, True, yes: split (default).
off, False, no: do not split.
Note that pyshell-t and ipy-t environments just displays the session,
while default pyshell and ipy removes all output (all output from print
statements will come after the entire session).

--ipynb_cite=...

Typesetting of bibliography.
plain: simple native typesetting (same as pandoc) (default)
latex: ipynb support for latex-style bibliographies (not mature).

Typesetting of admonitions (hint, remarks, box, notice, summary,
warning, question, block - quotes are typeset as quotes).
quote: as Markdown quote (default) with gray line on the left.
paragraph: just the content with the title as paragraph heading.
hrule: title with horizontal rule above and below, then text and
horozontal rule.

--ipynb_figure=...

How to typeset figures in ipynb:
md (plain Markdown syntax),
imgtag (<img src="..." width=...> tag, default)
Image (python cell with Image object).

--ipynb_movie=...

How to typeset movies in ipynb:
md (plain Markdown syntax, default)
HTML: python cell with notebook HTML object containing the raw HTML code
that is used in the DocOnce HTML format
ipynb: python cell with notebook HTML object with simple/standard
ipynb HTML code for showing a YouTube or local video with a <video>
tag.

--verbose

Write out all OS commands run by doconce.

--examples_as_exercises

Treat examples of the form "==== Example: ..."
as in exercise environments.

--exercises_as_subsections

Forces exercises to be typeset as subsections. Used to override
various latex environments for exercises (esp. in Springer styles).

--solutions_at_end

Place solutions to exercises at the end of the document.

--without_solutions

Leave out solution environments from exercises.

Leave out answer environments from exercises.

--without_hints

Leave out hints from exercises.

--exercise_solution=...

Typesetting of solutions: paragraph, admon, or quote.

--wordpress

Make HTML output for wordpress.com pages.

--tables2csv

Write each table to a CSV file table_X.csv,
where X is the table number (autonumbered in according to
appearance in the DocOnce source file).

--sections_up

Upgrade all sections: sections to chapters, subsections
to sections, etc.

--sections_down

Downgrade all sections: chapters to sections, sections
to subsections, etc.

--os_prompt=...

Terminal prompt in output from running OS commands (the
@@@OSCMD instruction). None or empty: no prompt, just the command;
nocmd: no command, just the output. Default is "Terminal>".

--code_skip_until=...

@@@CODE import: skip lines in files up to (and incuding) specified line.

--code_prefix=...

Prefix all @@@CODE imports with some path.

--figure_prefix=...

Prefix all figure filenames with, e.g., an URL.

--movie_prefix=...

Prefix all movie filenames with, e.g., an URL.

--no_mp4_webm_ogg_alternatives

Use just the specified (.mp4, .webm, .ogg) movie file;
do not allow alternatives in HTML5 video tag.
Used if the just the specified movie format should be played.

--handout

Makes slides output suited for printing.

--urlcheck

Check that all URLs referred to in the document are valid.

--labelcheck=...

Check that all ref{X} has a corresponding label{X}. Fake examples will fail this check and so will generalized references.
Turn on when useful. Values: off (default), on.

--short_title=...

Short version of the document's title.

--markdown

Allow Markdown (and some Extended Markdown) syntax as input.

--md2do_output=...

Dump to file the DocOnce code arising from converting from
Markdown. Default value is None (no dump).
Any filename can be specified: --md2do_output=myfile.do.txt

--github_md

Turn on GitHub-flavored Markdown dialect of the pandoc translator

--slate_md

Turn on Slate-extensions to Markdown in the pandoc translator.
To be used together with --github_md.

--strapdown

Wrap Markdown output in HTML header/footer such that the
output file (renamed as .html) can automatically be rendered as
an HTML via strapdownjs.com technology. Combine with --github_md
for richer output. Styles are set with --bootswatch_theme=cyborg
(for instance).

--bootswatch_theme=...

Bootswatch theme for use with --strapdown option.

--strict_markdown_output

Ensure strict/basic Markdown as output.

--multimarkdown_output

Allow MultiMarkdown as output.

--quiz_question_prefix=...

Prefix/title before question in quizzes. Default: "Question:".
Can also be set in square brackets for each individual question.
("Q: [] What is 1+1?"
results in no prefix/title before the "What is 1+1?".

--quiz_choice_prefix=...

Prefix/title before choices in quizzes.
Default for HTML: "Choice", resulting in numbered choices
"Choice 1:", "Choice 2:", etc.
A value with colon, period, or question mark (e.g., "Answer:")
leaves out the numbering.
Default for latex/pdflatex: letter or letter+checkbox.
Other values: number, number+checkbox, number+circle, letter+circle,
letter.
The checkbox or circle is always omitted if answers or solutions are
included (i.e., if none of the --without_answers and
--without_solutions is set).
The choice prefix can also be set in square brackets for each
individual choice.
("Cr: [] Two"
results in no prefix/title before the the answer "Two".

--quiz_horizontal_rule=...

on (default): <hr> before and after quiz in HTML. off: no <hr>.

--quiz_explanations=...

on/off
(some output formats do not support explanations with figures,
math and/or code, this option turns all explanations off.

--rst_uio

Univ. of Oslo version of rst files for their Vortex system.

--rst_mathjax

Use raw HTML with MathJax for LaTeX mathematics in rst files.

--sphinx_keep_splits

Respect user's !split commands. Default: Override user's !split
and insert new !split before all topmost sections. This is what
the document into multiple parts.

--sphinx_figure_captions=...

Font style in figure captions: emphasize (default) or normal. If you use boldface or emphasize in the caption, the font style will be normal for that caption.

--oneline_paragraphs

Combine paragraphs to one line (does not work well).


## Installation of DocOnce and its Dependencies¶

Below, we explain the manual installation of all software that may be needed when working with DocOnce documents. The impatient way to install everything that is needed is to use Anaconda Python and the conda program:

DocOnce is available from the conda-forge channel. To add the conda-forge channel and subsequently install DocOnce, run the following commands.

Terminal> conda config --add channels conda-forge
Terminal> conda install doconce


If you do not want to use Anaconda and are on a Debian-based Linux computer (running, e.g., Ubuntu), you can instead run the Bash script install_doconce.sh or the equivalent Python script install_doconce.py. These scripts give a comprehensive installation. Some users will prefer to install just what is needed for them, and this is explained below.

Version control systems are needed

The coming installation instructions require that the version control systems Subversion, Mercurial, and Git are installed on your computer.

DocOnce is primarily tested on GNU/Debian Linux systems, but also to a minor extent on Mac OS X. Experience with Windows is limited. Since most packages are Python-based and can be installed via pip install no problems should arise on Mac and Windows. However, some of the image processing tools and spell checking apply Unix-specific software.

You can omit reading the next sections if you rely on conda or apt-get install commands in the Bash script for installing DocOnce.

### DocOnce¶

DocOnce itself is pure Python code hosted at https://github.com/hplgit/doconce. Installation can be done via

sudo pip install -e git+https://github.com/hplgit/doconce#egg=doconce
# or if doconce is already installed
sudo pip install -e git+https://github.com/hplgit/doconce#egg=doconce --upgrade


However, the recommended approach is to have a copy of the source on the local computer and run setup.py:

git clone git@github.com:hplgit/doconce.git
cd doconce
sudo python setup.py install
cd ..


Since DocOnce is frequently updated, it becomes necessary to ensure that you work with the most recent version:

cd doconce
git pull origin master
sudo python setup.py install


### Dependencies¶

Producing HTML documents, plain text, pandoc-extended Markdown, and wikis can be done without installing any other software. However, if you want other formats as output (LaTeX, Sphinx, reStructuredText) and assisting utilities such as preprocesors, spellcheck, file differences, bibliographies, and so on, a lot of extra software must be installed.

#### Python v2.7¶

First you need Python version 2.7 and the pip installation program. Unless you already have these, we recommend to install a comprehensive Python bundle like Anaconda.

You do not need more software if you avoid using preprocessors, there is no bibliography, and you stick to the output formats LaTeX and HTML (you need of course LaTeX installed to process .tex files).

#### Preprocessors¶

If you make use of the Preprocess preprocessor, this program must be installed:

pip install -e \


A much more advanced alternative to Preprocess is Mako. Its installation is done by

pip install Mako


It is recommended to install both Preprocess and Mako.

Note that neither Preprocess nor Mako is run if you do not have preprocessor directives in your DocOnce source. That is, you only need this extra software if you make active use of preprocessors.

#### Bibliography¶

The Python package Publish is needed if you use a bibliography in your document (cite commands and a BIBFILE: specification). The installation is done by

pip install -e hg+https://bitbucket.org/logg/publish#egg=publish


#### Image file handling¶

Different output formats require different formats of image files. For example, PDF or PNG is used for pdflatex, PostScript for latex, while HTML needs JPEG, GIF, or PNG formats. DocOnce calls up programs from the ImageMagick suite for converting image files to a proper format if needed. The ImageMagick suite can be installed on all major platforms. On Debian Linux (including Ubuntu) systems one can simply write

sudo apt-get install imagemagick


The convenience program doconce combine_images, for combining several images into one, will use montage and convert from ImageMagick and the pdftk, pdfnup, and pdfcrop programs from the texlive-extra-utils Debian package. The latter gets installed by

sudo apt-get install texlive-extra-utils


Automatic image conversion from EPS to PDF calls up epstopdf, which can be installed by

sudo apt-get install texlive-font-utils


#### Spellcheck¶

The utility doconce spellcheck applies the ispell program for spellcheck. On Debian (including Ubuntu) it is installed by

sudo apt-get install ispell


#### Ptex2tex for LaTeX Output¶

Originally, DocOnce relied on the ptex2tex program for very flexible choice of typesetting of verbatim code blocks. A simplified version, doconce ptex2tex, is bundled with DocOnce. However, even greater flexibility is now offered by the --latex_code_style= option to doconce format so unless you already are a ptex2tex user, it is recommended to forget about ptex2tex and just use the --latex_code_style= option.

The stand-alone ptex2tex program is installed by

svn checkout http://ptex2tex.googlecode.com/svn/trunk/ ptex2tex
cd ptex2tex
sudo python setup.py install


It may happen that you need additional style files, you can run a script, cp2texmf.sh:

cd latex
sh cp2texmf.sh  # copy stylefiles to ~/texmf directory
cd ../..


This script copies some special stylefiles that that ptex2tex potentially makes use of. Some more standard stylefiles are also needed. These are installed by

sudo apt-get install texlive


on Debian Linux (including Ubuntu) systems. TeXShop on Mac comes with the necessary stylefiles (if not, they can be found by googling and installed manually in the ~/texmf/tex/latex/misc directory).

Note that the doconce ptex2tex command, which needs no installation beyond DocOnce itself, can be used as a simpler alternative to the ptex2tex program.

#### Pygments and the Minted Code Style¶

The minted LaTeX style is popular for typesetting code. This style requires the package Pygments to be installed. On Debian Linux, the simplest approach is to install sphinx:

pip install sphinx


All use of the minted style requires the -shell-escape command-line argument when running LaTeX, i.e., pdflatex -shell-escape.

Inline comments apply the todonotes LaTeX package if the option --latex_todonotes is given. The todonotes package requires several other packages: xcolor, ifthen, xkeyval, tikz, calc, graphicx, and setspace. The relevant Debian packages for installing all this are listed below.

#### LaTeX packages¶

Many LaTeX packages are potentially needed, depending on various constructions in the text and command-line options used when compling DocOnce to LaTeX. The standard packages always required are relsize, makeidx, setspace, color, amsmath, amsfonts, xcolor, bm, microtype, inputenc, and hyperref. Optional packages that might be included in the .tex output are minted, listings, fancyvrb, xunicode, inputenc, helvet, mathpazo, wrapfig, calc, ifthen, xkeyval, tikz, graphicx, setspace, shadow, disable, todonotes, lineno, xr, framed, mdframe, movie15, a4paper, and a6paper.

Relevant Debian packages that gives you all of these LaTeX packages are

texlive
texlive-extra-utils
texlive-latex-extra
texlive-font-utils


Alternatively, one may pull in texlive-full to get all available style files.

If you want to use the anslistings code environment with ptex2tex (.ptex2tex.cfg styles Python_ANS, Python_ANSt, Cpp_ANS, etc.) or doconce ptex2tex (envir=ans or envir=ans:nt), you need the anslistings.sty file. It can be obtained from the ptex2tex source. The same code style is in “modern DocOnce” just implemented by the command-line option

"--latex_code_style=default:lst[style=yellow2_fb]"


#### Sphinx or reStructuredText Output¶

Output to sphinx or rst requires the Sphinx software, installed by

pip install sphinx --upgrade


DocOnce comes with many Sphinx themes that are not part of the standard Sphinx source distribution:

Appropriate installation commands for these themes are

pip install -e hg+https://bitbucket.org/ecollins/cloud_sptheme#egg=cloud_sptheme
pip install -e git+https://github.com/ryan-roemer/sphinx-bootstrap-theme#egg=sphinx-bootstrap-theme
pip install -e hg+https://bitbucket.org/miiton/sphinxjp.themes.solarized#egg=sphinxjp.themes.solarized
pip install -e git+https://github.com/shkumagai/sphinxjp.themes.impressjs#egg=sphinxjp.themes.impressjs
pip install -e git+https://github.com/kriskda/sphinx-sagecell#egg=sphinx-sagecell


It can also be handy to have special typesetting of IPython sessions:

pip install -e git+https://bitbucket.org/hplbit/pygments-ipython-console#egg=pygments-ipython-console


To make OpenOffice or LibreOffice documents from rst output, you will need more software, typically the following on a Debian system:

sudo apt-get install unoconv libreoffice libreoffice-dmaths


#### Markdown and Pandoc Output¶

The DocOnce format pandoc outputs the document in various Markdown versions: the Pandoc extended Markdown format (which via the pandoc program can be translated to a range of other formats), strict Markdown, and GitHub-flavored Markdown. Installation of Pandoc, written in Haskell, is most easily done by

sudo apt-get install pandoc


on Debian (Ubuntu) systems.

#### Epydoc Output¶

When the output format is epydoc one needs that program too, installed by

svn co https://epydoc.svn.sourceforge.net/svnroot/epydoc/trunk/epydoc epydoc
cd epydoc
sudo make install
cd ..


Remark. Several of the packages above installed from source code are also available in Debian-based system through the apt-get install command. However, we recommend installation directly from the version control system repository as there might be important updates and bug fixes. For svn directories, go to the directory, run svn update, and then sudo python setup.py install. For Mercurial (hg) directories, go to the directory, run hg pull; hg update, and then sudo python setup.py install.

#### Analyzing file differences¶

The doconce diff file1 file prog command for illustrating differences between two files file1 and file2 using the program prog requires prog to be installed. By default, prog is difflib which comes with Python and is always present if you have DocOnce installed. Another choice, diff, should be available on all Unix/Linux systems. Other choices, their URL, and their sudo apt-get install command on Debian (Ubuntu) systems appear in the table below.

Program URL Debian/Ubuntu install
pdiff a2ps wdiff sudo apt-get install a2ps wdiff texlive-latex-extra texlive-latex-recommended
latexdiff latexdiff sudo apt-get install latexdiff
kdiff3 kdiff3 sudo apt-get install kdiff3
diffuse diffuse sudo apt-get install diffuse
xxdiff xxdiff sudo apt-get install xxdiff
meld meld sudo apt-get install meld
tkdiff.tcl tkdiff not in Debian

## Basic Parsing Ideas¶

The (parts of) files with computer code to be directly included in the document are first copied into verbatim blocks.

All verbatim and TeX blocks are removed and stored elsewhere to ensure that no formatting rules are not applied to these blocks.

The text is examined line by line for typesetting of lists, as well as handling of blank lines and comment lines. List parsing needs some awareness of the context. Each line is interpreted by a regular expression

(?P<indent> *(?P<listtype>[*o-] )? *)(?P<keyword>[^:]+?:)?(?P<text>.*)\s?


That is, a possible indent (which we measure), an optional list item identifier, optional space, optional words ended by colon, and optional text. All lines are of this form. However, some ordinary (non-list) lines may contain a colon, and then the keyword and text group must be added to get the line contents. Otherwise, the text group will be the line.

When lists are typeset, the text is examined for sections, paragraphs, title, author, date, plus all the inline tags for emphasized, boldface, and verbatim text. Plain substitutions based on regular expressions are used for this purpose.

The final step is to insert the code and TeX blocks again (these should be untouched and are therefore left out of the previous parsing).

It is important to keep the DocOnce format and parsing simple. When a new format is needed and this format is not obtained by a simple edit of the definition of existing formats, it might be better to convert the document to reST and then to XML, parse the XML and write out in the new format. When the DocOnce format is not sufficient to getting the layout you want, it is suggested to filter the document to another, more complex format, say reST or LaTeX, and work further on the document in this format.

### Typesetting of Function Arguments, Return Values, and Variables¶

Note

This text is somewhat outdated. Now DocOnce supports NumPy-style docstrings. DocOnce can also do automatic references to Python documentation, say the math module, but the link only works in case of Sphinx output. Typical syntax is

With :mod:numpy and the :func:scipy.io.loadmat function in
the :mod:scipy.io module, we can ...


In case of ambiguous names, say a local math module, one can use python, numpy, scipy, and mpl (matplotlib) as prefix (as defined in conf.py, generated by the doconce sphinx_dir):

With :func:python:math.sin instead of :func:math.sin ...


(More info in the Sphinx API doc by the author - under development.)

A Mako function can provide greater flexibility such that other formats than Sphinx can take advantage of such references (full URL can be built into the function, depending on the format).

As part of comments (or doc strings) in computer code one often wishes to explain what a function takes of arguments and what the return values are. Similarly, it is desired to document class, instance, and module variables. Such arguments/variables can be typeset as description lists of the form listed below and placed at the end of the doc string. Note that argument, keyword argument, return, instance variable, class variable, and module variable are the only legal keywords (descriptions) for the description list in this context. If the output format is Epytext (Epydoc) or Sphinx, such lists of arguments and variables are nicely formatted.

- argument x: x value (float),
which must be a positive number.
- keyword argument tolerance: tolerance (float) for stopping
the iterations.
- return: the root of the equation (float), if found, otherwise None.
- instance variable eta: surface elevation (array).
- class variable items: the total number of MyClass objects (int).
- module variable debug: True: debug mode is on; False: no debugging
(bool variable).
`

The result depends on the output format: all formats except Epytext and Sphinx just typeset the list as a list with keywords.

var x: x value (float), which must be a positive number. tolerance (float) for stopping the iterations.

## References¶

Note

The references below are just for illustrating and testing citation syntax and not references for explaining parts of the text.

 [Ref1] D. E. Knuth. Theory and Practice, EATCS Bulletin, 27, pp. 14-21, 1985.
 [Ref2] (1, 2) H. P. Langtangen. A Document for Testing DocOnce, http://hplgit.github.io/doconce/test/demo_testdoc.html.
 [Ref3] (1, 2) H. P. Langtangen and G. Pedersen. Propagation of Large Destructive Waves, International Journal of Applied Mechanics and Engineering, 7(1), pp. 187-204, 2002.
 [Ref4] (1, 2, 3) H. P. Langtangen, K.-A. Mardal and R. Winther. Numerical Methods for Incompressible Viscous Flow, Advances in Water Resources, 25, pp. 1125-1146, 2002.
 [Ref5] H. P. Langtangen. Numerical Solution of First Passage Problems in Random Vibrations, SIAM Journal of Scientific and Statistical Computing, 15, pp. 997-996, 1994.
 [Ref6] (1, 2) K.-A. Mardal, G. W. Zumbusch and H. P. Langtangen. Software Tools for Multigrid Methods, Advanced Topics in Computational Partial Differential Equations – Numerical Methods and Diffpack Programming, edited by H. P. Langtangen and A. Tveito, Springer, 2003.
 [Ref7] H. P. Langtangen. The FEMDEQS Program System, Department of Mathematics, University of Oslo, 1989.