Working with the eLML Developer Release using Eclipse

This manual will give you an introduction into using the eLML developer release from the CVS repository. Please note that this approach is meant for authors working with eLML and wanting to update the eLML core files regularly or commit updates themselves. For non-developers we recommend downloading the stable ZIP version at Sourceforge and to install this complete package containing all files (the CVS version meant for developers does NOT contain all required files, only the stable ZIP version does!). In this manual we will explain how developers can work with Eclipse and either Oxygen or XMLSpy Editor used as Eclipse-Plugin. Eclipse is used for CVS operations and file management. Eclipse is available for Mac, Windows or Unix and therefore a good solution for a group of authers working together.

Downloading and installing Eclipse and Oxygen or XMLSpy

Since Eclipse is an open source project, you can get it for free from the eclipse.org website. Oxygen, the XML editor of choice (to us), is a commercial software like Eclipse based on Java and therefore also available for Mac OSX, Windows, Linux and different Unix flavors. Additionally it is also available as an integrated eclipse Plugin, which makes it easier for authors using eLML to have all their working files in one place and working with one tool only. The platform-independency of Eclipse and Oxygen makes it for us the no. 1 choice when working with XML and CVS. But also Altovas XMLSpy is available es Eclipse plugin but only on Windows platforms. So here is a short tutorial on how to install the software on your computer:

Download Eclipse 3.1 (or higher) and install it on your harddisk.
Start Eclipse and you will be asked to define a workspace where all your files will be stored. We recommend creating a new folder and naming it e.g. "eclipse_elml_workspace". Now lets install the Oxygen Plugin (the XMLSpy Plugin follows below).
Open the Menu "Help" and go to "Software Update: Find and Install". Select the checkbox: "Search for new features to install" and press the "Next" button.
From the dialog "Update sites to visit" press the button "Add update site" or "New Remote Site". Enter "oXygen XML Editor" in the "Name" field and the value http://www.oxygenxml.com/InstData/Eclipse/site.xml into the "URL" field of the "New Update Site" dialog. Press the "Finish" or "OK" button. (If the above URL does not work, check the Oxygen Download page for more info)
Eclipse will look for the available software now. In the result window select the checkbox "oXygen XML Editor" and press the "Next" button.
Select the new feature to install "oXygen XML Editor and XSLT debugger" and press the "Next" button in the following install pages. Oxygen is downloaded and installed now. When finished, you must accept the Eclipse restart.
If you would like to install also the XMLSpy Plugin, please go to Altovas Eclipse page and download the Installer. Follow the instructions of the installer.

Please be aware that installing plugins might cause problems with other already installed plugins. Eg. one of our authors experienced problems when installing both Oxygen and the Eclipse Web Tools plugin. You should not have them running both at the same time.

Authentication and key generation in Eclipse (using Sourceforge CVS repositories)

Generating a key in Eclipse:

If you already generated a keypair (public and private key), you can skip this chapter and go to the next chapter. If you did not yet generate a key, Eclipse offers a nice GUI to generate key pairs.

Choose "Preferences..." from the "Windows" Menu. Now look for "Team:CVS:SSH2 Connection Method". By clicking on the "Key Management" Tab you are able to create and manage keys.
Click on "Generate DSA Key" and a new DSA key (RSA is an older method not recommended using) is generated. Enter a useful comment to remember what you created this key for (E.g. "eLML Content Server for YOURPROJECTNAME" or something similar) and enter a password for this key.
Click "Save Private Key" to save your public and private key. Usually this is done in the ".ssh" directory of your home directory and usually it is named "id_dsa" but both can be chosen as wished. Just be sure that your application (here Eclipse) knows where to look for the keys (see below). Give a useful name to your key and after saving Eclipse generated both a public (with the ".pub" extension) and a private key. Set your permissions correctly so that no one but you has privileges to read your private key!!! This is usually done using the command chmod 700 YOURKEY within the .ssh directory.
Click "Apply" and "OK" and your done with this step.

