==============================
Documentation on documentation
==============================

Documentation is now written in ReStructuredText, a lightweight and
readable markup language designed for Python.

Conventions
===========

ReStructuredText leaves much freedom in the syntax - in our help files we
try to stick to consistent conventions as in the following.

Markup for sectioning
---------------------

::

  ==============
  Document title
  ==============

  Section title
  =============

  Subsection title
  ----------------

  Sub-subsection title
  ********************

Blank and spaces
----------------

One blank line before and after every paragraph.
Two-char indent in definition lists.

Inline help parser syntax
=========================

As to the time when this documentation was last updated, the online help
parser programmed into Angband does the following:

- ignore colons (``|``)
- ignore paragraphs starting with ``..`` (including their trailing blank
  line)
- recognize link targets (``.. _something``) and be
  able to open a file to the right position using them.
- recognize "menu" links for the online help navigation. Links are given 
  with the following format (``g`` is the hotkey here):

:: 

.. menu:: [g] option.txt

Tricks
======

Sometimes it is tricky to get a thing to display in the correct way in both
the online help and the compiled RST. This is often due to the complex
interaction between backslashes and backticks in RST. In particular, in
several places we need to use in RST a syntax such as

::

``D``\isarm

If this appeared directly in the help file, then the online help parser
would display a spurious backslash character ``\`` before the ``i`` letter.
It would be quite complicated to instruct it to parse backslashes using the
full RST syntax. Instead, we adopt the following workaround: we write

::

  this is a paragraph containing the word |``D``isarm| just in the middle

and later in the file we define a substitution directive

::

.. |``D``isarm| replace:: ``D``\isarm

Magically this works, since the online help parser *skips* pipes.