java-gnome 4.1.3, released 4 May 2013
About
Overview, News
Documentation
Tutorials, API, and Hacking
Download
Binaries and Source
Interact
Mailing Lists, IRC, and Reporting Bugs

doc/style/MARKUP

MARKUP

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.

Syntax overview

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:

`filename`

which puts the filename in a <code> span.

If you write

Heading
-------

you get an <H2> heading. Using === (which is visually a bit stronger) creates an <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 <TAB> or 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 margin and padding around PRE blocks.

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!

Download

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.

Convenient rendering

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 view.php.

Last modified 14 Aug 07

Contents copyright © 2006-2011 Operational Dynamics Consulting Pty Ltd, and Others. See AUTHORS file and source code history for the various files comprising this site for full details. This page was generated from a text document! We use John Gruber's Markdown syntax as ported to PHP by Michel Fortin. See MARKUP for details