OpenRails reST Manual Writing Guide

OpenRails reST Manual Writing Guide.rst

Installing Sphinx and MikTex

• Install Python and Sphinx, as described here

• Install sphinx-autobuild if you want to use livehtml (see below) as target. Open a command prompt and type:

  pip install sphinx-autobuild

• Install MikTex as described here.

Building the manual ---------------

The following three build targets are configured and can be used:

make.bat html
make.bat latexpdf
make.bat livehtml

Targeting latexpdf will build the documentation first to LaTex format, then using MikTex will be converted to pdf. Please take care, that some object types (tables being one of them) are built differently to html, using different in-document configuration options. To ensure proper result, a test latexpdf build should be performed at inserting such objects.

Please be aware that MikTex will download additional modules from internet at first run, please make sure to allow that.

Livehtml target will watch the source rst files continuously while running, opening a browser, and rebuilding/updating its contents upon changes detected.

Styling used for reST Manual

• Headings:

  1.  above & below heading title   *******************
  1.1         below heading title   ===================
  1.1.1       below heading title   -------------------
  1.1.1.1     below heading title   '''''''''''''''''''

• Keyboard key:

  ``<Ctrl+Alt+G>`` 

• Italics emphasis: Menu entry, button, or something can be read from screen:

  *Main Route* 

• Monospaced emphasis: Something that must be typed in exactly as written in manual e.g. commands, filenames, keywords in configuraiton files, program code snippets, etc.:

  ``sigcfg.dat``
  ``$wait=<train> /maxdelay=n /notstarted /owndelay=n``
  ``ORTSCurtius_Kniffler ( A B C D )``

• Bold emphasis: Use it only very rarely, where is really needed, because it doesn't look right in a document. Use italics emphasis instead, almost everywhere! :

  **Table: Technical Reference -- 1962**

• Also avoid using quotation marks for emphasising, e.g.: "steam ejector". Emphasise with italics instead, like: *steam ejector*.
• Separate dash from en-dash. En-dash is to be written as double-dash: --
• Split lines in source files at about column number 75-79 at initial commit of new text. (<Ctrl+I> in Notepad++) But don't necessarily re-split lines of sections at later edits, so that changed lines could be kept on minimum in version control (git, svn).
• Leave a whitespace character at the end of each line inside paragraphs, so that possible re-joins will be easier. (<Ctrl+J> in Notepad++).
• Take big care of beginning-of-line indents. This is the base information in reST for rendering document structure. Indent in 2- or 4-spaces steps.
• Replace all "tab" characters with whitespaces, if copying from other sources (e.g. Word).
• name internal links and images as: "simplified section name" - dash - "function keyword / subsection" - dash - "further descripition if needed"

• keep a whitespace between the number and its unit, use standard unit abbreviations. E.g.: 120 km/h is good; 120kph is bad. Exception is the Celsius degree, where to get the proper result, it should be written as:

  15.5\ |deg|\ C

• International English: Don't use "," (comma) as a thousand-separator. Just write the number regularly. In most other languages comma is used as decimal separator, so using it as thousand separator leads to misinterpretation, or in best case just confusion.

  • Good: 2240
  • Wrong: 2,240

• Superscript, subscript:

  35.0 m\ :sup:`2` 
  F\ :sub:`max` 

• Internal reference point:

  .. _driving-ai-shunting:

• References:

  :ref:`Extended AI Shunting <driving-ai-shunting>`
  `Trainsim.com <http://trainsim.com>`_

• Image:

  .. image:: images/driving-briefing.png