Telling Eclipse where to look for keys:

If you generated a key as described in the last chapter, your preferences are probably already set correctly. Just to be sure you might check the following steps:

Choose "Preferences..." from the "Windows" Menu. Now look for "Team:CVS:SSH2 Connection Method". Go to the "General" Tab if you're not already there.
Define here where you ".ssh" directory is (normally this is "~/.ssh") and the names of your keys (usually "id_dsa" for DSA keys). Please note that in the "Private keys" field you can enter as many keys as you like, separated by commas. If they are all in the SSH directory defined right above, entering just the name is fine, else enter the whole path (or just use the "Browse" button and Eclipse does it for you :-)
Click "Apply" and "OK" and your done with this step.

Submitting your key to Sourceforge (or to the administrator):

Eclipse is now ready to work with key authentication but the server where you will be downloading and uploading files (Sourceforge) does not know anything about your keys yet. You will have to transmit your public key (!!!) - your private key always stays on your computer - to Sourceforge. Here is how you do it:

Go to your Sourceforge Account page and click on "Account Options". If you do not have a free Sourceforge Account yet, open one now and submit your username to the eLML project responsible.
Look for the "Host Access Information" title on this page. Click on the link to edit your SSH keys.
Open the public key you generated above in your text editor of choice and copy the content. The public key should start with either "ssh-dss" or "ssh-rsa" (old format) followed by a blank and by a line of characters and numbers. Do check that the text editor added no line breaks to the public key.
Paste the public key into the provided field and once again check that you have only one key per line!
Click "Update" and wait 10 to 15 minutes until the key becomes active on Sourceforge.

If you are a developer using the elml.unizh.ch content server at the University of Zurich, submit your key by e-mail to , the server administrator. He will create an account for you and send you back your username. With this username you will be able to upload and download content for your project (e.g. GITTA or CartouCHe).

Checking out eLML and content in Eclipse using key authentication

This chapter will assume that you are an eLML project member and that you already followed the above steps about key authentication. We will also assume that your projects content files are stored on our elml.unizh.ch content server (Since Sourceforge does not allow to store content within their repository, we created a second server for storing the content. If you are interested in storing your eLML lessons on our server, please contact the administrator ).

Checking out eLML from Sourceforge

In Eclipse choose File:New:Project... and the Eclipse "Project wizard" will open.
Double click on "CVS" and the option "Checkout project from CVS" will become available. Double click it to create a new CVS project.
Now enter the information as listed below:
Host: cvs.sourceforge.net
Path: /cvsroot/elml
Username: YOURUSERNAME (your Sourceforge login name!)
Password: leave empty (you will use key login)
Connection type: Use "extssh" ("ext" will use an external ssh application)
Click "Next" and choose "Use an existing module" in the next window.
Eclipse will now connect to Sourceforge and - if the key authentication works - show you a list of available modules to download. Choose and mark the "core" module by clicking on it. Click "finish" and your done.

Now you should have a new project called "core" in your Eclipse workspace with the servername "cvs.sourceforge.net" to the right of the projectname. Now lets checkout the project specific stuff like content etc.

Checking out project specific stuff from elml.unizh.ch

Besides the "core" project within your Eclipse workspace you will need a second project containing all the project specific stuff (content, layout templates, config files etc.). It will be named after your project and can should be checked out from elml.unizh.ch. Contact the administrator of the eLML content server (at the moment ) for an account and access to that server. If you have access, here is how you can checkout e.g. the GITTA project folder:

