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 (repo). You can access a public web view of the repo or clone the repo to work with the files on your local machine. To clone the repo, you will need to install a git client. (See also available git clients.)

To gain write access and push your changes back to the shared repo, post a request for access to the repository on the volunteer mailing list.

To clone the repo anonymously for read-only purposes, run the following on the command line.

git clone https://git.projectaon.org/project-aon.git

To clone it in order to make changes that you will push back to the shared repo, you first need to set up git to accept the shared repo.

ssh YOUR_USERNAME@projectaon.org
git config --global --add safe.directory /home/aongit/repos/project-aon.git
logout

Then you should be able to clone the repo on your local machine.

git clone ssh://YOUR_USERNAME@projectaon.org/~aongit/repos/project-aon.git
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 changes.

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:

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.