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.