Quick introduction on how to use Corbon

So you've got better things to do than read documentation. No problem: here's a quick overview of how Corbon works, and what you need to get started.

How Corbon works

Corbon doesn't differ much from a pure HTML site. It just adds a few tags that might be handy when developing sites:

  1. Corbon assumes a lot of pages in your site will use the same header, footer and styles. That's why it has an <include> tag that can include a settings file containing a generic header, footer, styles, and basically any content you like (navigation-menus, shared graphics, shared javascript, you name it). The included page is just like any other Corbon page.
  2. To semantically enhance your page, Corbon uses the <synopsis> tag that can contain a name, description and keytwords describing a page. These are used for the <uplink> tag (which links to the parent page), the <seealso> tag (which links to other pages with the same keywords), the <locallink> tag (which links to other pages in the same directory), the <directory> tag (which links to all subdirectories of the current directory) and the <keywordindex>.
  3. A lot of the housekeeping is about pages linking to eachoter. Corbon provides a few convenience tags for that:

Corbon uses the file-system, just like a standard HTML-based site, to define pages and directories. Each Corbon source file ends in .XML instead of .html .

How to work with Corbon

Grab a release

Corbon releases are hosted on SourceForge. Grab the latest release here.

Install it

On Windows, you can use the .EXE installer to automatically install Corbon. On Mac and Linux, use the command line.

cd downloads/corbon
python setup.py install
	

This will install Corbon in the default location (/usr/lib/python2.3/site-packages/corbon on Linux, /Library/Python/2.3/corbon on Mac OS X). You can test the release by starting python and typing the following:

python
Python 2.3 (#1, Sep 13 2003, 00:49:11)
>>> import corbon
	

If no errors are reported, you're good to go.

Begin a site

A basic page will look like this (actually, this is the Corbon source of this page):

<xml>
	<include src="settings/generic.xml"/>

	<synopsis description="Quick introduction on how to use Corbon" name="Quickstart"/>	
	<title>Corbon: Quickstart</title>

	<content>
	<h1>Quick introduction on how to use Corbon</h1>
	<p>So you've got better things to do...</p>
	</content>
</xml>

Let's go over each tag in detail:

And this is how the settings file of the documentation site looks like:

<xml>
	<synopsis generate="0"/>
	<link href="default.css" rel="stylesheet" type="text/css" />
	
	<div id="header">
	<img src="g/logo.png" alt="The Corbon Logo" />
	</div>
	
	<div id="nav">
	<ul>
		<li><a href="index.html">Home</a></li>
		<li><a href="tutorial/index.html">Tutorial</a></li>
		<li><a href="documentation/index.html">Documentation</a></li>
		<li><a href="installation/index.html">Installation</a></li>
	</ul>
	</div>	
</xml>

Once again, let's see what is here:

Caveats

There are a few things to watch out for when using Corbon.

Relative linking

Every link in Corbon, whether it's for another page or an image, uses a relative link that starts from the root. So it doesn't matter what directory you start from, you always must link from the root.

Let's give an example: let's say you have a file in the directory projects and you're pointing to an image in the projects/images folder. The code for this is:

<img src="projects/images/image.png" alt="An Image" />

So you can't reference to the image by only using the "images" folder, you have to use the full path starting from the root.

This is very important for include files to work: because included files can reference elements from anywhere in the site, they must be able to do so from anywhere in the site using the same link.

HTML entities

You can use HTML entities in your XML files. Just note that they won't validate as XML documents — XML only accepts lt, gt, and amp entities. It's better to set the content-encoding (for example to UTF-8) and use the characters directly.