[doconce] push by h...@simula.no - updates on 2013-06-29 14:20 GMT
7 views
Skip to first unread message
doc...@googlecode.com
Jun 29, 2013, 10:20:48 AM6/29/13
to docon...@googlegroups.com
Revision: 942b05f56ab5
Branch: default
Author: "Hans Petter Langtangen <h...@simula.no>"
Date: Sat Jun 29 07:20:35 2013
Log: updates
http://code.google.com/p/doconce/source/detail?r=942b05f56ab5
Deleted:
/doc/demos/manual/manual.st
=======================================
--- /doc/demos/manual/manual.st Wed May 29 03:54:41 2013
+++ /dev/null
@@ -1,3981 +0,0 @@
-TITLE: Doconce Description
-BY: Hans Petter Langtangen (Center for Biomedical Computing, Simula
Research Laboratory, and Department of Informatics, University of Oslo)
-DATE: May 29, 2013
-What Is Doconce?
-
-
-Doconce is a very simple and minimally tagged markup language that
-looks like ordinary ASCII text, much like what you would use in an
-email, but the text can be transformed to numerous other formats,
-including HTML, Sphinx, LaTeX, PDF, reStructuredText (reST), Markdown,
-MediaWiki, Google wiki, Creole wiki, blogger.com, wordpress.com,
-Epytext, and also plain (untagged) text for email.
-From reST or Markdown you can go to XML, OpenOffice, MS
-Word, HTML, LaTeX, PDF, DocBook, GNU Texinfo, and more.
-
-Doconce supports a working strategy of never duplicating information.
-Text is written in a single place and then transformed to a number of
-different destinations of diverse type: scientific reports, software
-manuals, books, thesis, software source code, wikis, blogs, emails,
-etc. The slogan is: "Write once, include anywhere".
-
-Here are some Doconce features:
-
- - Doconce addresses small and large documents containing
- *text with much computer source code and
- LaTeX mathematics*, where the output is desired in different formats
- such as LaTeX, pdfLaTeX, Sphinx, HTML,
- MediaWiki, blogger.com, and wordpress.com.
- A piece of Doconce text can enter (e.g.) a classical
- science book, an ebook, a web document, and a blog.
- - Doconce targets in particular large book projects where many different
- pieces of text and software can be assembled and published in different
- formats for different devices.
- - Doconce enables authors who write for many times of media
- (blogs, wikis, LaTeX manuscripts, Sphinx, HTML) to use a common
- source language such that lots of different pieces can easily be
- brought together later to form a coherent (big) document.
- - Doconce has good support for copying computer code
- directly from the source code files via regular expressions
- for the start and end lines.
- - Doconce first runs two preprocessors (Preprocess and Mako), which
- allow programming constructs (includes, if-tests, function calls)
- as part of the text. This feature makes it easy to write *one text*
- with different flavors: long vs short text, Python vs Matlab code
- examples, experimental vs mature content.
- - Doconce can be converted to plain *untagged* text,
- often desirable for email and computer code documentation.
- - Doconce markup does include tags, so the format is more tagged than
- Markdown, but less than reST, and very much less than
- LaTeX and HTML.
- - Compared to the related tools Sphinx and Markdown, Doconce
- allows more types of equations (especially systems of
- equations with references), has more flexible
- inclusion of source code, integrates preprocessors, has
- special support for exercises, and produces
- cleaner LaTeX and HTML output.
-
-*History.* Doconce was developed in 2006 at a time when most popular
-markup languages used quite some tagging. Later, almost untagged
-markup languages like Markdown and Pandoc became popular. Doconce is
-not a replacement of Pandoc, which is a considerably more
-sophisticated project. Moreover, Doconce was developed mainly to
-fulfill the needs for a flexible source code base for books with much
-mathematics and computer code.
-
-*Disclaimer.* Doconce is a simple tool, largely based on interpreting
-and handling text through regular expressions. The possibility for
-tweaking the layout is obviously limited since the text can go to
-all sorts of sophisticated markup languages. Moreover, because of
-limitations of regular expressions, some formatting of Doconce syntax
-may face problems when transformed to HTML, LaTeX, Sphinx, and similar
-formats.
-
-
-
-
-
-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":http://code.google.com/p/doconce.
Its installation from the
-Mercurial ('hg') source follows the standard procedure::
-
-
- # Doconce
- hg clone https://code.google.com/p/doconce/ doconce
- cd doconce
- sudo python setup.py install
- cd ..
-
-Since Doconce is frequently updated, it is recommended to use the
-above procedure and whenever a problem occurs, make sure to
-update to the most recent version::
-
-
- cd doconce
- hg pull
- hg update
- sudo python setup.py install
-
-
-
-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.
-
-
-Preprocessors
-
-If you make use of the "http://code.google.com/p/preprocess":Preprocess
-preprocessor, this program must be installed::
-
-
- svn checkout http://preprocess.googlecode.com/svn/trunk/ preprocess
- cd preprocess
- cd doconce
- sudo python setup.py install
- cd ..
-
-
-A much more advanced alternative to Preprocess is
-"http://www.makotemplates.org":Mako. Its installation is most
-conveniently done by 'pip',
-
-!bc sys
- pip install Mako
-
-This command requires 'pip' to be installed. On Debian Linux systems,
-such as Ubuntu, the installation is simply done by::
-
-
- sudo apt-get install python-pip
-
-Alternatively, one can install from
the 'pip' "http://pypi.python.org/pypi/pip":source code.
-
-Mako can also be installed directly from
-"http://www.makotemplates.org/download.html":source: download the
-tarball, pack it out, go to the directory and run
-the usual 'sudo python setup.py install'.
-
-Image file handling
-
-Different output formats require different formats of image files.
-For example, PostScript or Encapuslated PostScript is required for 'latex'
-output, while HTML needs JPEG, GIF, or PNG formats.
-Doconce calls up programs from the ImageMagick suite for converting
-image files to a proper format if needed.
The "http://www.imagemagick.org/script/index.php":ImageMagick suite can be
installed on all major platforms.
-On Debian Linux (including Ubuntu) systems one can simply write::
-
-
- sudo apt-get install imagemagick
-
-
-The convenience program 'doconce combine_images', for combining several
-images into one, will use 'montage' and 'convert' from ImageMagick and
-the 'pdftk', 'pdfnup', and 'pdfcrop' programs from
the 'texlive-extra-utils'
-Debian package. The latter gets installed by::
-
-
- 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
-
-The utility 'doconce spellcheck' applies the 'ispell' program for
-spellcheck. On Debian (including Ubuntu) it is installed by::
-
-
- 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
-
-To make LaTeX documents with very flexible choice of typesetting of
-verbatim code blocks you need "http://code.google.com/p/ptex2tex":ptex2tex,
-which is installed by::
-
-
- svn checkout http://ptex2tex.googlecode.com/svn/trunk/ ptex2tex
- cd ptex2tex
- sudo python setup.py install
-
-It may happen that you need additional style files, you can run
-a script, 'cp2texmf.sh':
-
-!bc sys
- cd latex
- sh cp2texmf.sh # copy stylefiles to ~/texmf directory
- cd ../..
-
-This script copies some special stylefiles that
-that 'ptex2tex' potentially makes use of. Some more standard stylefiles
-are also needed. These are installed by::
-
-
- 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
-manually in the '~/texmf/tex/latex/misc' directory).
-
-Note that the 'doconce ptex2tex' command, which needs no installation
-beyond Doconce itself, can be used as a simpler alternative to
the 'ptex2tex'
-program.
-
-The *minted* LaTeX style is offered by 'ptex2tex' and 'doconce ptext2tex'
-and popular among many
-users. This style requires the package "http://pygments.org":Pygments
-to be installed. On Debian Linux::
-
-
- sudo apt-get install python-pygments
-
-Alternatively, the package can be installed manually::
-
-
- hg clone ssh://h...@bitbucket.org/birkenfeld/pygments-main pygments
- 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
-argument when running LaTeX, i.e., 'latex -shell-escape' or 'pdflatex
--shell-escape'.
-
-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
-
-The 'rst' output from Doconce allows further transformation to LaTeX,
-HTML, XML, OpenOffice, and so on, through
the "http://docutils.sourceforge.net":docutils package. The installation
of the
-most recent version can be done by::
-
-
- 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
-
-
-There is a possibility to create PDF files from reST documents
-using ReportLab instead of LaTeX. The enabling software is
-"http://code.google.com/p/rst2pdf":rst2pdf. Either download the tarball
-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,
-installed by::
-
-
- hg clone https://bitbucket.org/birkenfeld/sphinx
- cd sphinx
- 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":https://bitbucket.org/ecollins/cloud_sptheme
- -
bootstrap: "https://github.com/ryan-roemer/sphinx-bootstrap-theme":https://github.com/ryan-roemer/sphinx-bootstrap-theme
- -
solarized: "https://bitbucket.org/miiton/sphinxjp.themes.solarized":https://bitbucket.org/miiton/sphinxjp.themes.solarized
- -
impressjs: "https://github.com/shkumagai/sphinxjp.themes.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
-
-The Doconce format 'pandoc' outputs the document in the Pandoc
-extended Markdown format, which via the 'pandoc' program can be
-translated to a range of other formats. Installation
of "http://johnmacfarlane.net/pandoc/":Pandoc, written in Haskell, is most
-easily done by::
-
-
- sudo apt-get install pandoc
-
-on Debian (Ubuntu) systems.
-
-Epydoc Output
-
-When the output format is 'epydoc' one needs that program too, installed
-by::
-
-
- svn co
https://epydoc.svn.sourceforge.net/svnroot/epydoc/trunk/epydoc epydoc
- cd epydoc
- sudo make install
- cd ..
-
-
-*Remark.* Several of the packages above installed from source code
-are also available in Debian-based system through the
-'apt-get install' command. However, we recommend installation directly
-from the version control system repository as there might be important
-updates and bug fixes. For 'svn' directories, go to the directory,
-run 'svn update', and then 'sudo python setup.py install'. For
-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 ../../..
-
-
-
-Demos
-
-
-The current text is generated from a Doconce format stored in the::
-
-
- docs/manual/manual.do.txt
-
-file in the Doconce source code tree. We have made a
-"https://doconce.googlecode.com/hg/doc/demos/manual/index.html":demo web
page
-where you can compare the Doconce source with the output in many
-different formats: HTML, LaTeX, plain text, etc.
-
-The file 'make.sh' in the same directory as the 'manual.do.txt' file
-(the current text) shows how to run 'doconce format' on the
-Doconce file to obtain documents in various formats.
-
-Another demo is found in::
-
-
- docs/tutorial/tutorial.do.txt
-
-In the 'tutorial' directory there is also a 'make.sh' file producing a
-lot of formats, with a corresponding
-"https://doconce.googlecode.com/hg/doc/demos/tutorial/index.html":web demo
-of the results.
-
-
-
-From Doconce to Other Formats
-
-Transformation of a Doconce document 'mydoc.do.txt' to various other
-formats applies the script 'doconce format':
-!bc sys
- Terminal> doconce format format mydoc.do.txt
-
-or just::
-
-
- 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
-
-The 'preprocess' and 'mako' programs are used to preprocess the
-file, and options to 'preprocess' and/or 'mako' can be added after the
-filename. For example::
-
-
- Terminal> doconce format latex mydoc -Dextra_sections -DVAR1=5
# preprocess
- Terminal> doconce format latex yourdoc extra_sections=True VAR1=5
# mako
-
-The variable 'FORMAT' is always defined as the current format when
-running 'preprocess' or 'mako'. That is, in the last example, 'FORMAT' is
-defined as 'latex'. Inside the Doconce document one can then perform
-format specific actions through tests like '#if FORMAT == "latex"'
-(for 'preprocess') or '% if FORMAT == "latex":' (for 'mako').
-
-Removal of inline comments
-
-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::
-
-
- Terminal> doconce format latex mydoc --skip_inline_comments
-
-One can also remove all such comments from the original Doconce
-file by running::
-
-
- Terminal> doconce remove_inline_comments mydoc
-
-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'
-is performed by::
-
-
- Terminal> doconce format html mydoc
-
-The resulting file 'mydoc.html' can be loaded into any web browser for
viewing.
-
-The HTML style can be defined either in the header of the HTML file,
-using a named built-in style;
-in an external CSS file; or in a template file.
-
-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
-
- - 'solarized': the famous "http://ethanschoonover.com/solarized":solarized
- style (yellowish),
- - 'blueish': a simple style with blue headings (default),
- - 'blueish2': a variant of *bluish*,
- - 'bloodish': as 'bluish', but dark read as color.
-
-Using '--css=filename' where 'filename' is a non-existing file makes
-Doconce write the built-in style to that file. Otherwise the HTML
-links to the CSS stylesheet in 'filename'. Several stylesheets can
-be specified: '--ccs=file1.css,file2.css,file3.css'.
-
-Templates are HTML files with "slots" '%(main)s' for the main body
-of text, '%(title)s' for the title, and '%(date)s' for the date.
-Doconce comes with a few templates. The usage of templates is
-described in
a "https://doconce.googlecode.com/hg/doc/design/wrapper_tech.html":separate
document. That document describes how you your Doconce-generated
-HTML file can have any specified layout.
-
-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'
-turns off the use of Pygments and makes code blocks appear with
-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'
-can be 'default', 'emacs', 'perldoc', and other valid names for
-Pygments styles.
-
-The HTML file can be embedded in a template with your own tailored
-design, see
a "tutorial": " "https://doconce.googlecode.com/hg/doc/design/wrapper_tech.html":https://doconce.googlecode.com/hg/doc/design/wrapper_tech.html"
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. The
-latter is the
-Doconce document translated to HTML. The title becomes the first
-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
-
-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.
-
-
-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.
-
-1. Write the blog text as a Doconce document without any
- title, author, and date.
-2. Generate HTML as described above.
-3. 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
-
-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.
-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":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
-
-Output in Pandoc's extended Markdown format results from::
-
-
- Terminal> doconce format pandoc mydoc
-
-The name of the output file is 'mydoc.mkd'.
-From this format one can go to numerous other formats::
-
-
- Terminal> pandoc -R -t mediawiki -o mydoc.mwk --toc mydoc.mkd
-
-Pandoc supports 'latex', 'html', 'odt' (OpenOffice), 'docx' (Microsoft
-Word), 'rtf', 'texinfo', to mention some. The '-R' option makes
-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. The HTML output from
-'pandoc' needs adjustments to provide full support for MathJax LaTeX
-mathematics, and for this purpose one should use 'doconce md2html':
-
-!bc sys
- 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 '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
- Terminal> doconce ptex2tex mydoc
- 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, '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
-inline verbatim text. Moreover, quite some additional 'doconce
-replace' and 'doconce subst' edits might be needed on the '.mkd' or
-'.tex' files to successfully have mathematics that is well translated
-to MS Word. Also when going to reStructuredText using Pandoc, it can
-be advantageous to go via LaTeX.
-
-Here is an example where we take a Doconce snippet (without title, author,
-and date), maybe with some unnumbered equations, and quickly generate
-HTML with mathematics displayed my MathJax::
-
-
- Terminal> doconce format pandoc mydoc
- Terminal> pandoc -t html -o mydoc.html -s --mathjax mydoc.mkd
-
-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:
-
-*Step 1.* Filter the doconce text to a pre-LaTeX form 'mydoc.p.tex' for
-the 'ptex2tex' program (or 'doconce ptex2tex')::
-
-
- Terminal> doconce format latex mydoc
-
-LaTeX-specific commands ("newcommands") in math formulas and similar
-can be placed in files 'newcommands.tex', 'newcommands_keep.tex', or
-'newcommands_replace.tex' (see the section "Macros (Newcommands)").
-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
-aimed at being printed. For example, links to web resources are
-associated with a footnote listing the complete web address (URL).
-
-*Step 2.* Run 'ptex2tex' (if you have it) to make a standard LaTeX file::
-
-
- Terminal> ptex2tex mydoc
-
-In case you do not have 'ptex2tex', you may run a (very) simplified
version::
-
-
- Terminal> doconce ptex2tex mydoc
-
-
-Note that Doconce generates a '.p.tex' file with some preprocessor macros
-that can be used to steer certain properties of the LaTeX document.
-For example, to turn on the Helvetica font instead of the standard
-Computer Modern font, run::
-
-
- Terminal> ptex2tex -DHELVETICA mydoc
- Terminal> doconce ptex2tex mydoc -DHELVETICA # alternative
-
-The title, authors, and date are by default typeset in a non-standard
-way to enable a nicer treatment of multiple authors having
-institutions in common. However, the standard LaTeX "maketitle" heading
-is also available through '-DLATEX_HEADING=traditional'.
-A separate titlepage can be generate by
-'-DLATEX_HEADING=titlepage'.
-
-Preprocessor variables to be defined or undefined are
-
- - 'XELATEX' for processing by 'xelatex'
- - 'PALATINO' for the Palatino font
- - 'HELVETICA' for the Helvetica font
- - 'A4PAPER' for A4 paper size
- - '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 '\href{run: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'.
-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
-present in 'myfile'). Otherwise, 'myfile' is assumed to contain
-*additional* LaTeX code to be added to the Doconce default preamble.
-
-The 'ptex2tex' tool makes it possible to easily switch between many
-different fancy formattings of computer or verbatim code in LaTeX
-documents. After any '!bc' command in the Doconce source you can
-insert verbatim block styles as defined in your '.ptex2tex.cfg'
-file, e.g., '!bc sys' for a terminal session, where 'sys' is set to
-a certain environment in '.ptex2tex.cfg' (e.g., 'CodeTerminal').
-There are about 40 styles to choose from, and you can easily add
-new ones.
-
-Also the 'doconce ptex2tex' command supports preprocessor directives
-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}"
\
- fpro=minted fcod=minted shcod=Verbatim envir=ans:nt
-
-Note that '@' must be used to separate the begin and end LaTeX
-commands, unless only the environment name is given (such as 'minted'
-above, which implies '\begin{minted}{fortran}' and '\end{minted}' as
-begin and end for blocks inside '!bc fpro' and '!ec'). Specifying
-'envir=ans:nt' means that all other environments are typeset with the
-'anslistings.sty' package, e.g., '!bc cppcod' will then result in
-'\begin{c++}'. If no environments like 'sys', 'fpro', or the common
-'envir' are defined on the command line, the plain '\begin{verbatim}'
-and '\end{verbatim}' used.
-
-
-*Step 2b (optional).* Edit the 'mydoc.tex' file to your needs.
-For example, you may want to substitute 'section' by 'section*' to
-avoid numbering of sections, you may want to insert linebreaks
-(and perhaps space) in the title, etc. This can be automatically
-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.
-You will use 'doconce replace' to edit 'section{' to 'section*{':
-!bc sys
- 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 so the 'doconce subst' or
-'doconce replace' commands can be put inside the script.
-
-*Step 3.* Compile 'mydoc.tex'
-and create the PDF file::
-
-
- Terminal> latex mydoc
- Terminal> latex mydoc
- Terminal> makeindex mydoc # if index
- Terminal> bibitem mydoc # if bibliography
- Terminal> latex mydoc
- Terminal> dvipdf mydoc
-
-
-If one wishes to run 'ptex2tex' and use the minted LaTeX package for
-typesetting code blocks ('Minted_Python', 'Minted_Cpp', etc., in
-'ptex2tex' specified through the '*pro' and '*cod' variables in
-'.ptex2tex.cfg' or '$HOME/.ptex2tex.cfg'), the minted LaTeX package is
-needed. This package is included by running 'ptex2tex' with the
-'-DMINTED' option::
-
-
- Terminal> ptex2tex -DMINTED mydoc
-
-In this case, 'latex' must be run with the
-'-shell-escape' option::
-
-
- Terminal> latex -shell-escape mydoc
- Terminal> latex -shell-escape mydoc
- Terminal> makeindex mydoc # if index
- Terminal> bibitem mydoc # if bibliography
- Terminal> latex -shell-escape mydoc
- Terminal> dvipdf mydoc
-
-When running 'doconce ptex2tex mydoc envir=minted' (or other minted
-specifications with 'doconce ptex2tex'), the minted package is
automatically
-included so there is no need for the '-DMINTED' option.
-
-
-PDFLaTeX
***The diff for this file has been truncated for email.***
Branch: default
Author: "Hans Petter Langtangen <h...@simula.no>"
Date: Sat Jun 29 07:20:35 2013
Log: updates
http://code.google.com/p/doconce/source/detail?r=942b05f56ab5
Deleted:
/doc/demos/manual/manual.st
=======================================
--- /doc/demos/manual/manual.st Wed May 29 03:54:41 2013
+++ /dev/null
@@ -1,3981 +0,0 @@
-TITLE: Doconce Description
-BY: Hans Petter Langtangen (Center for Biomedical Computing, Simula
Research Laboratory, and Department of Informatics, University of Oslo)
-DATE: May 29, 2013
-What Is Doconce?
-
-
-Doconce is a very simple and minimally tagged markup language that
-looks like ordinary ASCII text, much like what you would use in an
-email, but the text can be transformed to numerous other formats,
-including HTML, Sphinx, LaTeX, PDF, reStructuredText (reST), Markdown,
-MediaWiki, Google wiki, Creole wiki, blogger.com, wordpress.com,
-Epytext, and also plain (untagged) text for email.
-From reST or Markdown you can go to XML, OpenOffice, MS
-Word, HTML, LaTeX, PDF, DocBook, GNU Texinfo, and more.
-
-Doconce supports a working strategy of never duplicating information.
-Text is written in a single place and then transformed to a number of
-different destinations of diverse type: scientific reports, software
-manuals, books, thesis, software source code, wikis, blogs, emails,
-etc. The slogan is: "Write once, include anywhere".
-
-Here are some Doconce features:
-
- - Doconce addresses small and large documents containing
- *text with much computer source code and
- LaTeX mathematics*, where the output is desired in different formats
- such as LaTeX, pdfLaTeX, Sphinx, HTML,
- MediaWiki, blogger.com, and wordpress.com.
- A piece of Doconce text can enter (e.g.) a classical
- science book, an ebook, a web document, and a blog.
- - Doconce targets in particular large book projects where many different
- pieces of text and software can be assembled and published in different
- formats for different devices.
- - Doconce enables authors who write for many times of media
- (blogs, wikis, LaTeX manuscripts, Sphinx, HTML) to use a common
- source language such that lots of different pieces can easily be
- brought together later to form a coherent (big) document.
- - Doconce has good support for copying computer code
- directly from the source code files via regular expressions
- for the start and end lines.
- - Doconce first runs two preprocessors (Preprocess and Mako), which
- allow programming constructs (includes, if-tests, function calls)
- as part of the text. This feature makes it easy to write *one text*
- with different flavors: long vs short text, Python vs Matlab code
- examples, experimental vs mature content.
- - Doconce can be converted to plain *untagged* text,
- often desirable for email and computer code documentation.
- - Doconce markup does include tags, so the format is more tagged than
- Markdown, but less than reST, and very much less than
- LaTeX and HTML.
- - Compared to the related tools Sphinx and Markdown, Doconce
- allows more types of equations (especially systems of
- equations with references), has more flexible
- inclusion of source code, integrates preprocessors, has
- special support for exercises, and produces
- cleaner LaTeX and HTML output.
-
-*History.* Doconce was developed in 2006 at a time when most popular
-markup languages used quite some tagging. Later, almost untagged
-markup languages like Markdown and Pandoc became popular. Doconce is
-not a replacement of Pandoc, which is a considerably more
-sophisticated project. Moreover, Doconce was developed mainly to
-fulfill the needs for a flexible source code base for books with much
-mathematics and computer code.
-
-*Disclaimer.* Doconce is a simple tool, largely based on interpreting
-and handling text through regular expressions. The possibility for
-tweaking the layout is obviously limited since the text can go to
-all sorts of sophisticated markup languages. Moreover, because of
-limitations of regular expressions, some formatting of Doconce syntax
-may face problems when transformed to HTML, LaTeX, Sphinx, and similar
-formats.
-
-
-
-
-
-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":http://code.google.com/p/doconce.
Its installation from the
-Mercurial ('hg') source follows the standard procedure::
-
-
- # Doconce
- hg clone https://code.google.com/p/doconce/ doconce
- cd doconce
- sudo python setup.py install
- cd ..
-
-Since Doconce is frequently updated, it is recommended to use the
-above procedure and whenever a problem occurs, make sure to
-update to the most recent version::
-
-
- cd doconce
- hg pull
- hg update
- sudo python setup.py install
-
-
-
-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.
-
-
-Preprocessors
-
-If you make use of the "http://code.google.com/p/preprocess":Preprocess
-preprocessor, this program must be installed::
-
-
- svn checkout http://preprocess.googlecode.com/svn/trunk/ preprocess
- cd preprocess
- cd doconce
- sudo python setup.py install
- cd ..
-
-
-A much more advanced alternative to Preprocess is
-"http://www.makotemplates.org":Mako. Its installation is most
-conveniently done by 'pip',
-
-!bc sys
- pip install Mako
-
-This command requires 'pip' to be installed. On Debian Linux systems,
-such as Ubuntu, the installation is simply done by::
-
-
- sudo apt-get install python-pip
-
-Alternatively, one can install from
the 'pip' "http://pypi.python.org/pypi/pip":source code.
-
-Mako can also be installed directly from
-"http://www.makotemplates.org/download.html":source: download the
-tarball, pack it out, go to the directory and run
-the usual 'sudo python setup.py install'.
-
-Image file handling
-
-Different output formats require different formats of image files.
-For example, PostScript or Encapuslated PostScript is required for 'latex'
-output, while HTML needs JPEG, GIF, or PNG formats.
-Doconce calls up programs from the ImageMagick suite for converting
-image files to a proper format if needed.
The "http://www.imagemagick.org/script/index.php":ImageMagick suite can be
installed on all major platforms.
-On Debian Linux (including Ubuntu) systems one can simply write::
-
-
- sudo apt-get install imagemagick
-
-
-The convenience program 'doconce combine_images', for combining several
-images into one, will use 'montage' and 'convert' from ImageMagick and
-the 'pdftk', 'pdfnup', and 'pdfcrop' programs from
the 'texlive-extra-utils'
-Debian package. The latter gets installed by::
-
-
- 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
-
-The utility 'doconce spellcheck' applies the 'ispell' program for
-spellcheck. On Debian (including Ubuntu) it is installed by::
-
-
- 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
-
-To make LaTeX documents with very flexible choice of typesetting of
-verbatim code blocks you need "http://code.google.com/p/ptex2tex":ptex2tex,
-which is installed by::
-
-
- svn checkout http://ptex2tex.googlecode.com/svn/trunk/ ptex2tex
- cd ptex2tex
- sudo python setup.py install
-
-It may happen that you need additional style files, you can run
-a script, 'cp2texmf.sh':
-
-!bc sys
- cd latex
- sh cp2texmf.sh # copy stylefiles to ~/texmf directory
- cd ../..
-
-This script copies some special stylefiles that
-that 'ptex2tex' potentially makes use of. Some more standard stylefiles
-are also needed. These are installed by::
-
-
- 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
-manually in the '~/texmf/tex/latex/misc' directory).
-
-Note that the 'doconce ptex2tex' command, which needs no installation
-beyond Doconce itself, can be used as a simpler alternative to
the 'ptex2tex'
-program.
-
-The *minted* LaTeX style is offered by 'ptex2tex' and 'doconce ptext2tex'
-and popular among many
-users. This style requires the package "http://pygments.org":Pygments
-to be installed. On Debian Linux::
-
-
- sudo apt-get install python-pygments
-
-Alternatively, the package can be installed manually::
-
-
- hg clone ssh://h...@bitbucket.org/birkenfeld/pygments-main pygments
- 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
-argument when running LaTeX, i.e., 'latex -shell-escape' or 'pdflatex
--shell-escape'.
-
-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
-
-The 'rst' output from Doconce allows further transformation to LaTeX,
-HTML, XML, OpenOffice, and so on, through
the "http://docutils.sourceforge.net":docutils package. The installation
of the
-most recent version can be done by::
-
-
- 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
-
-
-There is a possibility to create PDF files from reST documents
-using ReportLab instead of LaTeX. The enabling software is
-"http://code.google.com/p/rst2pdf":rst2pdf. Either download the tarball
-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,
-installed by::
-
-
- hg clone https://bitbucket.org/birkenfeld/sphinx
- cd sphinx
- 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":https://bitbucket.org/ecollins/cloud_sptheme
- -
bootstrap: "https://github.com/ryan-roemer/sphinx-bootstrap-theme":https://github.com/ryan-roemer/sphinx-bootstrap-theme
- -
solarized: "https://bitbucket.org/miiton/sphinxjp.themes.solarized":https://bitbucket.org/miiton/sphinxjp.themes.solarized
- -
impressjs: "https://github.com/shkumagai/sphinxjp.themes.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
-
-The Doconce format 'pandoc' outputs the document in the Pandoc
-extended Markdown format, which via the 'pandoc' program can be
-translated to a range of other formats. Installation
of "http://johnmacfarlane.net/pandoc/":Pandoc, written in Haskell, is most
-easily done by::
-
-
- sudo apt-get install pandoc
-
-on Debian (Ubuntu) systems.
-
-Epydoc Output
-
-When the output format is 'epydoc' one needs that program too, installed
-by::
-
-
- svn co
https://epydoc.svn.sourceforge.net/svnroot/epydoc/trunk/epydoc epydoc
- cd epydoc
- sudo make install
- cd ..
-
-
-*Remark.* Several of the packages above installed from source code
-are also available in Debian-based system through the
-'apt-get install' command. However, we recommend installation directly
-from the version control system repository as there might be important
-updates and bug fixes. For 'svn' directories, go to the directory,
-run 'svn update', and then 'sudo python setup.py install'. For
-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 ../../..
-
-
-
-Demos
-
-
-The current text is generated from a Doconce format stored in the::
-
-
- docs/manual/manual.do.txt
-
-file in the Doconce source code tree. We have made a
-"https://doconce.googlecode.com/hg/doc/demos/manual/index.html":demo web
page
-where you can compare the Doconce source with the output in many
-different formats: HTML, LaTeX, plain text, etc.
-
-The file 'make.sh' in the same directory as the 'manual.do.txt' file
-(the current text) shows how to run 'doconce format' on the
-Doconce file to obtain documents in various formats.
-
-Another demo is found in::
-
-
- docs/tutorial/tutorial.do.txt
-
-In the 'tutorial' directory there is also a 'make.sh' file producing a
-lot of formats, with a corresponding
-"https://doconce.googlecode.com/hg/doc/demos/tutorial/index.html":web demo
-of the results.
-
-
-
-From Doconce to Other Formats
-
-Transformation of a Doconce document 'mydoc.do.txt' to various other
-formats applies the script 'doconce format':
-!bc sys
- Terminal> doconce format format mydoc.do.txt
-
-or just::
-
-
- 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
-
-The 'preprocess' and 'mako' programs are used to preprocess the
-file, and options to 'preprocess' and/or 'mako' can be added after the
-filename. For example::
-
-
- Terminal> doconce format latex mydoc -Dextra_sections -DVAR1=5
# preprocess
- Terminal> doconce format latex yourdoc extra_sections=True VAR1=5
# mako
-
-The variable 'FORMAT' is always defined as the current format when
-running 'preprocess' or 'mako'. That is, in the last example, 'FORMAT' is
-defined as 'latex'. Inside the Doconce document one can then perform
-format specific actions through tests like '#if FORMAT == "latex"'
-(for 'preprocess') or '% if FORMAT == "latex":' (for 'mako').
-
-Removal of inline comments
-
-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::
-
-
- Terminal> doconce format latex mydoc --skip_inline_comments
-
-One can also remove all such comments from the original Doconce
-file by running::
-
-
- Terminal> doconce remove_inline_comments mydoc
-
-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'
-is performed by::
-
-
- Terminal> doconce format html mydoc
-
-The resulting file 'mydoc.html' can be loaded into any web browser for
viewing.
-
-The HTML style can be defined either in the header of the HTML file,
-using a named built-in style;
-in an external CSS file; or in a template file.
-
-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
-
- - 'solarized': the famous "http://ethanschoonover.com/solarized":solarized
- style (yellowish),
- - 'blueish': a simple style with blue headings (default),
- - 'blueish2': a variant of *bluish*,
- - 'bloodish': as 'bluish', but dark read as color.
-
-Using '--css=filename' where 'filename' is a non-existing file makes
-Doconce write the built-in style to that file. Otherwise the HTML
-links to the CSS stylesheet in 'filename'. Several stylesheets can
-be specified: '--ccs=file1.css,file2.css,file3.css'.
-
-Templates are HTML files with "slots" '%(main)s' for the main body
-of text, '%(title)s' for the title, and '%(date)s' for the date.
-Doconce comes with a few templates. The usage of templates is
-described in
a "https://doconce.googlecode.com/hg/doc/design/wrapper_tech.html":separate
document. That document describes how you your Doconce-generated
-HTML file can have any specified layout.
-
-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'
-turns off the use of Pygments and makes code blocks appear with
-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'
-can be 'default', 'emacs', 'perldoc', and other valid names for
-Pygments styles.
-
-The HTML file can be embedded in a template with your own tailored
-design, see
a "tutorial": " "https://doconce.googlecode.com/hg/doc/design/wrapper_tech.html":https://doconce.googlecode.com/hg/doc/design/wrapper_tech.html"
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. The
-latter is the
-Doconce document translated to HTML. The title becomes the first
-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
-
-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.
-
-
-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.
-
-1. Write the blog text as a Doconce document without any
- title, author, and date.
-2. Generate HTML as described above.
-3. 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
-
-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.
-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":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
-
-Output in Pandoc's extended Markdown format results from::
-
-
- Terminal> doconce format pandoc mydoc
-
-The name of the output file is 'mydoc.mkd'.
-From this format one can go to numerous other formats::
-
-
- Terminal> pandoc -R -t mediawiki -o mydoc.mwk --toc mydoc.mkd
-
-Pandoc supports 'latex', 'html', 'odt' (OpenOffice), 'docx' (Microsoft
-Word), 'rtf', 'texinfo', to mention some. The '-R' option makes
-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. The HTML output from
-'pandoc' needs adjustments to provide full support for MathJax LaTeX
-mathematics, and for this purpose one should use 'doconce md2html':
-
-!bc sys
- 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 '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
- Terminal> doconce ptex2tex mydoc
- 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, '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
-inline verbatim text. Moreover, quite some additional 'doconce
-replace' and 'doconce subst' edits might be needed on the '.mkd' or
-'.tex' files to successfully have mathematics that is well translated
-to MS Word. Also when going to reStructuredText using Pandoc, it can
-be advantageous to go via LaTeX.
-
-Here is an example where we take a Doconce snippet (without title, author,
-and date), maybe with some unnumbered equations, and quickly generate
-HTML with mathematics displayed my MathJax::
-
-
- Terminal> doconce format pandoc mydoc
- Terminal> pandoc -t html -o mydoc.html -s --mathjax mydoc.mkd
-
-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:
-
-*Step 1.* Filter the doconce text to a pre-LaTeX form 'mydoc.p.tex' for
-the 'ptex2tex' program (or 'doconce ptex2tex')::
-
-
- Terminal> doconce format latex mydoc
-
-LaTeX-specific commands ("newcommands") in math formulas and similar
-can be placed in files 'newcommands.tex', 'newcommands_keep.tex', or
-'newcommands_replace.tex' (see the section "Macros (Newcommands)").
-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
-aimed at being printed. For example, links to web resources are
-associated with a footnote listing the complete web address (URL).
-
-*Step 2.* Run 'ptex2tex' (if you have it) to make a standard LaTeX file::
-
-
- Terminal> ptex2tex mydoc
-
-In case you do not have 'ptex2tex', you may run a (very) simplified
version::
-
-
- Terminal> doconce ptex2tex mydoc
-
-
-Note that Doconce generates a '.p.tex' file with some preprocessor macros
-that can be used to steer certain properties of the LaTeX document.
-For example, to turn on the Helvetica font instead of the standard
-Computer Modern font, run::
-
-
- Terminal> ptex2tex -DHELVETICA mydoc
- Terminal> doconce ptex2tex mydoc -DHELVETICA # alternative
-
-The title, authors, and date are by default typeset in a non-standard
-way to enable a nicer treatment of multiple authors having
-institutions in common. However, the standard LaTeX "maketitle" heading
-is also available through '-DLATEX_HEADING=traditional'.
-A separate titlepage can be generate by
-'-DLATEX_HEADING=titlepage'.
-
-Preprocessor variables to be defined or undefined are
-
- - 'XELATEX' for processing by 'xelatex'
- - 'PALATINO' for the Palatino font
- - 'HELVETICA' for the Helvetica font
- - 'A4PAPER' for A4 paper size
- - '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 '\href{run: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'.
-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
-present in 'myfile'). Otherwise, 'myfile' is assumed to contain
-*additional* LaTeX code to be added to the Doconce default preamble.
-
-The 'ptex2tex' tool makes it possible to easily switch between many
-different fancy formattings of computer or verbatim code in LaTeX
-documents. After any '!bc' command in the Doconce source you can
-insert verbatim block styles as defined in your '.ptex2tex.cfg'
-file, e.g., '!bc sys' for a terminal session, where 'sys' is set to
-a certain environment in '.ptex2tex.cfg' (e.g., 'CodeTerminal').
-There are about 40 styles to choose from, and you can easily add
-new ones.
-
-Also the 'doconce ptex2tex' command supports preprocessor directives
-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}"
\
- fpro=minted fcod=minted shcod=Verbatim envir=ans:nt
-
-Note that '@' must be used to separate the begin and end LaTeX
-commands, unless only the environment name is given (such as 'minted'
-above, which implies '\begin{minted}{fortran}' and '\end{minted}' as
-begin and end for blocks inside '!bc fpro' and '!ec'). Specifying
-'envir=ans:nt' means that all other environments are typeset with the
-'anslistings.sty' package, e.g., '!bc cppcod' will then result in
-'\begin{c++}'. If no environments like 'sys', 'fpro', or the common
-'envir' are defined on the command line, the plain '\begin{verbatim}'
-and '\end{verbatim}' used.
-
-
-*Step 2b (optional).* Edit the 'mydoc.tex' file to your needs.
-For example, you may want to substitute 'section' by 'section*' to
-avoid numbering of sections, you may want to insert linebreaks
-(and perhaps space) in the title, etc. This can be automatically
-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.
-You will use 'doconce replace' to edit 'section{' to 'section*{':
-!bc sys
- 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 so the 'doconce subst' or
-'doconce replace' commands can be put inside the script.
-
-*Step 3.* Compile 'mydoc.tex'
-and create the PDF file::
-
-
- Terminal> latex mydoc
- Terminal> latex mydoc
- Terminal> makeindex mydoc # if index
- Terminal> bibitem mydoc # if bibliography
- Terminal> latex mydoc
- Terminal> dvipdf mydoc
-
-
-If one wishes to run 'ptex2tex' and use the minted LaTeX package for
-typesetting code blocks ('Minted_Python', 'Minted_Cpp', etc., in
-'ptex2tex' specified through the '*pro' and '*cod' variables in
-'.ptex2tex.cfg' or '$HOME/.ptex2tex.cfg'), the minted LaTeX package is
-needed. This package is included by running 'ptex2tex' with the
-'-DMINTED' option::
-
-
- Terminal> ptex2tex -DMINTED mydoc
-
-In this case, 'latex' must be run with the
-'-shell-escape' option::
-
-
- Terminal> latex -shell-escape mydoc
- Terminal> latex -shell-escape mydoc
- Terminal> makeindex mydoc # if index
- Terminal> bibitem mydoc # if bibliography
- Terminal> latex -shell-escape mydoc
- Terminal> dvipdf mydoc
-
-When running 'doconce ptex2tex mydoc envir=minted' (or other minted
-specifications with 'doconce ptex2tex'), the minted package is
automatically
-included so there is no need for the '-DMINTED' option.
-
-
-PDFLaTeX
***The diff for this file has been truncated for email.***
Reply all
Reply to author
Forward
0 new messages