Lightweight markup language - Document Once
OTHER License
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.
NOTE
If you are new to DocOnce and consider using it, we recommend to also have a look at Quarto. Quarto has almost all functionality that is offered by Doconce, but in contrast to Doconce, Quarto uses more up-to-date technology, is actively developed and has a large user community.
Some information on the similarities and differences between DocOnce and Quarto can be found at the bottom of this page.
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 a Python 3 package that can be installed with pip
or conda
. This procedure installs a minimal number of dependencies.
python -V
and pip -V
commands should refer to Python 3.x. If that is not the case, you might want to use the pip3
and python3
commands in the following instructions.Install DocOnce and its dependencies:
pip install DocOnce --user
Create a conda environment with pip
:
conda create --name doconce python=3
conda activate doconce
conda install pip
Install DocOnce:
pip install DocOnce
A Python virtual environment is an isolated environment for python projects, which makes this option the safest installation.
Create a virtual environment:
python -m venv venv
. venv/bin/activate
Install DocOnce:
pip install DocOnce
For carrying out a comprehensive installation clone this repository
on the local computer and run pip install
in that directory:
git clone --recurse-submodules [email protected]:doconce/doconce.git
cd doconce
pip install -r requirements.txt
python setup.py install
Also refer to the manual to upgrade your DocOnce software to the latest update.
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).
Here are some of the most recent features and enhancements in DocOnce:
Here are some books written in DocOnce:
Refer to the guide Getting Started with Development. There you can read about how the DocOnce project is structured, and how to write a run/debug configuration script for a Python IDE.
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.
DocOnce is licensed under the BSD license, see the included LICENSE
file.
DocOnce was originally written by Hans Petter Langtangen at [email protected] in 2006-2016. Alessandro Marin (email address) has assumed in 2020 the role of developer and principal maintainer. A lot of people have contributed to testing the software and suggesting improvements.
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
...
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/doconce/doconce},
key = {DocOnce},
note = {\url{https://github.com/doconce/doconce}},
}
Publish format:
* misc
** {DocOnce} markup language
key: DocOnce
author: H. P. Langtangen
url: https://github.com/doconce/doconce
status: published
sortkey: DocOnce
note: \url{https://github.com/doconce/doconce}
Quarto is "an open-source scientific and technical publishing system" with very similar philosophy as DocOnce: write in a markup-language (like Markdown), convert to, and publish in, many different output formats.
Quarto is developed by Posit together with the user community, see Quarto's main GitHub repository.
DocOnce is no longer actively developed and is in maintance-only mode. This is not likely to change in the near future. There we see Quarto as a good, probably preferable, alternative to DocOnce. We are considering developing a command that converts a DocOnce file (.do.txt
) to a file compatible with Quarto (.qmd
).
Not all functionality of DocOnce is natively available with Quarto as of this moment. Here is an overview of the differences. Note that this is a work in progress - we appreciate contribtutions to this list should you have any!
:::
. While in DocOnce one can quickly locate the end of a fenced block, e.g. !ec
or !esol
, this may not be so straightforward in Quarto and closing fences have no label.#
symbols at the start of a line. As Quarto is based on MarkDown, comments need to be added using plain html, i.e. fenced with <!--
and -->
This list is a work in progress...
.ipynb
), DocOnce generates a ipynb-<filename>-src.tar.gz
file containing images for distribution with the notebook, but Quarto does not. Note that Quarto's --extract-media
setting may be a solution, this allows a custom folder for images. See https://quarto.org/docs/reference/formats/ipynb.html#rendering
link-citations: true
)::: {#exr}
blocks do not allow formatting of exercises title in .ipynb
, and overrides ::: {.cell .markdown}
blocks--without-solutions
flag for hiding solutions in the output can be done in Quarto using Project Profiles
@@@CODE
or results from commands through @@@OSCMD
. The Quarto extension include-code-files may solve this#| label:
or #| tag:
, which then becomes the ID of the cell.ipynb
) works in Quarto, this is currently a bug in DocOnce::: {.cell .markdown}
blocks for markdown-cells in notebooks, enabling determining which text should be in a single markdown cell::: {.fragment}
for stepping through arbitrary content, not just bulleted listsbc pycod-t
environment can be emulated in Quarto using```python
print("Hei")
```
Note the use of python
instead of {python}