|Summary||Crawl manual in reStructuredText|
|Further information||b0rsuk 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 on||2010-07-04 00:51|
The actual reST document to be found here.
Note b0rsuk is much more familiar with reST markup than DokuWiki markup.
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.
Default style for .pdf output
One of most distinguishing features of this style are spaces between paragraphs. I think it's more readable that way.
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):
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.
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.
The simplest way is to copy the contents of the code tag from the other page and put them into http://rst2a.com/create/type/ .
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…