Project Aon

Warning: Parts of this page are sorely in need of revision

Obtaining the XML

Project Aon uses XML source files to create the end product that is consumed by visitors to the website. These source files are located in several places:

Git

The current working copies are stored in a Git repository. If you need to work on the XML files themselves, you need to use Git.

You can access a anonmyous http view of the repository and you can also anonymously access the repository using a Git client

To gain write access, you must

  1. set up a Git client for your operating system. The Git site lists different clients available. For MS Windows users, we highly recommend TortoiseGit.
  2. post a request for access to the repository on the volunteer mailing list

Using the Git command line

For users that have the command line git client available for their operating system. You can do the following to checkout all the XML files:

  • Request access to the repository:
    • Anonymous access: git clone https://git.projectaon.org/project-aon.git
    • Write access: git clone ssh://YOUR_USER@projectaon.org/~aongit/repos/project-aon.git (you will be prompted for your password)

Once cloned, please configure Git properly by executing: 

cd project-aon
git config --local user.name "Your Name"
git config --local user.email "your.name@projectaon.org"

Development takes place in the 'develop' branch, so make sure to check out this branch first before making any commits:

git checkout develop

If you make changes, make sure you send them back using git push.

For an in-depth view of Git read the Git book.

Checking for Errors

When you have altered an XML source file, it is critical that you validate your revision.

XML Validation

Your XML must validate. RXP is a good XML validator, you can use. This validator is also available in many Linux distributors.

gblint.pl

For some of the common problems found in our XML files, we have created gblint.pl which is available in Git in the "common/scripts" module.

Publishing from XML

Those who need to publish the XML will need access to upload XML source files to the website. Request this access on the volunteer mailing list.

If everything is set up correctly and the planets are aligned, simply uploading to the previously mentioned directories will cause an XHTML version of the book to be generated from the XML source file.

Prerequisites for Automatic Publication

There are quite a few things that must be set up before automatic publication will work correctly.

  1. Each XML file must validate
  2. Publication of an entirely new language requires that the site administrator revise the cron-gbtoxhtml.pl script to include the new language and create published and working draft directories for the language including the xml/ and .publisher/ directories [Although this needs fixing, there is currently only one .publisher/ directory for each language located in the working draft area.]
  3. Each book must have an entry in the language's rules file (e.g. .publisher/rules/standard)
  4. Each book linked to within an XML file must also have an entry in the htmllink.mod file
  5. All graphics for the book must be in the correct locations

Graphics Locations

The location for graphics files is a bit byzantine. Since there is only one .publisher/ directory, both published and working draft sections pull their graphics files from the same location on the web server. For example, here is the directory structure for one English Lone Wolf book:

http://www.projectaon.org/en/gif/lw/01fftd/ http://www.projectaon.org/en/gif/lw/01fftd/ill/ http://www.projectaon.org/en/gif/lw/01fftd/ill/alvarez-blake/ http://www.projectaon.org/en/gif/lw/01fftd/ill/blake/ http://www.projectaon.org/en/gif/lw/01fftd/ill/chalk/ http://www.projectaon.org/en/gif/lw/01fftd/skins/ http://www.projectaon.org/en/gif/lw/01fftd/skins/standard/ http://www.projectaon.org/en/jpeg/lw/01fftd/ill/chalk/

Examining the contents of each directory should give some insight into what needs to go where. The ill/ directory stores all proper illustrations. The skins/ directory stores all graphics which are part of the presentation of the book.

Other languages may not have complete archives. Only those graphics which require translation may be included in the non-English directories. The graphics which don't require translation are pulled from the English (en) directories.