How to write a Book in DocOnce¶

This note tells why and how you can use DocOnce to ease the writing of scientific books with much mathematics and computer code.

Why DocOnce?¶

Scientific books are very often written in LaTeX, but LaTeX is primarily suited for PDF output on paper. Today, your readers will be using different devices like tablet and phones for reading, and to address these media you need to write HTML. DocOnce lets you write in a syntax that is as simple as you use in email, and can then automatically translate that syntax to highly professional LaTeX or HTML for output (it can produce other formats too). So, the writing itself is easier since you avoid a lot of LaTeX or HTML tags, and the output is more versatile. We refer to the DocOnce tutorial and the web page for more arguments!

Hwo do I get started?¶

1. Read the web page: https://github.com/hplgit/doconce
2. Read the tutorial to get a glimpse of the basic syntax

1. HTML format
2. PDF for printing

3. Familiarize yourself with the manual
4. Install DocOnce and all it needs: try to run the entire Bash script (just comment out lines that don’t work and rerun)
5. Make a GitHhub or Bitbucket Git repository for the book project, see quick intro (or PDF for printing)
6. Take a brief look at the best practice document which documents the setup of files
7. Download the tarfile with a dummy file tree to be packed out in the root directory of the book repo (remember commit and push!)
8. Go to doc/src and start writing the first chapter! (replace why.do.txt)
9. Compile the document to PDF: bash make.sh, see my-book-4print.pdf (this is the standard Springer book layout, the svmono class adapted to DocOnce)
10. Compile the document to HTML: bash make_html.sh, see my-book.html

Some real writing¶

Let us demonstrate emphasize text, bold text, inline monospace font, and of course computer code that we can copy from a part of a file using regular expressions:

def f(x):
    return 42*x

It is a big advantage to copy computer code directly into the book, but you can also write it as part of the text, this time the FORTRAN equivalent:

subroutine f(x)
real*8 x
f = 42*x
return
end

Mathematics is written in plain LaTeX inside a begin-end tex environment:

Remember to use simple LaTeX: just the equation, equation*, \[ ... \], align, align*, alignat, or alignat* environments! Inline mathematics makes use of dollar signs: \(f(x)=42x\).

As LaTeX writer, remember that white space counts in DocOnce syntax! Be extra careful with indentation of lists.

Also remember that DocOnce avoids backslash in label, ref and cite, e.g., in references like [Ref1].