.. raw:: html
.. File automatically generated using DocOnce (https://github.com/doconce/doconce/):
.. doconce format sphinx manual.do.txt --no_mako --cite_doconce --no_abort
.. |nbsp| unicode:: 0xA0
:trim:
.. Document title:
DocOnce Manual
%%%%%%%%%%%%%%
:Authors: Hans Petter Langtangen, Kristian Gregorius Hustad
:Date: Aug 18, 2021
.. lines beginning with # are doconce comment lines
.. (documents can also have mako comment lines)
.. warning::
Some parts of this manual may be outdated. Please create an issue at ``_ to report errors.
.. !split
.. _what:is:doconce:
What Is DocOnce?
================
.. index:: 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 be included in 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 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) using 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). It has more flexible inclusion of source code, integration of preprocessors and special support for exercises. Finally, it produces cleaner LaTeX and HTML output.
**History.**
The DocOnce development started in 2006 at a time when
most popular markup languages used lots of tagging (LaTeX,
reStructuredText, HTML). Later, almost untagged markup languages
became popular, especially `Markdown `__ and its sisters
`MultiMarkdown `__,
`Pandoc-extended Markdown `__, and
`Markua `__. DocOnce looks like
Markdown, and is close in functionality and nature to
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 dominate 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 be converted 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:
.. figure:: doconce_books.jpg
:width: 600
.. Here are some comment lines that do not affect any formatting
.. these lines are converted to comments in the output format.
.. This may have some side effects, especially in rst and sphinx
.. where lines following the comment may be taken as part of
.. the comment if there are no blank lines after the comment.
.. One can use ## and the mako preprocessor to remove comments
.. *before* doconce sees the text. That can be useful when
.. doconce comments interferes with formatting.
.. The mako tool also supports <%doc> .. %doc>
Demos and Documentation
-----------------------
.. index:: demos
.. admonition:: 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 `__.
.. admonition:: 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.)
.. admonition:: Tip: Read the FAQ
Over the years, a lot of tips and problems have 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
.. code-block:: text
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
shows 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
.. code-block:: text
doc/src/manual/manual.do.txt
You can compare this source with the available output in
`HTML `__,
`Sphinx `__,
and
`PDF `__.
.. !split
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)
--------------------------------
.. index::
single: keywords; TITLE
.. index::
single: keywords; AUTHOR
.. index::
single: keywords; DATE
.. index:: TITLE keyword
.. index:: AUTHOR keyword
.. index:: DATE keyword
.. index::
single: author; email
.. index::
single: author; institution
.. Note: AUTHOR: must here be indented one space to avoid
.. interpretation as author
Lines starting with ``TITLE:``, ``AUTHOR:``, and ``DATE:`` are optional and are used
to identify the 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
.. code-block:: text
AUTHOR: name at institution1 & institution2 & institution3
The ``at`` with surrounding spaces
is essential for adding information about institution(s)
to the author name, and the ``and`` (ampersand) with surrounding spaces is
essential as delimiter between different institutions.
An email address can optionally be included, using the syntax
.. code-block:: text
AUTHOR: name Email: somename@site.net at institution1 & 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:
.. code-block:: doconce
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),
or 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:
.. code-block:: text
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``.
.. _copyright:
Copyright
---------
.. index:: copyright syntax
A copyright notice can be given as part of the ``AUTHOR:`` command.
The syntax is
.. code-block:: text
{copyright,year1-year2|license}
where ``year1-year2`` represents the year(s) and ``license`` represents
the type of license (e.g. Creative Commons license) if that applies.
The year and license parts can be left out. In that case, the current
year is used, and no license appears.
Note that *the year and the license must be identical in all copyright
specifications* for all authors who claim copyright!
(Otherwise, an error message is issued.)
The ``{copyright...}`` specification can appear after the author's name
(and email address) and/or after an organization's name (see examples below).
The syntax of the ``year1-year`` part goes as follows:
* A single year: ``2012``.
* A range: ``2006-2010``. Up to the current year is specified by ``2005-present``. Any attempt to use an upper limit into the future will be replaced by ``present``, e.g. ``2001-2100`` becomes ``2001-present``.
* A single year: ``date``, which fetches the year from the ``DATE:`` field in the DocOnce document.
The syntax of the ``license`` part is flexible:
* Any formulation can be given. For example, ``{copyright|This work is released under an MIT license}``.
* Standardized short forms for Creative Commons (CC) licenses are available. For example, ``CC BY``, which means a CC Attribution license. ``BY`` can be replaced by ``BY-NC`` (Attribution-NonCommercial) and other abbreviations from ``_. The command-line option ``--CC_license=`` is used to provide a template for embedding the spelled out name of the abbreviated CC license. By default this template reads ``Released under a CC %s 4.0 license``, where ``%s`` is to be replaced by the license name. A common value is ``--CC_license="This work is released under the Creative Commons %s 4.0 license"``.
How the copyright is typeset depends on the format:
* LaTeX: The copyright appears as a footer on all pages (typeset with the ``\fancyfoot[C]`` command from the ``fancyhdr`` package). The command-line option ``--latex_copyright=titlepages`` leads to a copyright statement in the footer of the titlepage and (for books) the first page of each chapter.
* Sphinx: The copyright is provided as the ``copyright`` variable in ``conf.py`` and appears in the footer according to the chosen theme.
* HTML: The copyright appears at the bottom of all pages (right before the ``