DocOnce Description Hans Petter Langtangen1,2 Kristian Gregorius Hustad3,2 1Center for Biomedical Computing, Simula Research Laboratory 2Department of Informatics, University of Oslo 3Centre for Computing in Science Education, University of Oslo Mar 4, 2018 Warning. Some parts of this manual may be outdated. Please create an issue at https://github.com/hplgit/doconce to report errors. 1 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 des- tinations 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 de- sired in different formats such as LATEX, PDFLATEX, Sphinx, HTML, Medi- aWiki, 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. c 2018, Hans Petter Langtangen, Kristian Gregorius Hustad. Made with DocOnce • 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 pub- lished 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 lan- guage 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 al- low 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, ex- perimental 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 out- put. 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, how- ever, is a series of features for supporting both small and large documents (books in particular) with much mathematics and computer code. While Mark- down 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 Multi- Markdown), a format that is very attractive for presenting scientific material and 2 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 expres- sions. 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 compen- sated, 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). Contents 1 What Is DocOnce?1 1.1 Demos and Documentation.....................7 2 Markup Based on Special Lines8 2.1 Heading with title and author(s)...................8 2.2 Copyright...............................9 2.3 Table of contents........................... 11 2.4 Section headings........................... 11 2.5 Abstract................................ 12 2.6 Appendix............................... 12 2.7 Figures................................ 12 2.8 Movies................................. 21 2.9 Copying Computer Code from Source Files............ 26 2.10 Inserting the Output from Operating System Commands..... 26 2.11 Comments.............................. 27 2.12 Tables................................. 28 2.13 Lists.................................. 30 3 Inline Tagging 31 3.1 Emphasized Words.......................... 32 3.2 Inline Verbatim Text......................... 32 3.3 Links to Web Addresses....................... 33 3.4 Links to Mail Addresses....................... 33 3.5 Links to Local Files.......................... 33 3.6 Quotes................................ 34 3.7 Non-Breaking Space......................... 35 3.8 Horizontal rule............................ 35 3.9 Em-dash............................... 35 3.10 En-dash................................ 36 3.11 Ampersand.............................. 36 3 3.12 Footnotes............................... 36 3.13 Inline Comments........................... 37 3.14 Inline Comments for Editing..................... 37 3.15 Forced Line Breaks.......................... 39 3.16 Inline Mathematics.......................... 39 3.17 Cross-Referencing.......................... 40 3.18 Generalized Cross-Referencing................... 41 3.19 Index.................................. 48 3.20 Emojis................................. 48 4 Exercises, Problems, Projects, and Examples 48 4.1 Examples on Exercise Syntax.................... 49 4.2 Typesetting of Exercises....................... 51 4.3 List of Exercises, Problems, and Projects............. 52 4.4 Numbering of Extra Equations in Solutions............ 53 4.5 Typesetting of solutions to exercises................ 53 4.6 Extracting Selected Exercises in a Separate Document..... 55 4.7 Extracting Exercises as Stand-Alone Documents......... 56 4.8 Example of an Exercise....................... 57 5 Other Environments 61 5.1 Blocks of Verbatim Computer Code................. 61 5.2 LATEX Blocks of Mathematical Text.................. 67 5.3 Macros (Newcommands)...................... 70 5.4 Writing Guidelines (Especially for LATEX Users!).......... 71 5.5 Typesetting of Algorithms...................... 75 5.6 Admonitions.............................. 75 5.7 User-Defined Environments..................... 80 6 Bibliography (References) 84 6.1 Importing your data to the Publish database............ 84 6.2 Requirements to input data..................... 85 6.3 Adding new references to the database.............. 85 6.4 Exporting the database....................... 86 6.5 Referring to publications....................... 86 6.6 Specifying the Publish database.................. 86 6.7 LATEX Bibliography Style....................... 87 7 Preprocessing and Postprocessing 87 7.1 The Preprocess and Mako Preprocessors............. 87 7.2 Splitting Documents into Smaller Pieces.............. 89 8 Writing Slides 91 8.1 Overview............................... 92 8.2 Slide Elements............................ 93 8.3 HTML5 Slides............................. 95 4 8.4 LATEX Beamer Slides......................... 95 9 Support for non-English 96 10 Misc 96 10.1 Missing Features........................... 96 10.2 Git .gitignore File......................... 97 10.3 Emacs DocOnce Formatter..................... 98 10.4 Atom Syntax Highlighting for DocOnce............... 98 11 Mako Programming 99 11.1 The Basics of Mako......................... 99 11.2 Debugging Python code in Mako.................. 100 11.3 Example: Nomenclature functionality................ 101 11.4 Example: Executing Python and using SymPy Objects in LATEX. 103 11.5 Example: Extending Tables to Handle Figures........... 104 11.6 Example: Defining a Theorem Environment............ 109 11.7 Tools for Writing DocOnce Documents............... 111 11.8 Debugging.............................. 111 12 From DocOnce to Other Formats 111 12.1 Writing a Makefile.......................... 111 12.2 Generating a Makefile........................ 113 12.3 Spell checking............................ 114 12.4 Preprocessing............................ 114 12.5 Removal of Inline Comments.................... 115