Index: /documentation/trunk/tutorials/xml-source/tutorial_en.xml
===================================================================
--- /documentation/trunk/tutorials/xml-source/tutorial_en.xml (revision 26011)
+++ /documentation/trunk/tutorials/xml-source/tutorial_en.xml (revision 26012)
@@ -627,5 +627,5 @@
First, set each file's field to be the same as its filename but without the filename extension.Click on Bear.jpg so its metadata fields are available, then click on its field on the right-hand side. Type in Bear.
-Repeat the process for Cat.jpg and Cheetah.jpg.
+Repeat the process for Cat.jpg, Cheetah.jpg and so on.
@@ -647,10 +647,10 @@
Click on the browse Format Feature. Find the section under documentNode where it says
- <td valign="top">
- <gsf:displayText name="ImageName"/>:<gsf:metadata name="Image"/><br/>
- <gsf:displayText name="Width"/>:<gsf:metadata name="ImageWidth"/><br/>
- <gsf:displayText name="Height"/>:<gsf:metadata name="ImageHeight"/><br/>
- <gsf:displayText name="Size"/>:<gsf:metadata name="ImageSize"/>
- </td>
+<td valign="top">
+<gsf:displayText name="ImageName"/>:<gsf:metadata name="Image"/><br/>
+<gsf:displayText name="Width"/>:<gsf:metadata name="ImageWidth"/><br/>
+<gsf:displayText name="Height"/>:<gsf:metadata name="ImageHeight"/><br/>
+<gsf:displayText name="Size"/>:<gsf:metadata name="ImageSize"/>
+</td>
Edit the text as follows:
@@ -722,8 +722,8 @@
-Switch to the panel, build the collection, then preview it. There is now a button in the navigation bar. As an example, search for the term "bear" in the index (which is the only index at this point).
-
-
-To change the text that is displayed for the index (), go to the panel back in the Librarian Interface. Select from the left-hand list. This panel allows you to change the text that is displayed on the search form. Change the for the "dc.Description" index to "image descriptions" (or other suitable text). Go back to the browser and reload the search page. Your new text will appear in the search form.
+Switch to the panel, build the collection, then preview it. There is now a button in the navigation bar. As an example, search for the term "bear" in the index (which is the only index at this point).
+
+
+To change the text that is displayed for the index (), go to the panel back in the Librarian Interface. Select from the left-hand list. This panel allows you to change the text that is displayed on the search form. Change the for the "dc.Description" index to "image descriptions" (or other suitable text). Go back to the browser and reload the search page. Your new text will appear in the search form. Note that if you use text instead of macros in the search metadata display text, you will need to do any translations yourself.
@@ -3204,7 +3204,14 @@
-Greenstone 2 collections are not enabled for OAI out of the box. To make a collection available for serving up over OAI, some minor adjustments need to be made first.
+Greenstone 2 collections are not enabled for OAI out of the box. To make a collection available for serving up over OAI, some minor adjustments need to be made first.
+Greenstone 3 collections are available over OAI by default. Their collectionConfig.xml files already specify that each collection is OAI enabled, through use of an OAIPMH element. If you want to disable a collection from being accessible over OAI, edit the OAIPMH element in that collection's collectionConfig.xml. This tutorial will look at how to make an existing collection available over OAI and testing its accessibility by getting it validated against the Open Archives validator.
+
+
+To make your Greenstone 3 OAI server accessible to the outside world you may need to first set the baseURL property in OAIConfig.xml. Use a text editor to open the file located in your Greenstone installation folder. Find the baseURL element and set its value to your usual Greenstone library URL, but with the suffix library replaced by oaiserver.
+
+
+Use a text editor to open the file etc/oai.cfg located in your Greenstone installation folder. The oai.cfg configuration file contains properties that control the behaviour and features of your Greenstone OAI server.
@@ -3223,7 +3230,14 @@
If you're on Windows, it's best to be using the Apache web server. So if you're using the Local Library Server, stop the web server by exiting the little white dialog (the Greenstone Server Interface). Use a file browser to go into your Greenstone installation directory and rename the there to to disable it. Now re-launch the Greenstone Server from the menu, so that this time, the included Apache web server will be used instead, launching its own little white dialog.
-
-You are now ready to visit your oaiserver home page to check that it's all looking good. Start up the Greenstone Server by going to Windows Start → All Programs → Greenstone 2.85 → Greenstone Server.
-Press the button and you will end up on your Digital Library home page as usual. Adjust the URL so that instead of the suffix, it says .
+
+
+You are now ready to visit your oaiserver home page to check that it's all looking good.
+
+Start up the Greenstone Server by going to Windows Start → All Programs → Greenstone 2.85 → Greenstone Server.
+
+
+Start up the Greenstone 3 Server by going to Windows Start → All Programs → Greenstone-3 → Greenstone3 Server.
+
+Press the button and you will end up on your Digital Library home page as usual. Adjust the URL so that instead of the suffix, it says .The page that loads now will contain an error message () saying that you've provided an illegal OAI verb. This is because the OAI specification requires you to provide more instruction in the URL as to what you want. The specification defines verbs and possible arguments to them.A basic verb is , which requests the OAI server to return some information about the OAI repository that it's serving. Adjust the URL once more by suffixing , so that your URL now looks like:
@@ -3241,13 +3255,18 @@
-You will see a couple of buttons next to each collection (or ) listed here. The first is Identifiers and the second Records. Click on the Identifiers button for the backdrop Set. This will list all the IDs of the documents contained in your OAI collection. If you look at the IDs, they look similar enough to Greenstone's internal document IDs, but with an additional prefix (oai:<repositoryID>:<setname>, where repositoryID was set by you in the configuration file, and setname is the name of the collection).
+You will see a couple of buttons next to each collection (or ) listed here. The first is Identifiers and the second Records. Click on the Identifiers button for the backdrop Set. This will list all the IDs of the documents contained in your OAI collection.
+
+If you look at the IDs, they look similar enough to Greenstone's internal document IDs, but with an additional prefix (oai:<repositoryID>:<setname>, where repositoryID was set by you in the configuration file, and setname is the name of the collection).
+Click the browser Back button to get back to the ListSets page and press the Records button located next to the backdrop collection.
-If you specified some Dublin Core (dc) metadata for each images in the backdrop collection, then the page that loads will display this information for each document in the collection (Set).
+If you had specified some Dublin Core (dc) metadata for each of the images in the backdrop collection, then the page that loads will display this information for each document in the collection (Set).
+Greenstone's OAI at present supports 3 metadata formats, as is explained in the instructive comments in the oai.cfg file. Of these three, the OAI standard for Dublin Core, , is the one pertinent to this tutorial. If your collection specifies metadata for a different metadata set format, you can use the oai.cfg file to tell Greenstone how to map the metadata fields of your chosen metadata set format into the Dublin Core metadata set supported by the Greenstone OAI server (or one of the other metadata sets it supports).Look in the oai.cfg file again and scroll down to the section on oaimapping, which will explain and provide examples for how to specify such mappings from your metadata format to one that Greenstone's OAI server uses. For instance, the demo collection comes enabled for OAI upon installation, and specifies some mappings from its metadata format to . Its metadata is mapped to using the following line in the oai.cfg configuration file (note the use of case):oaimapping dls.Title oai_dc.titleBecause the backdrop collection uses DC metadata already, no mapping is required.
+
@@ -3260,4 +3279,5 @@
We'll be using an external OAI client to access our up-and-running Greenstone OAI server. It's not just any OAI client either, but an OAI Server validator.
+You will want to be running the included Apache web server. So if you're on Windows and using the Local Library Server, quit it and rename the application in your Greenstone installation folder to server.not. Then use the menu shortcut to the Greenstone Server once more, to now launch the Apache web server.
@@ -3287,7 +3307,16 @@
Press the button in the Greenstone Server Interface dialog that says (or it may say ). Your Digital Library home page will open up in a browser tab. Adjust this URL to have a suffix of oaiserver.cgi in place of the terminating library.cgi, then copy the resulting URL and visit http://www.openarchives.org/Register/ValidateSite.
+
+
+
+For this exercise, we will be visiting the Open Archives Validator, for which your OAIserver needs to provide a valid email address. In a text editor, open up your Greenstone installation's file again and set the value of the adminEmail element to your email address to which you would like to get the validation results sent. If testing the behaviour of the resumptionToken, set the resumeAfter element to a low value like 5.
+
+
+Restart the Greenstone 3 server if it was running. Otherwise, go to to start up the server. When the library home page opens in your browser, change the library suffix in the URL to oaiserver to visit the OAIServer page. Copy this URL.
+
+The Open Archives Validator page will request the URL to your Greenstone OAI server. Paste the URL you have in your copy buffer into the field provided for this, and press the Validate baseURL button to start running the tests. You will be told to check your email to continue the remaining tests and get the validation report.
-If the validator does not recognise the URL, make sure you have given the full domain of your host machine rather than just the host name. Alternatively, visit the page again and check that works. If it doesn't, maybe your machine is not set up to be accessible to outside networks. Check your proxy settings, make sure you've set up port forwarding and that your firewall is not interfering.
+If the validator does not recognise the URL, make sure you have given the full domain of your host machine rather than just the host name. If the URL is still not accepted, visit the page again and check that works. If it doesn't, maybe your machine is not set up to be accessible to outside networks. Check your proxy settings, make sure you've set up port forwarding and that your firewall is not interfering.