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:
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
- set up a Git client for your operating system. The Git site lists different clients available. For MS Windows users, we highly recommend TortoiseGit.
- 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)
- Anonymous access:
Once cloned, please configure Git properly by executing:
cd project-aon git config --local user.name "Your Name" git config --local user.email "email@example.com"
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
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.
Your XML must validate. RXP is a good XML validator, you can use. This validator is also available in many Linux distributors.
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.
- Each XML file must validate
- 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.]
- Each book must have an entry in the language's rules file (e.g. .publisher/rules/standard)
- Each book linked to within an XML file must also have an entry in the htmllink.mod file
- All graphics for the book must be in the correct 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.