Motivation

(You might want to skip this section and jump to the sections where you start running some examples.)

I have mostly written my documents in LaTeX, plain text, TeXinfo and Docbook. Each of these has strengths and limitations. ReStructuredText (from here on reST) seems to occupy an important area that stands between the plain text and the richer markup in LaTeX, TeXinfo and Docbook.

In this post I will discuss the boundary between LaTeX and plain text.

LaTeX is the clear choice for writing mathematical and scientific documents, but it works poorly for computer documentation. This is because TeX and LaTeX are aimed at typsetting text, which often does not make for good "cut and paste" of the text into a command line or into a computer program.

For example, LaTeX has the lstlisting package which allows you to do very nice typsetting of program listings and command line examples, but it is hard to select text from the output PDF document and insert it into a program or the command line. You end up with spurious text and weird spaces.

You can use plain text for computer instructions, as is done in many simple README files, but as soon as the document gets bigger you will want to give it some structure.

Lightweight markup languages, such as markdown/reST (from here on I will just say reST since I use that), fill that space: they allow you to build a full book out of a document, but at the same time the HTML output is simple and close to plain text, so you can select sections and paste them into your command line or your programs.

reST is widely adopted, being the Python documentation project standard as well as the new choice for the GNU Scientific Library book. Its tools are powerful, if a bit "young". There are also some agile tools for markdown, and these tools will convert most of your reST document.

Simplest example

Let us create a simple file. Put the following marked up text into a file called rest-sample.rst

=============================
 A lightweight document title
=============================

This is a very short document with *very* little markup in it.

Now let us convert rest-sample.rst to a few output formats.

html

rst2html rest-sample.rst > rest-sample.html

pdf

rst2pdf rest-sample.rst ## output goes into rest-sample.pdf

odt (libreoffice writer)

rst2odt rest-sample.rst > rest-sample.odt

latex (LaTeX)

rst2latex rest-sample.rst > rest-sample.tex

(you can then process rest-sample.tex with pdflatex, which might overwrite the rest-sample.pdf file which you created with rst2pdf!)

What we have just done is write a very simple markdown document and convert it to LaTeX, html, pdf and odt.

From LaTeX to markdown

## download a sample LaTeX document and its figure form the web
$ wget http://www.electronics.oulu.fi/latex/examples/example_1/example1.tex
$ wget http://www.electronics.oulu.fi/latex/examples/example_1/myfigure.pdf
## now typeset it with:
$ pdflatex example1.tex
## and view it by opening example1.pdf in your favorite pdf
## viewer, for example:
$ evince example1.pdf &

$ pandoc -o example1.rst example1.tex

$ rst2html example1.rst > example1.html

A bigger project: using sphinx

We will now try to create a new reST project and set it up to be processed by sphinx, that very powerful tool that can make a whole web site out of your reST marked-up documents.

First install some of the sphinx tools with:

$ sudo apt-get install python-sphinx
$ sudo apt-get install fonts-mathjax libjs-mathjax

Then make a new diretory to work in

$ mkdir my-sphinx-project
$ cd my-sphinx-project

Then create a project in there with sphinx-quickstart

$ sphinx-quickstart

You can answer most of these questions with the defaults, but you might change the following:

• Separate source and build directories: y
• Project name: my-sphinx-project
• Author name(s): Your Name
• Version: 0.1
• Release: 0.1.0
• epub builder: y
• mathjax: y
• Create Windows command file: n

You now have a project! You will see that there is a file called index.rst which lets you include your own test. We will first build the project:

$ make html

Now load up the file _build/html/index.html in your web browser, and you can reload it whenever you make changes and type make

Now let us modify the index.rst file to include a file of our own:

Welcome to my-sphinx-project's documentation!
=============================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   my-project.rst

Indices and tables
==================

and create a minimal file called my-project.rst

This is my project
==================

This is my project

From here on you put your text in my-project.rst and you can do the usual cycle of running make and reloading the page in your web browser to see how things are going.

References

• http://pandoc.org/demos.html
• http://zverovich.net/2016/06/16/rst-vs-markdown.html
• http://www.unexpected-vortices.com/doc-notes/markdown-and-rest-compared.html
• http://www.electronics.oulu.fi/latex/examples/example_1/