First we need an empty project folder named after your project: In Eclipse choose File:New:Project... and the Eclipse "Project wizard" will open. Here chose Simple:Project and click "Next". You can enter the name of your project (gitta, cartouche, pto, efeed etc.) in the next window and click "Finish".
Now again choose File:New:Project... and the Eclipse "Project wizard" will open again. This time open or double click "CVS" and choose the option "Checkout project from CVS" that will become available. Double click it to create a new CVS project.
Eclipse will show you a list of stored repositories to choose from. If you already checked out lessons from the eLML content server, you can click on the settings in the list. Otherwise choose "Create a new repository location" to create a new checkout of a repository.
Now enter the information as listed below:
Host: elml.unizh.ch
Path: /usr/local/var/lib/cvs/gitta
(replace "gitta" with "cartouche" or "fois" if you work for another project)
Username: YOURUSERNAME (as sent to you by the administrator)
Password: leave empty (you will use key login)
Connection type: Use "extssh" ("ext" will use an external ssh application)
In the next window you can click the second radio button to view a list of modules you can checkout. Now you have to choose the folder "_config" and "_templates" (without them eLML wont work) and additionally choose the lessons you want to check out using command-click. Choose "Next" (not "Finish") because you are not finished yet :-)
In the next window choose the last option "Check out into an existing project" and click "Next".
Now you will see the project folder you just created (named after your project) as target folder in the following window. Choose it and now you can click "Finished" because you're done :-)

Now you can start working with eLML as described in the manual. Do not hesitate to contact if you have any problems working with this manual. The following chapter brings you a short summary of the most important points.

In the end your Eclipse workspace will look like this (instead of "Alpecole" there will be a folder with your project name of course):

eLML directory lising

The next steps: Working with Oxygen in Eclipse

These steps are described in more detail in the eLML manual that is part of the eLML project. I provide them here for the experts already working with eLML as a checklist and reminder. For more details consult the manual. OK, here are the next steps after having installed Eclipse and Oxygen and checked out eLML:

Adapt your config files: Within your project folder open the "_config" folder and you will find two configuration files. One is for the XSLT transformations (called "transform.xsl") and the other one is for the XML Schema (called "validation.xsd"). Adapted the parameters as described in the manual (or by reading the comments) and be especially careful about the following parameters:
Set path to workspace: In the _config/transform.xsl file set the path to the eLML root folder correctly. When working with Eclipse, the eLML root path is identical with the path to the Eclipse workspace (Without the last slash)! Some examples:
- Mac/Unix: "/Volumes/macgis/fisler/eclipse_workspace"
- Windows: "\C:\Documents%20and%20Settings\eclipse_workspace" (Note the %20 for blank spaces, note also that the used slash is \ and not / and that the statment starts with a slash!)
- Most platforms: ".." (relative path - seems to work on most platforms but does not work with the PDF generator!)
Set your language, project name and layout template used: Also the _config/transform.xsl file of your project be sure to set the language of the lesson you want to transform and the name of your project folder.
Set the layout template you want to use: Define the layout template you want to use and the page-break-level within the _config/transform.xsl file. Within the _template folder you also checked out there must be a folder named after the layout you set in the config file. This folder contains an online.xsl and a print.xsl file together with all other files used for the template. Refer to the eLML manual for more information.
Define an Oxygen transformation scenario: Open a lesson XML file before continuing. Now click on the wrench and screwdriver icon next to the red arrow to define a new transformation scenario. Click "new" and name it e.g. "eLML to XHTML". In the XSLT tab click the folder icon to select the _config/transform.xsl file. Choose "Saxon 8B" as XSLT engine. Click on the output tab and define an output folder. Although the correct paths are defined in the XSL file and nothing will be stored in the output folder you define, this step is necessary as Oxygen will not work without it. Choose e.g. the "html" folder of your lesson. Click save and then "Transform now" and you should get HTML files within your lesson folder as output.
To validate (if the reference is not already set in your lesson!) use the _config/validate.xsd file.
To generate a PDF: In your _config/transform.xsl File manually change the import File from online.xsl to print.xsl. If you run your transformation now the output is Formatting Objects (FO). Now create a second Oxygen transformation szenario (call it eg. "eLML to PDF") exactly as above with the only difference in the middle tab "FO Processor" you activate "Perform FO Processing" and chosse the Built-In Appache FOP processor. We recommend that under "Output" you choose "Prompt for file" so that you can name your generated PDF file as you like and store it whereever needed.