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:
   • <uplink>, linking to the parent page.
   • <prevpage> and <nextpage>, allowing for step-by-step instruction pages.
   • <locallink>, linking to all other pages in the same directory.
   • <directory>, linking to all subdirectories of the current directory.

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:

• <xml>: every Corbon page starts with this. In addition, all Corbon pages have the ".xml" extension.
• <include src="settings/generic.xml"/>: Include the settings file. The settings file will be described later.
• <synopsis description="Quick introduction on how to use Corbon" name="Quickstart"/>: Additional meta-information for defining the page. This data is used when doing directory listings, creating keyword indices etc.
• <title>Corbon: Quickstart</title>: Title tag. This will be converted to a HTML <title> tag.
• <content>: Start of content. Corbon will insert a <div id="content"> tag that you can use in CSS. Note that you're not required to use the content tag. You can just start using your own divs here. It's only provided as a convenience.
• HTML content: The real content. You can use any HTML you want here, but read the caveats first.
• </content></xml>: Close up the document.

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:

• <synopsis generate="0"/>: Indicate that this page should not be compiled into a HTML page. This is something you might want to do with all included pages.
• HTML content: As you can see, the rest of the page is just plain HTML content. In fact, there's nothing special about an included page. Altough not used here, the <footer> tag is often a handy instrument for placing content at the bottom of the page.

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.

Back to Home