[doconce.wiki] push by h...@simula.no - updates on 2013-06-28 16:25 GMT
3 views
Skip to first unread message
doc...@googlecode.com
Jun 28, 2013, 12:26:18 PM6/28/13
to docon...@googlegroups.com
Revision: 05c2965fe836
Branch: default
Author: "Hans Petter Langtangen <h...@simula.no>"
Date: Fri Jun 28 09:25:55 2013
Log: updates
http://code.google.com/p/doconce/source/detail?r=05c2965fe836&repo=wiki
Modified:
/Description.wiki
/Quickref.wiki
/Tutorial.wiki
=======================================
--- /Description.wiki Sat Feb 23 07:34:38 2013
+++ /Description.wiki Fri Jun 28 09:25:55 2013
@@ -1,16 +1,15 @@
#summary Doconce Description
By *Hans Petter Langtangen*
-
-==== Feb 23, 2013 ====
+==== Jun 28, 2013 ====
<wiki:comment> lines beginning with # are doconce comment lines
</wiki:comment>
<wiki:comment> (documents can also have mako comment lines) </wiki:comment>
-
== 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,
@@ -56,8 +55,15 @@
+
+
== Installation of Doconce and its Dependencies ==
+Below, we explain the manual installation of all software that may be
+needed when working with Doconce documents.
+The impatient way to install what is needed is to run the
+[doconce_install_all.sh `doconce_install_all.sh`] script.
+
==== Doconce ====
Doconce itself is pure Python code hosted at
http://code.google.com/p/doconce. Its installation from the
@@ -79,21 +85,18 @@
sudo python setup.py install
}}}
-Debian GNU/Linux users can also run
-{{{
-sudo apt-get install doconce
-}}}
-This installs the latest release and not the most updated and bugfixed
-version.
-On Ubuntu one needs to run
-{{{
-sudo add-apt-repository ppa:scitools/ppa
-sudo apt-get update
-sudo apt-get install doconce
-}}}
==== Dependencies ====
+Producing HTML documents, plain text, pandoc-extended Markdown,
+and wikis can be done without installing any other
+software. However, if you want other formats as output
+(LaTeX, Sphinx, reStructuredText) and assisting utilities such
+as preprocesors, spellcheck, file differences, bibliographies,
+and so on, the software below must be installed.
+
+<wiki:comment> Make a debpkg_doconce.txt file with everything that is
needed on Debian </wiki:comment>
+
==== Preprocessors ====
If you make use of the [http://code.google.com/p/preprocess Preprocess]
@@ -148,6 +151,13 @@
{{{
sudo apt-get install texlive-extra-utils
}}}
+
+Automatic image conversion from EPS to PDF calls up `epstopdf`, which
+can be installed by
+
+{{{
+sudo apt-get install texlive-font-utils
+}}}
==== Spellcheck ====
@@ -157,6 +167,25 @@
{{{
sudo apt-get install ispell
}}}
+
+
+==== Bibliography ====
+
+The Python package [https://bitbucket.org/logg/publish Publish] is needed
if you use a bibliography
+in your document. On the website, click on *Clone*, copy the
+command and run it:
+
+{{{
+hg clone https://bitbucket.org/logg/publish
+}}}
+Thereafter go to the `publish` directory and run the `setup.py` script
+for installing Publish:
+
+{{{
+cd publish
+sudo python setup.py
+}}}
+
==== Ptex2tex for LaTeX Output ====
@@ -182,7 +211,7 @@
are also needed. These are installed by
{{{
-sudo apt-get install texlive-latex-recommended texlive-latex-extra
+sudo apt-get install texlive
}}}
on Debian Linux (including Ubuntu) systems. TeXShop on Mac comes with
the necessary stylefiles (if not, they can be found by googling and
installed
@@ -205,17 +234,70 @@
cd pygments
sudo python setup.py install
}}}
+One can also do the simple
+
+{{{
+pip install sphinx
+}}}
+which also installs pygments.
If you use the minted style together with `ptex2tex`, you have to
enable it by the `-DMINTED` command-line argument to `ptex2tex`.
This is not necessary if you run the alternative `doconce ptex2tex`
program.
-All
-use of the minted style requires the `-shell-escape` command-line
+All use of the minted style requires the `-shell-escape` command-line
argument when running LaTeX, i.e., `latex -shell-escape` or `pdflatex
-shell-escape`.
-<wiki:comment> Say something about anslistings.sty </wiki:comment>
+Inline comments apply the `todonotes` LaTeX package if the `ptex2tex`
+or `doconce ptex2tex` command is run with `-DTODONOTES`. The
+`todonotes` package requires several other packages: `xcolor`,
+`ifthen`, `xkeyval`, `tikz`, `calc`, `graphicx`, and `setspace`. The
+relevant Debian packages for installing all this are listed below.
+
+==== LaTeX packages ====
+
+Many LaTeX packages are potentially needed (depending on various
+preprocessor variables given to `ptex2tex` or `doconce ptex2tex`. The
+standard packages always included are `relsize`, `epsfig`, `makeidx`,
+`setspace`, `color`, `amsmath`, `amsfonts`, `xcolor`, `bm`,
+`microtype`, `titlesec`, and `hyperref`. The `ptex2tex` package (from
+[http://code.google.com/p/ptex2tex ptex2tex]) is also included, but
+removed again if `doconce ptex2tex` is run instead of the `ptex2tex`
+program, meaning that if you do not use `ptex2tex`, you do not need
+`ptex2tex.sty`. Optional packages that might be included are `minted`,
+`fontspec`, `xunicode`, `inputenc`, `helvet`, `mathpazo`, `wrapfig`,
+`calc`, `ifthen`, `xkeyval`, `tikz`, `graphicx`, `setspace`, `shadow`,
+`disable`, `todonotes`, `lineno`, `xr`, `framed`, `mdframe`,
+`movie15`, `a4paper`, and `a6paper`.
+
+Relevant Debian packages that gives you all of these LaTeX packages are
+
+{{{
+texlive
+texlive-extra-utils
+texlive-latex-extra
+texlive-font-utils
+}}}
+On old Ubuntu 12.04 one has to do `sudo add-apt-repository
ppa:texlive-backports/ppa` and `sudo apt-get update` first, or
alternatively install these as well:
+
+{{{
+texlive-math-extra
+texlive-bibtex-extra
+texlive-xetex
+texlive-humanities
+texlive-pictures
+}}}
+Alternatively, one may pull in `texlive-full` to get all available
+style files.
+
+If you want to use the *anslistings* code environment with `ptex2tex`
+(`.ptex2tex.cfg` styles `Python_ANS`, `Python_ANSt`, `Cpp_ANS`, etc.) or
+`doconce ptex2tex` (`envir=ans` or `envir=ans:nt`), you need the
+`anslistings.sty` file. It can be obtained from
+the
[https://code.google.com/p/ptex2tex/source/browse/trunk/latex/styles/with_license/anslistings.sty
ptex2tex source]. It should get installed
+by the `cp2texmf.sh` script executed above.
+
==== reStructuredText (reST) Output ====
@@ -224,11 +306,19 @@
most recent version can be done by
{{{
-svn checkout
http://docutils.svn.sourceforge.net/svnroot/docutils/trunk/docutils
+svn checkout \
+ http://docutils.svn.sourceforge.net/svnroot/docutils/trunk/docutils
cd docutils
sudo python setup.py install
cd ..
}}}
+The command
+
+{{{
+pip install sphinx
+}}}
+installs Docutils along with Sphinx and Pygments.
+
To use the OpenOffice suite you will typically on Debian systems install
{{{
sudo apt-get install unovonv libreoffice libreoffice-dmaths
@@ -240,6 +330,7 @@
or clone the svn repository, go to the `rst2pdf` directory and
run the usual `sudo python setup.py install`.
+==== Sphinx Output ====
Output to `sphinx` requires of course the
[http://sphinx.pocoo.org Sphinx software],
@@ -251,6 +342,24 @@
sudo python setup.py install
cd ..
}}}
+An alternative is
+
+{{{
+pip install sphinx
+}}}
+
+Doconce comes with many Sphinx themes that are not part of the
+standard Sphinx source distribution. Some of these themes require
+additional Python/Sphinx modules to be installed:
+
+
+ * cloud and redcloud: https://bitbucket.org/ecollins/cloud_sptheme
+ * bootstrap: https://github.com/ryan-roemer/sphinx-bootstrap-theme
+ * solarized: https://bitbucket.org/miiton/sphinxjp.themes.solarized
+ * impressjs: https://github.com/shkumagai/sphinxjp.themes.impressjs
+
+These must be downloaded or cloned, and `setup.py` must be run as shown
+above.
==== Markdown and Pandoc Output ====
@@ -284,7 +393,86 @@
Mercurial (`hg`) directories, go to the directory, run
`hg pull; hg update`, and then `sudo python setup.py install`.
+==== The `doconce diff` command ====
+
+The `doconce diff file1 file prog` command for illustrating differences
between
+two files `file1` and `file2` using the program `prog` requires `prog`
+to be installed. By default, `prog` is `difflib` which comes with Python
+and is always present if you have Doconce installed. Another choice,
`diff`,
+should be available on all Unix/Linux systems. Other choices, their
+URL, and their `sudo apt-get install` command on Debian (Ubuntu) systems
+appear in the table below.
+
+
+ ||
*Program* |
|
*URL* |
| *Debian/Ubuntu
install* ||
+ ||
`pdiff`
|| [http://www.gnu.org/software/a2ps/ a2ps]
[http://www.gnu.org/software/wdiff/ wdiff] || `sudo apt-get install
a2ps wdiff texlive-latex-extra texlive-latex-recommended` ||
+ ||
`latexdiff`
|| [http://www.ctan.org/pkg/latexdiff
latexdiff] || `sudo apt-get
install
latexdiff` ||
+ ||
`kdiff3`
|| [http://kdiff3.sourceforge.net/
kdiff3] || `sudo
apt-get install
kdiff3` ||
+ ||
`diffuse`
|| [http://diffuse.sourceforge.net/
diffuse] || `sudo apt-get
install
diffuse` ||
+ ||
`xxdiff`
|| [http://xxdiff.sourceforge.net/local/
xxdiff] || `sudo apt-get
install
xxdiff` ||
+ ||
`meld`
|| [http://meldmerge.org/
meld] ||
`sudo apt-get install
meld` ||
+ ||
`tkdiff.tcl`
|| [https://sourceforge.net/projects/tkdiff/
tkdiff] || not in
Debian
||
+
+
+==== Quick Debian/Ubuntu Install ====
+
+On Debian (including Ubuntu) systems, it is straightforward to install the
+long series of Doconce dependencies:
+
+{{{
+# Version control systems
+sudo apt-get install -y mercurial git subversion
+
+# Python
+sudo apt-get install -y idle ipython python-pip python-pdftools texinfo
+
+# These lines are only necessary for Ubuntu 12.04 to install texlive 2012
+ubuntu_version=`lsb_release -r | awl '{print $2}'`
+if [ $ubuntu_version = "12.04" ]; then
+ sudo add-apt-repository ppa:texlive-backports/ppa
+ sudo apt-get update
+fi
+# LaTeX
+sudo apt-get install -y texlive texlive-extra-utils texlive-latex-extra
texlive-math-extra texlive-font-utils
+# or sudo apt-get install -y texlive-full # get everything
+sudo apt-get install -y latexdiff auctex
+
+# Image and movie tools
+sudo apt-get install -y imagemagick netpbm mjpegtools pdftk giftrans gv
evince smpeg-plaympeg mplayer totem ffmpeg libav-tools
+
+# Misc
+sudo apt-get install -y ispell pandoc libreoffice unoconv
libreoffice-dmaths curl a2ps wdiff meld xxdiff diffpdf kdiff3 diffuse
+
+# More Python software
+pip install sphinx # install pygments and docutils too
+pip install mako
+pip install -e
svn+http://preprocess.googlecode.com/svn/trunk#egg=preprocess
+pip install -e hg+https://bitbucket.org/logg/publish#egg=publish
+pip install -e
hg+https://bitbucket.org/ecollins/cloud_sptheme#egg=cloud_sptheme
+pip install -e
git+https://github.com/ryan-roemer/sphinx-bootstrap-theme#egg=sphinx-bootstrap-theme
+pip install -e
hg+https://bitbucket.org/miiton/sphinxjp.themes.solarized#egg=sphinxjp.themes.solarized
+pip install -e
git+https://github.com/shkumagai/sphinxjp.themes.impressjs#egg=sphinxjp.themes.impressjs
+pip install -e
svn+https://epydoc.svn.sourceforge.net/svnroot/epydoc/trunk/epydoc#egg=epydoc
+
+# Doconce itself
+rm -rf srclib # put downloaded software in srclib
+mkdir srclib
+cd srclib
+hg clone https://code.google.com/p/doconce/
+cd doconce
+sudo python setup.py install -y
+cd ../..
+
+# Ptex2tex
+cd srclib
+svn checkout http://ptex2tex.googlecode.com/svn/trunk/ ptex2tex
+cd ptex2tex
+sudo python setup.py install -y
+cd latex
+sh cp2texmf.sh # copy stylefiles to ~/texmf directory
+cd ../../..
+}}}
<wiki:comment> </wiki:comment>
<wiki:comment> Here are some comment lines that do not affect any
formatting </wiki:comment>
<wiki:comment> these lines are converted to comments in the output format.
</wiki:comment>
@@ -298,6 +486,7 @@
<wiki:comment> The mako tool also supports <%doc> .. </%doc>
</wiki:comment>
<wiki:comment> </wiki:comment>
+
==== Demos ====
The current text is generated from a Doconce format stored in the
@@ -325,11 +514,11 @@
<wiki:comment> Example on including another Doconce file: </wiki:comment>
-
== From Doconce to Other Formats ==
+
Transformation of a Doconce document `mydoc.do.txt` to various other
-formats applies the script `doconce format`:
+formats apply the script `doconce format`:
{{{
Terminal> doconce format format mydoc.do.txt
}}}
@@ -337,6 +526,30 @@
{{{
Terminal> doconce format format mydoc
}}}
+
+==== Generating a makefile ====
+
+Producing HTML, Sphinx, and in particular LaTeX documents from
+Doconce sources requires a few commands. Often you want to
+produce several different formats. The relevant commands should
+then be placed in a script that acts as a "makefile".
+
+The `doconce makefile` can be used to automatically generate
+such a makefile, more precisely a Bash script `make.sh`, which
+carries out the commands explained below. If our Doconce source
+is in `main_myproj.do.txt`, we run
+
+{{{
+doconce makefile main_myproj html pdflatex sphinx
+}}}
+to produce the necessary output for generating HTML, pdfLaTeX, and
+Sphinx. Usually, you need to edit `make.sh` to really fit your
+needs. Some examples lines are inserted as comments to show
+various options that can be added to the basic commands.
+A handy feature of the generated `make.sh` script is that it
+inserts checks for successful runs of the `doconce format` commands,
+and if something goes wrong, the `make.sh` exits.
+
==== Preprocessing ====
@@ -355,9 +568,7 @@
==== Removal of inline comments ====
-<wiki:comment> mention notes also </wiki:comment>
-
-The command-line arguments `--no-preprocess` and `--no-mako` turn off
+The command-line arguments `--no_preprocess` and `--no_mako` turn off
running `preprocess` and `mako`, respectively.
Inline comments in the text are removed from the output by
@@ -372,6 +583,25 @@
This action is convenient when a Doconce document reaches its final form
and comments by different authors should be removed.
+==== Notes ====
+
+Doconce does not have a tag for longer notes, because implementation
+of a "notes feature" is so easy using the `preprocess` or `mako`
+programs. Just introduce some variable, say `NOTES`, that you define
+through `-DNOTES` (or not) when running `doconce format ...`. Inside
+the document you place your notes between `# #ifdef NOTES` and
+`# #endif` preprocess tags. Alternatively you use `% if NOTES:`
+and `% endif` that `mako` will recognize. In the same way you may
+encapsulate unfinished material, extra material to be removed
+for readers but still nice to archive as part of the document for
+future revisions.
+
+==== Demo of different formats ====
+
+A simple scientific report is available in
[http://hplgit.github.com/teamods/writing_reports/doconce_commands.html a
lot of different formats].
+How to create the different formats is explained in more depth
+in the coming sections.
+
==== HTML ====
Making an HTML version of a Doconce file `mydoc.do.txt`
@@ -387,7 +617,7 @@
An external CSS file `filename` used by setting the command-line
argument `--css=filename`. There available built-in styles are
-specified as `--html-style=name`, where `name` can be
+specified as `--html_style=name`, where `name` can be
* `solarized`: the famous [http://ethanschoonover.com/solarized
solarized] style (yellowish),
@@ -408,56 +638,91 @@
If the Pygments package (including the `pygmentize` program)
is installed, code blocks are typeset with
-aid of this package. The command-line argument `--no-pygments-html`
+aid of this package. The command-line argument `--no_pygments_html`
turns off the use of Pygments and makes code blocks appear with
-plain (`pre`) HTML tags. The option `--pygments-html-linenos` turns
+plain (`pre`) HTML tags. The option `--pygments_html_linenos` turns
on line numbers in Pygments-formatted code blocks. A specific
-Pygments style is set by `--pygments-html-style=style`, where `style`
+Pygments style is set by `--pygments_html_style=style`, where `style`
can be `default`, `emacs`, `perldoc`, and other valid names for
Pygments styles.
-The HTML file can be embedded in a template if the Doconce document
-does not have a title (because then there will be
-no header and footer in the HTML file). The template file must contain
+The HTML file can be embedded in a template with your own tailored
+design, see a [
https://doconce.googlecode.com/hg/doc/design/wrapper_tech.html tutorial] on
this topic. The template file must contain
valid HTML code and can have three "slots": `%(title)s` for a title,
-`%(date)s` for a date, and `%(main)s` for the main body of text, i.e., the
+`%(date)s` for a date, and `%(main)s` for the main body of text. The
+latter is the
Doconce document translated to HTML. The title becomes the first
-heading in the Doconce document, and the date is extracted from the
-`DATE:` line, if present. With the template feature one can easily embed
-the text in the look and feel of a website. The template can be extracted
-from the source code of a page at the site; just insert `%(title)s` and
-`%(date)s` at appropriate places and replace the main bod of text
-by `%(main)s`. Here is an example:
+heading in the Doconce document, or the title (but a title is not
+recommended when using templates). The date is extracted from the
+`DATE:` line. With the template feature one can easily embed
+the text in the look and feel of a website. Doconce comes with
+two templates in `bundled/html_styles`. Just copy the directory
+containing the template and the CSS and JavaScript files to your
+document directory, edit the template as needed (also check that
+paths to the `css` and `js` subdirectories are correct - according
+to how you store the template files), and run
{{{
-Terminal> doconce format html mydoc --html-template=mytemplate.html
+Terminal> doconce format html mydoc --html_template=mytemplate.html
}}}
+The template in `style_vagrant` also needs an extra option
+`--html_style=vagrant`. With this style, one has nice navigation buttons
+that are used if the document contains `!split` commands for splitting
+it into many pages.
+
-==== Blogs ====
+==== Blog Posts ====
-Doconce can be used for writing blogs provided the blog site accepts
+Doconce can be used for writing blog posts provided the blog site accepts
raw HTML code. Google's Blogger service (`blogger.com` or
-`blogname.blogspot.com`)
-is particularly well suited since it also allows extensive LaTeX
mathematics via
-MathJax.
-Write the blog text as a Doconce document without any title, author, and
-date. Then generate HTML as described above. Copy the text and paste it
-into the text area in the blog, making sure the input format is HTML.
-On Google's Blogger service you can use Doconce to generate blogs with
-LaTeX mathematics and pretty (pygmentized) blocks of computer code.
-See a [http://doconce.blogspot.no blog example] for details on blogging.
+`blogname.blogspot.com`) is particularly well suited since it also
+allows extensive LaTeX mathematics via MathJax.
+
+
+# Write the blog text as a Doconce document without any title, author,
and date.
+# Generate HTML as described above.
+# Copy the text and paste it into the text area in the blog (just delete
the HTML code that initially pops up in the text area). Make sure the
input format is HTML.
+
+See a [http://doconce.blogspot.no simple blog example] and
+a [http://doconce-report-demo.blogspot.no/ scientific report]
+for demonstrations of blogs at `blogspot.no`.
+
+*Warning.*
+In the readers' comments after the blog one cannot paste raw HTML
+code with MathJax
+scripts so there is no support for mathematics in the discussion forum.
+*Notice.*
+Figure files must be uploaded to some web site and the filenames name must
+be replaced by the relevant URL. This can be automatically edited:
+{{{
+cp mydoc.do.txt mydoc2.do.txt
+url="https//raw.github.com/someuser/someuser.github.com"
+dir="master/project/dir1/dir2"
+for figname in fig1 fig2 fig3; do
+ doconce replace "[$figname," "[$site/$dir/$figname.png," \
+ mydoc2.do.txt
+done
+doconce format html mydoc2
+# Paste mydoc2.html into a new blog page
+}}}
-*Warning.* In the comments after the blog one cannot paste raw HTML code
with MathJax
-scripts so there is no support for mathematics in the comments.
+Blog posts at Google can also be published
[http://support.google.com/blogger/bin/answer.py?hl=en&answer=41452
automatically through email].
+A Python program can send the contents of the HTML file
+to the blog's email address using the packages `smtplib` and `email`.
WordPress (`wordpress.com`) allows raw HTML code in blogs,
but has very limited
LaTeX support, basically only formulas. The `--wordpress` option to
`doconce` modifies the HTML code such that all equations are typeset
in a way that is acceptable to WordPress.
-There is a [http://doconce.wordpress.com doconce example]
-on blogging with mathematics and code on WordPress.
+Look at a [http://doconce.wordpress.com simple doconce example]
+and a [http://doconcereportdemo.wordpress.com/ scientific report]
+to see blogging with mathematics and code on WordPress.
+
+Speaking of WordPress, the related project http://pressbooks.com can take
raw HTML code (from Doconce, for
+instance) and produce very nice-looking books. There is no support
+for mathematics in the text, though.
==== Pandoc and Markdown ====
@@ -475,13 +740,21 @@
Pandoc pass raw HTML or LaTeX to the output format instead of ignoring it,
while the `--toc` option generates a table of contents.
See the [http://johnmacfarlane.net/pandoc/README.html Pandoc documentation]
-for the many features of the `pandoc` program.
+for the many features of the `pandoc` program. The HTML output from
+`pandoc` needs adjustments to provide full support for MathJax LaTeX
+mathematics, and for this purpose one should use `doconce md2html`:
+
+{{{
+Terminal> doconce format pandoc mydoc
+Terminal> doconce m2html mydoc
+}}}
+The result `mydoc.html` can be viewed in a browser.
-Pandoc is useful to go from LaTeX mathematics to, e.g., HTML or MS Word.
-There are two ways (experiment to find the best one for your document):
-`doconce format pandoc` and then translating using `pandoc`, or
-`doconce format latex`, and then going from LaTeX to the desired format
-using `pandoc`.
+Pandoc is useful to go from LaTeX mathematics to, e.g., HTML or MS
+Word. There are two ways (experiment to find the best one for your
+document): `doconce format pandoc` and then translating using `doconce
+md2latex` (which runs `pandoc`), or `doconce format latex`, and then
+going from LaTeX to the desired format using `pandoc`.
Here is an example on the latter strategy:
{{{
Terminal> doconce format latex mydoc
@@ -489,8 +762,8 @@
Terminal> doconce replace '\Verb!' '\verb!' mydoc.tex
Terminal> pandoc -f latex -t docx -o mydoc.docx mydoc.tex
}}}
-When we go through `pandoc`, only single equations or `align*`
-environments are well understood.
+When we go through `pandoc`, only single equations, `align`, or `align*`
+environments are well understood for output to HTML.
Note that Doconce applies the `Verb` macro from the `fancyvrb` package
while `pandoc` only supports the standard `verb` construction for
@@ -510,6 +783,7 @@
The `-s` option adds a proper header and footer to the `mydoc.html` file.
This recipe is a quick way of makeing HTML notes with (some) mathematics.
+
==== LaTeX ====
Making a LaTeX file `mydoc.tex` from `mydoc.do.txt` is done in two steps:
@@ -528,7 +802,7 @@
If these files are present, they are included in the LaTeX document
so that your commands are defined.
-An option `--latex-printed` makes some adjustments for documents
+An option `--latex_printed` makes some adjustments for documents
aimed at being printed. For example, links to web resources are
associated with a footnote listing the complete web address (URL).
@@ -559,17 +833,23 @@
Preprocessor variables to be defined or undefined are
- * `BOOK` for the "book" documentclass rather than the
standard "article" class (necessary if you apply chapter headings)
+ * `XELATEX` for processing by `xelatex`
* `PALATINO` for the Palatino font
- * `HELVETIA` for the Helvetica font
+ * `HELVETICA` for the Helvetica font
* `A4PAPER` for A4 paper size
- * `A6PAPER` for A6 paper size (suitable for reading on small devices)
- * `MOVIE15` for using the movie15 LaTeX package to display movies
- * `PREAMBLE` to turn the LaTeX preamble on or off (i.e., complete
document or document to be included elsewhere)
- * `MINTED` for inclusion of the minted package (which requires `latex`
or `pdflatex` to be run with the `-shell-escape` option)
+ * `A6PAPER` for A6 paper size (suitable for reading PDFs on phones)
+ * `MOVIE` for specifying how movies are handled: the value `media9`
implies the `media9` package and the `\includemedia` command (default),
while other values are `movie15` (`\includemovie` command), `multimedia`
(for Beamer-style `\movie` command), or `href-run` (for the plain
`\hrun:file` command)
+ * `PREAMBLE` to turn the LaTeX preamble on or off (i.e., complete
document or document to be included elsewhere - and note that the
preamble is only included if the document has a title, author, and date)
+ * `MINTED` for inclusion of the minted package for typesetting of code
with the Pygments tool (which requires `latex` or `pdflatex` to be run
with the `-shell-escape` option)
+ * `TODONOTES` for using the fancy `todonotes` package for typesetting
inline comments (looks much like track changes in MS Word). This macro
has only effect if inline comments are used (name, colon, and comment
inside brackets).
+ * `LINENUMBERS` for inclusion of line numbers in the text.
+ * `AMON` for setting the type of admonitions: `"colors"` for colored
boxes with icons, `"graybox1"` for gray frame boxes with rounded corners
(default), `"graybox2"` for narrower square gray frame boxes (except for
summary, which for A4 format is small and with wrapped text around if it
does not contain verbatim code), or `"paragraph"` for simple, plain
paragraph headings and ordinary text
+ * `COLORED_TABLE_ROWS` for coloring every other table rows (set this
variable to `gray` or `blue`)
+ * `BLUE_SECTION_HEADINGS` for blue section and subsection headings
+ * `LATEX_HEADING` for the typesetting of the title, author, parts of
preamble (values: `traditional` for traditional LaTeX heading,
`titlepage` for a separate titlepage, `Springer_collection` for edited
volumes on Springer, `beamer` for Beamer slides, `doconce_heading`
(default) for listing institutions after names)
If you are not satisfied with the Doconce preamble, you can provide
-your own preamble by adding the command-line option
`--latex-preamble=myfile`.
+your own preamble by adding the command-line option
`--latex_preamble=myfile`.
In case `myfile` contains a documentclass definition, Doconce assumes
that the file contains the *complete* preamble you want (not that all
the packages listed in the default preamble are required and must be
@@ -612,16 +892,24 @@
edited with the aid of the `doconce replace` and `doconce subst`
commands. The former works with substituting text directly, while the
latter performs substitutions using regular expressions.
-Here are two examples:
+You will use `doconce replace` to edit `section{` to `section*{`:
{{{
Terminal> doconce replace 'section{' 'section*{' mydoc.tex
+}}}
+For fixing the line break of a title, you may pick a word in the
+title, say "Using", and insert a break after than word. With
+`doconce subst` this is easy employing regular expressions with
+a group before "Using" and a group after:
+
+{{{
Terminal> doconce subst 'title\{(.+)Using (.+)\}' \
'title{\g<1> \\\\ [1.5mm] Using \g<2>' mydoc.tex
}}}
A lot of tailored fixes to the LaTeX document can be done by
an appropriate set of text replacements and regular expression
substitutions. You are anyway encourged to make a script for
-generating PDF from the LaTeX file.
+generating PDF from the LaTeX file so the `doconce subst` or
+`doconce replace` commands can be put inside the script.
*Step 3.* Compile `mydoc.tex`
and create the PDF file:
@@ -657,6 +945,7 @@
specifications with `doconce ptex2tex`), the minted package is
automatically
included so there is no need for the `-DMINTED` option.
+
==== PDFLaTeX ====
Running `pdflatex` instead of `latex` follows almost the same steps,
@@ -671,6 +960,19 @@
Terminal> bibitem mydoc # if bibliography
Terminal> pdflatex -shell-escape mydoc
}}}
+
+==== XeLaTeX ====
+
+XeLaTeX is an alternative to pdfLaTeX and is run in almost the
+same way, except for the `-DXELATEX` flag to ptex2tex:
+
+{{{
+Terminal> doconce format pdflatex mydoc
+Terminal> doconce ptex2tex mydoc -DXELATEX
+Terminal> ptex2tex -DXELATEX mydoc # alternative
+Terminal> xelatex mydoc
+}}}
+
==== Plain ASCII Text ====
@@ -756,40 +1058,119 @@
`automake_sphinx.py` for compiling the Sphinx document into an HTML
document. One can either run `automake_sphinx.py` or perform the
steps in the script manually, possibly with necessary modifications.
-You should at least read the script prior to executing it to have
-some idea of what is done.
+Normally, executing the script works well, but if you are new
+to Sphinx and end up producing quite some Sphinx documents, I encourave
+you to read the Sphinx documentation and study the `automake_sphinx.py`
+file.
-The `doconce sphinx_dir` script copies directories named `figs` or
-`figures` over to the Sphinx directory so that figures are accessible
-in the Sphinx compilation. If figures or movies are located in other
-directories, `automake_sphinx.py` must be edited accordingly. Files,
-to which there are local links (not `http:` or `file:` URLs), must be
-placed in the `_static` subdirectory of the Sphinx directory. The
-utility `doconce sphinxfix_localURLs` is run to check for local links
-in the Doconce file: for each such link, say `dir1/dir2/myfile.txt` it
-replaces the link by `_static/myfile.txt` and copies
-`dir1/dir2/myfile.txt` to a local `_static` directory (in the same
-directory as the script is run). However, we recommend instead that
-the writer of the document places files in `_static` or lets a script
-do it automatically. The user must copy all `_static/*` files to the
-`_static` subdirectory of the Sphinx directory. It may be wise to
-always put files, to which there are local links in the Doconce
-document, in a `_static` or `_static-name` directory and use these
-local links. Then links do not need to be modified when creating a
-Sphinx version of the document.
+*Links.* The `automake_sphinx.py` script copies directories named `fig*`
+over to the Sphinx directory so that figures are accessible
+in the Sphinx compilation. It also examines `MOVIE:` and `FIGURE:`
+commands in the Doconce file to find other image files and copies
+these too. I strongly recommend to put files
+to which there are local links (not `http:` or `file:` URLs) in
+a directory named `_static`. The `automake_sphinx.py` copies
+`_static*` to the Sphinx directory, which guarantees that the links
+to the local files will work in the Sphinx document.
+
+There is a utility `doconce sphinxfix_localURLs` for checking links to
+local files and moving the files to `_static` and changing the links
+accordingly. For example, a link to `dir1/dir2/myfile.txt` is changed
+to `_static/myfile.txt` and `myfile.txt` is copied to `_static`.
+However, I recommend instead that you manually copy
+files to `_static` when you want to link to them, or let your
+script which compiles the Doconce document do it automatically.
-Doconce comes with a collection of HTML themes for Sphinx documents.
-These are packed out in the Sphinx directory, the `conf.py`
-configuration file for Sphinx is edited accordingly, and a script
+*Themes.* Doconce comes with a rich collection of HTML themes for Sphinx
documents,
+much larger than what is found in the standard Sphinx distribution.
+Additional themes include
+`agni`,
+`basicstrap`,
+`bootstrap`,
+`cloud`,
+`fenics`,
+`fenics_minimal`,
+`flask`,
+`haiku`,
+`impressjs`,
+`jal`,
+`pylons`,
+`redcloud`,
+`scipy_lectures`,
+`slim-agogo`, and
+`vlinux-theme`.
+
+All the themes are packed out in the Sphinx directory, and the
+`doconce sphinx_dir` insert lots of extra code in the `conf.py`
+file to enable easy specification and customization of themes.
+For example, modules are loaded for the additional themes that
+come with Doconce, code is inserted to allow customization of
+the look and feel of themes, etc. The `conf.py` file is a
+good starting point for fine-tuning your favorite team, and your
+own `conf.py` file can later be supplied and used when running
+`doconce sphinx_dir`: simply add the command-line option
+`conf.py=conf.py`.
+
+A script
`make-themes.sh` can make HTML documents with one or more themes.
For example,
-to realize the themes `fenics` and `pyramid`, one writes
+to realize the themes `fenics`, `pyramid`, and `pylon` one writes
{{{
-Terminal> ./make-themes.sh fenics pyramid
+Terminal> ./make-themes.sh fenics pyramid pylon
}}}
The resulting directories with HTML documents are `_build/html_fenics`
and `_build/html_pyramid`, respectively. Without arguments,
-`make-themes.sh` makes all available themes (!).
+`make-themes.sh` makes all available themes (!). With `make-themes.sh`
+it is easy to check out various themes to find the one that is most
+attractive for your document.
+
+You may supply your own theme and avoid copying all the themes
+that come with Doconce into the Sphinx directory. Just specify
+`theme_dir=path` on the command line, where `path` is the relative
+path to the directory containing the Sphinx theme. You must also
+specify a configure file by `conf.py=path`, where `path` is the
+relative path to your `conf.py` file.
+
+*Example.* Say you like the `scipy_lectures` theme, but you want
+a table of contents to appear *to the right*, much in the same style
+as in the `default` theme (where the table of contents is to the left).
+You can then run `doconce sphinx_dir`, invoke a text editor with the
+`conf.py` file, find the line `html_theme == 'scipy_lectures'`,
+edit the following `nosidebar` to `false` and `rightsidebar` to `true`.
+Alternatively, you may write a little script using `doconce replace`
+to replace a portion of text in `conf.py` by a new one:
+
+{{{
+doconce replace "elif html_theme == 'scipy_lectures':
+ html_theme_options = {
+ 'nosidebar': 'true',
+ 'rightsidebar': 'false',
+ 'sidebarbgcolor': '#f2f2f2',
+ 'sidebartextcolor': '#20435c',
+ 'sidebarlinkcolor': '#20435c',
+ 'footerbgcolor': '#000000',
+ 'relbarbgcolor': '#000000',
+ }" "elif html_theme == 'scipy_lectures':
+ html_theme_options = {
+ 'nosidebar': 'false',
+ 'rightsidebar': 'true',
+ 'sidebarbgcolor': '#f2f2f2',
+ 'sidebartextcolor': '#20435c',
+ 'sidebarlinkcolor': '#20435c',
+ 'footerbgcolor': '#000000',
+ 'relbarbgcolor': '#000000',
+ }" conf.py
+}}}
+Obviously, we could also have changed colors in the edit above.
+The final alternative is to save the edited `conf.py` file somewhere
+and reuse it the next time `doconce sphinx_dir` is run
+
+{{{
+doconce sphinx_dir theme=scipy_lectures \
+ conf.py=../some/path/conf.py mydoc
+}}}
+
+==== The manual Sphinx procedure ====
If it is not desirable to use the autogenerated scripts explained
above, here is the complete manual procedure of generating a
@@ -879,6 +1260,7 @@
(`code-block:: python` in Sphinx syntax) and `cppcod` gives C++, but
all such arguments can be customized both for Sphinx and LaTeX output.
+
==== Wiki Formats ====
There are many different wiki formats, but Doconce only supports three:
@@ -1058,12 +1440,13 @@
line. Here is an example:
{{{
TITLE: On an Ultimate Markup Language
-AUTHOR: H. P. Langtangen at Center for Biomedical Computing, Simula
Research Laboratory and Dept. of Informatics, Univ. of Oslo
+AUTHOR: H. P. Langtangen at Center for Biomedical Computing, Simula
Research Laboratory & Dept. of Informatics, Univ. of Oslo
AUTHOR: Kaare Dump Email: du...@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,
+Note how one can specify a single institution, multiple institutions
+(with `&` as separator between institutions),
and 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
@@ -1138,8 +1521,6 @@
__A Paragraph.__ The running text goes here.
}}}
-
-
== Special Lines ==
@@ -1240,25 +1621,27 @@
is generated, and a link to this file is inserted in the output document.
That is, a simple "movie viewer" for the frames is made.
-Many publish their scientific movies on YouTube, and Doconce recognizes
-YouTube URLs as movies. When the output from Doconce
+Many publish their scientific movies on YouTube or Vimeo, and Doconce
recognizes
+YouTube and Vimeo URLs as movies. When the output from Doconce
is an HTML file, the movie will
-be embedded, otherwise a URL to the YouTube page is inserted.
+be embedded, otherwise a URL to the YouTube or Vimeo page is inserted.
You should equip the `MOVIE:` command with the right width and height
-of *embedded* YouTube movies. The recipe goes as follows:
+of *embedded* YouTube and Vimeo movies. The recipe goes as follows:
-# click on *Share* and then *Embed*
-# copy the URL for the embedded movie
+# click on *Share* (and on YouTube then *Embed*)
# note the height and width of the embedded movie
A typical `MOVIE` command with a YouTube movie is then
{{{
-MOVIE: [http://www.youtube.com/embed/sI2uCHH3qIM, width=420 height=315]
+MOVIE: [http://www.youtube.com/watch?v=sI2uCHH3qIM, width=420 height=315]
+
+MOVIE: [http://vimeo.com/55562330, width=500 height=278] Computational
fluid dynamics movie.
}}}
-Doconce will be able to embed standard YouTube URLs also, but then
-the width and height might be inappropriate.
+Note that there must be a blank line after every `MOVIE:` command.
+The width and height parameters are not required, but leaving them out
+may lead to movie sizes you do not want.
==== Copying Computer Code from Source Files ====
@@ -1266,10 +1649,12 @@
of computer code from a file directly into a verbatim environment, see
the section [#Blocks_of_Verbatim_Computer_Code] below.
+
==== Inline Tagging ====
Doconce supports tags for *emphasized phrases*, *boldface phrases*,
-and `verbatim text` (also called type writer text, for inline code)
+and `verbatim text` (also called type writer text, for inline code),
+<font color="blue">colored words</font>,
plus LaTeX/TeX inline mathematics, such as `v = sin(x)`.
==== Emphasized Words ====
@@ -1303,9 +1688,8 @@
the Doconce file, because some formats (LaTeX and `ptex2tex`) will have
problems with inline verbatim text that is split over two lines.
-
-
-*Notice.* Watch out for mixing back-ticks and asterisk (i.e., verbatim and
+*Notice.*
+Watch out for mixing back-ticks and asterisk (i.e., verbatim and
emphasized code): the Doconce interpreter is not very smart so inline
computer code can soon lead to problems in the final format. Go back to the
Doconce source and modify it so the format to which you want to go
@@ -1404,10 +1788,11 @@
}}}
where `name` is the name of the author of the command, and `comment` is a
plain text text. Note that there must be a space after the colon,
-otherwise the comment is not recognized. Inline comments
+otherwise the comment is not recognized. [hpl 1: Inline comments
can span
several lines,
-if desired.
+if desired.]
+
The name and comment are visible in the output unless `doconce format`
is run with a command-line argument `--skip_inline_comments`
(see the section [#From_Doconce_to_Other_Formats] for an example). Inline
comments
@@ -1416,6 +1801,11 @@
All such comments can easily be removed from the `.do.txt` file
(see the section [#From_Doconce_to_Other_Formats]).
+Inline comments are typeset in a simple way (boldface name and the
+comment in parenthesis), but in LaTeX very visible color boxes
+are used (via the `todonotes` package).
+
+
==== Inline Mathematics ====
Inline mathematics is written as in LaTeX, i.e., inside dollar signs.
@@ -1477,6 +1867,7 @@
preprocessor and an if-else block with a variable that is undefined
(typically something like a test `# #ifdef EXTRA` in Preprocess).
+
==== Cross-Referencing ====
References and labels are supported. The syntax is simple:
@@ -1593,7 +1984,7 @@
@testdoc:12, Doconce documents may include movies.
}}}
-==== Index and Bibliography ====
+==== Index ====
An index can be created for the `latex`, `rst`, and `sphinx` formats
by the `idx` keyword, following a LaTeX-inspired syntax:
@@ -1616,73 +2007,147 @@
index items related to a paragraph should be placed above the
paragraph one a separate line (and not in between the text or between
the paragraph heading and the text body, although this works fine if
-LaTeX is the output format).
+LaTeX is the output format). For paragraphs with `===` heading,
+the index keywords should be placed above the heading.
-Literature citations also follow a LaTeX-inspired style:
+The keywords in the index are automatically placed in a meta
+tag in `html` output such that search engines can make use of the them.
+
+==== Bibliography ====
+
+Doconce applies the software tool [https://bitbucket.org/logg/publish
Publish] to handle the bibliography in a
+document. With Publish it is easy to import BibTeX data and maintain a
+database in a clean, self-explanatory textual format. From the Publish
+format it is easy to go BibTeX and reST or straightforward Doconce
+typesetting (and from there to HTML, plain text, wiki formats, and so
+on).
+
+Installing Publish is straightforward: just checkout the code on
***The diff for this file has been truncated for email.***
=======================================
--- /Quickref.wiki Sat Feb 23 07:34:38 2013
+++ /Quickref.wiki Fri Jun 28 09:25:55 2013
@@ -1,17 +1,22 @@
#summary Doconce Quick Reference
By *Hans Petter Langtangen*
-
-==== Feb 23, 2013 ====
+==== Jun 8, 2013 ====
<wiki: toc max_depth="2" />
-<wiki:comment> Very preliminary </wiki:comment>
-
*WARNING: This quick reference is very incomplete!*
+*Mission.* Enable writing documentation with much mathematics and
+computer code *once, in one place* and include it in traditional LaTeX
+books, thesis, and reports, and without extra efforts also make
+professionally looking web versions with Sphinx or HTML. Other outlets
+include Google's `blogger.com`, Wikipedia/Wikibooks, IPython
+notebooks, plus a wide variety of formats for documents without
+mathematics and code.
+
==== Supported Formats ====
Doconce currently translates files to the following formats:
@@ -22,14 +27,49 @@
* reStructuredText (format `rst`)
* plain (untagged) ASCII (format `plain`)
* Sphinx (format `sphinx`)
+ * IPython notebook (format `ipynb`)
+ * MediaWiki (format `mwiki`)
* (Pandoc extended) Markdown (format `pandoc`)
* Googlecode wiki (format `gwiki`)
- * MediaWiki for Wikipedia and Wikibooks (format `mwiki`)
* Creoloe wiki (format `cwiki`)
* Epydoc (format `epydoc`)
* StructuredText (format `st`)
-The best supported formats are `latex`, `sphinx`, `html`, and `plain`.
+For documents with much code and mathematics, the best (and most supported)
+formats are `latex`, `pdflatex`, `sphinx`, and `html`; and to a slightly
+less extent `mwiki` and `pandoc`. The HTML format supports blogging on
+Google and Wordpress.
+
+
+==== Emacs syntax support ====
+
+The file
[https://doconce.googlecode.com/hg/misc/.doconce-mode.el .doconce-mode.el]
in the Doconce source distribution
+gives a "Doconce Editing Mode" in Emacs. Store the file in the home
+directory and add `(load-file "~/.doconce-mode.el")` to the `.emacs`
+file.
+
+Besides syntax highlighting of Doconce documents, this Emacs mode
+provides a lot of shortcuts for setting up many elements in a document:
+
+
+ || *Emacs key* ||
*Action* ||
+ || Ctrl+c f ||
figure ||
+ || Ctrl+c v ||
movie/video ||
+ || Ctrl+c h1 || heading level 1
(section/h1) ||
+ || Ctrl+c h2 || heading level 2
(subsection/h2) ||
+ || Ctrl+c h3 || heading level 2
(subsection/h3) ||
+ || Ctrl+c hp || heading for
paragraph ||
+ || Ctrl+c me || math environment: !bt
equation !et ||
+ || Ctrl+c ma || math environment: !bt
align !et ||
+ || Ctrl+c ce || code
environment: !bc !ec ||
+ || Ctrl+c cf || code from file:
@@@CODE ||
+ || Ctrl+c table2 || table with 2
columns ||
+ || Ctrl+c table3 || table with 3
columns ||
+ || Ctrl+c table4 || table with 4
columns ||
+ || Ctrl+c exer || exercise
outline ||
+ || Ctrl+c slide || slide
outline ||
+ || Ctrl+c help || print this
table ||
+
==== Title, Authors, and Date ====
@@ -38,7 +78,7 @@
reads
{{{
TITLE: On an Ultimate Markup Language
-AUTHOR: H. P. Langtangen at Center for Biomedical Computing, Simula
Research Laboratory and Dept. of Informatics, Univ. of Oslo
+AUTHOR: H. P. Langtangen at Center for Biomedical Computing, Simula
Research Laboratory & Dept. of Informatics, Univ. of Oslo
AUTHOR: Kaare Dump Email: du...@cyb.space.com at Segfault, Cyberspace Inc.
AUTHOR: A. Dummy Author
DATE: today
@@ -47,11 +87,12 @@
The entire title must appear on a single line.
The author syntax is
{{{
-name Email: some...@adr.net at institution1 and institution2
+name Email: some...@adr.net at institution1 & institution2
}}}
where the email is optional, the "at" keyword is required if one or
-more institutions are to be specified, and the "and" keyword
-separates the institutions. Each author specification must appear
+more institutions are to be specified, and the `&` keyword
+separates the institutions (the keyword `and` works too).
+Each author specification must appear
on a single line.
When more than one author belong to the
same institution, make sure that the institution is specified in an
identical
@@ -62,30 +103,41 @@
The table of contents is removed by writing `TOC: off`.
+
==== Section Types ====
- || *Section type* ||
*Syntax* ||
- || chapter || `========= Heading
========` (9 `=`) ||
- || section || `======= Heading
=======` (7 `=`) ||
- || subsection || `===== Heading
=====` (5 `=`) ||
- || subsubsection || `=== Heading
===` (3 `=`) ||
- || paragraph ||
`__Heading.__` (2 `_`) ||
- || abstract || `__Abstract.__` Running
text... ||
+ || *Section type* |
| *Syntax* ||
+ || chapter || `=========
Heading ========` (9 `=`) ||
+ || section || `======= Heading
=======` (7 `=`) ||
+ || subsection || `===== Heading
=====` (5 `=`) ||
+ || subsubsection || `=== Heading
===` (3 `=`) ||
+ || paragraph ||
`__Heading.__` (2 `_`) ||
+ || abstract || `__Abstract.__`
Running text... ||
+ || appendix || `=======
Appendix: heading =======` (7 `=`) ||
+ || appendix || `===== Appendix:
heading =====` (5 `=`) ||
+ || exercise || `=======
Exercise: heading =======` (7 `=`) ||
+ || exercise || `===== Exercise:
heading =====` (5 `=`) ||
-Note that abstracts are recognized by starting with `__Abstract.__` at
-the beginning of a line and ending with three or more `=` signs of the
-next heading.
+Note that abstracts are recognized by starting with `__Abstract.__` or
+`__Summary.__` at the beginning of a line and ending with three or
+more `=` signs of the next heading.
-Appendix is supported: just let the heading start with "Appendix: "
-(this affects only `latex` output, where the appendix formatting
-is used - all other formats just leave the heading as it is written).
+The `Exercise:` keyword kan be substituted by `Problem:` or `Project:`.
+A recommended convention is that an exercise is tied to the text,
+a problem can stand on its own, and a project is a comprehensive
+problem.
==== Inline Formatting ====
Words surrounded by `*` are emphasized: `*emphasized words*` becomes
*emphasized words*. Similarly, an underscore surrounds words that
-appear in boldface: `_boldface_` become *boldface*.
+appear in boldface: `_boldface_` becomes *boldface*. Colored words
+are also possible: the text
+{{{
+`color{red}{two red words}`
+}}}
+becomes <font color="red">two red words</font>.
==== Lists ====
@@ -160,7 +212,7 @@
* keyword3:
and its description may fit on one line
-==== Comments ====
+==== Comment lines ====
Lines starting with `#` are treated as comments in the document and
translated to the proper syntax for comments in the output
@@ -168,34 +220,49 @@
blocks, verbatim code blocks, or lists if the formats `rst` and
`sphinx` are desired.
+Comment lines starting with `##` are not propagated to the output
+document and can be used for comments that are only interest in
+the Doconce file.
+
+Large portions of text can be left out using Preprocess. Just place
+`# #ifdef EXTRA` and `# #endif` around the text. The command line
+option `-DEXTRA` will bring the text alive again.
+
When using the Mako preprocessor one can also place comments in
the Doconce source file that will be removed by Mako before
-Doconce starts processing the file. Mako comments are recognized
-by lines starting with two hashes `##` or by blocks of text
-inside the comment directives `%<doc>` (beginning) and `<%doc/>` (end).
+Doconce starts processing the file.
+
+
+==== Inline comments ====
-Inline comments, in the text, that are meant as messages or notes to
readers
-(authors in particular)
-are often useful and enabled by the syntax
+Inline comments meant as messages or notes, to authors during development
+in particular,
+are enabled by the syntax
{{{
[name: running text]
}}}
where `name` is the name or ID of an author or reader making the comment,
-and `running text` is the comment. There must be a space after the colon.
+and `running text` is the comment. Here goes an example.
+[hpl 1: There must be a space after the colon,
+but the running text can occupy multiple lines.]
+The inline comments have simple typesetting in most formats, typically
boldface
+name and everything surrounded by parenthesis, but with LaTeX
+output and the `-DTOTONOTES` option to `ptex2tex` or `doconce ptex2tex`,
+colorful margin or inline boxes (using the `todonotes` package)
+make it very easy to spot the comments.
+
Running
{{{
doconce format html mydoc.do.txt --skip_inline_comments
}}}
-removes all such inline comments from the output. This feature makes it
easy
-to turn on and off notes to readers and is frequently used while writing
-a document.
+removes all inline comments from the output. This feature makes it easy
+to turn on and off notes to authors during the development of the document.
All inline comments to readers can also be physically
-removed from the Doconce source if desired:
+removed from the Doconce source by
{{{
doconce remove_inline_comments mydoc.do.txt
}}}
-This action is appropriate when all issues with such comments are resolved.
==== Verbatim/Computer Code ====
@@ -273,9 +340,9 @@
==== LaTeX Mathematics ====
Doconce supports inline mathematics and blocks of mathematics, using
-standard LaTeX syntax. The output formats `sphinx`, `latex`, and `pdflatex`
-work with this syntax while all other formats will just display the
-raw LaTeX code.
+standard LaTeX syntax. The output formats `html`, `sphinx`, `latex`,
+pdflatex`, `pandoc`, and `mwiki` work with this syntax while all other
+formats will just display the raw LaTeX code.
Inline expressions are written in the standard
LaTeX way with the mathematics surrounded by dollar signs, as in
@@ -287,8 +354,7 @@
}}}
That is, the LaTeX expression appears to the left of a vertical bar (pipe
symbol) and the more readable expression appears to the right. Both
-expressions are surrounded by dollar signs. Plain text formats and HTML
-will applied the expression to the right.
+expressions are surrounded by dollar signs.
Blocks of LaTeX mathematics are written within
`!bt`
@@ -298,19 +364,17 @@
{{{
!bt
\begin{align*}
-\nabla\cdot \pmb{u} &= 0,\\
+\nabla\cdot \pmb{u} &= 0,\\
\nabla\times \pmb{u} &= 0.
\end{align*}
!et
}}}
-<wiki:comment> Note: !bt and !et (and !bc and !ec below) are used to
illustrate </wiki:comment>
-<wiki:comment> tex and code blocks in inside verbatim blocks and are
replaced </wiki:comment>
-<wiki:comment> by !bt, !et, !bc, and !ec after all other formatting is
finished. </wiki:comment>
+
This LaTeX code gets rendered as
{{{
\begin{align*}
-\nabla\cdot \pmb{u} &= 0,\\
+\nabla\cdot \pmb{u} &= 0,\\
\nabla\times \pmb{u} &= 0.
\end{align*}
}}}
@@ -326,27 +390,20 @@
{{{
\[ \frac{\partial\pmb{u}}{\partial t} + \pmb{u}\cdot\nabla\pmb{u} = 0.\]
}}}
-
-One can use `#if FORMAT in
("latex", "pdflatex", "html", "sphinx", "mwiki")`
-to let the preprocessor choose a block of mathematics in LaTeX format
-or (`#else`) a modified form more suited for plain text and wiki
-formats without support for mathematics.
Any LaTeX syntax is accepted, but if output in the `sphinx`, `pandoc`,
-`mwiki`, or `html` formats
-is important, one must know that these formats does not support many
-LaTeX constructs. For output both in `latex` or `pdflatex` *and*
-the mentioned formats with LaTeX support,
-the following rules are recommended:
+`mwiki`, `html`, or `ipynb` formats
+is also important, one should follow these rules:
* Use only the equation environments `\[`, `\]`, `equation`,
`equation*`, `align`, and `align*`.
- * Labels in multiple equation environments such as `align` are not
(yet) handled by `pandoc`.
* MediaWiki (`mwiki`) does not support references to equations.
+(Doconce performs extensions to `sphinx` and other formats such that
+labels in `align` environments work well.)
-
-*Notice.* LaTeX supports lots of fancy formatting, for example, multiple
+*Notice.*
+LaTeX supports lots of fancy formatting, for example, multiple
plots in the same figure, footnotes, margin notes, etc.
Allowing other output formats, such as `sphinx`, makes it necessary
to only utilze very standard LaTeX and avoid, for instance, more than
@@ -357,7 +414,17 @@
also allow advanced LaTeX features and fine tuning of resulting
PDF document.
-*LaTeX Newcommands.* Text missing...
+*LaTeX Newcommands.* The author can define `newcommand` statements in
files with names
+`newcommands*.tex`. Such commands should only be used for mathematics
+(other LaTeX constructions are only understood by LaTeX itself).
+The convention is that `newcommands_keep.tex`
+contains the newcommands that are kept in the document, while
+those in `newcommands_replace.tex` will be replaced by their full
+LaTeX code. This conventions helps make readable documents in formats
+without LaTeX support. For `html`, `sphinx`, `latex`, `pdflatex`,
+`mwiki`, `ipynb`, and `pandoc`, the mathematics in newcommands is
+rendered nicely anyway.
+
==== Figures and Movies ====
@@ -368,28 +435,42 @@
MOVIE: [relative/path/to/moviefile, width=500] Here goes the caption which
must be on a single line. label{some:fig:label}
}}}
-Note the mandatory comma after the figure/movie file.
+Note three important syntax details:
+
+
+ # A mandatory comma after the figure/movie filename,
+ # all of the command must appear on a single line,
+ # there must be a blank line after the command.
The figure file can be listed without extension. Doconce will then find
the version of the file with the most appropriate extension for the chosen
output format. If not suitable version is found, Doconce will convert
-another format to the desired one.
+another format to the needed one.
Movie files can either be a video or a wildcard expression for a
series of frames. In the latter case, a simple device in an HTML page
will display the individual frame files as a movie.
Combining several image files into one can be done by the
-`convert` and `montage` programs from the ImageMagick suite:
{{{
-montage file1.png file2.png ... file4.png -geometry +2+2 result.png
-montage file1.png file2.png -tile x1 result.png
-montage file1.png file2.png -tile 1x result.png
+doconce combine_images image1 image2 ... output_image
+}}}
+This command applies `montage` or PDF-based tools to combine the images
+to get the highest quality.
-convert -background white file1.png file2.png +append tmp.png
+YouTube and Vimeo movies will be embedded in `html` and `sphinx` documents
+and otherwise be represented by a link. The syntax is
+
+{{{
+MOVIE: [http://www.youtube.com/watch?v=_O7iUiftbKU, width=420 height=315]
YouTube movie.
+
+MOVIE: [http://vimeo.com/55562330, width=500 height=278] Vimeo movie.
+
}}}
-Use `+append` for stacking left to right, `-append` for top to bottom.
-The positioning of the figures can be controlled by `-gravity`.
+The latter results in
+
+ Vimeo movie. http://vimeo.com/55562330
+
==== Tables ====
@@ -416,16 +497,22 @@
* If the horizontal rules are without alignment information there
should be no vertical bar (pipe symbol) between the columns. Otherwise,
such a bar indicates a vertical bar between columns in LaTeX.
* Many output formats are so primitive that heading and column
alignment have no effect.
-==== Labels, References, Citations, and Index ====
+The command-line option `--tables2csv` (to `doconce format`)
+makes Doconce dump each table to CSV format in a file `table_X.csv`,
+where `X` is the table number. This feature makes it easy to
+load tables into spreadsheet programs for further analysis.
-The notion of labels, references, citations, and an index is adopted
+==== Labels and References ====
+
+The notion of labels and references (as well as bibliography and index)
+is adopted
from LaTeX with a very similar syntax. As in LaTeX, a label can be
inserted anywhere, using the syntax
{{{
label{name}
}}}
with no backslash
-preceding the label keyword! It is common practice to choose `name`
+preceding the label keyword. It is common practice to choose `name`
as some hierarchical name, say `a:b:c`, where `a` and `b` indicate
some abbreviations for a section and/or subsection for the topic and
`c` is some name for the particular unit that has a label.
@@ -436,6 +523,13 @@
}}}
again with no backslash before `ref`.
+Use labels for sections and equations only, and preceed the reference
+by "Section" or "Chapter", or in case of an equation, surround the
+reference by parenthesis.
+
+
+==== Citations and Bibliography ====
+
Single citations are written as
{{{
cite{name}
@@ -451,20 +545,22 @@
cite{name1,name2,name3}
}}}
-The bibliography is specified by a line `BIBFILE: name_bib.bib,
-name_bib.rst, name_bib.py`, where `name` is the logical name of the
-document (the doconce file will then normally have the name
-`name.do.txt`), and the various files reflect different formattings of
-the bibliography: '.bib' indicates a BibTeX file, '.rst' a reST-style
-bibliography, and '.py' a Python list of dictionaries for specifying
-the entries in the bibliography. The bibliography (as read from file)
-is inserted where the `BIBFILE` keyword appears.
+The bibliography is specified by a line `BIBFILE: papers.pub`,
+where `papers.pub` is a publication database in the
+[https://bitbucket.org/logg/publish Publish] format.
+BibTeX `.bib` files can easily be combined to a Publish database
+(which Doconce needs to create bibliographies in other formats
+than LaTeX).
+
+==== Generalized Citations ====
There is a *generalized referencing* feature in Doconce that allows
a reference with `ref` to have one formulation if the label is
in the same document and another formulation if the reference is
-to an item in an external document. The syntax of a generalized
-reference is
+to an item in an external document. This construction makes it easy
+to work with many small, independent documents in parallel with
+a book assembly of some of the small elements.
+The syntax of a generalized reference is
{{{
ref[internal][cite][external]
@@ -486,6 +582,8 @@
documents. If none of the two situations above applies, the
`external` text will be the output.
+==== Index of Keywords ====
+
Doconce supports creating an index of keywords. A certain keyword
is registered for the index by a syntax like (no
backslash!)
@@ -496,10 +594,10 @@
running text, i.e., after (sub)section titles and in the space between
paragraphs. Index specifications placed right before paragraphs also
gives the doconce source code an indication of the content in the
-forthcoming text. The index is only produced for the `latex`, `rst`, and
-`sphinx` formats.
+forthcoming text. The index is only produced for the `latex`,
+`pdflatex`, `rst`, and `sphinx` formats.
-==== Capabilities of the "doconce" Program ====
+==== Capabilities of The Program `doconce` ====
The `doconce` program can be used for a number of purposes besides
transforming a `.do.txt` file to some format. Here is the
@@ -507,7 +605,7 @@
{{{
Usage: doconce command [optional arguments]
-commands: format help sphinx_dir subst replace replace_from_file clean
spellcheck ptex2tex expand_commands combine_images guess_encoding
change_encoding gwiki_figsubst remove_inline_comments grab remove
remove_exercise_answers split_rst split_html slides_html latin2html
latex_header latex_footer bbl2rst html_colorbullets list_labels teamod
sphinxfix_localURLs make_figure_code_links latex_exercise_toc insertdocstr
old2new_format
+commands: format help sphinx_dir subst replace replace_from_file clean
spellcheck ptex2tex expand_commands combine_images guess_encoding
change_encoding gwiki_figsubst md2html remove_inline_comments grab remove
remove_exercise_answers split_rst split_html slides_html slides_beamer
latin2html latex_header latex_footer bbl2rst html_colorbullets list_labels
teamod sphinxfix_localURLs make_figure_code_links latex_exercise_toc
insertdocstr old2new_format latex2doconce latex_dislikes pygmentize
makefile diff gitdiff fix_bibtex4publish csv2table
# transform doconce file to another format
@@ -565,7 +663,10 @@
doconce bbl2rst file.bbl
# split a sphinx/rst file into parts
-doconce split_rst complete_file.rst
+doconce format sphinx complete_file
+doconce split_rst complete_file # !split delimiters
+doconce sphinx_dir complete_file
+python automake_sphinx.py
# edit URLs to local files and place them in _static
doconce sphinxfix_local_URLs file.rst
@@ -573,9 +674,12 @@
# split an html file into parts according to !split commands
doconce split_html complete_file.html
-# create slides from a (doconce) html file
+# create HTML slides from a (doconce) html file
doconce slides_html slide_type complete_file.html
+# create LaTeX Beamer slides from a (doconce) latex/pdflatex file
+doconce slides_beamer complete_file.tex
+
# replace bullets in lists by colored bullets
doconce html_colorbullets file1.html file2.html ...
@@ -585,9 +689,6 @@
# remove selected text from a file
doconce remove --from[-] from-text [--to[-] to-text] somefile
-# remove answers to exercises
-doconce remove_exercise_answers file_in_some_format
-
# run spellcheck on a set of files
doconce spellcheck [-d .mydict.txt] *.do.txt
@@ -595,6 +696,12 @@
# and manage the code environments
doconce ptex2tex mydoc -DMINTED pycod=minted sys=Verbatim \
dat=\begin{quote}\begin{verbatim};\end{verbatim}\end{quote}
+
+# make HTML file via pandoc from Markdown (.md) file
+doconce md2html file
+
+# make LaTeX file via pandoc from Markdown (.md) file
+doconce md2latex file
# expand short cut commands to full form in files
doconce expand_commands file1 file2 ...
@@ -607,6 +714,31 @@
# list all labels in a document (for purposes of cleaning them up)
doconce list_labels myfile
+
+# translate a latex document to doconce (requires usually manual fixing)
+doconce latex2doconce latexfile
+
+# check if there are problems with translating latex to doconce
+doconce latex_dislikes latexfile
+
+# typeset a doconce document with pygments (for pretty print of doconce
itself)
+doconce pygmentize myfile [pygments-style]
+
+# generate a make.sh script for translating a doconce file to various
formats
+doconce makefile docname doconcefile [html sphinx pdflatex ...]
+
+# fix common problems in bibtex files for publish import
+doconce fix_bibtex4publish file1.bib file2.bib ...
+
+# find differences between two files
+doconce diff file1.do.txt file2.do.txt [diffprog]
+(diffprog can be difflib, diff, pdiff, latexdiff, kdiff3, diffuse, ...)
+
+# find differences between the last two Git versions of several files
+doconce gitdiff file1 file2 file3 ...
+
+# convert csv file to doconce table format
+doconce csv2table somefile.csv
}}}
==== Exercises ====
@@ -709,10 +841,11 @@
}}}
By default, answers, solutions, and hints are typeset as paragraphs.
-The command-line arguments `--without-answers` and `--without-solutions`
+The command-line arguments `--without_answers` and `--without_solutions`
turn off output of answers and solutions, respectively, except for
examples.
+
==== Environments ====
Doconce environments start with `!benvirname` and end with `!eenvirname`,
@@ -725,14 +858,11 @@
* `subex`: sub-exercise
* `ans`: short answer to exercise or sub-exercise
* `sol`: full solution to exercise or sub-exercise
- * `notes`: multi-line notes to be included or not
* `quote`: indented text
- * `notice`, `summary`, `warning`, `question`, `hint`: boxes with
specialy typesetting (or symbols)
+ * `notice`, `summary`, `warning`, `question`, `hint`: admonition boxes
with custom title, special icon, and (frequently) background color
* `pop`: text to gradually pop up in slide presentations
* `slidecell`: indication of cells in a grid layout for elements on a
slide
-==== Labels, Index, and Citations ====
-
==== Preprocessing ====
Doconce documents may utilize a preprocessor, either `preprocess` and/or
@@ -754,11 +884,11 @@
\caption{Some words... label{mytab}}
\begin{tabular}{lrr}
\hline\noalign{\smallskip}
-\multicolumn{1}{c}{time} & \multicolumn{1}{c}{velocity} &
\multicolumn{1}{c}{acceleration} \\
+\multicolumn{1}{c}{time} & \multicolumn{1}{c}{velocity} &
\multicolumn{1}{c}{acceleration} \\
\hline
-0.0 & 1.4186 & -5.01 \\
-2.0 & 1.376512 & 11.919 \\
-4.0 & 1.1E+1 & 14.717624 \\
+0.0 & 1.4186 & -5.01 \\
+2.0 & 1.376512 & 11.919 \\
+4.0 & 1.1E+1 & 14.717624 \\
\hline
\end{tabular}
\end{table}
@@ -786,3 +916,4 @@
* Excellent "Sphinx Tutorial" by C.
Reller: "http://people.ee.ethz.ch/~creller/web/tricks/reST.html"
+
=======================================
--- /Tutorial.wiki Sat Feb 23 07:34:38 2013
+++ /Tutorial.wiki Fri Jun 28 09:25:55 2013
@@ -1,10 +1,8 @@
-<wiki:comment> Missing: FIGURE, MOVIE, environments </wiki:comment>
#summary Doconce: Document Once, Include Anywhere
By *Hans Petter Langtangen*
-
-==== Feb 23, 2013 ====
+==== May 29, 2013 ====
* When writing a note, report, manual, etc., do you find it difficult
to choose the typesetting format? That is, to choose between plain
(email-like) text, wiki, Word/OpenOffice, LaTeX, HTML, reStructuredText,
Sphinx, XML, etc. Would it be convenient to start with some very simple
text-like format that easily converts to the formats listed above, and
then at some later stage eventually go with a particular format?
* Do you need to write documents in varying formats but find it
difficult to remember all the typesetting details of various formats like
[http://refcards.com/docs/silvermanj/amslatex/LaTeXRefCard.v2.0.pdf LaTeX],
[http://www.htmlcodetutorial.com/ HTML],
[http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html
reStructuredText], [http://sphinx.pocoo.org/contents.html Sphinx], and
[http://code.google.com/p/support/wiki/WikiSyntax wiki]? Would it be
convenient to generate the typesetting details of a particular format
from a very simple text-like format with minimal tagging?
@@ -13,34 +11,80 @@
If any of these questions are of interest, you should keep on reading.
+== Some Doconce Features ==
+
+
+ * Strong support for texts with much math and code.
+ * Same source can produce a variety of output formats. The following
support LaTeX math and (pygmentized) code:
+
+ #
[http://hplgit.github.com/teamods/writing_reports/_static/report_4printing.pdf
traditional LaTeX B/W documents for printing]
+ # [http://hplgit.github.com/teamods/writing_reports/_static/report.pdf
color LaTeX PDF documents]
+ #
[http://hplgit.github.com/teamods/writing_reports/_static/report_4phone.pdf
color LaTeX PDF documents for viewing on small phones]
+ #
[http://hplgit.github.com/teamods/writing_reports/_static/sphinx-fenics_minimal/report.html
Sphinx HTML documents with 20+ different designs]
+ # [http://hplgit.github.com/teamods/writing_reports/_static/report.html
Plain HTML] or with a
[http://hplgit.github.com/teamods/writing_reports/_static/report_vagrant.html
template] or
[http://hplgit.github.com/teamods/writing_reports/_static/report_github_minimal.html
another template] or
[http://hplgit.github.com/teamods/writing_reports/_static/report_solarized.html
solarized]
+ # HTML for [http://doconce-report-demo.blogspot.no/ Google] or
[http://doconcereportdemo.wordpress.com/ Wordpress] blogs
+ # [http://doconcedemo.shoutwiki.com/wiki/Doconce_demo_page MediaWiki]
(Wikipedia, Wikibooks, etc)
+ # Markdown
+ # IPython notebook
+
+ Other formats include plain untagged text (for email), Creole wiki
(for Bitbucket wikis), Google wiki (for Googlecode), reStructuredText,
and Epytext.
+ * Integration with Mako enables use of variables, functions, if-tests,
and loops to parameterize the text and generate various versions of the
text for different purposes.
+ * Computer code can be copied directly from parts of source code files.
+ * Running text can quickly be edited to slide formats (reveal.js and
deck.js, based on HTML5+CSS3).
+ * Special exercise environments with support for hints, answers,
subexercises, etc.
+ * Automatic inline embedding of YouTube and Vimeo movies.
+ * Good support for admonitions in various LaTeX and HTML styles for
warnings, questions, hints, remarks, summaries, etc.
== What Does Doconce Look Like? ==
-Doconce text looks like ordinary text, but there are some almost invisible
-text constructions that allow you to control the formating. Here are
-som examples.
+Doconce text looks like ordinary text (much like Markdown), but there
+are some almost invisible text constructions that allow you to control
+the formating. Here are some examples.
- * Bullet lists arise from lines starting with `*`.
- * *Emphasized words* are surrounded by `*`.
- * *Words in boldface* are surrounded by underscores.
+ * Bullet lists automatically arise from lines starting with `*`, or
`o` if the list is to be enumerated.
+ * *Emphasized words* are surrounded by `*`. *Words in boldface* are
surrounded by underscores.
* Words from computer code are enclosed in back quotes and then
typeset `verbatim (in a monospace font)`.
- * Section headings are recognied by equality (`=`) signs before and
after the title, and the number of `=` signs indicates the level of the
section: 7 for main section, 5 for subsection, and 3 for subsubsection.
- * Paragraph headings are recognized by a double underscore before and
after the heading.
+ * Section and paragraph headings are recognied special decorating
characters (`=` or `_`) before and after the heading. The length of the
decoration determines the level of the section.
+ * Blocks of computer code are included by surrounding the blocks with
`!bc` (begin code) and `!ec` (end code) tags on separate lines.
+ * Blocks of computer code can also be imported from source files.
+ * Blocks of LaTeX mathematics are included by surrounding the blocks
with `!bt` (begin TeX) and `!et` (end TeX) tags on separate lines.
+ * There is support for both LaTeX and text-like inline mathematics
such that formulas make sense also when not rendered by LaTeX or MathJax.
+ * Figures and movies with captions, simple tables, URLs with links,
index list, labels and references are supported. YouTube and Vimeo
videos are automatically embedded in web documents.
* The abstract of a document starts with *Abstract* as paragraph
heading, and all text up to the next heading makes up the abstract,
- * Blocks of computer code can easily be included by placing `!bc`
(begin code) and `!ec` (end code) commands at separate lines before and
after the code block.
- * Blocks of computer code can also be imported from source files.
- * Blocks of LaTeX mathematics can easily be included by placing `!bt`
(begin TeX) and `!et` (end TeX) commands at separate lines before and
after the math block.
- * There is support for both LaTeX and text-like inline mathematics.
- * Figures and movies with captions, simple tables, URLs with links,
index list, labels and references are supported.
- * Invisible comments in the output format can be inserted throughout
the text.
- * Visible comments can be inserted so that authors and readers can
comment upon the text (and at any time turn on/off output of such
comments).
+ * Special comment lines are not visible in the output.
+ * Comments to authors can be inserted throughout the text and made
visible or invisible as desired.
* There is an exercise environment with many advanced features.
- * With a preprocessor, Preprocess or Mako, one can include other
documents (files) and large portions of text can be defined in or out of
the text.
- * With Mako one can also have Python code embedded in the Doconce
document and thereby parameterize the text (e.g., one text can describe
programming in two languages).
+ * With a preprocessor, Preprocess or Mako, one can include other
documents (files), large portions of text can be defined in or out of
the text, and tailored format-specific constructs can easily be
included. With Mako a single text can output its program examples in two
or more languages.
+
+==== What Can Doconce Be Used For? ====
+
+LaTeX is ideal for articles, thesis, and books, but not so suited
+for web documents. Nice environments for web documents, such as
+Sphinx, Markdown, or plain HTML, are not particularly well
+suited for thesis and books. IPython notebooks are ideal for
+documenting computational experiments, but do not (yet) meet the
+requirements of books and thesis.
+
+What about migrating a part of a book for blogging? What about making
+an MS Word version of parts or an untagged text for inclusion in
+email? What about efficiently generating slides in modern HTML5
+style? Doconce enables all this with just *one source* (the slogan is
+*document once - include anywhere*).
+Doconce also
+has many extra features for supporting documents with much code and
+mathematics, not found in any of the mentioned formats.
+
+==== Basic Syntax ====
Here is an example of some simple text written in the Doconce format:
{{{
+======= First a Section Heading =======
+
+Section headings have 7 equality characters before and after the heading.
+With 9 characters we have a chapter heading, 5 gives a subsection
+heading, and 3 a subsubsection heading.
+
===== A Subsection with Sample Text =====
label{my:first:sec}
@@ -58,9 +102,14 @@
o item 2
o item 3
+__Hyperlinks.__ Paragraph headings are surrounded by double underscores.
URLs with a link word are possible, as in "hpl": "http://folk.uio.no/hpl".
If the word is URL, the URL itself becomes the link name,
-as in "URL": "tutorial.do.txt".
+as in "URL": "tutorial.do.txt". Doconce distinguishes between paper
+and screen output. In traditional paper output, in PDF generated from LaTeX
+generated from Doconce, the URLs of links appear as footnotes.
+With screen output, all links are clickable hyperlinks, except in
+the plain text format which does not support hyperlinks.
References to sections may use logical names as labels (e.g., a
"label" command right after the section title), as in the reference to
@@ -86,6 +135,13 @@
}}}
The Doconce text above results in the following little document:
+
+== First a Section Heading ==
+
+Section headings have 7 equality characters before and after the heading.
+With 9 characters we have a chapter heading, 5 gives a subsection
+heading, and 3 a subsubsection heading.
+
==== A Subsection with Sample Text ====
Ordinary text looks like ordinary text, and the tags used for
@@ -105,18 +161,25 @@
# item 2
# item 3
+*Hyperlinks.* Paragraph headings are surrounded by double underscores.
URLs with a link word are possible, as in [http://folk.uio.no/hpl hpl].
If the word is URL, the URL itself becomes the link name,
-as in tutorial.do.txt.
+as in tutorial.do.txt. Doconce distinguishes between paper
+and screen output. In traditional paper output, in PDF generated from LaTeX
+generated from Doconce, the URLs of links appear as footnotes.
+With screen output, all links are clickable hyperlinks, except in
+the plain text format which does not support hyperlinks.
References to sections may use logical names as labels (e.g., a
"label" command right after the section title), as in the reference to
the section [#A_Subsection_with_Sample_Text].
-Doconce also allows inline comments such as [hpl: here I will make
+Doconce also allows inline comments such as [hpl 1: here I will make
some remarks to the text] for allowing authors to make notes. Inline
comments can be removed from the output by a command-line argument
-(see the section [#From_Doconce_to_Other_Formats] for an example).
+(see the section [#From_Doconce_to_Other_Formats] for an example).
Ordinary comment
+lines start with `#` and are copied to comment lines in the
+output format.
Tables are also supperted, e.g.,
@@ -126,11 +189,13 @@
|| 2.0 || 1.376512 || 11.919 ||
|| 4.0 || 1.1E+1 || 14.717624 ||
+
==== Mathematics and Computer Code ====
Inline mathematics, such as `v = sin(x)`,
allows the formula to be specified both as LaTeX and as plain text.
-This results in a professional LaTeX typesetting, but in other formats
+This results in a professional LaTeX typesetting, but in formats
+not supporting LaTeX mathematics
the text version normally looks better than raw LaTeX mathematics with
backslashes. An inline formula like `v = sin(x)` is
typeset as
@@ -158,19 +223,16 @@
{{{
!bt
\begin{align}
-{\partial u\over\partial t} &= \nabla^2 u + f, label{myeq1}\\
+{\partial u\over\partial t} &= \nabla^2 u + f, label{myeq1}\\
{\partial v\over\partial t} &= \nabla\cdot(q(u)\nabla v) + g
\end{align}
!et
}}}
-<wiki:comment> Note: !bt and !et (and !bc and !ec below) are used to
illustrate </wiki:comment>
-<wiki:comment> tex and code blocks in inside verbatim blocks and are
replaced </wiki:comment>
-<wiki:comment> by !bt, !et, !bc, and !ec after all other formatting is
finished. </wiki:comment>
The result looks like this:
{{{
\begin{align}
-{\partial u\over\partial t} &= \nabla^2 u + f, label{myeq1}\\
+{\partial u\over\partial t} &= \nabla^2 u + f, label{myeq1}\\
{\partial v\over\partial t} &= \nabla\cdot(q(u)\nabla v) + g
\end{align}
}}}
@@ -204,7 +266,7 @@
I = integrate.trapezoidal(myfunc, 0, pi, 100)
}}}
A code block must come after some plain sentence (at least for successful
-output to `sphinx`, `rst`, and ASCII-close formats),
+output to `sphinx`, `rst`, and formats close to plain text),
not directly after a section/paragraph heading or a table.
@@ -219,46 +281,64 @@
trailing `.txt` denotes a text document so that editors gives you
plain text editing capabilities.
+
==== Macros (Newcommands), Cross-References, Index, and Bibliography ====
Doconce supports a type of macros via a LaTeX-style *newcommand*
-construction. The newcommands defined in a file with name
-`newcommand_replace.tex` are expanded when Doconce is filtered to
-other formats, except for LaTeX (since LaTeX performs the expansion
-itself). Newcommands in files with names `newcommands.tex` and
-`newcommands_keep.tex` are kept unaltered when Doconce text is
-filtered to other formats, except for the Sphinx format. Since Sphinx
-understands LaTeX math, but not newcommands if the Sphinx output is
-HTML, it makes most sense to expand all newcommands. Normally, a user
-will put all newcommands that appear in math blocks surrounded by
-`!bt` and `!et` in `newcommands_keep.tex` to keep them unchanged, at
-least if they contribute to make the raw LaTeX math text easier to
-read in the formats that cannot render LaTeX. Newcommands used
-elsewhere throughout the text will usually be placed in
-`newcommands_replace.tex` and expanded by Doconce. The definitions of
-newcommands in the `newcommands*.tex` files *must* appear on a single
-line (multi-line newcommands are too hard to parse with regular
-expressions).
+construction. The newcommands are defined in files with names
+`newcommands*.tex`, using standard LaTeX syntax. Only newcommands
+for use inside math environments are supported.
+
+Labels, corss-references, citations, and support of an index and
+bibliography are much inspired by LaTeX syntax, but Doconce features
+no backslashes. Use labels for sections and equations only, and
+preceed the reference by "Section" or "Chapter", or in case of
+an equation, surround the reference by parenthesis.
+
+Here is an example:
+
+{{{
+===== My Section =====
+label{sec:mysec}
+
+idx{key equation} idx{$\u$ conservation}
+
+We refer to Section ref{sec:yoursec} for background material on
+the *key equation*. Here we focus on the extension
+
+# \Ddt, \u and \mycommand are defined in newcommands_keep.tex
+
+!bt
+\begin{equation}
+\Ddt{\u} = \mycommand{v},
+label{mysec:eq:Dudt}
+\end{equation}
+!et
+where $\Ddt{\u}$ is the material derivative of $\u$.
+Equation (ref{mysec:eq:Dudt}) is important in a number
+of contexts, see cite{Larsen_et_al_2002,Johnson_Friedman_2010a}.
+Also, cite{Miller_2000} supports such a view.
+
+As see in Figure ref{mysec:fig:myfig}, the key equation
+features large, smooth regions *and* abrupt changes.
+
+FIGURE: [fig/myfile, width=600] My figure. label{mysec:fig:myfig}
+
+===== References =====
+
+BIBFILE: papers.pub
+}}}
-Recent versions of Doconce also offer cross referencing, typically one
-can define labels below (sub)sections, in figure captions, or in
-equations, and then refer to these later. Entries in an index can be
-defined and result in an index at the end for the LaTeX and Sphinx
-formats. Citations to literature, with an accompanying bibliography in
-a file, are also supported. The syntax of labels, references,
-citations, and the bibliography closely resembles that of LaTeX,
-making it easy for Doconce documents to be integrated in LaTeX
-projects (manuals, books). For further details on functionality and
+For further details on functionality and
syntax we refer to the `doc/manual/manual.do.txt` file (see the
[https://doconce.googlecode.com/hg/doc/demos/manual/index.html demo page]
for various formats of this document).
-<wiki:comment> Example on including another Doconce file (using
preprocess): </wiki:comment>
+== From Doconce to Other Formats ==
-== From Doconce to Other Formats ==
Transformation of a Doconce document `mydoc.do.txt` to various other
formats applies the script `doconce format`:
@@ -269,6 +349,30 @@
{{{
Terminal> doconce format format mydoc
}}}
+
+==== Generating a makefile ====
+
+Producing HTML, Sphinx, and in particular LaTeX documents from
+Doconce sources requires a few commands. Often you want to
+produce several different formats. The relevant commands should
+then be placed in a script that acts as a "makefile".
+
+The `doconce makefile` can be used to automatically generate
+such a makefile, more precisely a Bash script `make.sh`, which
+carries out the commands explained below. If our Doconce source
+is in `main_myproj.do.txt`, we run
+
+{{{
+doconce makefile main_myproj html pdflatex sphinx
+}}}
+to produce the necessary output for generating HTML, pdfLaTeX, and
+Sphinx. Usually, you need to edit `make.sh` to really fit your
+needs. Some examples lines are inserted as comments to show
+various options that can be added to the basic commands.
+A handy feature of the generated `make.sh` script is that it
+inserts checks for successful runs of the `doconce format` commands,
+and if something goes wrong, the `make.sh` exits.
+
==== Preprocessing ====
@@ -287,9 +391,7 @@
==== Removal of inline comments ====
-<wiki:comment> mention notes also </wiki:comment>
-
-The command-line arguments `--no-preprocess` and `--no-mako` turn off
+The command-line arguments `--no_preprocess` and `--no_mako` turn off
running `preprocess` and `mako`, respectively.
Inline comments in the text are removed from the output by
@@ -304,6 +406,25 @@
This action is convenient when a Doconce document reaches its final form
and comments by different authors should be removed.
+==== Notes ====
+
+Doconce does not have a tag for longer notes, because implementation
+of a "notes feature" is so easy using the `preprocess` or `mako`
+programs. Just introduce some variable, say `NOTES`, that you define
+through `-DNOTES` (or not) when running `doconce format ...`. Inside
+the document you place your notes between `# #ifdef NOTES` and
+`# #endif` preprocess tags. Alternatively you use `% if NOTES:`
+and `% endif` that `mako` will recognize. In the same way you may
+encapsulate unfinished material, extra material to be removed
+for readers but still nice to archive as part of the document for
+future revisions.
+
+==== Demo of different formats ====
+
+A simple scientific report is available in
[http://hplgit.github.com/teamods/writing_reports/doconce_commands.html a
lot of different formats].
+How to create the different formats is explained in more depth
+in the coming sections.
+
==== HTML ====
Making an HTML version of a Doconce file `mydoc.do.txt`
@@ -319,7 +440,7 @@
An external CSS file `filename` used by setting the command-line
argument `--css=filename`. There available built-in styles are
-specified as `--html-style=name`, where `name` can be
+specified as `--html_style=name`, where `name` can be
* `solarized`: the famous [http://ethanschoonover.com/solarized
solarized] style (yellowish),
@@ -340,56 +461,91 @@
If the Pygments package (including the `pygmentize` program)
is installed, code blocks are typeset with
-aid of this package. The command-line argument `--no-pygments-html`
+aid of this package. The command-line argument `--no_pygments_html`
turns off the use of Pygments and makes code blocks appear with
-plain (`pre`) HTML tags. The option `--pygments-html-linenos` turns
+plain (`pre`) HTML tags. The option `--pygments_html_linenos` turns
on line numbers in Pygments-formatted code blocks. A specific
-Pygments style is set by `--pygments-html-style=style`, where `style`
+Pygments style is set by `--pygments_html_style=style`, where `style`
can be `default`, `emacs`, `perldoc`, and other valid names for
Pygments styles.
-The HTML file can be embedded in a template if the Doconce document
-does not have a title (because then there will be
-no header and footer in the HTML file). The template file must contain
+The HTML file can be embedded in a template with your own tailored
+design, see a [
https://doconce.googlecode.com/hg/doc/design/wrapper_tech.html tutorial] on
this topic. The template file must contain
valid HTML code and can have three "slots": `%(title)s` for a title,
-`%(date)s` for a date, and `%(main)s` for the main body of text, i.e., the
+`%(date)s` for a date, and `%(main)s` for the main body of text. The
+latter is the
Doconce document translated to HTML. The title becomes the first
-heading in the Doconce document, and the date is extracted from the
-`DATE:` line, if present. With the template feature one can easily embed
-the text in the look and feel of a website. The template can be extracted
-from the source code of a page at the site; just insert `%(title)s` and
-`%(date)s` at appropriate places and replace the main bod of text
-by `%(main)s`. Here is an example:
+heading in the Doconce document, or the title (but a title is not
+recommended when using templates). The date is extracted from the
+`DATE:` line. With the template feature one can easily embed
+the text in the look and feel of a website. Doconce comes with
+two templates in `bundled/html_styles`. Just copy the directory
+containing the template and the CSS and JavaScript files to your
+document directory, edit the template as needed (also check that
+paths to the `css` and `js` subdirectories are correct - according
+to how you store the template files), and run
{{{
-Terminal> doconce format html mydoc --html-template=mytemplate.html
+Terminal> doconce format html mydoc --html_template=mytemplate.html
}}}
+The template in `style_vagrant` also needs an extra option
+`--html_style=vagrant`. With this style, one has nice navigation buttons
+that are used if the document contains `!split` commands for splitting
+it into many pages.
-==== Blogs ====
-Doconce can be used for writing blogs provided the blog site accepts
+==== Blog Posts ====
+
+Doconce can be used for writing blog posts provided the blog site accepts
raw HTML code. Google's Blogger service (`blogger.com` or
-`blogname.blogspot.com`)
-is particularly well suited since it also allows extensive LaTeX
mathematics via
-MathJax.
-Write the blog text as a Doconce document without any title, author, and
-date. Then generate HTML as described above. Copy the text and paste it
-into the text area in the blog, making sure the input format is HTML.
-On Google's Blogger service you can use Doconce to generate blogs with
-LaTeX mathematics and pretty (pygmentized) blocks of computer code.
-See a [http://doconce.blogspot.no blog example] for details on blogging.
+`blogname.blogspot.com`) is particularly well suited since it also
+allows extensive LaTeX mathematics via MathJax.
+
+
+# Write the blog text as a Doconce document without any title, author,
and date.
+# Generate HTML as described above.
+# Copy the text and paste it into the text area in the blog (just delete
the HTML code that initially pops up in the text area). Make sure the
input format is HTML.
+
+See a [http://doconce.blogspot.no simple blog example] and
+a [http://doconce-report-demo.blogspot.no/ scientific report]
+for demonstrations of blogs at `blogspot.no`.
+
+*Warning.*
+In the readers' comments after the blog one cannot paste raw HTML
+code with MathJax
+scripts so there is no support for mathematics in the discussion forum.
+*Notice.*
+Figure files must be uploaded to some web site and the filenames name must
+be replaced by the relevant URL. This can be automatically edited:
+{{{
+cp mydoc.do.txt mydoc2.do.txt
+url="https//raw.github.com/someuser/someuser.github.com"
+dir="master/project/dir1/dir2"
+for figname in fig1 fig2 fig3; do
+ doconce replace "[$figname," "[$site/$dir/$figname.png," \
+ mydoc2.do.txt
+done
+doconce format html mydoc2
+# Paste mydoc2.html into a new blog page
+}}}
-*Warning.* In the comments after the blog one cannot paste raw HTML code
with MathJax
-scripts so there is no support for mathematics in the comments.
+Blog posts at Google can also be published
[http://support.google.com/blogger/bin/answer.py?hl=en&answer=41452
automatically through email].
+A Python program can send the contents of the HTML file
+to the blog's email address using the packages `smtplib` and `email`.
WordPress (`wordpress.com`) allows raw HTML code in blogs,
but has very limited
LaTeX support, basically only formulas. The `--wordpress` option to
`doconce` modifies the HTML code such that all equations are typeset
in a way that is acceptable to WordPress.
-There is a [http://doconce.wordpress.com doconce example]
-on blogging with mathematics and code on WordPress.
+Look at a [http://doconce.wordpress.com simple doconce example]
+and a [http://doconcereportdemo.wordpress.com/ scientific report]
+to see blogging with mathematics and code on WordPress.
+
+Speaking of WordPress, the related project http://pressbooks.com can take
raw HTML code (from Doconce, for
+instance) and produce very nice-looking books. There is no support
+for mathematics in the text, though.
==== Pandoc and Markdown ====
@@ -407,13 +563,21 @@
Pandoc pass raw HTML or LaTeX to the output format instead of ignoring it,
while the `--toc` option generates a table of contents.
See the [http://johnmacfarlane.net/pandoc/README.html Pandoc documentation]
-for the many features of the `pandoc` program.
+for the many features of the `pandoc` program. The HTML output from
+`pandoc` needs adjustments to provide full support for MathJax LaTeX
+mathematics, and for this purpose one should use `doconce md2html`:
+
+{{{
+Terminal> doconce format pandoc mydoc
+Terminal> doconce m2html mydoc
+}}}
+The result `mydoc.html` can be viewed in a browser.
-Pandoc is useful to go from LaTeX mathematics to, e.g., HTML or MS Word.
-There are two ways (experiment to find the best one for your document):
-`doconce format pandoc` and then translating using `pandoc`, or
-`doconce format latex`, and then going from LaTeX to the desired format
-using `pandoc`.
+Pandoc is useful to go from LaTeX mathematics to, e.g., HTML or MS
+Word. There are two ways (experiment to find the best one for your
+document): `doconce format pandoc` and then translating using `doconce
+md2latex` (which runs `pandoc`), or `doconce format latex`, and then
+going from LaTeX to the desired format using `pandoc`.
Here is an example on the latter strategy:
{{{
Terminal> doconce format latex mydoc
@@ -421,8 +585,8 @@
Terminal> doconce replace '\Verb!' '\verb!' mydoc.tex
Terminal> pandoc -f latex -t docx -o mydoc.docx mydoc.tex
}}}
-When we go through `pandoc`, only single equations or `align*`
-environments are well understood.
+When we go through `pandoc`, only single equations, `align`, or `align*`
+environments are well understood for output to HTML.
Note that Doconce applies the `Verb` macro from the `fancyvrb` package
while `pandoc` only supports the standard `verb` construction for
@@ -442,6 +606,7 @@
The `-s` option adds a proper header and footer to the `mydoc.html` file.
This recipe is a quick way of makeing HTML notes with (some) mathematics.
+
==== LaTeX ====
Making a LaTeX file `mydoc.tex` from `mydoc.do.txt` is done in two steps:
@@ -460,7 +625,7 @@
If these files are present, they are included in the LaTeX document
so that your commands are defined.
-An option `--latex-printed` makes some adjustments for documents
+An option `--latex_printed` makes some adjustments for documents
aimed at being printed. For example, links to web resources are
associated with a footnote listing the complete web address (URL).
@@ -491,17 +656,23 @@
Preprocessor variables to be defined or undefined are
- * `BOOK` for the "book" documentclass rather than the
standard "article" class (necessary if you apply chapter headings)
+ * `XELATEX` for processing by `xelatex`
* `PALATINO` for the Palatino font
- * `HELVETIA` for the Helvetica font
+ * `HELVETICA` for the Helvetica font
* `A4PAPER` for A4 paper size
- * `A6PAPER` for A6 paper size (suitable for reading on small devices)
- * `MOVIE15` for using the movie15 LaTeX package to display movies
- * `PREAMBLE` to turn the LaTeX preamble on or off (i.e., complete
document or document to be included elsewhere)
- * `MINTED` for inclusion of the minted package (which requires `latex`
or `pdflatex` to be run with the `-shell-escape` option)
+ * `A6PAPER` for A6 paper size (suitable for reading PDFs on phones)
+ * `MOVIE` for specifying how movies are handled: the value `media9`
implies the `media9` package and the `\includemedia` command (default),
while other values are `movie15` (`\includemovie` command), `multimedia`
(for Beamer-style `\movie` command), or `href-run` (for the plain
`\hrun:file` command)
+ * `PREAMBLE` to turn the LaTeX preamble on or off (i.e., complete
document or document to be included elsewhere - and note that the
preamble is only included if the document has a title, author, and date)
+ * `MINTED` for inclusion of the minted package for typesetting of code
with the Pygments tool (which requires `latex` or `pdflatex` to be run
with the `-shell-escape` option)
+ * `TODONOTES` for using the fancy `todonotes` package for typesetting
inline comments (looks much like track changes in MS Word). This macro
has only effect if inline comments are used (name, colon, and comment
inside brackets).
+ * `LINENUMBERS` for inclusion of line numbers in the text.
+ * `AMON` for setting the type of admonitions: `"colors"` for colored
boxes with icons, `"graybox1"` for gray frame boxes with rounded corners
(default), `"graybox2"` for narrower square gray frame boxes (except for
summary, which for A4 format is small and with wrapped text around if it
does not contain verbatim code), or `"paragraph"` for simple, plain
paragraph headings and ordinary text
+ * `COLORED_TABLE_ROWS` for coloring every other table rows (set this
variable to `gray` or `blue`)
+ * `BLUE_SECTION_HEADINGS` for blue section and subsection headings
+ * `LATEX_HEADING` for the typesetting of the title, author, parts of
preamble (values: `traditional` for traditional LaTeX heading,
`titlepage` for a separate titlepage, `Springer_collection` for edited
volumes on Springer, `beamer` for Beamer slides, `doconce_heading`
(default) for listing institutions after names)
If you are not satisfied with the Doconce preamble, you can provide
-your own preamble by adding the command-line option
`--latex-preamble=myfile`.
+your own preamble by adding the command-line option
`--latex_preamble=myfile`.
In case `myfile` contains a documentclass definition, Doconce assumes
that the file contains the *complete* preamble you want (not that all
the packages listed in the default preamble are required and must be
@@ -521,9 +692,9 @@
for processing the `.p.tex` file. The command allows specifications
of code environments as well. Here is an example:
{{{
-Terminal> doconce ptex2tex mydoc -DLATEX_HEADING=traditional \
- -DPALATINO -DA6PAPER \
- "sys=\begin{quote}\begin{verbatim}@\end{verbatim}\end{quote}" \
+Terminal> doconce ptex2tex mydoc -DLATEX_HEADING=traditional \
+ -DPALATINO -DA6PAPER \
+ "sys=\begin{quote}\begin{verbatim}@\end{verbatim}\end{quote}" \
fpro=minted fcod=minted shcod=Verbatim envir=ans:nt
}}}
Note that `@` must be used to separate the begin and end LaTeX
@@ -544,16 +715,24 @@
edited with the aid of the `doconce replace` and `doconce subst`
commands. The former works with substituting text directly, while the
latter performs substitutions using regular expressions.
-Here are two examples:
+You will use `doconce replace` to edit `section{` to `section*{`:
{{{
Terminal> doconce replace 'section{' 'section*{' mydoc.tex
-Terminal> doconce subst 'title\{(.+)Using (.+)\}' \
+}}}
+For fixing the line break of a title, you may pick a word in the
+title, say "Using", and insert a break after than word. With
+`doconce subst` this is easy employing regular expressions with
+a group before "Using" and a group after:
+
+{{{
+Terminal> doconce subst 'title\{(.+)Using (.+)\}' \
'title{\g<1> \\\\ [1.5mm] Using \g<2>' mydoc.tex
}}}
A lot of tailored fixes to the LaTeX document can be done by
an appropriate set of text replacements and regular expression
substitutions. You are anyway encourged to make a script for
-generating PDF from the LaTeX file.
+generating PDF from the LaTeX file so the `doconce subst` or
+`doconce replace` commands can be put inside the script.
*Step 3.* Compile `mydoc.tex`
and create the PDF file:
@@ -589,6 +768,7 @@
specifications with `doconce ptex2tex`), the minted package is
automatically
included so there is no need for the `-DMINTED` option.
+
==== PDFLaTeX ====
Running `pdflatex` instead of `latex` follows almost the same steps,
@@ -603,6 +783,19 @@
Terminal> bibitem mydoc # if bibliography
Terminal> pdflatex -shell-escape mydoc
}}}
+
+==== XeLaTeX ====
+
+XeLaTeX is an alternative to pdfLaTeX and is run in almost the
+same way, except for the `-DXELATEX` flag to ptex2tex:
+
+{{{
+Terminal> doconce format pdflatex mydoc
+Terminal> doconce ptex2tex mydoc -DXELATEX
+Terminal> ptex2tex -DXELATEX mydoc # alternative
+Terminal> xelatex mydoc
+}}}
+
==== Plain ASCII Text ====
@@ -663,8 +856,8 @@
Sphinx documents demand quite some steps in their creation. We have
automated
most of the steps through the `doconce sphinx_dir` command:
{{{
-Terminal> doconce sphinx_dir author="authors' names" \
- title="some title" version=1.0 dirname=sphinxdir \
+Terminal> doconce sphinx_dir author="authors' names" \
+ title="some title" version=1.0 dirname=sphinxdir \
theme=mytheme file1 file2 file3 ...
}}}
The keywords `author`, `title`, and `version` are used in the headings
@@ -688,40 +881,119 @@
`automake_sphinx.py` for compiling the Sphinx document into an HTML
document. One can either run `automake_sphinx.py` or perform the
steps in the script manually, possibly with necessary modifications.
-You should at least read the script prior to executing it to have
-some idea of what is done.
+Normally, executing the script works well, but if you are new
+to Sphinx and end up producing quite some Sphinx documents, I encourave
+you to read the Sphinx documentation and study the `automake_sphinx.py`
+file.
-The `doconce sphinx_dir` script copies directories named `figs` or
-`figures` over to the Sphinx directory so that figures are accessible
-in the Sphinx compilation. If figures or movies are located in other
-directories, `automake_sphinx.py` must be edited accordingly. Files,
-to which there are local links (not `http:` or `file:` URLs), must be
-placed in the `_static` subdirectory of the Sphinx directory. The
-utility `doconce sphinxfix_localURLs` is run to check for local links
-in the Doconce file: for each such link, say `dir1/dir2/myfile.txt` it
-replaces the link by `_static/myfile.txt` and copies
-`dir1/dir2/myfile.txt` to a local `_static` directory (in the same
-directory as the script is run). However, we recommend instead that
-the writer of the document places files in `_static` or lets a script
-do it automatically. The user must copy all `_static/*` files to the
-`_static` subdirectory of the Sphinx directory. It may be wise to
-always put files, to which there are local links in the Doconce
-document, in a `_static` or `_static-name` directory and use these
-local links. Then links do not need to be modified when creating a
-Sphinx version of the document.
+*Links.* The `automake_sphinx.py` script copies directories named `fig*`
+over to the Sphinx directory so that figures are accessible
+in the Sphinx compilation. It also examines `MOVIE:` and `FIGURE:`
+commands in the Doconce file to find other image files and copies
+these too. I strongly recommend to put files
+to which there are local links (not `http:` or `file:` URLs) in
+a directory named `_static`. The `automake_sphinx.py` copies
+`_static*` to the Sphinx directory, which guarantees that the links
+to the local files will work in the Sphinx document.
-Doconce comes with a collection of HTML themes for Sphinx documents.
-These are packed out in the Sphinx directory, the `conf.py`
-configuration file for Sphinx is edited accordingly, and a script
+There is a utility `doconce sphinxfix_localURLs` for checking links to
+local files and moving the files to `_static` and changing the links
+accordingly. For example, a link to `dir1/dir2/myfile.txt` is changed
+to `_static/myfile.txt` and `myfile.txt` is copied to `_static`.
+However, I recommend instead that you manually copy
+files to `_static` when you want to link to them, or let your
+script which compiles the Doconce document do it automatically.
+
+*Themes.* Doconce comes with a rich collection of HTML themes for Sphinx
documents,
+much larger than what is found in the standard Sphinx distribution.
+Additional themes include
+`agni`,
+`basicstrap`,
+`bootstrap`,
+`cloud`,
+`fenics`,
+`fenics_minimal`,
+`flask`,
+`haiku`,
+`impressjs`,
+`jal`,
+`pylons`,
+`redcloud`,
+`scipy_lectures`,
+`slim-agogo`, and
+`vlinux-theme`.
+
+All the themes are packed out in the Sphinx directory, and the
+`doconce sphinx_dir` insert lots of extra code in the `conf.py`
+file to enable easy specification and customization of themes.
+For example, modules are loaded for the additional themes that
+come with Doconce, code is inserted to allow customization of
+the look and feel of themes, etc. The `conf.py` file is a
+good starting point for fine-tuning your favorite team, and your
+own `conf.py` file can later be supplied and used when running
+`doconce sphinx_dir`: simply add the command-line option
+`conf.py=conf.py`.
+
+A script
`make-themes.sh` can make HTML documents with one or more themes.
For example,
-to realize the themes `fenics` and `pyramid`, one writes
+to realize the themes `fenics`, `pyramid`, and `pylon` one writes
{{{
-Terminal> ./make-themes.sh fenics pyramid
+Terminal> ./make-themes.sh fenics pyramid pylon
}}}
The resulting directories with HTML documents are `_build/html_fenics`
and `_build/html_pyramid`, respectively. Without arguments,
-`make-themes.sh` makes all available themes (!).
+`make-themes.sh` makes all available themes (!). With `make-themes.sh`
+it is easy to check out various themes to find the one that is most
+attractive for your document.
+
+You may supply your own theme and avoid copying all the themes
+that come with Doconce into the Sphinx directory. Just specify
+`theme_dir=path` on the command line, where `path` is the relative
+path to the directory containing the Sphinx theme. You must also
+specify a configure file by `conf.py=path`, where `path` is the
+relative path to your `conf.py` file.
+
+*Example.* Say you like the `scipy_lectures` theme, but you want
+a table of contents to appear *to the right*, much in the same style
+as in the `default` theme (where the table of contents is to the left).
+You can then run `doconce sphinx_dir`, invoke a text editor with the
+`conf.py` file, find the line `html_theme == 'scipy_lectures'`,
+edit the following `nosidebar` to `false` and `rightsidebar` to `true`.
+Alternatively, you may write a little script using `doconce replace`
+to replace a portion of text in `conf.py` by a new one:
+
+{{{
+doconce replace "elif html_theme == 'scipy_lectures':
+ html_theme_options = {
+ 'nosidebar': 'true',
+ 'rightsidebar': 'false',
+ 'sidebarbgcolor': '#f2f2f2',
+ 'sidebartextcolor': '#20435c',
+ 'sidebarlinkcolor': '#20435c',
+ 'footerbgcolor': '#000000',
+ 'relbarbgcolor': '#000000',
+ }" "elif html_theme == 'scipy_lectures':
+ html_theme_options = {
+ 'nosidebar': 'false',
+ 'rightsidebar': 'true',
+ 'sidebarbgcolor': '#f2f2f2',
+ 'sidebartextcolor': '#20435c',
+ 'sidebarlinkcolor': '#20435c',
+ 'footerbgcolor': '#000000',
+ 'relbarbgcolor': '#000000',
+ }" conf.py
+}}}
+Obviously, we could also have changed colors in the edit above.
+The final alternative is to save the edited `conf.py` file somewhere
+and reuse it the next time `doconce sphinx_dir` is run
+
+{{{
+doconce sphinx_dir theme=scipy_lectures \
+ conf.py=../some/path/conf.py mydoc
+}}}
+
+==== The manual Sphinx procedure ====
If it is not desirable to use the autogenerated scripts explained
above, here is the complete manual procedure of generating a
@@ -811,6 +1083,7 @@
(`code-block:: python` in Sphinx syntax) and `cppcod` gives C++, but
all such arguments can be customized both for Sphinx and LaTeX output.
+
==== Wiki Formats ====
There are many different wiki formats, but Doconce only supports three:
@@ -868,11 +1141,12 @@
format(s). The `make.sh` files in `docs/manual` and `docs/tutorial`
constitute comprehensive examples on how such scripts can be made.
+
==== Demos ====
The current text is generated from a Doconce format stored in the file
{{{
-docs/tutorial/tutorial.do.txt
+doc/tutorial/tutorial.do.txt
}}}
The file `make.sh` in the `tutorial` directory of the
Doconce source code contains a demo of how to produce a variety of
@@ -891,6 +1165,11 @@
== Installation of Doconce and its Dependencies ==
+Below, we explain the manual installation of all software that may be
+needed when working with Doconce documents.
+The impatient way to install what is needed is to run the
+[doconce_install_all.sh `doconce_install_all.sh`] script.
+
==== Doconce ====
Doconce itself is pure Python code hosted at
http://code.google.com/p/doconce. Its installation from the
@@ -912,21 +1191,18 @@
sudo python setup.py install
}}}
-Debian GNU/Linux users can also run
-{{{
-sudo apt-get install doconce
-}}}
-This installs the latest release and not the most updated and bugfixed
-version.
-On Ubuntu one needs to run
-{{{
-sudo add-apt-repository ppa:scitools/ppa
-sudo apt-get update
-sudo apt-get install doconce
-}}}
==== Dependencies ====
+Producing HTML documents, plain text, pandoc-extended Markdown,
+and wikis can be done without installing any other
+software. However, if you want other formats as output
+(LaTeX, Sphinx, reStructuredText) and assisting utilities such
+as preprocesors, spellcheck, file differences, bibliographies,
+and so on, the software below must be installed.
+
+<wiki:comment> Make a debpkg_doconce.txt file with everything that is
needed on Debian </wiki:comment>
+
==== Preprocessors ====
If you make use of the [http://code.google.com/p/preprocess Preprocess]
@@ -981,6 +1257,13 @@
{{{
sudo apt-get install texlive-extra-utils
}}}
+
+Automatic image conversion from EPS to PDF calls up `epstopdf`, which
+can be installed by
+
+{{{
+sudo apt-get install texlive-font-utils
+}}}
==== Spellcheck ====
@@ -990,6 +1273,25 @@
{{{
sudo apt-get install ispell
}}}
+
+
+==== Bibliography ====
+
+The Python package [https://bitbucket.org/logg/publish Publish] is needed
if you use a bibliography
+in your document. On the website, click on *Clone*, copy the
+command and run it:
+
+{{{
+hg clone https://bitbucket.org/logg/publish
+}}}
+Thereafter go to the `publish` directory and run the `setup.py` script
+for installing Publish:
+
+{{{
+cd publish
+sudo python setup.py
+}}}
+
==== Ptex2tex for LaTeX Output ====
@@ -1015,7 +1317,7 @@
are also needed. These are installed by
{{{
-sudo apt-get install texlive-latex-recommended texlive-latex-extra
+sudo apt-get install texlive
}}}
on Debian Linux (including Ubuntu) systems. TeXShop on Mac comes with
the necessary stylefiles (if not, they can be found by googling and
installed
@@ -1038,17 +1340,70 @@
cd pygments
sudo python setup.py install
}}}
+One can also do the simple
+
+{{{
+pip install sphinx
+}}}
+which also installs pygments.
If you use the minted style together with `ptex2tex`, you have to
enable it by the `-DMINTED` command-line argument to `ptex2tex`.
This is not necessary if you run the alternative `doconce ptex2tex`
program.
-All
-use of the minted style requires the `-shell-escape` command-line
+All use of the minted style requires the `-shell-escape` command-line
argument when running LaTeX, i.e., `latex -shell-escape` or `pdflatex
-shell-escape`.
-<wiki:comment> Say something about anslistings.sty </wiki:comment>
+Inline comments apply the `todonotes` LaTeX package if the `ptex2tex`
+or `doconce ptex2tex` command is run with `-DTODONOTES`. The
+`todonotes` package requires several other packages: `xcolor`,
+`ifthen`, `xkeyval`, `tikz`, `calc`, `graphicx`, and `setspace`. The
+relevant Debian packages for installing all this are listed below.
+
+==== LaTeX packages ====
+
+Many LaTeX packages are potentially needed (depending on various
+preprocessor variables given to `ptex2tex` or `doconce ptex2tex`. The
+standard packages always included are `relsize`, `epsfig`, `makeidx`,
+`setspace`, `color`, `amsmath`, `amsfonts`, `xcolor`, `bm`,
+`microtype`, `titlesec`, and `hyperref`. The `ptex2tex` package (from
+[http://code.google.com/p/ptex2tex ptex2tex]) is also included, but
+removed again if `doconce ptex2tex` is run instead of the `ptex2tex`
+program, meaning that if you do not use `ptex2tex`, you do not need
+`ptex2tex.sty`. Optional packages that might be included are `minted`,
+`fontspec`, `xunicode`, `inputenc`, `helvet`, `mathpazo`, `wrapfig`,
+`calc`, `ifthen`, `xkeyval`, `tikz`, `graphicx`, `setspace`, `shadow`,
+`disable`, `todonotes`, `lineno`, `xr`, `framed`, `mdframe`,
+`movie15`, `a4paper`, and `a6paper`.
+
+Relevant Debian packages that gives you all of these LaTeX packages are
+
+{{{
+texlive
+texlive-extra-utils
+texlive-latex-extra
+texlive-font-utils
+}}}
+On old Ubuntu 12.04 one has to do `sudo add-apt-repository
ppa:texlive-backports/ppa` and `sudo apt-get update` first, or
alternatively install these as well:
+
+{{{
+texlive-math-extra
+texlive-bibtex-extra
+texlive-xetex
+texlive-humanities
+texlive-pictures
+}}}
+Alternatively, one may pull in `texlive-full` to get all available
+style files.
+
+If you want to use the *anslistings* code environment with `ptex2tex`
+(`.ptex2tex.cfg` styles `Python_ANS`, `Python_ANSt`, `Cpp_ANS`, etc.) or
***The diff for this file has been truncated for email.***
Branch: default
Author: "Hans Petter Langtangen <h...@simula.no>"
Date: Fri Jun 28 09:25:55 2013
Log: updates
http://code.google.com/p/doconce/source/detail?r=05c2965fe836&repo=wiki
Modified:
/Description.wiki
/Quickref.wiki
/Tutorial.wiki
=======================================
--- /Description.wiki Sat Feb 23 07:34:38 2013
+++ /Description.wiki Fri Jun 28 09:25:55 2013
@@ -1,16 +1,15 @@
#summary Doconce Description
By *Hans Petter Langtangen*
-
-==== Feb 23, 2013 ====
+==== Jun 28, 2013 ====
<wiki:comment> lines beginning with # are doconce comment lines
</wiki:comment>
<wiki:comment> (documents can also have mako comment lines) </wiki:comment>
-
== 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,
@@ -56,8 +55,15 @@
+
+
== Installation of Doconce and its Dependencies ==
+Below, we explain the manual installation of all software that may be
+needed when working with Doconce documents.
+The impatient way to install what is needed is to run the
+[doconce_install_all.sh `doconce_install_all.sh`] script.
+
==== Doconce ====
Doconce itself is pure Python code hosted at
http://code.google.com/p/doconce. Its installation from the
@@ -79,21 +85,18 @@
sudo python setup.py install
}}}
-Debian GNU/Linux users can also run
-{{{
-sudo apt-get install doconce
-}}}
-This installs the latest release and not the most updated and bugfixed
-version.
-On Ubuntu one needs to run
-{{{
-sudo add-apt-repository ppa:scitools/ppa
-sudo apt-get update
-sudo apt-get install doconce
-}}}
==== Dependencies ====
+Producing HTML documents, plain text, pandoc-extended Markdown,
+and wikis can be done without installing any other
+software. However, if you want other formats as output
+(LaTeX, Sphinx, reStructuredText) and assisting utilities such
+as preprocesors, spellcheck, file differences, bibliographies,
+and so on, the software below must be installed.
+
+<wiki:comment> Make a debpkg_doconce.txt file with everything that is
needed on Debian </wiki:comment>
+
==== Preprocessors ====
If you make use of the [http://code.google.com/p/preprocess Preprocess]
@@ -148,6 +151,13 @@
{{{
sudo apt-get install texlive-extra-utils
}}}
+
+Automatic image conversion from EPS to PDF calls up `epstopdf`, which
+can be installed by
+
+{{{
+sudo apt-get install texlive-font-utils
+}}}
==== Spellcheck ====
@@ -157,6 +167,25 @@
{{{
sudo apt-get install ispell
}}}
+
+
+==== Bibliography ====
+
+The Python package [https://bitbucket.org/logg/publish Publish] is needed
if you use a bibliography
+in your document. On the website, click on *Clone*, copy the
+command and run it:
+
+{{{
+hg clone https://bitbucket.org/logg/publish
+}}}
+Thereafter go to the `publish` directory and run the `setup.py` script
+for installing Publish:
+
+{{{
+cd publish
+sudo python setup.py
+}}}
+
==== Ptex2tex for LaTeX Output ====
@@ -182,7 +211,7 @@
are also needed. These are installed by
{{{
-sudo apt-get install texlive-latex-recommended texlive-latex-extra
+sudo apt-get install texlive
}}}
on Debian Linux (including Ubuntu) systems. TeXShop on Mac comes with
the necessary stylefiles (if not, they can be found by googling and
installed
@@ -205,17 +234,70 @@
cd pygments
sudo python setup.py install
}}}
+One can also do the simple
+
+{{{
+pip install sphinx
+}}}
+which also installs pygments.
If you use the minted style together with `ptex2tex`, you have to
enable it by the `-DMINTED` command-line argument to `ptex2tex`.
This is not necessary if you run the alternative `doconce ptex2tex`
program.
-All
-use of the minted style requires the `-shell-escape` command-line
+All use of the minted style requires the `-shell-escape` command-line
argument when running LaTeX, i.e., `latex -shell-escape` or `pdflatex
-shell-escape`.
-<wiki:comment> Say something about anslistings.sty </wiki:comment>
+Inline comments apply the `todonotes` LaTeX package if the `ptex2tex`
+or `doconce ptex2tex` command is run with `-DTODONOTES`. The
+`todonotes` package requires several other packages: `xcolor`,
+`ifthen`, `xkeyval`, `tikz`, `calc`, `graphicx`, and `setspace`. The
+relevant Debian packages for installing all this are listed below.
+
+==== LaTeX packages ====
+
+Many LaTeX packages are potentially needed (depending on various
+preprocessor variables given to `ptex2tex` or `doconce ptex2tex`. The
+standard packages always included are `relsize`, `epsfig`, `makeidx`,
+`setspace`, `color`, `amsmath`, `amsfonts`, `xcolor`, `bm`,
+`microtype`, `titlesec`, and `hyperref`. The `ptex2tex` package (from
+[http://code.google.com/p/ptex2tex ptex2tex]) is also included, but
+removed again if `doconce ptex2tex` is run instead of the `ptex2tex`
+program, meaning that if you do not use `ptex2tex`, you do not need
+`ptex2tex.sty`. Optional packages that might be included are `minted`,
+`fontspec`, `xunicode`, `inputenc`, `helvet`, `mathpazo`, `wrapfig`,
+`calc`, `ifthen`, `xkeyval`, `tikz`, `graphicx`, `setspace`, `shadow`,
+`disable`, `todonotes`, `lineno`, `xr`, `framed`, `mdframe`,
+`movie15`, `a4paper`, and `a6paper`.
+
+Relevant Debian packages that gives you all of these LaTeX packages are
+
+{{{
+texlive
+texlive-extra-utils
+texlive-latex-extra
+texlive-font-utils
+}}}
+On old Ubuntu 12.04 one has to do `sudo add-apt-repository
ppa:texlive-backports/ppa` and `sudo apt-get update` first, or
alternatively install these as well:
+
+{{{
+texlive-math-extra
+texlive-bibtex-extra
+texlive-xetex
+texlive-humanities
+texlive-pictures
+}}}
+Alternatively, one may pull in `texlive-full` to get all available
+style files.
+
+If you want to use the *anslistings* code environment with `ptex2tex`
+(`.ptex2tex.cfg` styles `Python_ANS`, `Python_ANSt`, `Cpp_ANS`, etc.) or
+`doconce ptex2tex` (`envir=ans` or `envir=ans:nt`), you need the
+`anslistings.sty` file. It can be obtained from
+the
[https://code.google.com/p/ptex2tex/source/browse/trunk/latex/styles/with_license/anslistings.sty
ptex2tex source]. It should get installed
+by the `cp2texmf.sh` script executed above.
+
==== reStructuredText (reST) Output ====
@@ -224,11 +306,19 @@
most recent version can be done by
{{{
-svn checkout
http://docutils.svn.sourceforge.net/svnroot/docutils/trunk/docutils
+svn checkout \
+ http://docutils.svn.sourceforge.net/svnroot/docutils/trunk/docutils
cd docutils
sudo python setup.py install
cd ..
}}}
+The command
+
+{{{
+pip install sphinx
+}}}
+installs Docutils along with Sphinx and Pygments.
+
To use the OpenOffice suite you will typically on Debian systems install
{{{
sudo apt-get install unovonv libreoffice libreoffice-dmaths
@@ -240,6 +330,7 @@
or clone the svn repository, go to the `rst2pdf` directory and
run the usual `sudo python setup.py install`.
+==== Sphinx Output ====
Output to `sphinx` requires of course the
[http://sphinx.pocoo.org Sphinx software],
@@ -251,6 +342,24 @@
sudo python setup.py install
cd ..
}}}
+An alternative is
+
+{{{
+pip install sphinx
+}}}
+
+Doconce comes with many Sphinx themes that are not part of the
+standard Sphinx source distribution. Some of these themes require
+additional Python/Sphinx modules to be installed:
+
+
+ * cloud and redcloud: https://bitbucket.org/ecollins/cloud_sptheme
+ * bootstrap: https://github.com/ryan-roemer/sphinx-bootstrap-theme
+ * solarized: https://bitbucket.org/miiton/sphinxjp.themes.solarized
+ * impressjs: https://github.com/shkumagai/sphinxjp.themes.impressjs
+
+These must be downloaded or cloned, and `setup.py` must be run as shown
+above.
==== Markdown and Pandoc Output ====
@@ -284,7 +393,86 @@
Mercurial (`hg`) directories, go to the directory, run
`hg pull; hg update`, and then `sudo python setup.py install`.
+==== The `doconce diff` command ====
+
+The `doconce diff file1 file prog` command for illustrating differences
between
+two files `file1` and `file2` using the program `prog` requires `prog`
+to be installed. By default, `prog` is `difflib` which comes with Python
+and is always present if you have Doconce installed. Another choice,
`diff`,
+should be available on all Unix/Linux systems. Other choices, their
+URL, and their `sudo apt-get install` command on Debian (Ubuntu) systems
+appear in the table below.
+
+
+ ||
*Program* |
|
*URL* |
| *Debian/Ubuntu
install* ||
+ ||
`pdiff`
|| [http://www.gnu.org/software/a2ps/ a2ps]
[http://www.gnu.org/software/wdiff/ wdiff] || `sudo apt-get install
a2ps wdiff texlive-latex-extra texlive-latex-recommended` ||
+ ||
`latexdiff`
|| [http://www.ctan.org/pkg/latexdiff
latexdiff] || `sudo apt-get
install
latexdiff` ||
+ ||
`kdiff3`
|| [http://kdiff3.sourceforge.net/
kdiff3] || `sudo
apt-get install
kdiff3` ||
+ ||
`diffuse`
|| [http://diffuse.sourceforge.net/
diffuse] || `sudo apt-get
install
diffuse` ||
+ ||
`xxdiff`
|| [http://xxdiff.sourceforge.net/local/
xxdiff] || `sudo apt-get
install
xxdiff` ||
+ ||
`meld`
|| [http://meldmerge.org/
meld] ||
`sudo apt-get install
meld` ||
+ ||
`tkdiff.tcl`
|| [https://sourceforge.net/projects/tkdiff/
tkdiff] || not in
Debian
||
+
+
+==== Quick Debian/Ubuntu Install ====
+
+On Debian (including Ubuntu) systems, it is straightforward to install the
+long series of Doconce dependencies:
+
+{{{
+# Version control systems
+sudo apt-get install -y mercurial git subversion
+
+# Python
+sudo apt-get install -y idle ipython python-pip python-pdftools texinfo
+
+# These lines are only necessary for Ubuntu 12.04 to install texlive 2012
+ubuntu_version=`lsb_release -r | awl '{print $2}'`
+if [ $ubuntu_version = "12.04" ]; then
+ sudo add-apt-repository ppa:texlive-backports/ppa
+ sudo apt-get update
+fi
+# LaTeX
+sudo apt-get install -y texlive texlive-extra-utils texlive-latex-extra
texlive-math-extra texlive-font-utils
+# or sudo apt-get install -y texlive-full # get everything
+sudo apt-get install -y latexdiff auctex
+
+# Image and movie tools
+sudo apt-get install -y imagemagick netpbm mjpegtools pdftk giftrans gv
evince smpeg-plaympeg mplayer totem ffmpeg libav-tools
+
+# Misc
+sudo apt-get install -y ispell pandoc libreoffice unoconv
libreoffice-dmaths curl a2ps wdiff meld xxdiff diffpdf kdiff3 diffuse
+
+# More Python software
+pip install sphinx # install pygments and docutils too
+pip install mako
+pip install -e
svn+http://preprocess.googlecode.com/svn/trunk#egg=preprocess
+pip install -e hg+https://bitbucket.org/logg/publish#egg=publish
+pip install -e
hg+https://bitbucket.org/ecollins/cloud_sptheme#egg=cloud_sptheme
+pip install -e
git+https://github.com/ryan-roemer/sphinx-bootstrap-theme#egg=sphinx-bootstrap-theme
+pip install -e
hg+https://bitbucket.org/miiton/sphinxjp.themes.solarized#egg=sphinxjp.themes.solarized
+pip install -e
git+https://github.com/shkumagai/sphinxjp.themes.impressjs#egg=sphinxjp.themes.impressjs
+pip install -e
svn+https://epydoc.svn.sourceforge.net/svnroot/epydoc/trunk/epydoc#egg=epydoc
+
+# Doconce itself
+rm -rf srclib # put downloaded software in srclib
+mkdir srclib
+cd srclib
+hg clone https://code.google.com/p/doconce/
+cd doconce
+sudo python setup.py install -y
+cd ../..
+
+# Ptex2tex
+cd srclib
+svn checkout http://ptex2tex.googlecode.com/svn/trunk/ ptex2tex
+cd ptex2tex
+sudo python setup.py install -y
+cd latex
+sh cp2texmf.sh # copy stylefiles to ~/texmf directory
+cd ../../..
+}}}
<wiki:comment> </wiki:comment>
<wiki:comment> Here are some comment lines that do not affect any
formatting </wiki:comment>
<wiki:comment> these lines are converted to comments in the output format.
</wiki:comment>
@@ -298,6 +486,7 @@
<wiki:comment> The mako tool also supports <%doc> .. </%doc>
</wiki:comment>
<wiki:comment> </wiki:comment>
+
==== Demos ====
The current text is generated from a Doconce format stored in the
@@ -325,11 +514,11 @@
<wiki:comment> Example on including another Doconce file: </wiki:comment>
-
== From Doconce to Other Formats ==
+
Transformation of a Doconce document `mydoc.do.txt` to various other
-formats applies the script `doconce format`:
+formats apply the script `doconce format`:
{{{
Terminal> doconce format format mydoc.do.txt
}}}
@@ -337,6 +526,30 @@
{{{
Terminal> doconce format format mydoc
}}}
+
+==== Generating a makefile ====
+
+Producing HTML, Sphinx, and in particular LaTeX documents from
+Doconce sources requires a few commands. Often you want to
+produce several different formats. The relevant commands should
+then be placed in a script that acts as a "makefile".
+
+The `doconce makefile` can be used to automatically generate
+such a makefile, more precisely a Bash script `make.sh`, which
+carries out the commands explained below. If our Doconce source
+is in `main_myproj.do.txt`, we run
+
+{{{
+doconce makefile main_myproj html pdflatex sphinx
+}}}
+to produce the necessary output for generating HTML, pdfLaTeX, and
+Sphinx. Usually, you need to edit `make.sh` to really fit your
+needs. Some examples lines are inserted as comments to show
+various options that can be added to the basic commands.
+A handy feature of the generated `make.sh` script is that it
+inserts checks for successful runs of the `doconce format` commands,
+and if something goes wrong, the `make.sh` exits.
+
==== Preprocessing ====
@@ -355,9 +568,7 @@
==== Removal of inline comments ====
-<wiki:comment> mention notes also </wiki:comment>
-
-The command-line arguments `--no-preprocess` and `--no-mako` turn off
+The command-line arguments `--no_preprocess` and `--no_mako` turn off
running `preprocess` and `mako`, respectively.
Inline comments in the text are removed from the output by
@@ -372,6 +583,25 @@
This action is convenient when a Doconce document reaches its final form
and comments by different authors should be removed.
+==== Notes ====
+
+Doconce does not have a tag for longer notes, because implementation
+of a "notes feature" is so easy using the `preprocess` or `mako`
+programs. Just introduce some variable, say `NOTES`, that you define
+through `-DNOTES` (or not) when running `doconce format ...`. Inside
+the document you place your notes between `# #ifdef NOTES` and
+`# #endif` preprocess tags. Alternatively you use `% if NOTES:`
+and `% endif` that `mako` will recognize. In the same way you may
+encapsulate unfinished material, extra material to be removed
+for readers but still nice to archive as part of the document for
+future revisions.
+
+==== Demo of different formats ====
+
+A simple scientific report is available in
[http://hplgit.github.com/teamods/writing_reports/doconce_commands.html a
lot of different formats].
+How to create the different formats is explained in more depth
+in the coming sections.
+
==== HTML ====
Making an HTML version of a Doconce file `mydoc.do.txt`
@@ -387,7 +617,7 @@
An external CSS file `filename` used by setting the command-line
argument `--css=filename`. There available built-in styles are
-specified as `--html-style=name`, where `name` can be
+specified as `--html_style=name`, where `name` can be
* `solarized`: the famous [http://ethanschoonover.com/solarized
solarized] style (yellowish),
@@ -408,56 +638,91 @@
If the Pygments package (including the `pygmentize` program)
is installed, code blocks are typeset with
-aid of this package. The command-line argument `--no-pygments-html`
+aid of this package. The command-line argument `--no_pygments_html`
turns off the use of Pygments and makes code blocks appear with
-plain (`pre`) HTML tags. The option `--pygments-html-linenos` turns
+plain (`pre`) HTML tags. The option `--pygments_html_linenos` turns
on line numbers in Pygments-formatted code blocks. A specific
-Pygments style is set by `--pygments-html-style=style`, where `style`
+Pygments style is set by `--pygments_html_style=style`, where `style`
can be `default`, `emacs`, `perldoc`, and other valid names for
Pygments styles.
-The HTML file can be embedded in a template if the Doconce document
-does not have a title (because then there will be
-no header and footer in the HTML file). The template file must contain
+The HTML file can be embedded in a template with your own tailored
+design, see a [
https://doconce.googlecode.com/hg/doc/design/wrapper_tech.html tutorial] on
this topic. The template file must contain
valid HTML code and can have three "slots": `%(title)s` for a title,
-`%(date)s` for a date, and `%(main)s` for the main body of text, i.e., the
+`%(date)s` for a date, and `%(main)s` for the main body of text. The
+latter is the
Doconce document translated to HTML. The title becomes the first
-heading in the Doconce document, and the date is extracted from the
-`DATE:` line, if present. With the template feature one can easily embed
-the text in the look and feel of a website. The template can be extracted
-from the source code of a page at the site; just insert `%(title)s` and
-`%(date)s` at appropriate places and replace the main bod of text
-by `%(main)s`. Here is an example:
+heading in the Doconce document, or the title (but a title is not
+recommended when using templates). The date is extracted from the
+`DATE:` line. With the template feature one can easily embed
+the text in the look and feel of a website. Doconce comes with
+two templates in `bundled/html_styles`. Just copy the directory
+containing the template and the CSS and JavaScript files to your
+document directory, edit the template as needed (also check that
+paths to the `css` and `js` subdirectories are correct - according
+to how you store the template files), and run
{{{
-Terminal> doconce format html mydoc --html-template=mytemplate.html
+Terminal> doconce format html mydoc --html_template=mytemplate.html
}}}
+The template in `style_vagrant` also needs an extra option
+`--html_style=vagrant`. With this style, one has nice navigation buttons
+that are used if the document contains `!split` commands for splitting
+it into many pages.
+
-==== Blogs ====
+==== Blog Posts ====
-Doconce can be used for writing blogs provided the blog site accepts
+Doconce can be used for writing blog posts provided the blog site accepts
raw HTML code. Google's Blogger service (`blogger.com` or
-`blogname.blogspot.com`)
-is particularly well suited since it also allows extensive LaTeX
mathematics via
-MathJax.
-Write the blog text as a Doconce document without any title, author, and
-date. Then generate HTML as described above. Copy the text and paste it
-into the text area in the blog, making sure the input format is HTML.
-On Google's Blogger service you can use Doconce to generate blogs with
-LaTeX mathematics and pretty (pygmentized) blocks of computer code.
-See a [http://doconce.blogspot.no blog example] for details on blogging.
+`blogname.blogspot.com`) is particularly well suited since it also
+allows extensive LaTeX mathematics via MathJax.
+
+
+# Write the blog text as a Doconce document without any title, author,
and date.
+# Generate HTML as described above.
+# Copy the text and paste it into the text area in the blog (just delete
the HTML code that initially pops up in the text area). Make sure the
input format is HTML.
+
+See a [http://doconce.blogspot.no simple blog example] and
+a [http://doconce-report-demo.blogspot.no/ scientific report]
+for demonstrations of blogs at `blogspot.no`.
+
+*Warning.*
+In the readers' comments after the blog one cannot paste raw HTML
+code with MathJax
+scripts so there is no support for mathematics in the discussion forum.
+*Notice.*
+Figure files must be uploaded to some web site and the filenames name must
+be replaced by the relevant URL. This can be automatically edited:
+{{{
+cp mydoc.do.txt mydoc2.do.txt
+url="https//raw.github.com/someuser/someuser.github.com"
+dir="master/project/dir1/dir2"
+for figname in fig1 fig2 fig3; do
+ doconce replace "[$figname," "[$site/$dir/$figname.png," \
+ mydoc2.do.txt
+done
+doconce format html mydoc2
+# Paste mydoc2.html into a new blog page
+}}}
-*Warning.* In the comments after the blog one cannot paste raw HTML code
with MathJax
-scripts so there is no support for mathematics in the comments.
+Blog posts at Google can also be published
[http://support.google.com/blogger/bin/answer.py?hl=en&answer=41452
automatically through email].
+A Python program can send the contents of the HTML file
+to the blog's email address using the packages `smtplib` and `email`.
WordPress (`wordpress.com`) allows raw HTML code in blogs,
but has very limited
LaTeX support, basically only formulas. The `--wordpress` option to
`doconce` modifies the HTML code such that all equations are typeset
in a way that is acceptable to WordPress.
-There is a [http://doconce.wordpress.com doconce example]
-on blogging with mathematics and code on WordPress.
+Look at a [http://doconce.wordpress.com simple doconce example]
+and a [http://doconcereportdemo.wordpress.com/ scientific report]
+to see blogging with mathematics and code on WordPress.
+
+Speaking of WordPress, the related project http://pressbooks.com can take
raw HTML code (from Doconce, for
+instance) and produce very nice-looking books. There is no support
+for mathematics in the text, though.
==== Pandoc and Markdown ====
@@ -475,13 +740,21 @@
Pandoc pass raw HTML or LaTeX to the output format instead of ignoring it,
while the `--toc` option generates a table of contents.
See the [http://johnmacfarlane.net/pandoc/README.html Pandoc documentation]
-for the many features of the `pandoc` program.
+for the many features of the `pandoc` program. The HTML output from
+`pandoc` needs adjustments to provide full support for MathJax LaTeX
+mathematics, and for this purpose one should use `doconce md2html`:
+
+{{{
+Terminal> doconce format pandoc mydoc
+Terminal> doconce m2html mydoc
+}}}
+The result `mydoc.html` can be viewed in a browser.
-Pandoc is useful to go from LaTeX mathematics to, e.g., HTML or MS Word.
-There are two ways (experiment to find the best one for your document):
-`doconce format pandoc` and then translating using `pandoc`, or
-`doconce format latex`, and then going from LaTeX to the desired format
-using `pandoc`.
+Pandoc is useful to go from LaTeX mathematics to, e.g., HTML or MS
+Word. There are two ways (experiment to find the best one for your
+document): `doconce format pandoc` and then translating using `doconce
+md2latex` (which runs `pandoc`), or `doconce format latex`, and then
+going from LaTeX to the desired format using `pandoc`.
Here is an example on the latter strategy:
{{{
Terminal> doconce format latex mydoc
@@ -489,8 +762,8 @@
Terminal> doconce replace '\Verb!' '\verb!' mydoc.tex
Terminal> pandoc -f latex -t docx -o mydoc.docx mydoc.tex
}}}
-When we go through `pandoc`, only single equations or `align*`
-environments are well understood.
+When we go through `pandoc`, only single equations, `align`, or `align*`
+environments are well understood for output to HTML.
Note that Doconce applies the `Verb` macro from the `fancyvrb` package
while `pandoc` only supports the standard `verb` construction for
@@ -510,6 +783,7 @@
The `-s` option adds a proper header and footer to the `mydoc.html` file.
This recipe is a quick way of makeing HTML notes with (some) mathematics.
+
==== LaTeX ====
Making a LaTeX file `mydoc.tex` from `mydoc.do.txt` is done in two steps:
@@ -528,7 +802,7 @@
If these files are present, they are included in the LaTeX document
so that your commands are defined.
-An option `--latex-printed` makes some adjustments for documents
+An option `--latex_printed` makes some adjustments for documents
aimed at being printed. For example, links to web resources are
associated with a footnote listing the complete web address (URL).
@@ -559,17 +833,23 @@
Preprocessor variables to be defined or undefined are
- * `BOOK` for the "book" documentclass rather than the
standard "article" class (necessary if you apply chapter headings)
+ * `XELATEX` for processing by `xelatex`
* `PALATINO` for the Palatino font
- * `HELVETIA` for the Helvetica font
+ * `HELVETICA` for the Helvetica font
* `A4PAPER` for A4 paper size
- * `A6PAPER` for A6 paper size (suitable for reading on small devices)
- * `MOVIE15` for using the movie15 LaTeX package to display movies
- * `PREAMBLE` to turn the LaTeX preamble on or off (i.e., complete
document or document to be included elsewhere)
- * `MINTED` for inclusion of the minted package (which requires `latex`
or `pdflatex` to be run with the `-shell-escape` option)
+ * `A6PAPER` for A6 paper size (suitable for reading PDFs on phones)
+ * `MOVIE` for specifying how movies are handled: the value `media9`
implies the `media9` package and the `\includemedia` command (default),
while other values are `movie15` (`\includemovie` command), `multimedia`
(for Beamer-style `\movie` command), or `href-run` (for the plain
`\hrun:file` command)
+ * `PREAMBLE` to turn the LaTeX preamble on or off (i.e., complete
document or document to be included elsewhere - and note that the
preamble is only included if the document has a title, author, and date)
+ * `MINTED` for inclusion of the minted package for typesetting of code
with the Pygments tool (which requires `latex` or `pdflatex` to be run
with the `-shell-escape` option)
+ * `TODONOTES` for using the fancy `todonotes` package for typesetting
inline comments (looks much like track changes in MS Word). This macro
has only effect if inline comments are used (name, colon, and comment
inside brackets).
+ * `LINENUMBERS` for inclusion of line numbers in the text.
+ * `AMON` for setting the type of admonitions: `"colors"` for colored
boxes with icons, `"graybox1"` for gray frame boxes with rounded corners
(default), `"graybox2"` for narrower square gray frame boxes (except for
summary, which for A4 format is small and with wrapped text around if it
does not contain verbatim code), or `"paragraph"` for simple, plain
paragraph headings and ordinary text
+ * `COLORED_TABLE_ROWS` for coloring every other table rows (set this
variable to `gray` or `blue`)
+ * `BLUE_SECTION_HEADINGS` for blue section and subsection headings
+ * `LATEX_HEADING` for the typesetting of the title, author, parts of
preamble (values: `traditional` for traditional LaTeX heading,
`titlepage` for a separate titlepage, `Springer_collection` for edited
volumes on Springer, `beamer` for Beamer slides, `doconce_heading`
(default) for listing institutions after names)
If you are not satisfied with the Doconce preamble, you can provide
-your own preamble by adding the command-line option
`--latex-preamble=myfile`.
+your own preamble by adding the command-line option
`--latex_preamble=myfile`.
In case `myfile` contains a documentclass definition, Doconce assumes
that the file contains the *complete* preamble you want (not that all
the packages listed in the default preamble are required and must be
@@ -612,16 +892,24 @@
edited with the aid of the `doconce replace` and `doconce subst`
commands. The former works with substituting text directly, while the
latter performs substitutions using regular expressions.
-Here are two examples:
+You will use `doconce replace` to edit `section{` to `section*{`:
{{{
Terminal> doconce replace 'section{' 'section*{' mydoc.tex
+}}}
+For fixing the line break of a title, you may pick a word in the
+title, say "Using", and insert a break after than word. With
+`doconce subst` this is easy employing regular expressions with
+a group before "Using" and a group after:
+
+{{{
Terminal> doconce subst 'title\{(.+)Using (.+)\}' \
'title{\g<1> \\\\ [1.5mm] Using \g<2>' mydoc.tex
}}}
A lot of tailored fixes to the LaTeX document can be done by
an appropriate set of text replacements and regular expression
substitutions. You are anyway encourged to make a script for
-generating PDF from the LaTeX file.
+generating PDF from the LaTeX file so the `doconce subst` or
+`doconce replace` commands can be put inside the script.
*Step 3.* Compile `mydoc.tex`
and create the PDF file:
@@ -657,6 +945,7 @@
specifications with `doconce ptex2tex`), the minted package is
automatically
included so there is no need for the `-DMINTED` option.
+
==== PDFLaTeX ====
Running `pdflatex` instead of `latex` follows almost the same steps,
@@ -671,6 +960,19 @@
Terminal> bibitem mydoc # if bibliography
Terminal> pdflatex -shell-escape mydoc
}}}
+
+==== XeLaTeX ====
+
+XeLaTeX is an alternative to pdfLaTeX and is run in almost the
+same way, except for the `-DXELATEX` flag to ptex2tex:
+
+{{{
+Terminal> doconce format pdflatex mydoc
+Terminal> doconce ptex2tex mydoc -DXELATEX
+Terminal> ptex2tex -DXELATEX mydoc # alternative
+Terminal> xelatex mydoc
+}}}
+
==== Plain ASCII Text ====
@@ -756,40 +1058,119 @@
`automake_sphinx.py` for compiling the Sphinx document into an HTML
document. One can either run `automake_sphinx.py` or perform the
steps in the script manually, possibly with necessary modifications.
-You should at least read the script prior to executing it to have
-some idea of what is done.
+Normally, executing the script works well, but if you are new
+to Sphinx and end up producing quite some Sphinx documents, I encourave
+you to read the Sphinx documentation and study the `automake_sphinx.py`
+file.
-The `doconce sphinx_dir` script copies directories named `figs` or
-`figures` over to the Sphinx directory so that figures are accessible
-in the Sphinx compilation. If figures or movies are located in other
-directories, `automake_sphinx.py` must be edited accordingly. Files,
-to which there are local links (not `http:` or `file:` URLs), must be
-placed in the `_static` subdirectory of the Sphinx directory. The
-utility `doconce sphinxfix_localURLs` is run to check for local links
-in the Doconce file: for each such link, say `dir1/dir2/myfile.txt` it
-replaces the link by `_static/myfile.txt` and copies
-`dir1/dir2/myfile.txt` to a local `_static` directory (in the same
-directory as the script is run). However, we recommend instead that
-the writer of the document places files in `_static` or lets a script
-do it automatically. The user must copy all `_static/*` files to the
-`_static` subdirectory of the Sphinx directory. It may be wise to
-always put files, to which there are local links in the Doconce
-document, in a `_static` or `_static-name` directory and use these
-local links. Then links do not need to be modified when creating a
-Sphinx version of the document.
+*Links.* The `automake_sphinx.py` script copies directories named `fig*`
+over to the Sphinx directory so that figures are accessible
+in the Sphinx compilation. It also examines `MOVIE:` and `FIGURE:`
+commands in the Doconce file to find other image files and copies
+these too. I strongly recommend to put files
+to which there are local links (not `http:` or `file:` URLs) in
+a directory named `_static`. The `automake_sphinx.py` copies
+`_static*` to the Sphinx directory, which guarantees that the links
+to the local files will work in the Sphinx document.
+
+There is a utility `doconce sphinxfix_localURLs` for checking links to
+local files and moving the files to `_static` and changing the links
+accordingly. For example, a link to `dir1/dir2/myfile.txt` is changed
+to `_static/myfile.txt` and `myfile.txt` is copied to `_static`.
+However, I recommend instead that you manually copy
+files to `_static` when you want to link to them, or let your
+script which compiles the Doconce document do it automatically.
-Doconce comes with a collection of HTML themes for Sphinx documents.
-These are packed out in the Sphinx directory, the `conf.py`
-configuration file for Sphinx is edited accordingly, and a script
+*Themes.* Doconce comes with a rich collection of HTML themes for Sphinx
documents,
+much larger than what is found in the standard Sphinx distribution.
+Additional themes include
+`agni`,
+`basicstrap`,
+`bootstrap`,
+`cloud`,
+`fenics`,
+`fenics_minimal`,
+`flask`,
+`haiku`,
+`impressjs`,
+`jal`,
+`pylons`,
+`redcloud`,
+`scipy_lectures`,
+`slim-agogo`, and
+`vlinux-theme`.
+
+All the themes are packed out in the Sphinx directory, and the
+`doconce sphinx_dir` insert lots of extra code in the `conf.py`
+file to enable easy specification and customization of themes.
+For example, modules are loaded for the additional themes that
+come with Doconce, code is inserted to allow customization of
+the look and feel of themes, etc. The `conf.py` file is a
+good starting point for fine-tuning your favorite team, and your
+own `conf.py` file can later be supplied and used when running
+`doconce sphinx_dir`: simply add the command-line option
+`conf.py=conf.py`.
+
+A script
`make-themes.sh` can make HTML documents with one or more themes.
For example,
-to realize the themes `fenics` and `pyramid`, one writes
+to realize the themes `fenics`, `pyramid`, and `pylon` one writes
{{{
-Terminal> ./make-themes.sh fenics pyramid
+Terminal> ./make-themes.sh fenics pyramid pylon
}}}
The resulting directories with HTML documents are `_build/html_fenics`
and `_build/html_pyramid`, respectively. Without arguments,
-`make-themes.sh` makes all available themes (!).
+`make-themes.sh` makes all available themes (!). With `make-themes.sh`
+it is easy to check out various themes to find the one that is most
+attractive for your document.
+
+You may supply your own theme and avoid copying all the themes
+that come with Doconce into the Sphinx directory. Just specify
+`theme_dir=path` on the command line, where `path` is the relative
+path to the directory containing the Sphinx theme. You must also
+specify a configure file by `conf.py=path`, where `path` is the
+relative path to your `conf.py` file.
+
+*Example.* Say you like the `scipy_lectures` theme, but you want
+a table of contents to appear *to the right*, much in the same style
+as in the `default` theme (where the table of contents is to the left).
+You can then run `doconce sphinx_dir`, invoke a text editor with the
+`conf.py` file, find the line `html_theme == 'scipy_lectures'`,
+edit the following `nosidebar` to `false` and `rightsidebar` to `true`.
+Alternatively, you may write a little script using `doconce replace`
+to replace a portion of text in `conf.py` by a new one:
+
+{{{
+doconce replace "elif html_theme == 'scipy_lectures':
+ html_theme_options = {
+ 'nosidebar': 'true',
+ 'rightsidebar': 'false',
+ 'sidebarbgcolor': '#f2f2f2',
+ 'sidebartextcolor': '#20435c',
+ 'sidebarlinkcolor': '#20435c',
+ 'footerbgcolor': '#000000',
+ 'relbarbgcolor': '#000000',
+ }" "elif html_theme == 'scipy_lectures':
+ html_theme_options = {
+ 'nosidebar': 'false',
+ 'rightsidebar': 'true',
+ 'sidebarbgcolor': '#f2f2f2',
+ 'sidebartextcolor': '#20435c',
+ 'sidebarlinkcolor': '#20435c',
+ 'footerbgcolor': '#000000',
+ 'relbarbgcolor': '#000000',
+ }" conf.py
+}}}
+Obviously, we could also have changed colors in the edit above.
+The final alternative is to save the edited `conf.py` file somewhere
+and reuse it the next time `doconce sphinx_dir` is run
+
+{{{
+doconce sphinx_dir theme=scipy_lectures \
+ conf.py=../some/path/conf.py mydoc
+}}}
+
+==== The manual Sphinx procedure ====
If it is not desirable to use the autogenerated scripts explained
above, here is the complete manual procedure of generating a
@@ -879,6 +1260,7 @@
(`code-block:: python` in Sphinx syntax) and `cppcod` gives C++, but
all such arguments can be customized both for Sphinx and LaTeX output.
+
==== Wiki Formats ====
There are many different wiki formats, but Doconce only supports three:
@@ -1058,12 +1440,13 @@
line. Here is an example:
{{{
TITLE: On an Ultimate Markup Language
-AUTHOR: H. P. Langtangen at Center for Biomedical Computing, Simula
Research Laboratory and Dept. of Informatics, Univ. of Oslo
+AUTHOR: H. P. Langtangen at Center for Biomedical Computing, Simula
Research Laboratory & Dept. of Informatics, Univ. of Oslo
AUTHOR: Kaare Dump Email: du...@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,
+Note how one can specify a single institution, multiple institutions
+(with `&` as separator between institutions),
and 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
@@ -1138,8 +1521,6 @@
__A Paragraph.__ The running text goes here.
}}}
-
-
== Special Lines ==
@@ -1240,25 +1621,27 @@
is generated, and a link to this file is inserted in the output document.
That is, a simple "movie viewer" for the frames is made.
-Many publish their scientific movies on YouTube, and Doconce recognizes
-YouTube URLs as movies. When the output from Doconce
+Many publish their scientific movies on YouTube or Vimeo, and Doconce
recognizes
+YouTube and Vimeo URLs as movies. When the output from Doconce
is an HTML file, the movie will
-be embedded, otherwise a URL to the YouTube page is inserted.
+be embedded, otherwise a URL to the YouTube or Vimeo page is inserted.
You should equip the `MOVIE:` command with the right width and height
-of *embedded* YouTube movies. The recipe goes as follows:
+of *embedded* YouTube and Vimeo movies. The recipe goes as follows:
-# click on *Share* and then *Embed*
-# copy the URL for the embedded movie
+# click on *Share* (and on YouTube then *Embed*)
# note the height and width of the embedded movie
A typical `MOVIE` command with a YouTube movie is then
{{{
-MOVIE: [http://www.youtube.com/embed/sI2uCHH3qIM, width=420 height=315]
+MOVIE: [http://www.youtube.com/watch?v=sI2uCHH3qIM, width=420 height=315]
+
+MOVIE: [http://vimeo.com/55562330, width=500 height=278] Computational
fluid dynamics movie.
}}}
-Doconce will be able to embed standard YouTube URLs also, but then
-the width and height might be inappropriate.
+Note that there must be a blank line after every `MOVIE:` command.
+The width and height parameters are not required, but leaving them out
+may lead to movie sizes you do not want.
==== Copying Computer Code from Source Files ====
@@ -1266,10 +1649,12 @@
of computer code from a file directly into a verbatim environment, see
the section [#Blocks_of_Verbatim_Computer_Code] below.
+
==== Inline Tagging ====
Doconce supports tags for *emphasized phrases*, *boldface phrases*,
-and `verbatim text` (also called type writer text, for inline code)
+and `verbatim text` (also called type writer text, for inline code),
+<font color="blue">colored words</font>,
plus LaTeX/TeX inline mathematics, such as `v = sin(x)`.
==== Emphasized Words ====
@@ -1303,9 +1688,8 @@
the Doconce file, because some formats (LaTeX and `ptex2tex`) will have
problems with inline verbatim text that is split over two lines.
-
-
-*Notice.* Watch out for mixing back-ticks and asterisk (i.e., verbatim and
+*Notice.*
+Watch out for mixing back-ticks and asterisk (i.e., verbatim and
emphasized code): the Doconce interpreter is not very smart so inline
computer code can soon lead to problems in the final format. Go back to the
Doconce source and modify it so the format to which you want to go
@@ -1404,10 +1788,11 @@
}}}
where `name` is the name of the author of the command, and `comment` is a
plain text text. Note that there must be a space after the colon,
-otherwise the comment is not recognized. Inline comments
+otherwise the comment is not recognized. [hpl 1: Inline comments
can span
several lines,
-if desired.
+if desired.]
+
The name and comment are visible in the output unless `doconce format`
is run with a command-line argument `--skip_inline_comments`
(see the section [#From_Doconce_to_Other_Formats] for an example). Inline
comments
@@ -1416,6 +1801,11 @@
All such comments can easily be removed from the `.do.txt` file
(see the section [#From_Doconce_to_Other_Formats]).
+Inline comments are typeset in a simple way (boldface name and the
+comment in parenthesis), but in LaTeX very visible color boxes
+are used (via the `todonotes` package).
+
+
==== Inline Mathematics ====
Inline mathematics is written as in LaTeX, i.e., inside dollar signs.
@@ -1477,6 +1867,7 @@
preprocessor and an if-else block with a variable that is undefined
(typically something like a test `# #ifdef EXTRA` in Preprocess).
+
==== Cross-Referencing ====
References and labels are supported. The syntax is simple:
@@ -1593,7 +1984,7 @@
@testdoc:12, Doconce documents may include movies.
}}}
-==== Index and Bibliography ====
+==== Index ====
An index can be created for the `latex`, `rst`, and `sphinx` formats
by the `idx` keyword, following a LaTeX-inspired syntax:
@@ -1616,73 +2007,147 @@
index items related to a paragraph should be placed above the
paragraph one a separate line (and not in between the text or between
the paragraph heading and the text body, although this works fine if
-LaTeX is the output format).
+LaTeX is the output format). For paragraphs with `===` heading,
+the index keywords should be placed above the heading.
-Literature citations also follow a LaTeX-inspired style:
+The keywords in the index are automatically placed in a meta
+tag in `html` output such that search engines can make use of the them.
+
+==== Bibliography ====
+
+Doconce applies the software tool [https://bitbucket.org/logg/publish
Publish] to handle the bibliography in a
+document. With Publish it is easy to import BibTeX data and maintain a
+database in a clean, self-explanatory textual format. From the Publish
+format it is easy to go BibTeX and reST or straightforward Doconce
+typesetting (and from there to HTML, plain text, wiki formats, and so
+on).
+
+Installing Publish is straightforward: just checkout the code on
***The diff for this file has been truncated for email.***
=======================================
--- /Quickref.wiki Sat Feb 23 07:34:38 2013
+++ /Quickref.wiki Fri Jun 28 09:25:55 2013
@@ -1,17 +1,22 @@
#summary Doconce Quick Reference
By *Hans Petter Langtangen*
-
-==== Feb 23, 2013 ====
+==== Jun 8, 2013 ====
<wiki: toc max_depth="2" />
-<wiki:comment> Very preliminary </wiki:comment>
-
*WARNING: This quick reference is very incomplete!*
+*Mission.* Enable writing documentation with much mathematics and
+computer code *once, in one place* and include it in traditional LaTeX
+books, thesis, and reports, and without extra efforts also make
+professionally looking web versions with Sphinx or HTML. Other outlets
+include Google's `blogger.com`, Wikipedia/Wikibooks, IPython
+notebooks, plus a wide variety of formats for documents without
+mathematics and code.
+
==== Supported Formats ====
Doconce currently translates files to the following formats:
@@ -22,14 +27,49 @@
* reStructuredText (format `rst`)
* plain (untagged) ASCII (format `plain`)
* Sphinx (format `sphinx`)
+ * IPython notebook (format `ipynb`)
+ * MediaWiki (format `mwiki`)
* (Pandoc extended) Markdown (format `pandoc`)
* Googlecode wiki (format `gwiki`)
- * MediaWiki for Wikipedia and Wikibooks (format `mwiki`)
* Creoloe wiki (format `cwiki`)
* Epydoc (format `epydoc`)
* StructuredText (format `st`)
-The best supported formats are `latex`, `sphinx`, `html`, and `plain`.
+For documents with much code and mathematics, the best (and most supported)
+formats are `latex`, `pdflatex`, `sphinx`, and `html`; and to a slightly
+less extent `mwiki` and `pandoc`. The HTML format supports blogging on
+Google and Wordpress.
+
+
+==== Emacs syntax support ====
+
+The file
[https://doconce.googlecode.com/hg/misc/.doconce-mode.el .doconce-mode.el]
in the Doconce source distribution
+gives a "Doconce Editing Mode" in Emacs. Store the file in the home
+directory and add `(load-file "~/.doconce-mode.el")` to the `.emacs`
+file.
+
+Besides syntax highlighting of Doconce documents, this Emacs mode
+provides a lot of shortcuts for setting up many elements in a document:
+
+
+ || *Emacs key* ||
*Action* ||
+ || Ctrl+c f ||
figure ||
+ || Ctrl+c v ||
movie/video ||
+ || Ctrl+c h1 || heading level 1
(section/h1) ||
+ || Ctrl+c h2 || heading level 2
(subsection/h2) ||
+ || Ctrl+c h3 || heading level 2
(subsection/h3) ||
+ || Ctrl+c hp || heading for
paragraph ||
+ || Ctrl+c me || math environment: !bt
equation !et ||
+ || Ctrl+c ma || math environment: !bt
align !et ||
+ || Ctrl+c ce || code
environment: !bc !ec ||
+ || Ctrl+c cf || code from file:
@@@CODE ||
+ || Ctrl+c table2 || table with 2
columns ||
+ || Ctrl+c table3 || table with 3
columns ||
+ || Ctrl+c table4 || table with 4
columns ||
+ || Ctrl+c exer || exercise
outline ||
+ || Ctrl+c slide || slide
outline ||
+ || Ctrl+c help || print this
table ||
+
==== Title, Authors, and Date ====
@@ -38,7 +78,7 @@
reads
{{{
TITLE: On an Ultimate Markup Language
-AUTHOR: H. P. Langtangen at Center for Biomedical Computing, Simula
Research Laboratory and Dept. of Informatics, Univ. of Oslo
+AUTHOR: H. P. Langtangen at Center for Biomedical Computing, Simula
Research Laboratory & Dept. of Informatics, Univ. of Oslo
AUTHOR: Kaare Dump Email: du...@cyb.space.com at Segfault, Cyberspace Inc.
AUTHOR: A. Dummy Author
DATE: today
@@ -47,11 +87,12 @@
The entire title must appear on a single line.
The author syntax is
{{{
-name Email: some...@adr.net at institution1 and institution2
+name Email: some...@adr.net at institution1 & institution2
}}}
where the email is optional, the "at" keyword is required if one or
-more institutions are to be specified, and the "and" keyword
-separates the institutions. Each author specification must appear
+more institutions are to be specified, and the `&` keyword
+separates the institutions (the keyword `and` works too).
+Each author specification must appear
on a single line.
When more than one author belong to the
same institution, make sure that the institution is specified in an
identical
@@ -62,30 +103,41 @@
The table of contents is removed by writing `TOC: off`.
+
==== Section Types ====
- || *Section type* ||
*Syntax* ||
- || chapter || `========= Heading
========` (9 `=`) ||
- || section || `======= Heading
=======` (7 `=`) ||
- || subsection || `===== Heading
=====` (5 `=`) ||
- || subsubsection || `=== Heading
===` (3 `=`) ||
- || paragraph ||
`__Heading.__` (2 `_`) ||
- || abstract || `__Abstract.__` Running
text... ||
+ || *Section type* |
| *Syntax* ||
+ || chapter || `=========
Heading ========` (9 `=`) ||
+ || section || `======= Heading
=======` (7 `=`) ||
+ || subsection || `===== Heading
=====` (5 `=`) ||
+ || subsubsection || `=== Heading
===` (3 `=`) ||
+ || paragraph ||
`__Heading.__` (2 `_`) ||
+ || abstract || `__Abstract.__`
Running text... ||
+ || appendix || `=======
Appendix: heading =======` (7 `=`) ||
+ || appendix || `===== Appendix:
heading =====` (5 `=`) ||
+ || exercise || `=======
Exercise: heading =======` (7 `=`) ||
+ || exercise || `===== Exercise:
heading =====` (5 `=`) ||
-Note that abstracts are recognized by starting with `__Abstract.__` at
-the beginning of a line and ending with three or more `=` signs of the
-next heading.
+Note that abstracts are recognized by starting with `__Abstract.__` or
+`__Summary.__` at the beginning of a line and ending with three or
+more `=` signs of the next heading.
-Appendix is supported: just let the heading start with "Appendix: "
-(this affects only `latex` output, where the appendix formatting
-is used - all other formats just leave the heading as it is written).
+The `Exercise:` keyword kan be substituted by `Problem:` or `Project:`.
+A recommended convention is that an exercise is tied to the text,
+a problem can stand on its own, and a project is a comprehensive
+problem.
==== Inline Formatting ====
Words surrounded by `*` are emphasized: `*emphasized words*` becomes
*emphasized words*. Similarly, an underscore surrounds words that
-appear in boldface: `_boldface_` become *boldface*.
+appear in boldface: `_boldface_` becomes *boldface*. Colored words
+are also possible: the text
+{{{
+`color{red}{two red words}`
+}}}
+becomes <font color="red">two red words</font>.
==== Lists ====
@@ -160,7 +212,7 @@
* keyword3:
and its description may fit on one line
-==== Comments ====
+==== Comment lines ====
Lines starting with `#` are treated as comments in the document and
translated to the proper syntax for comments in the output
@@ -168,34 +220,49 @@
blocks, verbatim code blocks, or lists if the formats `rst` and
`sphinx` are desired.
+Comment lines starting with `##` are not propagated to the output
+document and can be used for comments that are only interest in
+the Doconce file.
+
+Large portions of text can be left out using Preprocess. Just place
+`# #ifdef EXTRA` and `# #endif` around the text. The command line
+option `-DEXTRA` will bring the text alive again.
+
When using the Mako preprocessor one can also place comments in
the Doconce source file that will be removed by Mako before
-Doconce starts processing the file. Mako comments are recognized
-by lines starting with two hashes `##` or by blocks of text
-inside the comment directives `%<doc>` (beginning) and `<%doc/>` (end).
+Doconce starts processing the file.
+
+
+==== Inline comments ====
-Inline comments, in the text, that are meant as messages or notes to
readers
-(authors in particular)
-are often useful and enabled by the syntax
+Inline comments meant as messages or notes, to authors during development
+in particular,
+are enabled by the syntax
{{{
[name: running text]
}}}
where `name` is the name or ID of an author or reader making the comment,
-and `running text` is the comment. There must be a space after the colon.
+and `running text` is the comment. Here goes an example.
+[hpl 1: There must be a space after the colon,
+but the running text can occupy multiple lines.]
+The inline comments have simple typesetting in most formats, typically
boldface
+name and everything surrounded by parenthesis, but with LaTeX
+output and the `-DTOTONOTES` option to `ptex2tex` or `doconce ptex2tex`,
+colorful margin or inline boxes (using the `todonotes` package)
+make it very easy to spot the comments.
+
Running
{{{
doconce format html mydoc.do.txt --skip_inline_comments
}}}
-removes all such inline comments from the output. This feature makes it
easy
-to turn on and off notes to readers and is frequently used while writing
-a document.
+removes all inline comments from the output. This feature makes it easy
+to turn on and off notes to authors during the development of the document.
All inline comments to readers can also be physically
-removed from the Doconce source if desired:
+removed from the Doconce source by
{{{
doconce remove_inline_comments mydoc.do.txt
}}}
-This action is appropriate when all issues with such comments are resolved.
==== Verbatim/Computer Code ====
@@ -273,9 +340,9 @@
==== LaTeX Mathematics ====
Doconce supports inline mathematics and blocks of mathematics, using
-standard LaTeX syntax. The output formats `sphinx`, `latex`, and `pdflatex`
-work with this syntax while all other formats will just display the
-raw LaTeX code.
+standard LaTeX syntax. The output formats `html`, `sphinx`, `latex`,
+pdflatex`, `pandoc`, and `mwiki` work with this syntax while all other
+formats will just display the raw LaTeX code.
Inline expressions are written in the standard
LaTeX way with the mathematics surrounded by dollar signs, as in
@@ -287,8 +354,7 @@
}}}
That is, the LaTeX expression appears to the left of a vertical bar (pipe
symbol) and the more readable expression appears to the right. Both
-expressions are surrounded by dollar signs. Plain text formats and HTML
-will applied the expression to the right.
+expressions are surrounded by dollar signs.
Blocks of LaTeX mathematics are written within
`!bt`
@@ -298,19 +364,17 @@
{{{
!bt
\begin{align*}
-\nabla\cdot \pmb{u} &= 0,\\
+\nabla\cdot \pmb{u} &= 0,\\
\nabla\times \pmb{u} &= 0.
\end{align*}
!et
}}}
-<wiki:comment> Note: !bt and !et (and !bc and !ec below) are used to
illustrate </wiki:comment>
-<wiki:comment> tex and code blocks in inside verbatim blocks and are
replaced </wiki:comment>
-<wiki:comment> by !bt, !et, !bc, and !ec after all other formatting is
finished. </wiki:comment>
+
This LaTeX code gets rendered as
{{{
\begin{align*}
-\nabla\cdot \pmb{u} &= 0,\\
+\nabla\cdot \pmb{u} &= 0,\\
\nabla\times \pmb{u} &= 0.
\end{align*}
}}}
@@ -326,27 +390,20 @@
{{{
\[ \frac{\partial\pmb{u}}{\partial t} + \pmb{u}\cdot\nabla\pmb{u} = 0.\]
}}}
-
-One can use `#if FORMAT in
("latex", "pdflatex", "html", "sphinx", "mwiki")`
-to let the preprocessor choose a block of mathematics in LaTeX format
-or (`#else`) a modified form more suited for plain text and wiki
-formats without support for mathematics.
Any LaTeX syntax is accepted, but if output in the `sphinx`, `pandoc`,
-`mwiki`, or `html` formats
-is important, one must know that these formats does not support many
-LaTeX constructs. For output both in `latex` or `pdflatex` *and*
-the mentioned formats with LaTeX support,
-the following rules are recommended:
+`mwiki`, `html`, or `ipynb` formats
+is also important, one should follow these rules:
* Use only the equation environments `\[`, `\]`, `equation`,
`equation*`, `align`, and `align*`.
- * Labels in multiple equation environments such as `align` are not
(yet) handled by `pandoc`.
* MediaWiki (`mwiki`) does not support references to equations.
+(Doconce performs extensions to `sphinx` and other formats such that
+labels in `align` environments work well.)
-
-*Notice.* LaTeX supports lots of fancy formatting, for example, multiple
+*Notice.*
+LaTeX supports lots of fancy formatting, for example, multiple
plots in the same figure, footnotes, margin notes, etc.
Allowing other output formats, such as `sphinx`, makes it necessary
to only utilze very standard LaTeX and avoid, for instance, more than
@@ -357,7 +414,17 @@
also allow advanced LaTeX features and fine tuning of resulting
PDF document.
-*LaTeX Newcommands.* Text missing...
+*LaTeX Newcommands.* The author can define `newcommand` statements in
files with names
+`newcommands*.tex`. Such commands should only be used for mathematics
+(other LaTeX constructions are only understood by LaTeX itself).
+The convention is that `newcommands_keep.tex`
+contains the newcommands that are kept in the document, while
+those in `newcommands_replace.tex` will be replaced by their full
+LaTeX code. This conventions helps make readable documents in formats
+without LaTeX support. For `html`, `sphinx`, `latex`, `pdflatex`,
+`mwiki`, `ipynb`, and `pandoc`, the mathematics in newcommands is
+rendered nicely anyway.
+
==== Figures and Movies ====
@@ -368,28 +435,42 @@
MOVIE: [relative/path/to/moviefile, width=500] Here goes the caption which
must be on a single line. label{some:fig:label}
}}}
-Note the mandatory comma after the figure/movie file.
+Note three important syntax details:
+
+
+ # A mandatory comma after the figure/movie filename,
+ # all of the command must appear on a single line,
+ # there must be a blank line after the command.
The figure file can be listed without extension. Doconce will then find
the version of the file with the most appropriate extension for the chosen
output format. If not suitable version is found, Doconce will convert
-another format to the desired one.
+another format to the needed one.
Movie files can either be a video or a wildcard expression for a
series of frames. In the latter case, a simple device in an HTML page
will display the individual frame files as a movie.
Combining several image files into one can be done by the
-`convert` and `montage` programs from the ImageMagick suite:
{{{
-montage file1.png file2.png ... file4.png -geometry +2+2 result.png
-montage file1.png file2.png -tile x1 result.png
-montage file1.png file2.png -tile 1x result.png
+doconce combine_images image1 image2 ... output_image
+}}}
+This command applies `montage` or PDF-based tools to combine the images
+to get the highest quality.
-convert -background white file1.png file2.png +append tmp.png
+YouTube and Vimeo movies will be embedded in `html` and `sphinx` documents
+and otherwise be represented by a link. The syntax is
+
+{{{
+MOVIE: [http://www.youtube.com/watch?v=_O7iUiftbKU, width=420 height=315]
YouTube movie.
+
+MOVIE: [http://vimeo.com/55562330, width=500 height=278] Vimeo movie.
+
}}}
-Use `+append` for stacking left to right, `-append` for top to bottom.
-The positioning of the figures can be controlled by `-gravity`.
+The latter results in
+
+ Vimeo movie. http://vimeo.com/55562330
+
==== Tables ====
@@ -416,16 +497,22 @@
* If the horizontal rules are without alignment information there
should be no vertical bar (pipe symbol) between the columns. Otherwise,
such a bar indicates a vertical bar between columns in LaTeX.
* Many output formats are so primitive that heading and column
alignment have no effect.
-==== Labels, References, Citations, and Index ====
+The command-line option `--tables2csv` (to `doconce format`)
+makes Doconce dump each table to CSV format in a file `table_X.csv`,
+where `X` is the table number. This feature makes it easy to
+load tables into spreadsheet programs for further analysis.
-The notion of labels, references, citations, and an index is adopted
+==== Labels and References ====
+
+The notion of labels and references (as well as bibliography and index)
+is adopted
from LaTeX with a very similar syntax. As in LaTeX, a label can be
inserted anywhere, using the syntax
{{{
label{name}
}}}
with no backslash
-preceding the label keyword! It is common practice to choose `name`
+preceding the label keyword. It is common practice to choose `name`
as some hierarchical name, say `a:b:c`, where `a` and `b` indicate
some abbreviations for a section and/or subsection for the topic and
`c` is some name for the particular unit that has a label.
@@ -436,6 +523,13 @@
}}}
again with no backslash before `ref`.
+Use labels for sections and equations only, and preceed the reference
+by "Section" or "Chapter", or in case of an equation, surround the
+reference by parenthesis.
+
+
+==== Citations and Bibliography ====
+
Single citations are written as
{{{
cite{name}
@@ -451,20 +545,22 @@
cite{name1,name2,name3}
}}}
-The bibliography is specified by a line `BIBFILE: name_bib.bib,
-name_bib.rst, name_bib.py`, where `name` is the logical name of the
-document (the doconce file will then normally have the name
-`name.do.txt`), and the various files reflect different formattings of
-the bibliography: '.bib' indicates a BibTeX file, '.rst' a reST-style
-bibliography, and '.py' a Python list of dictionaries for specifying
-the entries in the bibliography. The bibliography (as read from file)
-is inserted where the `BIBFILE` keyword appears.
+The bibliography is specified by a line `BIBFILE: papers.pub`,
+where `papers.pub` is a publication database in the
+[https://bitbucket.org/logg/publish Publish] format.
+BibTeX `.bib` files can easily be combined to a Publish database
+(which Doconce needs to create bibliographies in other formats
+than LaTeX).
+
+==== Generalized Citations ====
There is a *generalized referencing* feature in Doconce that allows
a reference with `ref` to have one formulation if the label is
in the same document and another formulation if the reference is
-to an item in an external document. The syntax of a generalized
-reference is
+to an item in an external document. This construction makes it easy
+to work with many small, independent documents in parallel with
+a book assembly of some of the small elements.
+The syntax of a generalized reference is
{{{
ref[internal][cite][external]
@@ -486,6 +582,8 @@
documents. If none of the two situations above applies, the
`external` text will be the output.
+==== Index of Keywords ====
+
Doconce supports creating an index of keywords. A certain keyword
is registered for the index by a syntax like (no
backslash!)
@@ -496,10 +594,10 @@
running text, i.e., after (sub)section titles and in the space between
paragraphs. Index specifications placed right before paragraphs also
gives the doconce source code an indication of the content in the
-forthcoming text. The index is only produced for the `latex`, `rst`, and
-`sphinx` formats.
+forthcoming text. The index is only produced for the `latex`,
+`pdflatex`, `rst`, and `sphinx` formats.
-==== Capabilities of the "doconce" Program ====
+==== Capabilities of The Program `doconce` ====
The `doconce` program can be used for a number of purposes besides
transforming a `.do.txt` file to some format. Here is the
@@ -507,7 +605,7 @@
{{{
Usage: doconce command [optional arguments]
-commands: format help sphinx_dir subst replace replace_from_file clean
spellcheck ptex2tex expand_commands combine_images guess_encoding
change_encoding gwiki_figsubst remove_inline_comments grab remove
remove_exercise_answers split_rst split_html slides_html latin2html
latex_header latex_footer bbl2rst html_colorbullets list_labels teamod
sphinxfix_localURLs make_figure_code_links latex_exercise_toc insertdocstr
old2new_format
+commands: format help sphinx_dir subst replace replace_from_file clean
spellcheck ptex2tex expand_commands combine_images guess_encoding
change_encoding gwiki_figsubst md2html remove_inline_comments grab remove
remove_exercise_answers split_rst split_html slides_html slides_beamer
latin2html latex_header latex_footer bbl2rst html_colorbullets list_labels
teamod sphinxfix_localURLs make_figure_code_links latex_exercise_toc
insertdocstr old2new_format latex2doconce latex_dislikes pygmentize
makefile diff gitdiff fix_bibtex4publish csv2table
# transform doconce file to another format
@@ -565,7 +663,10 @@
doconce bbl2rst file.bbl
# split a sphinx/rst file into parts
-doconce split_rst complete_file.rst
+doconce format sphinx complete_file
+doconce split_rst complete_file # !split delimiters
+doconce sphinx_dir complete_file
+python automake_sphinx.py
# edit URLs to local files and place them in _static
doconce sphinxfix_local_URLs file.rst
@@ -573,9 +674,12 @@
# split an html file into parts according to !split commands
doconce split_html complete_file.html
-# create slides from a (doconce) html file
+# create HTML slides from a (doconce) html file
doconce slides_html slide_type complete_file.html
+# create LaTeX Beamer slides from a (doconce) latex/pdflatex file
+doconce slides_beamer complete_file.tex
+
# replace bullets in lists by colored bullets
doconce html_colorbullets file1.html file2.html ...
@@ -585,9 +689,6 @@
# remove selected text from a file
doconce remove --from[-] from-text [--to[-] to-text] somefile
-# remove answers to exercises
-doconce remove_exercise_answers file_in_some_format
-
# run spellcheck on a set of files
doconce spellcheck [-d .mydict.txt] *.do.txt
@@ -595,6 +696,12 @@
# and manage the code environments
doconce ptex2tex mydoc -DMINTED pycod=minted sys=Verbatim \
dat=\begin{quote}\begin{verbatim};\end{verbatim}\end{quote}
+
+# make HTML file via pandoc from Markdown (.md) file
+doconce md2html file
+
+# make LaTeX file via pandoc from Markdown (.md) file
+doconce md2latex file
# expand short cut commands to full form in files
doconce expand_commands file1 file2 ...
@@ -607,6 +714,31 @@
# list all labels in a document (for purposes of cleaning them up)
doconce list_labels myfile
+
+# translate a latex document to doconce (requires usually manual fixing)
+doconce latex2doconce latexfile
+
+# check if there are problems with translating latex to doconce
+doconce latex_dislikes latexfile
+
+# typeset a doconce document with pygments (for pretty print of doconce
itself)
+doconce pygmentize myfile [pygments-style]
+
+# generate a make.sh script for translating a doconce file to various
formats
+doconce makefile docname doconcefile [html sphinx pdflatex ...]
+
+# fix common problems in bibtex files for publish import
+doconce fix_bibtex4publish file1.bib file2.bib ...
+
+# find differences between two files
+doconce diff file1.do.txt file2.do.txt [diffprog]
+(diffprog can be difflib, diff, pdiff, latexdiff, kdiff3, diffuse, ...)
+
+# find differences between the last two Git versions of several files
+doconce gitdiff file1 file2 file3 ...
+
+# convert csv file to doconce table format
+doconce csv2table somefile.csv
}}}
==== Exercises ====
@@ -709,10 +841,11 @@
}}}
By default, answers, solutions, and hints are typeset as paragraphs.
-The command-line arguments `--without-answers` and `--without-solutions`
+The command-line arguments `--without_answers` and `--without_solutions`
turn off output of answers and solutions, respectively, except for
examples.
+
==== Environments ====
Doconce environments start with `!benvirname` and end with `!eenvirname`,
@@ -725,14 +858,11 @@
* `subex`: sub-exercise
* `ans`: short answer to exercise or sub-exercise
* `sol`: full solution to exercise or sub-exercise
- * `notes`: multi-line notes to be included or not
* `quote`: indented text
- * `notice`, `summary`, `warning`, `question`, `hint`: boxes with
specialy typesetting (or symbols)
+ * `notice`, `summary`, `warning`, `question`, `hint`: admonition boxes
with custom title, special icon, and (frequently) background color
* `pop`: text to gradually pop up in slide presentations
* `slidecell`: indication of cells in a grid layout for elements on a
slide
-==== Labels, Index, and Citations ====
-
==== Preprocessing ====
Doconce documents may utilize a preprocessor, either `preprocess` and/or
@@ -754,11 +884,11 @@
\caption{Some words... label{mytab}}
\begin{tabular}{lrr}
\hline\noalign{\smallskip}
-\multicolumn{1}{c}{time} & \multicolumn{1}{c}{velocity} &
\multicolumn{1}{c}{acceleration} \\
+\multicolumn{1}{c}{time} & \multicolumn{1}{c}{velocity} &
\multicolumn{1}{c}{acceleration} \\
\hline
-0.0 & 1.4186 & -5.01 \\
-2.0 & 1.376512 & 11.919 \\
-4.0 & 1.1E+1 & 14.717624 \\
+0.0 & 1.4186 & -5.01 \\
+2.0 & 1.376512 & 11.919 \\
+4.0 & 1.1E+1 & 14.717624 \\
\hline
\end{tabular}
\end{table}
@@ -786,3 +916,4 @@
* Excellent "Sphinx Tutorial" by C.
Reller: "http://people.ee.ethz.ch/~creller/web/tricks/reST.html"
+
=======================================
--- /Tutorial.wiki Sat Feb 23 07:34:38 2013
+++ /Tutorial.wiki Fri Jun 28 09:25:55 2013
@@ -1,10 +1,8 @@
-<wiki:comment> Missing: FIGURE, MOVIE, environments </wiki:comment>
#summary Doconce: Document Once, Include Anywhere
By *Hans Petter Langtangen*
-
-==== Feb 23, 2013 ====
+==== May 29, 2013 ====
* When writing a note, report, manual, etc., do you find it difficult
to choose the typesetting format? That is, to choose between plain
(email-like) text, wiki, Word/OpenOffice, LaTeX, HTML, reStructuredText,
Sphinx, XML, etc. Would it be convenient to start with some very simple
text-like format that easily converts to the formats listed above, and
then at some later stage eventually go with a particular format?
* Do you need to write documents in varying formats but find it
difficult to remember all the typesetting details of various formats like
[http://refcards.com/docs/silvermanj/amslatex/LaTeXRefCard.v2.0.pdf LaTeX],
[http://www.htmlcodetutorial.com/ HTML],
[http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html
reStructuredText], [http://sphinx.pocoo.org/contents.html Sphinx], and
[http://code.google.com/p/support/wiki/WikiSyntax wiki]? Would it be
convenient to generate the typesetting details of a particular format
from a very simple text-like format with minimal tagging?
@@ -13,34 +11,80 @@
If any of these questions are of interest, you should keep on reading.
+== Some Doconce Features ==
+
+
+ * Strong support for texts with much math and code.
+ * Same source can produce a variety of output formats. The following
support LaTeX math and (pygmentized) code:
+
+ #
[http://hplgit.github.com/teamods/writing_reports/_static/report_4printing.pdf
traditional LaTeX B/W documents for printing]
+ # [http://hplgit.github.com/teamods/writing_reports/_static/report.pdf
color LaTeX PDF documents]
+ #
[http://hplgit.github.com/teamods/writing_reports/_static/report_4phone.pdf
color LaTeX PDF documents for viewing on small phones]
+ #
[http://hplgit.github.com/teamods/writing_reports/_static/sphinx-fenics_minimal/report.html
Sphinx HTML documents with 20+ different designs]
+ # [http://hplgit.github.com/teamods/writing_reports/_static/report.html
Plain HTML] or with a
[http://hplgit.github.com/teamods/writing_reports/_static/report_vagrant.html
template] or
[http://hplgit.github.com/teamods/writing_reports/_static/report_github_minimal.html
another template] or
[http://hplgit.github.com/teamods/writing_reports/_static/report_solarized.html
solarized]
+ # HTML for [http://doconce-report-demo.blogspot.no/ Google] or
[http://doconcereportdemo.wordpress.com/ Wordpress] blogs
+ # [http://doconcedemo.shoutwiki.com/wiki/Doconce_demo_page MediaWiki]
(Wikipedia, Wikibooks, etc)
+ # Markdown
+ # IPython notebook
+
+ Other formats include plain untagged text (for email), Creole wiki
(for Bitbucket wikis), Google wiki (for Googlecode), reStructuredText,
and Epytext.
+ * Integration with Mako enables use of variables, functions, if-tests,
and loops to parameterize the text and generate various versions of the
text for different purposes.
+ * Computer code can be copied directly from parts of source code files.
+ * Running text can quickly be edited to slide formats (reveal.js and
deck.js, based on HTML5+CSS3).
+ * Special exercise environments with support for hints, answers,
subexercises, etc.
+ * Automatic inline embedding of YouTube and Vimeo movies.
+ * Good support for admonitions in various LaTeX and HTML styles for
warnings, questions, hints, remarks, summaries, etc.
== What Does Doconce Look Like? ==
-Doconce text looks like ordinary text, but there are some almost invisible
-text constructions that allow you to control the formating. Here are
-som examples.
+Doconce text looks like ordinary text (much like Markdown), but there
+are some almost invisible text constructions that allow you to control
+the formating. Here are some examples.
- * Bullet lists arise from lines starting with `*`.
- * *Emphasized words* are surrounded by `*`.
- * *Words in boldface* are surrounded by underscores.
+ * Bullet lists automatically arise from lines starting with `*`, or
`o` if the list is to be enumerated.
+ * *Emphasized words* are surrounded by `*`. *Words in boldface* are
surrounded by underscores.
* Words from computer code are enclosed in back quotes and then
typeset `verbatim (in a monospace font)`.
- * Section headings are recognied by equality (`=`) signs before and
after the title, and the number of `=` signs indicates the level of the
section: 7 for main section, 5 for subsection, and 3 for subsubsection.
- * Paragraph headings are recognized by a double underscore before and
after the heading.
+ * Section and paragraph headings are recognied special decorating
characters (`=` or `_`) before and after the heading. The length of the
decoration determines the level of the section.
+ * Blocks of computer code are included by surrounding the blocks with
`!bc` (begin code) and `!ec` (end code) tags on separate lines.
+ * Blocks of computer code can also be imported from source files.
+ * Blocks of LaTeX mathematics are included by surrounding the blocks
with `!bt` (begin TeX) and `!et` (end TeX) tags on separate lines.
+ * There is support for both LaTeX and text-like inline mathematics
such that formulas make sense also when not rendered by LaTeX or MathJax.
+ * Figures and movies with captions, simple tables, URLs with links,
index list, labels and references are supported. YouTube and Vimeo
videos are automatically embedded in web documents.
* The abstract of a document starts with *Abstract* as paragraph
heading, and all text up to the next heading makes up the abstract,
- * Blocks of computer code can easily be included by placing `!bc`
(begin code) and `!ec` (end code) commands at separate lines before and
after the code block.
- * Blocks of computer code can also be imported from source files.
- * Blocks of LaTeX mathematics can easily be included by placing `!bt`
(begin TeX) and `!et` (end TeX) commands at separate lines before and
after the math block.
- * There is support for both LaTeX and text-like inline mathematics.
- * Figures and movies with captions, simple tables, URLs with links,
index list, labels and references are supported.
- * Invisible comments in the output format can be inserted throughout
the text.
- * Visible comments can be inserted so that authors and readers can
comment upon the text (and at any time turn on/off output of such
comments).
+ * Special comment lines are not visible in the output.
+ * Comments to authors can be inserted throughout the text and made
visible or invisible as desired.
* There is an exercise environment with many advanced features.
- * With a preprocessor, Preprocess or Mako, one can include other
documents (files) and large portions of text can be defined in or out of
the text.
- * With Mako one can also have Python code embedded in the Doconce
document and thereby parameterize the text (e.g., one text can describe
programming in two languages).
+ * With a preprocessor, Preprocess or Mako, one can include other
documents (files), large portions of text can be defined in or out of
the text, and tailored format-specific constructs can easily be
included. With Mako a single text can output its program examples in two
or more languages.
+
+==== What Can Doconce Be Used For? ====
+
+LaTeX is ideal for articles, thesis, and books, but not so suited
+for web documents. Nice environments for web documents, such as
+Sphinx, Markdown, or plain HTML, are not particularly well
+suited for thesis and books. IPython notebooks are ideal for
+documenting computational experiments, but do not (yet) meet the
+requirements of books and thesis.
+
+What about migrating a part of a book for blogging? What about making
+an MS Word version of parts or an untagged text for inclusion in
+email? What about efficiently generating slides in modern HTML5
+style? Doconce enables all this with just *one source* (the slogan is
+*document once - include anywhere*).
+Doconce also
+has many extra features for supporting documents with much code and
+mathematics, not found in any of the mentioned formats.
+
+==== Basic Syntax ====
Here is an example of some simple text written in the Doconce format:
{{{
+======= First a Section Heading =======
+
+Section headings have 7 equality characters before and after the heading.
+With 9 characters we have a chapter heading, 5 gives a subsection
+heading, and 3 a subsubsection heading.
+
===== A Subsection with Sample Text =====
label{my:first:sec}
@@ -58,9 +102,14 @@
o item 2
o item 3
+__Hyperlinks.__ Paragraph headings are surrounded by double underscores.
URLs with a link word are possible, as in "hpl": "http://folk.uio.no/hpl".
If the word is URL, the URL itself becomes the link name,
-as in "URL": "tutorial.do.txt".
+as in "URL": "tutorial.do.txt". Doconce distinguishes between paper
+and screen output. In traditional paper output, in PDF generated from LaTeX
+generated from Doconce, the URLs of links appear as footnotes.
+With screen output, all links are clickable hyperlinks, except in
+the plain text format which does not support hyperlinks.
References to sections may use logical names as labels (e.g., a
"label" command right after the section title), as in the reference to
@@ -86,6 +135,13 @@
}}}
The Doconce text above results in the following little document:
+
+== First a Section Heading ==
+
+Section headings have 7 equality characters before and after the heading.
+With 9 characters we have a chapter heading, 5 gives a subsection
+heading, and 3 a subsubsection heading.
+
==== A Subsection with Sample Text ====
Ordinary text looks like ordinary text, and the tags used for
@@ -105,18 +161,25 @@
# item 2
# item 3
+*Hyperlinks.* Paragraph headings are surrounded by double underscores.
URLs with a link word are possible, as in [http://folk.uio.no/hpl hpl].
If the word is URL, the URL itself becomes the link name,
-as in tutorial.do.txt.
+as in tutorial.do.txt. Doconce distinguishes between paper
+and screen output. In traditional paper output, in PDF generated from LaTeX
+generated from Doconce, the URLs of links appear as footnotes.
+With screen output, all links are clickable hyperlinks, except in
+the plain text format which does not support hyperlinks.
References to sections may use logical names as labels (e.g., a
"label" command right after the section title), as in the reference to
the section [#A_Subsection_with_Sample_Text].
-Doconce also allows inline comments such as [hpl: here I will make
+Doconce also allows inline comments such as [hpl 1: here I will make
some remarks to the text] for allowing authors to make notes. Inline
comments can be removed from the output by a command-line argument
-(see the section [#From_Doconce_to_Other_Formats] for an example).
+(see the section [#From_Doconce_to_Other_Formats] for an example).
Ordinary comment
+lines start with `#` and are copied to comment lines in the
+output format.
Tables are also supperted, e.g.,
@@ -126,11 +189,13 @@
|| 2.0 || 1.376512 || 11.919 ||
|| 4.0 || 1.1E+1 || 14.717624 ||
+
==== Mathematics and Computer Code ====
Inline mathematics, such as `v = sin(x)`,
allows the formula to be specified both as LaTeX and as plain text.
-This results in a professional LaTeX typesetting, but in other formats
+This results in a professional LaTeX typesetting, but in formats
+not supporting LaTeX mathematics
the text version normally looks better than raw LaTeX mathematics with
backslashes. An inline formula like `v = sin(x)` is
typeset as
@@ -158,19 +223,16 @@
{{{
!bt
\begin{align}
-{\partial u\over\partial t} &= \nabla^2 u + f, label{myeq1}\\
+{\partial u\over\partial t} &= \nabla^2 u + f, label{myeq1}\\
{\partial v\over\partial t} &= \nabla\cdot(q(u)\nabla v) + g
\end{align}
!et
}}}
-<wiki:comment> Note: !bt and !et (and !bc and !ec below) are used to
illustrate </wiki:comment>
-<wiki:comment> tex and code blocks in inside verbatim blocks and are
replaced </wiki:comment>
-<wiki:comment> by !bt, !et, !bc, and !ec after all other formatting is
finished. </wiki:comment>
The result looks like this:
{{{
\begin{align}
-{\partial u\over\partial t} &= \nabla^2 u + f, label{myeq1}\\
+{\partial u\over\partial t} &= \nabla^2 u + f, label{myeq1}\\
{\partial v\over\partial t} &= \nabla\cdot(q(u)\nabla v) + g
\end{align}
}}}
@@ -204,7 +266,7 @@
I = integrate.trapezoidal(myfunc, 0, pi, 100)
}}}
A code block must come after some plain sentence (at least for successful
-output to `sphinx`, `rst`, and ASCII-close formats),
+output to `sphinx`, `rst`, and formats close to plain text),
not directly after a section/paragraph heading or a table.
@@ -219,46 +281,64 @@
trailing `.txt` denotes a text document so that editors gives you
plain text editing capabilities.
+
==== Macros (Newcommands), Cross-References, Index, and Bibliography ====
Doconce supports a type of macros via a LaTeX-style *newcommand*
-construction. The newcommands defined in a file with name
-`newcommand_replace.tex` are expanded when Doconce is filtered to
-other formats, except for LaTeX (since LaTeX performs the expansion
-itself). Newcommands in files with names `newcommands.tex` and
-`newcommands_keep.tex` are kept unaltered when Doconce text is
-filtered to other formats, except for the Sphinx format. Since Sphinx
-understands LaTeX math, but not newcommands if the Sphinx output is
-HTML, it makes most sense to expand all newcommands. Normally, a user
-will put all newcommands that appear in math blocks surrounded by
-`!bt` and `!et` in `newcommands_keep.tex` to keep them unchanged, at
-least if they contribute to make the raw LaTeX math text easier to
-read in the formats that cannot render LaTeX. Newcommands used
-elsewhere throughout the text will usually be placed in
-`newcommands_replace.tex` and expanded by Doconce. The definitions of
-newcommands in the `newcommands*.tex` files *must* appear on a single
-line (multi-line newcommands are too hard to parse with regular
-expressions).
+construction. The newcommands are defined in files with names
+`newcommands*.tex`, using standard LaTeX syntax. Only newcommands
+for use inside math environments are supported.
+
+Labels, corss-references, citations, and support of an index and
+bibliography are much inspired by LaTeX syntax, but Doconce features
+no backslashes. Use labels for sections and equations only, and
+preceed the reference by "Section" or "Chapter", or in case of
+an equation, surround the reference by parenthesis.
+
+Here is an example:
+
+{{{
+===== My Section =====
+label{sec:mysec}
+
+idx{key equation} idx{$\u$ conservation}
+
+We refer to Section ref{sec:yoursec} for background material on
+the *key equation*. Here we focus on the extension
+
+# \Ddt, \u and \mycommand are defined in newcommands_keep.tex
+
+!bt
+\begin{equation}
+\Ddt{\u} = \mycommand{v},
+label{mysec:eq:Dudt}
+\end{equation}
+!et
+where $\Ddt{\u}$ is the material derivative of $\u$.
+Equation (ref{mysec:eq:Dudt}) is important in a number
+of contexts, see cite{Larsen_et_al_2002,Johnson_Friedman_2010a}.
+Also, cite{Miller_2000} supports such a view.
+
+As see in Figure ref{mysec:fig:myfig}, the key equation
+features large, smooth regions *and* abrupt changes.
+
+FIGURE: [fig/myfile, width=600] My figure. label{mysec:fig:myfig}
+
+===== References =====
+
+BIBFILE: papers.pub
+}}}
-Recent versions of Doconce also offer cross referencing, typically one
-can define labels below (sub)sections, in figure captions, or in
-equations, and then refer to these later. Entries in an index can be
-defined and result in an index at the end for the LaTeX and Sphinx
-formats. Citations to literature, with an accompanying bibliography in
-a file, are also supported. The syntax of labels, references,
-citations, and the bibliography closely resembles that of LaTeX,
-making it easy for Doconce documents to be integrated in LaTeX
-projects (manuals, books). For further details on functionality and
+For further details on functionality and
syntax we refer to the `doc/manual/manual.do.txt` file (see the
[https://doconce.googlecode.com/hg/doc/demos/manual/index.html demo page]
for various formats of this document).
-<wiki:comment> Example on including another Doconce file (using
preprocess): </wiki:comment>
+== From Doconce to Other Formats ==
-== From Doconce to Other Formats ==
Transformation of a Doconce document `mydoc.do.txt` to various other
formats applies the script `doconce format`:
@@ -269,6 +349,30 @@
{{{
Terminal> doconce format format mydoc
}}}
+
+==== Generating a makefile ====
+
+Producing HTML, Sphinx, and in particular LaTeX documents from
+Doconce sources requires a few commands. Often you want to
+produce several different formats. The relevant commands should
+then be placed in a script that acts as a "makefile".
+
+The `doconce makefile` can be used to automatically generate
+such a makefile, more precisely a Bash script `make.sh`, which
+carries out the commands explained below. If our Doconce source
+is in `main_myproj.do.txt`, we run
+
+{{{
+doconce makefile main_myproj html pdflatex sphinx
+}}}
+to produce the necessary output for generating HTML, pdfLaTeX, and
+Sphinx. Usually, you need to edit `make.sh` to really fit your
+needs. Some examples lines are inserted as comments to show
+various options that can be added to the basic commands.
+A handy feature of the generated `make.sh` script is that it
+inserts checks for successful runs of the `doconce format` commands,
+and if something goes wrong, the `make.sh` exits.
+
==== Preprocessing ====
@@ -287,9 +391,7 @@
==== Removal of inline comments ====
-<wiki:comment> mention notes also </wiki:comment>
-
-The command-line arguments `--no-preprocess` and `--no-mako` turn off
+The command-line arguments `--no_preprocess` and `--no_mako` turn off
running `preprocess` and `mako`, respectively.
Inline comments in the text are removed from the output by
@@ -304,6 +406,25 @@
This action is convenient when a Doconce document reaches its final form
and comments by different authors should be removed.
+==== Notes ====
+
+Doconce does not have a tag for longer notes, because implementation
+of a "notes feature" is so easy using the `preprocess` or `mako`
+programs. Just introduce some variable, say `NOTES`, that you define
+through `-DNOTES` (or not) when running `doconce format ...`. Inside
+the document you place your notes between `# #ifdef NOTES` and
+`# #endif` preprocess tags. Alternatively you use `% if NOTES:`
+and `% endif` that `mako` will recognize. In the same way you may
+encapsulate unfinished material, extra material to be removed
+for readers but still nice to archive as part of the document for
+future revisions.
+
+==== Demo of different formats ====
+
+A simple scientific report is available in
[http://hplgit.github.com/teamods/writing_reports/doconce_commands.html a
lot of different formats].
+How to create the different formats is explained in more depth
+in the coming sections.
+
==== HTML ====
Making an HTML version of a Doconce file `mydoc.do.txt`
@@ -319,7 +440,7 @@
An external CSS file `filename` used by setting the command-line
argument `--css=filename`. There available built-in styles are
-specified as `--html-style=name`, where `name` can be
+specified as `--html_style=name`, where `name` can be
* `solarized`: the famous [http://ethanschoonover.com/solarized
solarized] style (yellowish),
@@ -340,56 +461,91 @@
If the Pygments package (including the `pygmentize` program)
is installed, code blocks are typeset with
-aid of this package. The command-line argument `--no-pygments-html`
+aid of this package. The command-line argument `--no_pygments_html`
turns off the use of Pygments and makes code blocks appear with
-plain (`pre`) HTML tags. The option `--pygments-html-linenos` turns
+plain (`pre`) HTML tags. The option `--pygments_html_linenos` turns
on line numbers in Pygments-formatted code blocks. A specific
-Pygments style is set by `--pygments-html-style=style`, where `style`
+Pygments style is set by `--pygments_html_style=style`, where `style`
can be `default`, `emacs`, `perldoc`, and other valid names for
Pygments styles.
-The HTML file can be embedded in a template if the Doconce document
-does not have a title (because then there will be
-no header and footer in the HTML file). The template file must contain
+The HTML file can be embedded in a template with your own tailored
+design, see a [
https://doconce.googlecode.com/hg/doc/design/wrapper_tech.html tutorial] on
this topic. The template file must contain
valid HTML code and can have three "slots": `%(title)s` for a title,
-`%(date)s` for a date, and `%(main)s` for the main body of text, i.e., the
+`%(date)s` for a date, and `%(main)s` for the main body of text. The
+latter is the
Doconce document translated to HTML. The title becomes the first
-heading in the Doconce document, and the date is extracted from the
-`DATE:` line, if present. With the template feature one can easily embed
-the text in the look and feel of a website. The template can be extracted
-from the source code of a page at the site; just insert `%(title)s` and
-`%(date)s` at appropriate places and replace the main bod of text
-by `%(main)s`. Here is an example:
+heading in the Doconce document, or the title (but a title is not
+recommended when using templates). The date is extracted from the
+`DATE:` line. With the template feature one can easily embed
+the text in the look and feel of a website. Doconce comes with
+two templates in `bundled/html_styles`. Just copy the directory
+containing the template and the CSS and JavaScript files to your
+document directory, edit the template as needed (also check that
+paths to the `css` and `js` subdirectories are correct - according
+to how you store the template files), and run
{{{
-Terminal> doconce format html mydoc --html-template=mytemplate.html
+Terminal> doconce format html mydoc --html_template=mytemplate.html
}}}
+The template in `style_vagrant` also needs an extra option
+`--html_style=vagrant`. With this style, one has nice navigation buttons
+that are used if the document contains `!split` commands for splitting
+it into many pages.
-==== Blogs ====
-Doconce can be used for writing blogs provided the blog site accepts
+==== Blog Posts ====
+
+Doconce can be used for writing blog posts provided the blog site accepts
raw HTML code. Google's Blogger service (`blogger.com` or
-`blogname.blogspot.com`)
-is particularly well suited since it also allows extensive LaTeX
mathematics via
-MathJax.
-Write the blog text as a Doconce document without any title, author, and
-date. Then generate HTML as described above. Copy the text and paste it
-into the text area in the blog, making sure the input format is HTML.
-On Google's Blogger service you can use Doconce to generate blogs with
-LaTeX mathematics and pretty (pygmentized) blocks of computer code.
-See a [http://doconce.blogspot.no blog example] for details on blogging.
+`blogname.blogspot.com`) is particularly well suited since it also
+allows extensive LaTeX mathematics via MathJax.
+
+
+# Write the blog text as a Doconce document without any title, author,
and date.
+# Generate HTML as described above.
+# Copy the text and paste it into the text area in the blog (just delete
the HTML code that initially pops up in the text area). Make sure the
input format is HTML.
+
+See a [http://doconce.blogspot.no simple blog example] and
+a [http://doconce-report-demo.blogspot.no/ scientific report]
+for demonstrations of blogs at `blogspot.no`.
+
+*Warning.*
+In the readers' comments after the blog one cannot paste raw HTML
+code with MathJax
+scripts so there is no support for mathematics in the discussion forum.
+*Notice.*
+Figure files must be uploaded to some web site and the filenames name must
+be replaced by the relevant URL. This can be automatically edited:
+{{{
+cp mydoc.do.txt mydoc2.do.txt
+url="https//raw.github.com/someuser/someuser.github.com"
+dir="master/project/dir1/dir2"
+for figname in fig1 fig2 fig3; do
+ doconce replace "[$figname," "[$site/$dir/$figname.png," \
+ mydoc2.do.txt
+done
+doconce format html mydoc2
+# Paste mydoc2.html into a new blog page
+}}}
-*Warning.* In the comments after the blog one cannot paste raw HTML code
with MathJax
-scripts so there is no support for mathematics in the comments.
+Blog posts at Google can also be published
[http://support.google.com/blogger/bin/answer.py?hl=en&answer=41452
automatically through email].
+A Python program can send the contents of the HTML file
+to the blog's email address using the packages `smtplib` and `email`.
WordPress (`wordpress.com`) allows raw HTML code in blogs,
but has very limited
LaTeX support, basically only formulas. The `--wordpress` option to
`doconce` modifies the HTML code such that all equations are typeset
in a way that is acceptable to WordPress.
-There is a [http://doconce.wordpress.com doconce example]
-on blogging with mathematics and code on WordPress.
+Look at a [http://doconce.wordpress.com simple doconce example]
+and a [http://doconcereportdemo.wordpress.com/ scientific report]
+to see blogging with mathematics and code on WordPress.
+
+Speaking of WordPress, the related project http://pressbooks.com can take
raw HTML code (from Doconce, for
+instance) and produce very nice-looking books. There is no support
+for mathematics in the text, though.
==== Pandoc and Markdown ====
@@ -407,13 +563,21 @@
Pandoc pass raw HTML or LaTeX to the output format instead of ignoring it,
while the `--toc` option generates a table of contents.
See the [http://johnmacfarlane.net/pandoc/README.html Pandoc documentation]
-for the many features of the `pandoc` program.
+for the many features of the `pandoc` program. The HTML output from
+`pandoc` needs adjustments to provide full support for MathJax LaTeX
+mathematics, and for this purpose one should use `doconce md2html`:
+
+{{{
+Terminal> doconce format pandoc mydoc
+Terminal> doconce m2html mydoc
+}}}
+The result `mydoc.html` can be viewed in a browser.
-Pandoc is useful to go from LaTeX mathematics to, e.g., HTML or MS Word.
-There are two ways (experiment to find the best one for your document):
-`doconce format pandoc` and then translating using `pandoc`, or
-`doconce format latex`, and then going from LaTeX to the desired format
-using `pandoc`.
+Pandoc is useful to go from LaTeX mathematics to, e.g., HTML or MS
+Word. There are two ways (experiment to find the best one for your
+document): `doconce format pandoc` and then translating using `doconce
+md2latex` (which runs `pandoc`), or `doconce format latex`, and then
+going from LaTeX to the desired format using `pandoc`.
Here is an example on the latter strategy:
{{{
Terminal> doconce format latex mydoc
@@ -421,8 +585,8 @@
Terminal> doconce replace '\Verb!' '\verb!' mydoc.tex
Terminal> pandoc -f latex -t docx -o mydoc.docx mydoc.tex
}}}
-When we go through `pandoc`, only single equations or `align*`
-environments are well understood.
+When we go through `pandoc`, only single equations, `align`, or `align*`
+environments are well understood for output to HTML.
Note that Doconce applies the `Verb` macro from the `fancyvrb` package
while `pandoc` only supports the standard `verb` construction for
@@ -442,6 +606,7 @@
The `-s` option adds a proper header and footer to the `mydoc.html` file.
This recipe is a quick way of makeing HTML notes with (some) mathematics.
+
==== LaTeX ====
Making a LaTeX file `mydoc.tex` from `mydoc.do.txt` is done in two steps:
@@ -460,7 +625,7 @@
If these files are present, they are included in the LaTeX document
so that your commands are defined.
-An option `--latex-printed` makes some adjustments for documents
+An option `--latex_printed` makes some adjustments for documents
aimed at being printed. For example, links to web resources are
associated with a footnote listing the complete web address (URL).
@@ -491,17 +656,23 @@
Preprocessor variables to be defined or undefined are
- * `BOOK` for the "book" documentclass rather than the
standard "article" class (necessary if you apply chapter headings)
+ * `XELATEX` for processing by `xelatex`
* `PALATINO` for the Palatino font
- * `HELVETIA` for the Helvetica font
+ * `HELVETICA` for the Helvetica font
* `A4PAPER` for A4 paper size
- * `A6PAPER` for A6 paper size (suitable for reading on small devices)
- * `MOVIE15` for using the movie15 LaTeX package to display movies
- * `PREAMBLE` to turn the LaTeX preamble on or off (i.e., complete
document or document to be included elsewhere)
- * `MINTED` for inclusion of the minted package (which requires `latex`
or `pdflatex` to be run with the `-shell-escape` option)
+ * `A6PAPER` for A6 paper size (suitable for reading PDFs on phones)
+ * `MOVIE` for specifying how movies are handled: the value `media9`
implies the `media9` package and the `\includemedia` command (default),
while other values are `movie15` (`\includemovie` command), `multimedia`
(for Beamer-style `\movie` command), or `href-run` (for the plain
`\hrun:file` command)
+ * `PREAMBLE` to turn the LaTeX preamble on or off (i.e., complete
document or document to be included elsewhere - and note that the
preamble is only included if the document has a title, author, and date)
+ * `MINTED` for inclusion of the minted package for typesetting of code
with the Pygments tool (which requires `latex` or `pdflatex` to be run
with the `-shell-escape` option)
+ * `TODONOTES` for using the fancy `todonotes` package for typesetting
inline comments (looks much like track changes in MS Word). This macro
has only effect if inline comments are used (name, colon, and comment
inside brackets).
+ * `LINENUMBERS` for inclusion of line numbers in the text.
+ * `AMON` for setting the type of admonitions: `"colors"` for colored
boxes with icons, `"graybox1"` for gray frame boxes with rounded corners
(default), `"graybox2"` for narrower square gray frame boxes (except for
summary, which for A4 format is small and with wrapped text around if it
does not contain verbatim code), or `"paragraph"` for simple, plain
paragraph headings and ordinary text
+ * `COLORED_TABLE_ROWS` for coloring every other table rows (set this
variable to `gray` or `blue`)
+ * `BLUE_SECTION_HEADINGS` for blue section and subsection headings
+ * `LATEX_HEADING` for the typesetting of the title, author, parts of
preamble (values: `traditional` for traditional LaTeX heading,
`titlepage` for a separate titlepage, `Springer_collection` for edited
volumes on Springer, `beamer` for Beamer slides, `doconce_heading`
(default) for listing institutions after names)
If you are not satisfied with the Doconce preamble, you can provide
-your own preamble by adding the command-line option
`--latex-preamble=myfile`.
+your own preamble by adding the command-line option
`--latex_preamble=myfile`.
In case `myfile` contains a documentclass definition, Doconce assumes
that the file contains the *complete* preamble you want (not that all
the packages listed in the default preamble are required and must be
@@ -521,9 +692,9 @@
for processing the `.p.tex` file. The command allows specifications
of code environments as well. Here is an example:
{{{
-Terminal> doconce ptex2tex mydoc -DLATEX_HEADING=traditional \
- -DPALATINO -DA6PAPER \
- "sys=\begin{quote}\begin{verbatim}@\end{verbatim}\end{quote}" \
+Terminal> doconce ptex2tex mydoc -DLATEX_HEADING=traditional \
+ -DPALATINO -DA6PAPER \
+ "sys=\begin{quote}\begin{verbatim}@\end{verbatim}\end{quote}" \
fpro=minted fcod=minted shcod=Verbatim envir=ans:nt
}}}
Note that `@` must be used to separate the begin and end LaTeX
@@ -544,16 +715,24 @@
edited with the aid of the `doconce replace` and `doconce subst`
commands. The former works with substituting text directly, while the
latter performs substitutions using regular expressions.
-Here are two examples:
+You will use `doconce replace` to edit `section{` to `section*{`:
{{{
Terminal> doconce replace 'section{' 'section*{' mydoc.tex
-Terminal> doconce subst 'title\{(.+)Using (.+)\}' \
+}}}
+For fixing the line break of a title, you may pick a word in the
+title, say "Using", and insert a break after than word. With
+`doconce subst` this is easy employing regular expressions with
+a group before "Using" and a group after:
+
+{{{
+Terminal> doconce subst 'title\{(.+)Using (.+)\}' \
'title{\g<1> \\\\ [1.5mm] Using \g<2>' mydoc.tex
}}}
A lot of tailored fixes to the LaTeX document can be done by
an appropriate set of text replacements and regular expression
substitutions. You are anyway encourged to make a script for
-generating PDF from the LaTeX file.
+generating PDF from the LaTeX file so the `doconce subst` or
+`doconce replace` commands can be put inside the script.
*Step 3.* Compile `mydoc.tex`
and create the PDF file:
@@ -589,6 +768,7 @@
specifications with `doconce ptex2tex`), the minted package is
automatically
included so there is no need for the `-DMINTED` option.
+
==== PDFLaTeX ====
Running `pdflatex` instead of `latex` follows almost the same steps,
@@ -603,6 +783,19 @@
Terminal> bibitem mydoc # if bibliography
Terminal> pdflatex -shell-escape mydoc
}}}
+
+==== XeLaTeX ====
+
+XeLaTeX is an alternative to pdfLaTeX and is run in almost the
+same way, except for the `-DXELATEX` flag to ptex2tex:
+
+{{{
+Terminal> doconce format pdflatex mydoc
+Terminal> doconce ptex2tex mydoc -DXELATEX
+Terminal> ptex2tex -DXELATEX mydoc # alternative
+Terminal> xelatex mydoc
+}}}
+
==== Plain ASCII Text ====
@@ -663,8 +856,8 @@
Sphinx documents demand quite some steps in their creation. We have
automated
most of the steps through the `doconce sphinx_dir` command:
{{{
-Terminal> doconce sphinx_dir author="authors' names" \
- title="some title" version=1.0 dirname=sphinxdir \
+Terminal> doconce sphinx_dir author="authors' names" \
+ title="some title" version=1.0 dirname=sphinxdir \
theme=mytheme file1 file2 file3 ...
}}}
The keywords `author`, `title`, and `version` are used in the headings
@@ -688,40 +881,119 @@
`automake_sphinx.py` for compiling the Sphinx document into an HTML
document. One can either run `automake_sphinx.py` or perform the
steps in the script manually, possibly with necessary modifications.
-You should at least read the script prior to executing it to have
-some idea of what is done.
+Normally, executing the script works well, but if you are new
+to Sphinx and end up producing quite some Sphinx documents, I encourave
+you to read the Sphinx documentation and study the `automake_sphinx.py`
+file.
-The `doconce sphinx_dir` script copies directories named `figs` or
-`figures` over to the Sphinx directory so that figures are accessible
-in the Sphinx compilation. If figures or movies are located in other
-directories, `automake_sphinx.py` must be edited accordingly. Files,
-to which there are local links (not `http:` or `file:` URLs), must be
-placed in the `_static` subdirectory of the Sphinx directory. The
-utility `doconce sphinxfix_localURLs` is run to check for local links
-in the Doconce file: for each such link, say `dir1/dir2/myfile.txt` it
-replaces the link by `_static/myfile.txt` and copies
-`dir1/dir2/myfile.txt` to a local `_static` directory (in the same
-directory as the script is run). However, we recommend instead that
-the writer of the document places files in `_static` or lets a script
-do it automatically. The user must copy all `_static/*` files to the
-`_static` subdirectory of the Sphinx directory. It may be wise to
-always put files, to which there are local links in the Doconce
-document, in a `_static` or `_static-name` directory and use these
-local links. Then links do not need to be modified when creating a
-Sphinx version of the document.
+*Links.* The `automake_sphinx.py` script copies directories named `fig*`
+over to the Sphinx directory so that figures are accessible
+in the Sphinx compilation. It also examines `MOVIE:` and `FIGURE:`
+commands in the Doconce file to find other image files and copies
+these too. I strongly recommend to put files
+to which there are local links (not `http:` or `file:` URLs) in
+a directory named `_static`. The `automake_sphinx.py` copies
+`_static*` to the Sphinx directory, which guarantees that the links
+to the local files will work in the Sphinx document.
-Doconce comes with a collection of HTML themes for Sphinx documents.
-These are packed out in the Sphinx directory, the `conf.py`
-configuration file for Sphinx is edited accordingly, and a script
+There is a utility `doconce sphinxfix_localURLs` for checking links to
+local files and moving the files to `_static` and changing the links
+accordingly. For example, a link to `dir1/dir2/myfile.txt` is changed
+to `_static/myfile.txt` and `myfile.txt` is copied to `_static`.
+However, I recommend instead that you manually copy
+files to `_static` when you want to link to them, or let your
+script which compiles the Doconce document do it automatically.
+
+*Themes.* Doconce comes with a rich collection of HTML themes for Sphinx
documents,
+much larger than what is found in the standard Sphinx distribution.
+Additional themes include
+`agni`,
+`basicstrap`,
+`bootstrap`,
+`cloud`,
+`fenics`,
+`fenics_minimal`,
+`flask`,
+`haiku`,
+`impressjs`,
+`jal`,
+`pylons`,
+`redcloud`,
+`scipy_lectures`,
+`slim-agogo`, and
+`vlinux-theme`.
+
+All the themes are packed out in the Sphinx directory, and the
+`doconce sphinx_dir` insert lots of extra code in the `conf.py`
+file to enable easy specification and customization of themes.
+For example, modules are loaded for the additional themes that
+come with Doconce, code is inserted to allow customization of
+the look and feel of themes, etc. The `conf.py` file is a
+good starting point for fine-tuning your favorite team, and your
+own `conf.py` file can later be supplied and used when running
+`doconce sphinx_dir`: simply add the command-line option
+`conf.py=conf.py`.
+
+A script
`make-themes.sh` can make HTML documents with one or more themes.
For example,
-to realize the themes `fenics` and `pyramid`, one writes
+to realize the themes `fenics`, `pyramid`, and `pylon` one writes
{{{
-Terminal> ./make-themes.sh fenics pyramid
+Terminal> ./make-themes.sh fenics pyramid pylon
}}}
The resulting directories with HTML documents are `_build/html_fenics`
and `_build/html_pyramid`, respectively. Without arguments,
-`make-themes.sh` makes all available themes (!).
+`make-themes.sh` makes all available themes (!). With `make-themes.sh`
+it is easy to check out various themes to find the one that is most
+attractive for your document.
+
+You may supply your own theme and avoid copying all the themes
+that come with Doconce into the Sphinx directory. Just specify
+`theme_dir=path` on the command line, where `path` is the relative
+path to the directory containing the Sphinx theme. You must also
+specify a configure file by `conf.py=path`, where `path` is the
+relative path to your `conf.py` file.
+
+*Example.* Say you like the `scipy_lectures` theme, but you want
+a table of contents to appear *to the right*, much in the same style
+as in the `default` theme (where the table of contents is to the left).
+You can then run `doconce sphinx_dir`, invoke a text editor with the
+`conf.py` file, find the line `html_theme == 'scipy_lectures'`,
+edit the following `nosidebar` to `false` and `rightsidebar` to `true`.
+Alternatively, you may write a little script using `doconce replace`
+to replace a portion of text in `conf.py` by a new one:
+
+{{{
+doconce replace "elif html_theme == 'scipy_lectures':
+ html_theme_options = {
+ 'nosidebar': 'true',
+ 'rightsidebar': 'false',
+ 'sidebarbgcolor': '#f2f2f2',
+ 'sidebartextcolor': '#20435c',
+ 'sidebarlinkcolor': '#20435c',
+ 'footerbgcolor': '#000000',
+ 'relbarbgcolor': '#000000',
+ }" "elif html_theme == 'scipy_lectures':
+ html_theme_options = {
+ 'nosidebar': 'false',
+ 'rightsidebar': 'true',
+ 'sidebarbgcolor': '#f2f2f2',
+ 'sidebartextcolor': '#20435c',
+ 'sidebarlinkcolor': '#20435c',
+ 'footerbgcolor': '#000000',
+ 'relbarbgcolor': '#000000',
+ }" conf.py
+}}}
+Obviously, we could also have changed colors in the edit above.
+The final alternative is to save the edited `conf.py` file somewhere
+and reuse it the next time `doconce sphinx_dir` is run
+
+{{{
+doconce sphinx_dir theme=scipy_lectures \
+ conf.py=../some/path/conf.py mydoc
+}}}
+
+==== The manual Sphinx procedure ====
If it is not desirable to use the autogenerated scripts explained
above, here is the complete manual procedure of generating a
@@ -811,6 +1083,7 @@
(`code-block:: python` in Sphinx syntax) and `cppcod` gives C++, but
all such arguments can be customized both for Sphinx and LaTeX output.
+
==== Wiki Formats ====
There are many different wiki formats, but Doconce only supports three:
@@ -868,11 +1141,12 @@
format(s). The `make.sh` files in `docs/manual` and `docs/tutorial`
constitute comprehensive examples on how such scripts can be made.
+
==== Demos ====
The current text is generated from a Doconce format stored in the file
{{{
-docs/tutorial/tutorial.do.txt
+doc/tutorial/tutorial.do.txt
}}}
The file `make.sh` in the `tutorial` directory of the
Doconce source code contains a demo of how to produce a variety of
@@ -891,6 +1165,11 @@
== Installation of Doconce and its Dependencies ==
+Below, we explain the manual installation of all software that may be
+needed when working with Doconce documents.
+The impatient way to install what is needed is to run the
+[doconce_install_all.sh `doconce_install_all.sh`] script.
+
==== Doconce ====
Doconce itself is pure Python code hosted at
http://code.google.com/p/doconce. Its installation from the
@@ -912,21 +1191,18 @@
sudo python setup.py install
}}}
-Debian GNU/Linux users can also run
-{{{
-sudo apt-get install doconce
-}}}
-This installs the latest release and not the most updated and bugfixed
-version.
-On Ubuntu one needs to run
-{{{
-sudo add-apt-repository ppa:scitools/ppa
-sudo apt-get update
-sudo apt-get install doconce
-}}}
==== Dependencies ====
+Producing HTML documents, plain text, pandoc-extended Markdown,
+and wikis can be done without installing any other
+software. However, if you want other formats as output
+(LaTeX, Sphinx, reStructuredText) and assisting utilities such
+as preprocesors, spellcheck, file differences, bibliographies,
+and so on, the software below must be installed.
+
+<wiki:comment> Make a debpkg_doconce.txt file with everything that is
needed on Debian </wiki:comment>
+
==== Preprocessors ====
If you make use of the [http://code.google.com/p/preprocess Preprocess]
@@ -981,6 +1257,13 @@
{{{
sudo apt-get install texlive-extra-utils
}}}
+
+Automatic image conversion from EPS to PDF calls up `epstopdf`, which
+can be installed by
+
+{{{
+sudo apt-get install texlive-font-utils
+}}}
==== Spellcheck ====
@@ -990,6 +1273,25 @@
{{{
sudo apt-get install ispell
}}}
+
+
+==== Bibliography ====
+
+The Python package [https://bitbucket.org/logg/publish Publish] is needed
if you use a bibliography
+in your document. On the website, click on *Clone*, copy the
+command and run it:
+
+{{{
+hg clone https://bitbucket.org/logg/publish
+}}}
+Thereafter go to the `publish` directory and run the `setup.py` script
+for installing Publish:
+
+{{{
+cd publish
+sudo python setup.py
+}}}
+
==== Ptex2tex for LaTeX Output ====
@@ -1015,7 +1317,7 @@
are also needed. These are installed by
{{{
-sudo apt-get install texlive-latex-recommended texlive-latex-extra
+sudo apt-get install texlive
}}}
on Debian Linux (including Ubuntu) systems. TeXShop on Mac comes with
the necessary stylefiles (if not, they can be found by googling and
installed
@@ -1038,17 +1340,70 @@
cd pygments
sudo python setup.py install
}}}
+One can also do the simple
+
+{{{
+pip install sphinx
+}}}
+which also installs pygments.
If you use the minted style together with `ptex2tex`, you have to
enable it by the `-DMINTED` command-line argument to `ptex2tex`.
This is not necessary if you run the alternative `doconce ptex2tex`
program.
-All
-use of the minted style requires the `-shell-escape` command-line
+All use of the minted style requires the `-shell-escape` command-line
argument when running LaTeX, i.e., `latex -shell-escape` or `pdflatex
-shell-escape`.
-<wiki:comment> Say something about anslistings.sty </wiki:comment>
+Inline comments apply the `todonotes` LaTeX package if the `ptex2tex`
+or `doconce ptex2tex` command is run with `-DTODONOTES`. The
+`todonotes` package requires several other packages: `xcolor`,
+`ifthen`, `xkeyval`, `tikz`, `calc`, `graphicx`, and `setspace`. The
+relevant Debian packages for installing all this are listed below.
+
+==== LaTeX packages ====
+
+Many LaTeX packages are potentially needed (depending on various
+preprocessor variables given to `ptex2tex` or `doconce ptex2tex`. The
+standard packages always included are `relsize`, `epsfig`, `makeidx`,
+`setspace`, `color`, `amsmath`, `amsfonts`, `xcolor`, `bm`,
+`microtype`, `titlesec`, and `hyperref`. The `ptex2tex` package (from
+[http://code.google.com/p/ptex2tex ptex2tex]) is also included, but
+removed again if `doconce ptex2tex` is run instead of the `ptex2tex`
+program, meaning that if you do not use `ptex2tex`, you do not need
+`ptex2tex.sty`. Optional packages that might be included are `minted`,
+`fontspec`, `xunicode`, `inputenc`, `helvet`, `mathpazo`, `wrapfig`,
+`calc`, `ifthen`, `xkeyval`, `tikz`, `graphicx`, `setspace`, `shadow`,
+`disable`, `todonotes`, `lineno`, `xr`, `framed`, `mdframe`,
+`movie15`, `a4paper`, and `a6paper`.
+
+Relevant Debian packages that gives you all of these LaTeX packages are
+
+{{{
+texlive
+texlive-extra-utils
+texlive-latex-extra
+texlive-font-utils
+}}}
+On old Ubuntu 12.04 one has to do `sudo add-apt-repository
ppa:texlive-backports/ppa` and `sudo apt-get update` first, or
alternatively install these as well:
+
+{{{
+texlive-math-extra
+texlive-bibtex-extra
+texlive-xetex
+texlive-humanities
+texlive-pictures
+}}}
+Alternatively, one may pull in `texlive-full` to get all available
+style files.
+
+If you want to use the *anslistings* code environment with `ptex2tex`
+(`.ptex2tex.cfg` styles `Python_ANS`, `Python_ANSt`, `Cpp_ANS`, etc.) or
***The diff for this file has been truncated for email.***
Reply all
Reply to author
Forward
0 new messages