DDSG is the official website for the Dependable Distributed Systems Lab at JAIST. The webpage is in two languages, in English and in Japanese.

Overview of tools

The page is generated from templates and from XML files with Anakia. Anakia is an XML transformation tool that uses JDOM and Velocity to transform XML documents into html pages. The transformation is directed by an Ant build file.

Please click the links to learn more about the referenced tools and technologies.

Files and directories

The following three directories are used for building the site:

~/ddsg/

This directory contains all the source files and files and software necessary for building the site. The only requirement is a recent version of the Java SDK (1.4) and basic UNIX tools. The build process never writes to this directory. It is placed under CVS version control. If you have the access rights, you can get it with the following commands: export CVSROOT=:ext:username@ddg.jaist.ac.jp:/home/cvs
export CVS_RSH=ssh
cd
cvs checkout ddsg or similar commands. (This document supposes that you did the checkout in your home directory.)

~/ddsg-intermediate/

This directory holds files temporarily needed for building the site.

~/ddsg-html/

This directory contains the generated website. It only contains basic HTML, CSS, images and other linked files. To install the site, just copy this directory to where the web server can find it and set the right file permissions. Don't worry, all hyperlinks within the site are relative. The host ddg has a user set up for building and exporting the website. Just log in as www (if you have the rights to do so) and type build.

Important: you should only ever modify files in the ~/ddsg/ directory. Modifications in the two others are overwritten when building the site.

All text files (source and generated) use the Unicode UTF-8 encoding, to support any combination of Japanese and Latin characters (including accented characters). Please make sure that your editor is capable of correctly editing UTF-8 encoded files. Also make sure that your webserver sends UTF-8 as the encoding in the HTTP header.

~/ddsg/

~/ddsg/build/

Scripts and information needed to build the site.

build

Shell script to build the whole site. You can call it from any directory. Sets up the environment and calls ant with the build.xml file.

build.xml

Ant build file. Its task is setting up necessary Ant tasks and generating and calling the actual build file.

velocity.properties

Configuration properties passed on to Velocity.

You should not need to modify any of these files.

~/ddsg/lib/

Contains all the Java software needed to build the site: Ant, JDOM, Jakarta Commons Collections, Log4J, Velocity and the Jing Relax NG schema validator. You only need a recent version of the Java SDK (we use 1.4).

