DocOnce is a modestly tagged (Markdown-like) markup language targeting scientific reports, software documentation, books, blog posts, and slides involving much math and code in the text. From DocOnce source you can generate LaTeX, Sphinx, HTML, IPython notebooks, Markdown, MediaWiki, and other formats. This means that you from a single source can get the most up-to-date publishing technologies for paper, tablets, and phones.

Here are some of the most recent features and enhancements in DocOnce:

• Kristian Gregorius Hustad has now made support for TikZ figures in DocOnce. This means that you can use TikZ (popular among LaTeX writers) to make a figure. The TikZ code will be used directly in latex or pdflatex output, while an SVG version is made for HTML and a PNG is made for all other formats. (This feature is still being developed. Please create an issue if your TikZ figure isn't displayed properly.)
• Thanks to support from Mirco Meiners and Kristian Gregorius Hustad, DocOnce now supports documents in foreign languages, at the moment Norwegian and German. (Expect the code to still be a bit unstable as these features are being tested and used.)
• It is easy to overlook the many warnings and non-fatal errors from DocOnce when compiling a document. Now all comments from DocOnce for a document mydoc.do.txt are collected in mydoc.dlog for careful inspection.
• Lots of automatic adjustments of the Bootstrap styles: if it looks good in one style, just switch to any other Bootstrap style and it will look good there as well (the generated code tweaks parameters in the various styles).
• The doconce format command may issue a lot of warnings and concerns, which are usually lost in the very long output from translating DocOnce to some output format. Now all the warnings, errors, and comments are available in mydoc.dolog (if the main file is named mydoc.do.txt). It is recommended to examine this .dolog file.
• Now you can copy code from files and left-adjust the code X spaces by the syntax @@@CODE-X filename. This is particularly useful when copying code snippets from function bodies and get the snippets to start in column 1.
• DocOnce supports various types of copyright statements for commercial and academic settings (thanks to Louis Criscuolo's many suggestions to implement this important feature). See description.
• LaTeX output for figures is now \begin{figure}[!ht] % my:fig if my:fig is the figure label. Note that the previous [t] option is now [!ht] ("work hard to place the figure here, but if impossible, place it on top of the next page"). Also, adding the label on the line makes it easy to autoedit the [!ht] option for specific figures, if desired.
• DocOnce supports interactive Bokeh plots for data exploration in HTML documents, see demo.
• DocOnce can generate Matlab notebooks in the publish format (output format matlabnb).
• Exercises can now be extracted as individual files (e.g., for distribution to students). The files are in DocOnce format and can be compiled to, e.g., LaTeX or IPython notebooks, see a quick description.
• DocOnce and all its dependencies are now trivial to install with Anaconda Python: sudo conda install --channel johannr doconce (thanks to Johannes Ring).
• Bootstrap HTML styles features hints, answers, and solutions in exercises as unfolded text.
• doconce extract_exercises extracts all exercises from a document (can be used, e.g., to publish exercises separately or to extract only those exercises suitable to being published as IPython notebooks).
• DocOnce features user-defined environments with begin-end tags, doing exactly what you want: you may (e.g.) use your favorite native example LaTeX environment when writing LaTeX.
• Documents can have interactive Python code in HTML and Sphinx via the pyscpro code environment (Sage Math Cells).
• New support for RunestoneInteractive books (as a special case of the Sphinx output format).
• New support for verbatim code blocks in LaTeX with a lot of flexibility for fancy typesetting via the Pygments and Listings packages (i.e., no more need for the ptex2tex step).
• New document explaining the efficient way to use DocOnce for book writing.
• Embedded quizzes or multiple-choice questions, which can be automatically uploaded to Kahoot online games.
• Admonitions, i.e., boxes for notifications, tips, warnings, etc., with great flexibility in the typesetting (at least in HTML and LaTeX).

Here are some recent books written in DocOnce:

DocOnce is a pure Python v2.7 package and installed by

Terminal> sudo python setup.py install

However, DocOnce has a lot of dependencies, depending on what type of formats you want to work with and how advanced constructions that are used in the text.

With Anaconda Python v2.7 it is trivial to install DocOnce and all dependencies by

Terminal> sudo conda install --channel johannr doconce

On Debian/Ubuntu it is fairly straightforward to get the packages you need. Basically, you can run a Bash script or an equivalent Python script. Such a script installs a very comprehensive bundle of software. You can read the Installation Guide to get a more detailed description of what is needed of software for various purposes. For HTML output, for example, you can usually get away with just installing the pure DocOnce source (and perhaps the preprocessors if you use them).

Install from GitHub repo, not from Debian. Although DocOnce is in Debian, do not run sudo apt-get install python-doconce as this gives a very old version of DocOnce that is out of sync with the documentation. Instead, clone the DocOnce GitHub repo as shown above and run setup.py or use conda install.

• DocOnce is a modestly tagged markup language (see syntax example), quite like Markdown, but with many more features, aimed at documents with much math and code in the text (see demo).
• There is extensive support for book projects. In addition to classical LaTeX-based paper books one gets for free fully responsive, modern-looking, HTML-based ebooks for tablets and phones. Parts of books can, e.g., appear in blog posts for discussion and as IPython notebooks for experimentation and annotation.
• For documents with math and code, you can generate clean plain LaTeX (PDF), HTML (with MathJax and Pygments - embedded in your own templates), Sphinx for attractive web design, Markdown, IPython notebooks, HTML for Google or Wordpress blog posts, and MediaWiki. The LaTeX output has many fancy layouts for typesetting of computer code.
• DocOnce can also output other formats (though without support for nicely typeset math and code): plain untagged text, Google wiki, Creole wiki, and reStructuredText. From Markdown or reStructuredText you can go to XML, DocBook, epub, OpenOffice/LibreOffice, MS Word, and other formats.
• The document source is first preprocessed by Preprocess and Mako, which gives you full programming capabilities in the document's text. For example, with Mako it is easy to write a book with all computer code examples in two alternative languages (say Matlab and Python), and you can determine the language at compile time of the document. New user-specific features of DocOnce can also be implemented via Mako.
• DocOnce extends Sphinx, Markdown, and MediaWiki output such that LaTeX align environments with labels work for systems of equations. DocOnce also adjusts Sphinx and HTML code such that it is possible to refer to equations outside the current web page.
• DocOnce makes it very easy to write slides with math and code by stripping down running text in a report or book. LaTeX Beamer slides, HTML5 slides (reveal.js, deck.js, dzslides), and Remark (Markdown) slides are supported. Slide elements can be arranged in a grid of cells to easily control the layout.

DocOnce looks similar to Markdown, Pandoc-extended Markdown, and in particular MultiMarkdown. The main advantage of DocOnce is the richer support for writing large documents (books) with much math and code and with tailored output both in HTML and LaTeX. DocOnce also has special support for exercises, quizzes, and admonitions, three very desired features when developing educational material. Books can be composed of many smaller documents that may exist independently of the book, thus lowering the barrier of writing books (see example).

A short scientific report demonstrates the many formats that DocOnce can generate and how mathematics and computer code look like. (Note that at the bottom of the page there is a link to another version of the demo with complete DocOnce commands for producing the different versions.)

Another demo shows how DocOnce can be used to create slides in various formats (HTML5 reveal.js, deck.js, etc., as well as LaTeX Beamer).

DocOnce has support for responsive HTML documents with design and functionality based on Bootstrap styles. A Bootstrap demo illustrates the many possibilities for colors and layouts.

DocOnce also has support for exercises in quiz format. Pure quiz files can be automatically uploaded to Kahoot! online quiz games operated through smart phones (with the aid of quiztools for DocOnce to Kahoot! translation).

Several books (up to over 1000 pages) have been written entirely in DocOnce. The primary format is a publisher-specific LaTeX style, but HTML or Sphinx formats can easily be generated, such as this chapter in Bootstrap style, or the solarized color style as many prefer. Slides can quickly be generated from the raw text in the book. Here are examples in the reveal.js (HTML5) style, or the more traditional LaTeX Beamer style, and even the modern IPython notebook tool, which allows for interactive experimentation and annotation.

Warning. These documents are under development...

• Tutorial: Sphinx, HTML, PDF
• Manual: Sphinx, HTML, PDF
• Quick Reference: Sphinx, HTML, PDF
• Troubleshooting and FAQ: Sphinx, HTML, PDF

The tutorial presents the basic syntax and the most fundamental elements of a scientific document, while the manual has accumulated all the different features available. The most efficient way to get started is to look at the report demo and study the source code (it has all the basic elements such as title, author, abstract, table of contents, headings, comments, inline mathematical formulas, single/multiple equations, with and without numbering, labels, cross-references to sections and equations, bullet lists, enumerated lists, copying of computer code from files, inline computer code, index entries, figures, tables, and admonitions).

DocOnce is licensed under the BSD license, see the included LICENSE file.

DocOnce is written by Hans Petter Langtangen (hpl@simula.no) 2006-2016. A lot of people have contributed to testing the software and suggesting improvements.

If you add a copyright ({copyright} after any author or institution name in the AUTHOR field(s)), the command-line option --cite_doconce can be used to equip the copyright field with a link to the present page. Here is an example involving some document mydoc.do.txt:

TITLE: Some document
AUTHOR: Joe Doe {copyright}
...

Compile to HTML with DocOnce link:

Terminal> doconce format html mydoc --cite_doconce

The footer of the first page will now contain "Made with DocOnce".

BibTeX format:

@misc{DocOnce,
  title = {{DocOnce} markup language},
  author = {H. P. Langtangen},
  url = {https://github.com/hplgit/doconce},
  key = {DocOnce},
  note = {\url{https://github.com/hplgit/doconce}},
}

Publish format:

* misc
** {DocOnce} markup language
   key:       DocOnce
   author:    H. P. Langtangen
   url:       https://github.com/hplgit/doconce
   status:    published
   sortkey:   DocOnce
   note:      \url{https://github.com/hplgit/doconce}