path: root/doc/rst.txt

===========================================================================
       Nim's implementation of |rst|
===========================================================================

:Author: Andreas Rumpf
:Version: |nimversion|

.. contents::

Introduction
============

This document describes the subset of `Docutils`_' `reStructuredText`_ as it
has been implemented in the Nim compiler for generating documentation.
Elements of |rst| that are not listed here have not been implemented.
Unfortunately, the specification of |rst| is quite vague, so Nim is not as
compatible to the original implementation as one would like.

Even though Nim's |rst| parser does not parse all constructs, it is pretty
usable. The missing features can easily be circumvented. An indication of this
fact is that Nim's *whole* documentation itself (including this document) is
processed by Nim's |rst| parser. (Which is an order of magnitude faster than
Docutils' parser.)


Inline elements
===============

Ordinary text may contain *inline elements*.


Bullet lists
============

*Bullet lists* look like this::

  * Item 1
  * Item 2 that
    spans over multiple lines
  * Item 3
  * Item 4
    - bullet lists may nest
    - item 3b
    - valid bullet characters are ``+``, ``*`` and ``-``

This results in:
* Item 1
* Item 2 that
  spans over multiple lines
* Item 3
* Item 4
  - bullet lists may nest
  - item 3b
  - valid bullet characters are ``+``, ``*`` and ``-``


Enumerated lists
================

*Enumerated lists*


Definition lists
================

Save this code to the file "greeting.nim". Now compile and run it:

  ``nim run greeting.nim``

As you see, with the ``run`` command Nim executes the file automatically
after compilation. You can even give your program command line arguments by
appending them after the filename that is to be compiled and run:

  ``nim run greeting.nim arg1 arg2``


Tables
======

Nim only implements simple tables of the form::

  ==================      ===============       ===================
  header 1                header 2              header n
  ==================      ===============       ===================
  Cell 1                  Cell 2                Cell 3
  Cell 4                  Cell 5; any           Cell 6
                          cell that is
                          not in column 1
                          may span over
                          multiple lines
  Cell 7                  Cell 8                Cell 9
  ==================      ===============       ===================

This results in:
==================      ===============       ===================
header 1                header 2              header n
==================      ===============       ===================
Cell 1                  Cell 2                Cell 3
Cell 4                  Cell 5; any           Cell 6
                        cell that is
                        not in column 1
                        may span over
                        multiple lines
Cell 7                  Cell 8                Cell 9
==================      ===============       ===================


.. |rst| replace:: reStructuredText
.. _reStructuredText: http://docutils.sourceforge.net/rst.html#reference-documentation
.. _docutils: http://docutils.sourceforge.net/