The velocity-1.5-dev-urbi.jar file is a modified version of the Velocity source code that fixes one annoying bug (http://issues.apache.org/bugzilla/, bug 21173). The source for the modification is stored elsewhere.

You should not need to modify any of these files.

~/ddsg/xdocs/

Contains the source files for the website. Files you would normally want to modify are found here.

site.xml

This file contains all the data that appears on the website. This is probably the file you need to modify most often (only some tags!).

site.rnc

Relax NG schema for site.xml. You only need to modify this file if major changes occur on the website and you need input data of a new format.

stylesheet.css, images/

The CSS stylesheet for the whole site and images. These files are copied to the website without changes.

xhtml11-flat.dtd

The DTD schema for the XHTML 1.1 specification, our output format. It is used for validating each webpage of the site. Note that if there is a validation error, you should not modify the generated pages in ~/ddsg-html/ !!! You should modify the corresponding source files instead.
There is no need to modify this file.

templates/

All Velocity templates used for building the website. See later in more detail.

~/ddsg/xdocs/templates/

build_generated.vsl

This template generates the Ant build file actually creating the website. The principal task of ~/ddsg/build/build.xml is only generating that build file. Such a two-phase build was necessary because Ant is rather limited in executing tasks for a pattern of files. You should not need to modify this file. If you do, beware of Anakia task's braindead rules for what directory is used for the files involved in executing the task.

site_lang.vsl

This template generates single-language variants of site.xml. You should not need to modify this file.

html/

The directory contains templates for XHTML pages (*.vsl) and some supporting files. The same template is used for both the English and Japanese variant of the page; the difference is which part of the data in site.xml is used.

The templates are declared in site.xml, under the <templates> tag, as id attributes of the <template> child tags. This implies, in particular, that you should add a <template> child tag when you add a new page template.

The templates have access to the $project variable that holds the contents of site.xml (that is, all data needed), and to the $root variable that holds the language and the template used for the current page being built.

The VM_global_library.vm file contains macro definitions that can be used in the templates. No macro definitions should appear in the templates themselves, because they are ignored anyway.

~/ddsg-intermediate/

You might want to look at these files when debugging the site.

build-generated.xml

The build file used to build most files of the website, produced by ~/ddsg/xdocs/templates/build-generated.vsl.

en/site.xml and jp/site.xml

One-language variant of the site.xml file: only the contents of the right <lang> tags are kept in each.

id/

Contains small XML files that will be parsed into the #36;root variable when processing the corresponding Velocity template. Such a file usually contains information like the name of the page generated and its language.

~/ddsg-html/

en/, jp/

The language specific parts of the site, like HTML pages.

others

The generic (not language dependent) parts of the site, such as images and BibTeX files.

Frequently occurring tasks

Getting a copy of the source

You only need to do this once. Later on, you can use your ~/ddsg directory.

cd
cvs -d :ext:username@ddg.jaist.ac.jp:/home/cvs co ddsg

Building or re-building the site

cd ~/ddsg
cvs up
build/build

A lot of messages will appear, following Ant's progress at building the site. If everything goes well, the message "BUILD SUCCESSFUL" should appear as one of the last lines. Check your page in a web browser as well.

When you're using the www account to build the production version of the site:

ssh -l www ddg bin/build

executes all of the above.

Modifying the site

You probably only need to modify some tags in the ~/ddsg/xdocs/site.xml file. Read the Velocity template corresponding to the page you want to modify. For example, ~/ddsg/xdocs/templates/html/people.vsl is the template for people.html. This should tell you which tags are used in generating your page.

(Sometimes you need to modify the template file itself, though, or the Relax NG schema for site.xml: ~/ddsg/xdocs/site.rnc.)

Build the site and double-check the result. Also in a web browser.

Check your changes with cvs diff -u -3. Please have only changes that are necessary (no reformatting of lines, no adding/removing empty lines, etc.).

Use cvs commit.

Adding a page

Create a new template in ~/ddsg/xdocs/templates/html by copying an existing template. Modify it. Then add a <page> tag within the <pages> tag of ~/ddsg/xdocs/site.xml. Rebuild until perfect and commit your changes, just as before.

Design of the code that generates the list of publications

The goal is to present lists of publications in both BibTeX and HTML format. Both presentations should be 100% correct, including things like accented characters and math formulas. The HTML presentation should include links to files stored either locally or remotely.

The publication data is stored in an XML format derived from the bibtexml format. The BibTeX format is not suitable for manipulating data. Modifications are necessary because it is not possible to have 100% correct presentation with the unchanged bibtexml format.

Most of our publications are in BibTeX format. The scripts in ~/ddsg/tools/bibtex2xml convert BibTeX entries to bibtexml format entries. They only need to work 90%; the rest can be done by hand.

Design details of the XML format are the following:

• All text is encoded using UTF-8 (as is all the website), including accented characters. No LaTeX control sequences are used in the text. They are generated when presenting data in BibTeX format. It should be an error if some character cannot be converted to LaTeX. In fact, the LaTeX output should only contain ASCII characters.
• Curly brackets { } can be used in every field. They have the same meaning as in BibTeX: enclosed characters are protected from capitalization functions. There is currently no way to have curly brackets appear in the output (some form of escaping curly brackets is needed).
• Certain fields (e.g., title) might need different BibTeX and HTML presentation. An example is math. To solve this problem, the use of the <b>text_for_BibTeX_only</b> and <h>text_for_HTML_only</h> tags are allowed in these fields. The tags cannot contain other tags. Not yet implemented.
• The HTML presentation of different types of entries is controlled by some Velocity code in ~/ddsg/xdocs/templates/html/bib.vm and bibtex.vm. Most of the code is a translation of BibTeX's btxbst.doc file (plain style). The alternative of using BibTeX and a LaTeX to HTML conversion would be ugly and mean a lot of work. Need to clean up the .vm files.
• Fields are needed to hold links to the abstract, PostScript, PDF and possibly other formats. There is also a generic link type where the user chooses the name for the link. The links are enclosed in a <links> tag at the beginning of the <entry> tag. The types of links are described in <linkType> tags.

  <abstract/>

  if the abstract is in the default place (say pub/bibtex_key.txt);

  <abstract href="..."/>

  if the abstract is in another place;

  <other name="simulation data" href="..."/>

  for a link of another type.
• Metadata is added with a <metadata> tag placed under <entry>. It contains tags like

  <meta name="important"/>

  or

  <meta name="grade">A</meta>

  See site.rnc for what metadata is allowed. The #setMeta Velocity macro reads all metadata into the $meta map.
• The title should link to the page that lists only that publication. Not yet implemented.

TODO

Critical

• Link to this page from the site - done
• Split up this page. Support subdirectories - done
• Welcome message on index.html - done. Have to be revised
• Translation into Japanese.

Important

• Remaking the site is slow. Make sure that only the necessary parts are remade.
• At the minimum, check if the files in id/ need to be remade.

Not so important

• Check if "$" appears in the generated files, because "$" usually indicates a Velocity reference that could not be dereferenced.
• Check if non-ASCII (0-127) characters appear in BibTeX files. All such characters should be replaced by LaTeX escape sequences.
• Use a link checker, at least for internal links.
• Have Velocity quit with errors whenever something is wrong. Usually, Velocity just puts an entry in a log file.
• "Home" link really needed?
• <title> tags should include the title of the page.
• Use single quotes rather than double quotes in Velocity templates whenever possible. - OK
• Consistent capitalization of variable names and the like.
• Split the validation of site.xml in two parts. One file should check the language independent parts: <lang>tags and the languages tag. site.rnc should then validate the language-specific XML files, not site.xml.

Evi

• CFP - done, but not in use
• home: short description of the projects?
• projects: add outils
• projects: acronymes?
• teaching: add link for exercises