The architecture of the Deep Space 6 Website

Mauro Tortonesi

Deep Space 6

Simone Piunno

Deep Space 6

Abstract

In this article we will show you the architecture of the Deep Space 6 Website. Our purpose is to explain you how to help us working on our site.


Table of Contents

1. The XML architecture of our website: an overview
2. Start working on the site
2.1. Checking out the website project from CVS
2.2. Installing required software
2.3. Generating the actual (X)HTML pages
2.4. Committing changes
References

1. The XML architecture of our website: an overview

The architecture of the Deep Space 6 website is rather simple. All the pages are written in XML: the main page and most of the sections pages are written in a custom XML flavour, while the articles are written in standard DocBook-XML - but we want to port all the site to DocBook-XML. From these XML documents, we generate the (X)HTML pages which are then published on our website. We also generate the PDF version of the most interesting articles.

The generation process of the (X)HTML pages is based on the XSL transformation of XML pages, with our customized XSL stylesheets. We make use of two XML+XSL parsers: sablotron and xstlproc (a program included in the libxslt package). Sablotron is used for the pages which are written in our custom XML flavour and xstlproc for the DocBook-XML pages. The whole (X)HTML generation process is automated by the use of Makefiles.


          An XSL transformation with Sablotron.

An XSL transformation with Sablotron.


          An XSL transformation with XSLTProc.

An XSL transformation with XSLTProc.

2. Start working on the site

2.1. Checking out the website project from CVS

To start working on the website, you have to checkout the website project from our CVS repository. To retrieve source code via anonymous CVS, you can use the following procedure. First, login to the CVS Repository:

$ cvs -d :pserver:anonymous@cvs.deepspace6.net:/ds6/cvs login

(just press enter at the password prompt, as any password will work). Then, retrieve (checkout) the source code of the project (which, no surprise, is named website):

$ cvs -d :pserver:anonymous@cvs.deepspace6.net:/ds6/cvs co website

Finally, you can logout from the CVS Repository:

$ cvs -d :pserver:anonymous@cvs.deepspace6.net:/ds6/cvs logout

2.2. Installing required software

In order to perform the generation process of the (X)HTML and PDF version of our pages, you need to install the following packages (name style and grouping based on Linux Mandrake 9.0):


 ed                  >= 0.2
 make                >= 3.79.1
 sablotron           >= 0.95
 libxml2             >= 2.5.2    [*]
 libxslt1            >= 1.0.25   [*]
 libxslt-proc        >= 1.0.25   [*]
 docbook-dtd41-sgml  >= 1.0
 docbook-dtd412-xml  >= 1.0
 docbook-style-dsssl >= 1.77
 docbook-style-xsl   >= 1.60.1   [*]
 docbook-utils       >= 0.6.11
 docbook-utils-pdf   >= 0.6.11
 openjade            >= 1.3.1
 jadetex             >= 3.12
 tetex               >= 1.0.7
 tetex-dvipdfm       >= 1.0.7

      

The packages libxml2, libxslt1, libxslt-proc and docbook-style-xsl are not shipped with the stock Mandrake 9.0 distribution, but you can download them from our FTP site. You should find the other packages on your installation CDs.

2.3. Generating the actual (X)HTML pages

Now that you have installed all the needed packages, you can start the (X)HTML generation process with the:

make

command.

2.4. Committing changes

As we have already showed you a couple of paragraphs above, everyone can checkout the website source anonymously from our CVS Repository. But only authorized users are allowed to commit changes to the Repository. So, if you want to contribute to our project, you you must be given the authorization to write to our CVS Repository and you must use an authenticated access.

In order to get an authenticated access, you should:

  • contact us to obtain the authorization to access our CVS Repository

  • send us your ssh public key (see man ssh-keygen).

When you'll have write access to our CVS Repository, you can checkout the website as an authenticated user:

export CVS_RSH=ssh

cvs -d :ext:ds6yourusername@deepspace6.net:/ds6/cvs checkout website

where yourusername is the login name you have been assigned.

Warning

PLEASE NOTICE THE ds6 LEADING PREFIX BEFORE yourusername!!!

As the whole authentication process relies on the use of ssh keys, no login phase is required.

For your best comfort, we suggest you to add the following lines to your .bashrc or .bash_profile:


export CVS_RSH=ssh
CVSROOT=:ext:ds6yourusername@deepspace6.net:/ds6/cvs/

      

After authenticated checkout, you can add files, update your local source repository and commit changes as usual:

cvs -d :ext:ds6yourusername@deepspace6.net:/ds6/cvs add filename

cvs -d :ext:ds6yourusername@deepspace6.net:/ds6/cvs commit

cvs -d :ext:ds6yourusername@deepspace6.net:/ds6/cvs update -d

Important

We strongly suggest you to setup a web server (we recommend apache 2.0 with SSI enabled) on your host and to perform a few rendering tests with at least two of browsers before committing changes to our CVS repository.

Remember also that your commits must never break the (X)HTML and PDF documents generation process.

References


XML | PDF | ChangeLogUpdated 12.05.2004Contribute | DeepSpace6

Valid XHTML 1.0!IPv6 Ready