This manual is for Achille 2.0 (version 2.0).
Copyright 2004, David Soulayrol
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover texts being Achille 2.0 Manual and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled GNU Free Documentation License.
(a) The FSF's Back-Cover Text is: You have freedom to copy and modify this manual, like GNU software.
This manual is for Achille 2.0 (version 2.0).
Copyright 2004, David Soulayrol
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover texts being Achille 2.0 Manual and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled GNU Free Documentation License.
(a) The FSF's Back-Cover Text is: You have freedom to copy and modify this manual, like GNU software.
Overview
IntroductionIntroduction Achille is a set of scripts and stylesheets aimed at generating websites. Achille is actually able to:
-
Transform articles written with the DocBook XML DTD to XHTML pages. Other input formats are studied but not implemented today.
-
Generate indexes for each of the sections of the website.
-
Generate file lists a la Apache but visually well integrated with the rest of the website (ie. using the same CSS stylesheets)
-
Integrate non-generated files such as images, or a whole branch of the website.
Achille is born from a simple problem: simply create static pages from a set of DocBook documents. It is a mainly a text and file processor and it is not aimed at implementing a framework for editing and publishing web pages like SPIP or PHPNuke and similars.
PrinciplesPrinciples Achille only manages the formatting of a website. Its role is to translate documents from some format to XHTML, and to generate all the missing pages that are only useful to the navigation, like the indexes or a map.
To achieve this goal, Achille relies on well known and open standards. Currently, the unique recognized input format is DocBook, but others are considered. Output pages are compliant to XHTML 1.1 and CSS 2 standards.
The standardsStandardsW3CXML The World Wide Web Consortium (W3C) publishes recommandations on all the subjects related to the web. These standards, when they are followed, allow a better navigation for the users, and facilitate the work of the programmers. Achille was designed with these standards in mind. All the pages either totally generated or transformed by Achille are (or shall be) conform to the recomandations of the W3C.
On the other side, Achille works on documents written using some other standards, currently only DocBook XML.
Writing DocBook documentsWriting DocBook documentsDocBook Docbook defines a document structure allowing to produce articles, books and so on from an SGML or an XML file.
XML and SGML are description languages. They are nothing more than a way to structurate a document with tags inserted in the text. For example,
<sect1 label="1.1" id="Introduction"> <title>Introduction</title> <para> Achille is a set of scripts and stylesheets aimed at generating websites. Achille is actually able to: </para> <itemizedlist mark="bullet"> <listitem> <para>Transform articles written with the DocBook XML DTD to XHTML pages. Other input formats are studied but not implemented today.</para> </listitem> <listitem> <para>Generate indexes for each of the sections of the website. </para> </listitem> <listitem> <para>Generate file lists <emphasis>a la Apache</emphasis> but visually well integrated with the rest of the website (ie. using the same CSS stylesheets)</para> </listitem> <listitem> <para>Integrate non-generated files such as images, or a whole branch of the website.</para> </listitem> </itemizedlist> <para> Achille is born from a simple problem: simply create static pages from a set of DocBook documents. It is a mainly a text and file processor and it is not aimed at implementing a framework for editing and publishing web pages like SPIP or PHPNuke and similars. </para> </sect1>DocBook is aimed only at structuring texts. It does not specify how those texts should be printed or displayed. This way, texts can be formated so as to be easely read through many media like a web page, an e-book, un printed book or sheet, and so on.
This kind of structured document has many advantages over closed formats. Seperation between the content of the document and its look allows the author to concentrate on its writing. The document can be edited with any text editor, on any kind of machine. Later, it can be easely processed to produce the desired output format.
DocBook processing with XSLTProcessing Docbook filesXSLT During this processing phase, or generation, the information hold in each of the articles of the site is extracted and combinated to build the whole site.
First, some new pages are created so as to get a complete site. Thus, indexes or maps are created using some information extracted from each one of the articles, like the title, the section it is stored in, a short introduction, and so on. Then, every file is transformed using XSLT to produce valid XHTML pages.
Document formatting with CSS2Formatting XHTML documentCSS2 Once transformed by Achille, a Docbook article should have the following look in nearly every browser:

Actually, the generated XHTML code is very simple. Like the DocBook format, it just contains structural information so as to be correctly parsed by your browser. So how to make this border thicker, this paragraph centered and the links in red colour? This is the job of the CSS stylesheet.
Your page will be correctly be displayed by any browser but if you are using a good and modern browser (like Firefox, Safari, Konqueror, and so on), a last transformation step takes place at the very moment you open the document. Each page comes with a link to a stylesheet that is applied by your browser before it is displayed.
The CSS stylesheet is composed of a list of HTML identifiants and, for each of them, a set of attributes. Here is an excerpt of a valid stylesheet.
h1 { color: #ffffff; font-weight: normal; margin: 0px 0px 0px 0px; padding: 2px 8px 2px 8px; margin-top: 15px; font-size: 20px } pre { border-right: 2px dashed #d0d0d0; border-left: 2px dashed #d0d0d0; background-color: #444444; padding: 8px; } a { text-decoration: none; font-weight: bold; color: #ffffff } AvantagesAvantages The principles described here present two really interesting aspects: the use of standards and structured documents, and the automatic generation of pages.
A structured document is also a document where content and presentation are separated. Separation of content and presentation brings a comfortable independance, allowing anyone to get access to the meat of the document without any interface obstacle. A structured text document can be edtied with any text editor on any system.
FIXME:
La separation entre le contenu du site et sa presentation apporte une confortable independance par rapport a tout outil et toute machine. Il permet d'ecrire des articles a l'aide de n'importe quel editeur (tel emacs) en ne se preoccupant que d'une chose : le texte doit etre correctement structure. Le texte ainsi produit peut etre lu et modifie depuis n'importe quel systeme, avant d'etre transforme. L'utilisation de standards lui permet d'etre ensuite consulte depuis n'importe quel outil comprenant ces standards.
Connected pages like indexes or site maps are often there only to present the different sections of a site, and constitute a double of the information. Generating these pages permit a lot of time saving.
LinksLinks Here are some links to read further on the subject.
-
docbook.sourceforge.net is the starting point to understand DocBook and discover the projects that are using it.
-
On docbook.org, you will find the official DocBook manual, also available at O'Reilly.
-
www.w3.org/XML/ is the XML standard page from the W3C
-
www.w3.org/TR/REC-CSS2/ is the CSS2 standard page from the W3C.
-
At last, Google is one of the best ways to find quickly additional information.
Problems and limitationsLimitationsBugs
-
Achille's DocBook DTD support is still limited. It will grow with newer versions, but it is not foreseen at the moment to support each of the 300 and more elements defined by the DTD. The goal is to take care of the mostly used elements.
-
Index generation still misses some control. The descriptor file, which is the file that describe the website structure, will be improved in the future to get better generation.
-
Certainly many other problems I not have still discovered.
About this document This document is aimed at introducting the Achille principles and describing how to work with. It is written in Texinfo.
LicenseLicense Achille is distributed under GPL (The GNU Public License). The GPL is a free license. Please consult the Free Software Foundation website to learn more.
Getting StartedGetting started
A sample siteSample site Whatever the system used by someone wishing to be assisted in creating a website, the first thing to do is to write down the structure of the site. In Achille, a site is nothing but a set of sections. A section usually groups articles with the same subject. There is no limit to the number of sections or the number of documents in each of these sections.
Each section is represented by a directory (or folder) on the filesystem. All the documents being in one directory belong to the corresponding section.
FIXME:
note: La version courante d'Achille ne gere pas les sous-sections. Si un repertoire SectA represente une section Section A, seuls les fichiers appertenant a ce repertoire SectA font bien partie de la section Section A. Les sous-repertoires de SectA ne representent rien et sont ignores.
In the following, we are going to create a simple site about literature. At first, we are going to define one section per style of book.

The simplest way to use Achille is to create a directory for our workspace (but it is also possible to work on many sources scattered on the whole disk if necessary). In this workspace, we will first create the following directories:
.../MySite .../MySite/source .../MySite/source/fantasy .../MySite/source/sf .../MySite/source/thriller .../MySite/targetFrom now on, we will only work under the MySite directory. The subdirectory source holds our site sections. Our site having three sections, we have created three directories fantasy, sf and thriller. We also have created a subdirectory named target, where we will produce the website pages.
We now need a way to make Achille aware of the structure of our website. This is achieved using the descriptor file.
The descriptorDescriptor Achille works on the basis of a file named the descriptor. A descriptor describes the whole website to generate. This includes the documents sources, the way to build indexes, and the stylesheets to use. Since version 2.0, this file is much more complete and is written in XML.
Like every XML document, the descriptor file begins with an XML declaration, and has a root element: Site. This tag has one mandatory attribute named target. The target is the root directory of the generated site.
The Site tag has two children we can fill immediatly: the elements title and Sections. The first represents the title of the website, and the second the list of the sections of the site.
<?xml version="1.0" encoding="ISO-8859-15"?> <site target='target'> <title>My library</title> <sections root='./source'> <section id='sci-fi' src='sf' target='/sf> <title>Science Fiction</title> <index type='summary' /> <articles /> </section> <section id='fantasy' src='fantasy' target='/fantasy> <title>Fantasy</title> <index type='summary' /> <articles /> </section> <section id='thriller' src='thriller' target='/thriller> <title>Thriller</title> <index type='summary' /> <articles /> </section> </sections> </site>Each Section of the site if declared thanks to a Section tag inside the Sections element. This new tag has three mandatory attributes:
-
id is the section identifier. This ID may be useful to refer to this section from anywhere in the descriptor file.
-
src is the directory where this section source documents can be found. These are the fils that will be copied or transformed to produce the final pages.
-
target is the directory where will be stored the produced files of this section. This path is relative to the root of the site.
The Section tag has many children, but none is mandatory. Here is a detailed explanation of the tags found in the Science Fiction section:
-
The Title tag tells Achille the name of this section, ie. the name used in the site menu.
-
The index element is the tag that tells Achille how to build an index for this section. index has many options and children, but the type attribute only is mandatory. If a section ha no element index, no index is generated for this section.
-
The articles element tells Achille to transform the Docbook articles is will find in this section.
Transformation files To produce correctly a website, Achille also needs to know what stylesheets to use. We will use the ones provided with Achille.
These sheets are declared thanks to the xslt-sheet tag. Achille transforms the documents on the basis of their type, so we must give it one stylesheet for each of them.
Here is how are new descriptor looks like:
<?xml version="1.0" encoding="ISO-8859-15"?> <site target='target'> <title>My library</title> <xslt-set> <xslt-sheet type='article'>xsl/docbook/page.xsl</xslt-sheet> <xslt-sheet type='index'>xsl/indexes/index.xsl</xslt-sheet> </xslt-set> <sections root='./source'> <section id='root' src='.' target='/'> <title>Home</title> <index type='summary'> <section-id>sci-fi</section-id> <section-id>fantasy</section-id> <section-id>thriller</section-id> </index> </section> <section id='sci-fi' src='sf' target='/sf> <title>Science Fiction</title> <index type='summary' /> <articles /> </section> <section id='fantasy' src='fantasy' target='/fantasy> <title>Fantasy</title> <index type='summary' /> <articles /> </section> <section id='thriller' src='thriller' target='/thriller> <title>Thriller</title> <index type='summary' /> <articles /> </section> </sections> </site>Do notice the new section named root. As it is defined, it is empty, but does declare an index. This index tag has a new child: section-id. This element gives the identifier of another section to analyse when building this index. The content of this section will be added to the content of the current section. Actually our root index will then contain a resume of the content of the sections named Science Fiction, Fantasy and Thriller.
First generationGeneration The first generation step is the creation of an index source for each section which have an index child. A file named index.xml is created in each of the directories representing these sections.
Here, a file named index.xml and nearly empty is created in the following directories: source, source/sf, source/thriller and source/fantasy.
The second step is the transformation of the whole pages to produce HTML pages. For each kind of document, Achille uses the correct stylesheet, as defined in the descripto. Here, we have told Achille to use the default stylesheet. These sheets introduce in each page the menu of the site, and a short footer with the date of generation. Generated pages are stored in target as defined in descriptor.

Article We have seen that Achille does only manages XML documents. Each of the articles we are going to write will obey to the DocBook XML DTD. This DTD defines some 300 elements today, allowing one to write an article or a book. Achille does only support a subset of these tags.
Here is how begins such a document:
<?xml version="1.0" encoding="ISO-8859-1"?> <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">]]></programlisting>These lines are the XML header and define an article. This declaration requires that the root element of our document is article. Hereafter is a short article for our site. The document is named hyperion.xml and is stored in the sf directory.
<?xml version="1.0" encoding="ISO-8859-1"?> <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <article> <artheader> <date>09/04/2003</date> <abstract> <para> A short article about Dan Simmons' <emphasis>Hyperion</emphasis>. </para> </abstract> </artheader> <title>Hyperion</title> <section> <title>Introduction</title> <para> <emphasis>Hyperion</emphasis> is the first book of one of the greatest sagas written today. </para> </section> <section> <title>Extrait</title> <blockquote> <para> The Hegemony Consul sat on the balcony of his ebony spaceship and played Rachmaninoff's Prelude in C-sharp Minor on an ancient but well-maintained Steinway while great, green, saurian things surged and bellowed in the swamps below. A thunderstorm was brewing to the north. Bruise-black clouds silhouetted a forest of giant gymnosperms while stratocumulus towered nine kilometers high in a violent sky. Lightning rippled along the horizon. Closer to the ship, occasional vague, reptilian shapes would blunder into the interdiction field, cry out, and then crash away through indigo mists. The Consul concentrated on a difficult section of the Prelude and ignored the approach of storm and nightfall. </para> </blockquote> </section>After generation, we see that the file target/sf/index.html has now the resume of our new article, with a link to it. The file target/index.html also has been modified in the same way. The article itself has been created too, and looks like this way:

StyleStylesheet We have seen all Achille really does. To render produced pages a better way, we must add to our site a CSS sheet. CSS language, defined by the W3C, allows to bring style to HTML tags. Actually, Achille does produce simple pages, conforming to XHTML 1.1. These pages does only contain information about document structure, and no indication on how they should be displayed.
To apply some style to our website, we are going to use the sheet provided with Achille. This stylesheet is named common.css, and its localisation depends on your platform and your installation. Lets copy it in the new directory css of our workspace, and lets add these lines to the descriptor file.
<css-set> <css-sheet name='Standard'>css/common.css</css-sheet> </css-set>The new element css-set is a simple container for the defined CSS sheets. Is can have one or many children of type css-sheet. This last tag has one possible attribute which is the name of the sheet. The uniq child of this element is the path to the stylesheet.
The stylesheet declared here are added to the produced pages. This way, a modern browser will display the page using the CSS pages. It should propose a way to choose the style to use.

Usage
InstallationInstallation Version 2.0 is a new implementation of Achille. It is written for Python 2.0 or above. Contrary to previous versions of Achille, there is no need of external tools but Python and the 4Suite module. Achille 2.0 should run everywhere Python is supported (ie. Linux, MacOS, MS Windows).
4Suite is a module for XML management and transformation, more powerful than pyXml. It provides in particular XSL and XPath functions. 4Suite is currently under development. You should download the latest available version, or extract the files from the CVS repository.
Once Python and 4Suite are correctly installed on your system, you shall use the setup.py script to install Achille.
The Achille 2.0 directory has the following structure.
achille/ Changelog COPYING css/ doc/ dtd/ gui/ README run_achille.py setup.py xsl/The achille directory contains all the files necessary to run the software. The run_achille.py script is a tool allowing to quickly use Achille. The directories named css, dtd and xsl contain respectivly the default CSS files for XHTML pages rendering, the document definition used by Achille and the XSL stylesheets used for producing XHTML pages. The doc directory contains this documentation as well as some examples to start using the software.
Command lineCommand line [FIXME] Invoqué sans argument, Achille retourne cette ligne :
Achille version 2.0, Copyright (C) 2003 David Soulayrol Achille comes with ABSOLUTELY NO WARRANTY; for details type `achille -w'. This is free software, and you are welcome to redistribute it under certain conditions; type `achille -c' for details. Usage: run_achille.py [options] -d descriptor command run_achille.py [options] [-d descriptor] -g | --guil'option indispensable -d permet de specifier le descripteur a lire. Ce fichier contient toute l'information sur le site a produire, aussi Achille n'a-t-il besoin de rien d'autre, si ce n'est une commande : build pour construire effectivement le site, check pour simplement lire le fichier descripteur et afficher un resume, ou clean pour detruire les fichiers produits par une precedente generation.
L'invocation de la commande build provoque la succession d'actions suivantes :
* lecture du descripteur, * construction des index : pour chaque repertoire declare par un element <Section> dans le descripteur et comprenant un sous element <Index>, un fichier index.xml est cree, selon les options fournies. * Construction des parametres pour les feuilles de style : pour chaque section, le fichier variable.xsl.in et lu afin de generer les feuilles de styles contenant des parametres a jour. * Transformation de l'ensemble des pages : pour chaque section, tous les documents XML sont transformes afin de generer les fichiers XHTML correspondant sous le repertoire cible. * Copie des fichiers : pour chaque section, les fichiers devant etre copies sont dupliques dans l'architecture cible.
The descriptor fileDescriptor file
StructureDescriptor structure
EnveloppeDescriptor enveloppe
XSLT formattingXSLT formattingXSLT stylesheets
CSS stylesheetsCSS stylesheetsCSS
SectionsSections
IndexesIndexesSection indexes
Graphical interfaceGraphical interfaceGUI
Index A About this document, see Article, see Avantages, see B Bugs, see C Command line, see CSS, see CSS stylesheets, see CSS2, see D Descriptor, see Descriptor enveloppe, see Descriptor file, see Descriptor structure, see DocBook, see F Formatting XHTML document, see G Generation, see Getting started, see Graphical interface, see GUI, see I Indexes, see Installation, see Introduction, see L License, see Limitations, see Links, see O Overview, see P Principles, see Problems and limitations, see Processing Docbook files, see S Sample site, see Section indexes, see Sections, see Standards, see Style, see Stylesheet, see T Transformation files, see U Usage, see W W3C, see Writing DocBook documents, see X XML, see XSLT, see XSLT formatting, see XSLT stylesheets, see