About the format of these documents
As a matter of sound practise, all our documentation is done in text files so that a developer can easily read them while browsing the code or working on their own projects. When writing our documents, however, we lightly mark them up with the syntax of John Gruber’s “Markdown” so that they also present nicely as web pages on our website.
In brief, the Markdown works like this: you just write text! Then, occasionally, you punctuate things in the way Markdown recognizes, and you get the markup you need.
The biggest problem with text documents is that in both spoken and written communications we use emphasis but the medium of the traditional terminal and Unix command line aren’t up to it. So from the early days of Usenet (and long, long before wikis), people developed the habit of using extra punctuation characters to express themselves:
I have a compulsive need to use _italics_ and **bold** in my writing
results in “I have a compulsive need to use italics and bold in my writing”.
To mark program names, file names, variables, etc in a constant width font you simply use backticks:
which puts the
filename in a
If you write
you get an
<H2> heading. Using
=== (which is visually a bit stronger)
<H1> heading, which makes sense and looks awesome in text.
To do code snippets we use:
<TAB>Mark a section as being a preformatted <TAB>code block, ignoring any _markup_ present. <TAB>
As you would expect, the result is a preformatted block like this:
Mark a section as being a preformatted code block, ignoring any _markup_ present.
This works with either a
4 spaces as the indent character. We used
to use two tabs to create the appearance of indent from the left margin so it
would look better when doing code snippets, but now we just use CSS to put some
Note that Markdown is actually quite a bit richer than this. It has all kinds of conveniences such as an easy and natural link (href) syntax, bullet lists and ordered lists, images, everything you need. It does The Right Thing (tm) when you’d expect it to, and doesn’t bother you about strictness — it just lets you get on with writing what looks like a nice readable text file.
Check it out!
John Gruber’s original Markdown is a Perl program intended for blogs and wikis; Michel Fortin ported Markdown to PHP. We use the latter version to render our documentation as HTML, working off the latest documents as checked into the mainline branch of the source code.
One way you can quickly look at the result of your markup is to create a simple script in a virtual host on your local web server and have it call markdown on the file you’re working on. In PHP it is as simple as:
include_once "markdown.php"; $text = file_get_contents("README"); echo Markdown($text);
An example is included in the source code as
Last modified 14 Aug 07