Document once, include anywhereDocOnce 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 get the most up-to-date publishing technologies for paper, tablets, and phones.
- 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.
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 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).
A complete book (900 pages) has 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 the popular 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.
These documents are under development...
- Tutorial: Sphinx, HTML, PDF
- Manual: Sphinx, HTML, PDF
- Quick Reference: Sphinx, HTML, PDF
- Troubleshooting and FAQ: Sphinx, HTML, PDF
InstallationDocOnce is a pure Python package and can be installed with
Terminal> sudo pip install --upgrade git+https://github.com/doconce/preprocess Terminal> sudo pip install --upgrade .
However, DocOnce has a lot of dependencies, depending on what type of formats you want to work with and how advanced constructiosn that are used in the text.
With Anaconda it is trivial to install DocOnce and all dependencies by
Terminal> conda config --add channels conda-forge Terminal> conda install doconce
As of March 2017, a few dependencies have yet to be added to the
conda-forge channel, but most formats should work fine.
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.
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
pip install or use