Crawl Manual

SummaryCrawl manual in reStructuredText
Further informationb0rsuk created a light weight markup (reST) version of Crawl's manual.
The purpose of this page is to make mutual changing of the manual a simple affair. Please do not edit parts unless you really know what you are doing (in which case you should be a developer). If you want to discuss the manual or propose improvements, please do so on this page.
reST quick reference
reST online converter
docutils package for commandline generation (Note docutils package is available in many Linux distributions)
Added bydpeg
Added on2010-07-04 00:51

The actual reST document to be found here.

Note b0rsuk is much more familiar with reST markup than DokuWiki markup.

Advantages of reStructuredText

  • reST is almost as readable as plain text, yet quite powerful
  • It can easily be processed into HTML, Latex (for pretty .pdf generation), man page, XML, .odt, or S5. Ironically, it doesn't have a way to generate plaintext document, but converting it with a script is quite straightforward.
  • Organizes your thoughts by what they mean, not how they look on the page. This has advantages such as being able to automatically generate Table of Contents from section structure. Styling comes later and is an independent process.
  • It's clean and straightforward enough we can just post it on a wiki page. No need to use an editor and reupload unless you like to.

Example output

Html version

This is just one stylesheet. I chose it because it's one of the nicest and it highlights various structures (such as lists, definition lists, sections) well. Note section titles are backlinks - clicking on them brings you back to Table Of Contents.

pdf - default style

Default style for .pdf output

pdf - zope style

One of most distinguishing features of this style are spaces between paragraphs. I think it's more readable that way.

Conventions used

I use 80 character static word wrap. It has no effect for HTML or PDF, and (hopefully) makes it look better in console.

Currently, I use 2 spaces for indentation, but it's not set in stone. Python convention used in many reST documents is 4 spaces, but I think that's too much space wasted if you're in 80×25 terminal.

In reST, there are no heading levels assigned to certain characters as the structure is determined from the succession of headings. I borrowed the following order from Python documentation (on Sphinx page):

  • # with overline, for parts
  • * with overline, for chapters
  • = for sections
  • - for subsections
  • ^ for subsubsections
  • ” for paragraphs

The one exception: I used plus signs + for document title.

Technically, section over- and underlines must be at least as long as section names. I decided to go with uniform 40, as variation between 4 (Shops) and 31 (Dungeon Crawl Stone Soup Manual was too high.

Table Of Contents is currently generated up to depth level 5. If you'd like a more old-school manual, try 2.

The commonest filename extension for reStructuredText is .reST . Please take care to make the two first letters lowercase to avoid confusion with REST technology. It might be of some concern that Windows users will likely hesitate before opening an unknown extension in a text editor, but fortunately they won't need to once HTML version is up. I think the more important point to get across is how the markup language is called.

Updating the in-game manual

The file in git is not the authoritative version, please don't edit it. You should instead edit the online copy then run ”make rest” then commit it to git – at least just before release, but occasionally syncing it can't hurt. Creation of the pdf is not automated yet. I'm not entirely certain anyone ever reads it, but you need to update or delete it at least at release time as well.

Also, note that the online manual is not branched – it should always apply to the next release. Please refrain from documenting your latest shiny feature in trunk when the next version is branched but not yet released (in beta). Likewise, manual updates in stable need to be done by hand as the online copy has likely gathered new stuff that doesn't apply to the old version.

Generating files from reST


The simplest way is to copy the contents of the code tag from the other page and put them into .



In Debian Linux (and most likely Ubuntu), you can install the python-docutils package:

apt-get install python-docutils

In Fedora (and presumably also in similar distributions), the proper incantation is:

yum install python-docutils

Then you generate like this:

rst2html manual2010_06_22.reST manual.html

Other tools are named rst2newlatex, rst2xml, rst2s5. It turns out that man page generation is a bit more complicated because it's a new feature. It's described here, but Debian Sid seems to have it in base docutils package.

If in doubt…

man rst2html


I have neither time nor motivation to write a detailed description. It's a bit more complex. I managed to get it working at work. But I can point you the right way:


How to make Python scripts executable (Python on Windows FAQ)

Logged in as: Anonymous (VIEWER)
dcss/manual/start.txt · Last modified: 2016-08-06 07:50 by gammafunk
Recent changes RSS feed Donate Powered by PHP Valid XHTML 1.0 Valid CSS Driven by DokuWiki