Ignore:
Timestamp:
2013-07-26T20:43:25+12:00 (11 years ago)
Author:
ak19
Message:

The tutorial doc changes for the last GS3 tutorials that needed going through.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • documentation/trunk/tutorials/xml-source/tutorial_en.xml

    r27936 r27937  
    32793279</Heading>
    32803280<NumberedItem>
    3281 <Text id="0597">There are sometimes several documents with the same title. For example, <AutoText text="All My Loving" type="italics"/> appears both as lyrics and tablature (under <AutoText text="ALL MY LOVING" type="italics"/>). The <MajorVersion number="2"><AutoText key="coredm::_Global:labelTitle_"/></MajorVersion><MajorVersion number="3"><AutoText key="gs3::metadata_names::Title.buttonname" /></MajorVersion> browser might be improved by grouping these together under a bookshelf icon. This is a job for an <AutoText text="AZCompactList"/>. In the previous tutorial we showed how to use the <AutoText text="bookshelf_type"/> option in <AutoText text="List"/> classifier to group documents with the same metadata value (<AutoText key="metadata::dc.Format"/> in that case) in one bookshelf. Here we use <AutoText text="AZCompactList"/> instead.</Text>
     3281<Text id="0597">There are sometimes several documents with the same title. For example, <AutoText text="All My Loving" type="italics"/> appears both as lyrics and tablature (under <AutoText text="ALL MY LOVING" type="italics"/>). The <MajorVersion number="2"><AutoText key="coredm::_Global:labelTitle_"/></MajorVersion><MajorVersion number="3"><AutoText key="gs3::metadata_names::Title.buttonname" /></MajorVersion> browser might be improved by grouping these together under a bookshelf icon. This is a job for an <AutoText text="AZCompactList"/>. In a previous tutorial we showed how to use the <AutoText text="bookshelf_type"/> option in <AutoText text="List"/> classifier to group documents with the same metadata value (<AutoText key="metadata::dc.Format"/> in that case) in one bookshelf. Here we use <AutoText text="AZCompactList"/> instead.</Text>
    32823282<BulletList>
    32833283<Bullet>
    … …  
    34383438</MajorVersion>
    34393439<NumberedItem>
    3440 <Text id="0648">Re-edit <MajorVersion number="2"><AutoText text="VList" /> your format statement</MajorVersion><MajorVersion number="3">the previously edited portion of the <AutoText text="documentNode"/> format statement of the <AutoText text="browse"/> format feature</MajorVersion> (in <AutoText key="glidict::CDM.GUI.Formats"/> on the <AutoText key="glidict::GUI.Format"/> panel) to be the following. You can copy this text from the file <Path>sample_files &rarr; beatles &rarr; format_tweaks &rarr; multi_icons<MajorVersion number="3">_3</MajorVersion>.txt</Path>.<MajorVersion number="3">Change: </MajorVersion></Text>
     3440<Text id="0648">Open the collection in GLI again and update <MajorVersion number="2"><AutoText text="VList" /> your format statement</MajorVersion><MajorVersion number="3">the previously edited portion of the <AutoText text="documentNode"/> format statement of the <AutoText text="browse"/> format feature</MajorVersion> (in <AutoText key="glidict::CDM.GUI.Formats"/> on the <AutoText key="glidict::GUI.Format"/> panel) to be the following. You can copy this text from the file <Path>sample_files &rarr; beatles &rarr; format_tweaks &rarr; multi_icons<MajorVersion number="3">_3</MajorVersion>.txt</Path>.<MajorVersion number="3">Change: </MajorVersion></Text>
    34413441<Format>
    34423442<MajorVersion number="2">
    … …  
    42644264<Content>
    42654265<Comment>
    4266 <MajorVersion number="2"><Text id="oaiserver-1">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. </Text></MajorVersion>
    4267 <MajorVersion number="3"><Text id="oaiserver-1-3">Greenstone 3 collections are available over OAI by default. Their <Format>collectionConfig.xml</Format> files already specify that each collection is OAI enabled, through use of an <Format>OAIPMH</Format> element. If you want to disable a collection from being accessible over OAI, edit the <Format>OAIPMH</Format> element in that collection's collectionConfig.xml. </Text></MajorVersion>
    4268 <Text id="oaiserver-2">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.</Text>
     4266<MajorVersion number="2"><Text id="oaiserver-1">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.</Text></MajorVersion>
     4267<MajorVersion number="3"><Text id="oaiserver-1-3">Greenstone 3 collections are available over OAI by default. Their <Format>collectionConfig.xml</Format> files already specify that each collection is OAI enabled, through use of an <Format>OAIPMH</Format> element. If you want to disable a collection from being accessible over OAI, edit the <Format>OAIPMH</Format> element in that collection's collectionConfig.xml.</Text></MajorVersion>
     4268<Text id="oaiserver-2"> 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.</Text>
    42694269</Comment>
    42704270<MajorVersion number="2">
    … …  
    43034303</NumberedItem>
    43044304<NumberedItem>
    4305 <Text id="oaiserver-14">Although the data transmitted over OAI is in the form of XML, Greenstone uses a stylesheet to transform that XML response into a user-friendly, structured web page that you see when you perform the <AutoText text="Identify"/> request (as happens when you visit the <AutoText text="verb=Identify" type="italics"/> response page). This allows <AutoText text="Identify" type="italics"/> and other verbs in the OAI specification to be shown in the main Greenstone OAI Server pages as link buttons. You can see these verbs represented in the main Greenstone <AutoText text="oaiserver.cgi" type="italics"/> (or <AutoText text="oaiserver.cgi?verb=Identify" type="italics"/>) page as a row of links, starting with "Identify" at the top and in the lower end of the page.</Text>
     4305<Text id="oaiserver-14">Although the data transmitted over OAI is in the form of XML, Greenstone uses a stylesheet to transform that XML response into a user-friendly, structured web page that you see when you perform the <AutoText text="Identify"/> request (as happens when you visit the <AutoText text="verb=Identify" type="italics"/> response page). This allows <AutoText text="Identify" type="italics"/> and other verbs in the OAI specification to be shown in the main Greenstone OAI Server pages as link buttons. You can see these verbs represented in the main Greenstone <MajorVersion number="2"><AutoText text="oaiserver.cgi" type="italics"/> (or <AutoText text="oaiserver.cgi?verb=Identify" type="italics"/>)</MajorVersion><MajorVersion number="3"><AutoText text="oaiserver" type="italics"/> (or <AutoText text="oaiserver?verb=Identify" type="italics"/>)</MajorVersion> page as a row of links, starting with "Identify" at the top and in the lower end of the page.</Text>
    43064306<Text id="oaiserver-15">Clicking on the links will execute that verb as a request and return the response from your Greenstone OAI server as a structured web page. Try clicking on all the links.</Text>
    43074307</NumberedItem>
    … …  
    43284328<MajorVersion number="3">
    43294329<Text id="oaiserver-22">Greenstone 3's OAI implementation uses the OAI standard for Dublin Core, <AutoText text="oai_dc" type="italics"/>, metadata format. By default, it maps all Dublin Core metadata you may have assigned to your collections into <AutoText text="oai_dc" type="italics"/>. This default mapping is specified in the <Path>web\WEB-INF\classes\OAIConfig.xml</Path> file. If all (or most) of your collections will be using a different metadata format, you can edit the OAIConfig.xml file's <Format>mappingList</Format> section to create mappings from the metadata fields you're using to those in <AutoText text="oai_dc" type="italics"/>. You can also specify mappings at a collection-level, overriding the mappings in OAIConfig.xml for that collection. So if a collection specifies metadata for a different metadata set format from the default mappings in OAIConfig.xml, adjust the collection's <Path>web\sites\localsite\collect\&lt;collection-name&gt;\etc\collectionConfig.xml</Path> file to tell Greenstone how to map the metadata fields of your chosen metadata set format into the <AutoText text="oai_dc" type="italics"/> Dublin Core metadata set supported by the Greenstone OAI server.</Text>
    4330 <Text id="oaiserver-23">For instance, look in the <b>demo</b> collection's collectionConfig.xml file (<Path>web\sites\localsite\collect\lucene-jdbm-demo\etc\collectionConfig.xml</Path>) and scroll down to the definition for the <Format>OAIPMH</Format> ServiceRack. Look in its <Format>mappingList</Format> which will explain and provide examples for how to specify such oai mappings from the <AutoText text="DLS" type="italics"/> metadata format that the <b>demo</b> collection uses, to the Dublin Core (<AutoText text="oai_dc" type="italics"/>) metadata used by Greenstone's OAI server. Its <AutoText key="metadata::dls.Title"/> metadata is mapped to <AutoText text="oai_dc.title"/> using the following line in the collectionConfig.xml configuration file (note the use of case):</Text>
    4331 <Format>&lt;mapping&gt;dc:title,dls.Title&lt;/mapping&gt;</Format>
    4332 <Text id="oaiserver-24">Because the <AutoText text="backdrop"/> collection uses DC metadata, no mapping is required, as the default mappings from DC metadata to <AutoText text="oai_dc" type="italics"/> are already specified in OAIConfig.xml.</Text>
     4330<Text id="oaiserver-23">For instance, look in the <b>demo</b> collection's collectionConfig.xml file (<Path>web\sites\localsite\collect\lucene-jdbm-demo\etc\collectionConfig.xml</Path>) and scroll down to the definition for the <Format>OAIPMH</Format> ServiceRack. Look in its <Format>mappingList</Format> which will explain and provide examples for how to specify such oai mappings from the <AutoText text="DLS" type="italics"/> metadata format that the <b>demo</b> collection uses, to the Dublin Core (<AutoText text="oai_dc" type="italics"/>) metadata used by Greenstone's OAI server. Its <AutoText key="metadata::dls.Organisation"/> metadata is mapped to <AutoText text="oai_dc.publisher"/> using the following line in the collectionConfig.xml configuration file (note the use of case):</Text>
     4331<Format>&lt;mapping&gt;dc:publisher,dls.Organization&lt;/mapping&gt;</Format>
     4332<Text id="oaiserver-24">Because the <AutoText text="backdrop"/> collection uses DC metadata, no mapping is required, as the default mappings from DC metadata to <AutoText text="oai_dc" type="italics"/> are already specified in OAIConfig.xml. (The <AutoText text="demo"/> collection has its DC metadata set's title, subject and language fields explicitly mapped to the oai_dc metadata set, although oai mappings are not necessary if the metadata set is already Dublin Core, dc.)</Text>
    43334333</MajorVersion>
    43344334</NumberedItem>
    … …  
    43654365<NumberedItem>
    43664366<Text id="gs-oai-13">Next you will need to set up your Greenstone server to be accessible from outside, so that external OAI clients can access it.</Text>
     4367<MajorVersion number="3"><Text id="gs-oai-13a">If your server runs on <AutoText text="localhost"/>, you will need to edit the tomcat-server property of your Greenstone installation's top-level file build.properties to your domain name or your machine's address.</Text></MajorVersion>
    43674368<Text id="gs-oai-14">Go to the <Path>File &rarr; Settings</Path> menu of your Greenstone server interface dialog and check the <AutoText text="Allow External Connections"/> option and also check the <AutoText text="Get local IP and resolve to a name"/> option (or the <AutoText text="Get local IP"/> option) as its address resolution method.</Text>
    43684369</NumberedItem>
    … …  
    43734374<MajorVersion number="3">
    43744375<NumberedItem>
    4375 <Text id="gs-oai-3-3">For this exercise, we will be visiting the <b>Open Archives Validator</b>, for which your OAIserver needs to provide a valid email address. In a text editor, open up your Greenstone installation's <AutoText text="web/WEB-INF/classes/OAIConfig.xml" type="italics"/> file again and set the value of the <Format>adminEmail</Format> element to the email address where the validation results are to be sent. If testing the behaviour of the <Format>resumptionToken</Format>, set the <Format>resumeAfter</Format> element to a low value like 5.</Text>
    4376 </NumberedItem>
    4377 <NumberedItem>
    4378 <Text id="gs-oai-3-4">Restart the Greenstone 3 server if it was running. Otherwise, go to <Menu>Start &rarr; Greenstone &rarr; Greenstone3 Server</Menu> to start up the server. When the library home page opens in your browser, change the library suffix in the URL to <Format>oaiserver</Format>, which is the baseURL of your OAI Server. Copy this URL and visit <Link>http://www.openarchives.org/Register/ValidateSite</Link>.</Text>
    4379 </NumberedItem>
    4380 </MajorVersion>
    4381 <NumberedItem>
    4382 <Text id="gs-oai-16">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 <b>Validate baseURL</b> button to start running the tests. You will be told to check your email to continue the remaining tests and to get the validation report.</Text>
     4376<Text id="gs-oai-3-3">For this exercise, we will be visiting the <b>Open Archives Validator</b>, for which your OAIserver needs to provide a valid email address. In a text editor, open up your Greenstone installation's <AutoText text="web/WEB-INF/classes/OAIConfig.xml.in" type="italics"/> file again. Set the value of the <Format>adminEmail</Format> element to the email address where the validation results are to be sent. Also set the <Format>repositoryId</Format> element (OAI repositoryIdentifier). The structure of its value is like a domain name and needs to be of the form of <Format>word-dot-extension</Format>, such as "greenstone.org". For more information on the structure of its value, see <Link>http://www.openarchives.org/OAI/2.0/guidelines-oai-identifier.htm</Link>. (If you wanted to additionally test the behaviour of the <Format>resumptionToken</Format> against the OAI Validator, you would set the <Format>resumeAfter</Format> element to a low value like 5).</Text>
     4377</NumberedItem>
     4378<NumberedItem>
     4379<Text id="gs-oai-3-4">Restart the Greenstone 3 server if it was running. Otherwise, go to <Menu>Start &rarr; Greenstone &rarr; Greenstone3 Server</Menu> to start up the server. When the library home page opens in your browser, change the library suffix in the URL to <Format>oaiserver</Format>, which is the baseURL of your OAI Server and would be of the form <Format>http://domain/greenstone3/oaiserver</Format>. Copy this URL and visit <Link>http://www.openarchives.org/Register/ValidateSite</Link>.</Text>
     4380</NumberedItem>
     4381</MajorVersion>
     4382<NumberedItem>
     4383<Text id="gs-oai-16">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 <b>Validate baseURL</b> button to start running the tests. You will be told to check the <Format>adminEmail</Format> address you provided to continue the remaining tests and to get the validation report.</Text>
    43834384<Text id="gs-oai-17">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 that URL is still not accepted, visit the <AutoText text="oaiserver.cgi?verb=Identify" type="italics"/> page again and check this works. If it doesn't, it may be 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.</Text>
    43844385</NumberedItem>
    … …  
    43934394<Content>
    43944395<Comment>
    4395 <Text id="0734">GLI can serve as an OAI client application: it can connect to a remote OAI server and retrieve metadata, even download documents. The tutorial <TutorialRef id="OAI_collection"/> did not obtain the data from an external OAI-PMH server. This missing step is accomplished either by running a command-line program or by using the <AutoText key="glidict::GUI.Download"/> panel in the Librarian Interface. This exercise explains how you would do this using both methods. In the previous exercise, we set up the Greenstone server to serve the <b>Simple image collection (backdrop)</b> over OAI. In this tutorial, we will use GLI to connect to that OAI server and download OAI metadata for the <b>Simple image collection</b> and even download its documents. The principle is the same if you wish to connect to other OAI servers.</Text>
     4396<Text id="0734">GLI can serve as an OAI client application: it can connect to a remote OAI server and retrieve metadata, even download documents. The tutorial <TutorialRef id="OAI_collection"/> did not obtain the data from an external OAI-PMH server. This missing step is accomplished either by running a command-line program or by using the <AutoText key="glidict::GUI.Download"/> panel in the Librarian Interface. This exercise explains how you would do this using both methods. In the previous exercise, we set up the Greenstone server to serve <MajorVersion number="2">the <b>Simple image collection (backdrop)</b></MajorVersion><MajorVersion number="3">your Greenstone 3 collections</MajorVersion> over OAI. In this tutorial, we will use GLI to connect to that OAI server and download OAI metadata for the <b>Simple image collection</b> and even download its documents. The principle is the same if you wish to connect to other OAI servers.</Text>
    43964397</Comment>
    43974398<Heading>
    … …  
    44714472<MajorVersion number="3">perl -S downloadfrom.pl -download_mode OAI -url http://&lt;hostname:portnumber&gt;/greenstone3/oaiserver -set localsite:backdrop -max_records 5</MajorVersion>
    44724473</Format>
    4473 <Text id="0747">The records (and optionally documents, if you additionally pass in the <Format>-get_doc</Format> flag to the above command) will be downloaded into the folder where the downloadfrom.pl script is run from. To change this, use the <Format>-cache_dir <i>full-path-to-folder</i></Format> option and set its value to the full path of the destination folder you choose.</Text>
     4474<Text id="0747">The OAI records will be downloaded into the folder where the downloadfrom.pl script is run from. To change this, use the <Format>-cache_dir <i>full-path-to-folder</i></Format> option and set its value to the full path of the destination folder you choose. (If you wanted to download the documents along with the records, then you would additionally pass in the <Format>-get_doc</Format> flag to the above command as well as the <Format>-get_doc_exts</Format> flag followed by a comma-separated list of file extensions like "jpg,pdf".)</Text>
    44744475</NumberedItem>
    44754476<Comment><Text id="0748">You can import the downloaded documents into a new Greenstone collection and build them in the usual manner.</Text></Comment>
    … …  
    44824483</NumberedItem>
    44834484<NumberedItem>
    4484 <Text id="gli-oai-15">Open GLI, locate files you downloaded over OAI and drag and drop these into a new Greenstone collection called <AutoText text="OAI Collection" />.<MajorVersion number="2"> Because there are <Format>*.oai</Format> files among those downloaded, GLI will offer to add the <AutoText text="OAIPlugin"/>. You may wish to go to the <AutoText key="glidict::GUI.Design"/> panel and remove the <AutoText text="EmbeddedMetadataPlugin"/> from the list of <AutoText key="glidict::CDM.GUI.Plugins"/> to speed up building.</MajorVersion></Text>
    4485 </NumberedItem>
     4485<Text id="gli-oai-15">Open GLI, locate files you downloaded over OAI and drag and drop these into a new Greenstone collection called <AutoText text="OAI Collection" />.<MajorVersion number="2"> Because there are <Format>*.oai</Format> files among those downloaded, GLI will offer to add the <AutoText text="OAIPlugin"/>. <!--You may wish to go to the <AutoText key="glidict::GUI.Design"/> panel and remove the <AutoText text="EmbeddedMetadataPlugin"/> from the list of <AutoText key="glidict::CDM.GUI.Plugins"/> to speed up building.--></MajorVersion></Text>
     4486</NumberedItem>
     4487<!--<NumberedItem>
     4488<Text id="gli-oai-15a">Go the <AutoText key="glidict::GUI.Design"/> panel, and configure the <AutoText text="OAIPlugin"/>'s <AutoText text="document_field"/> option to <AutoText key="metadata::ex.dc.Identifier"/>.</Text>
     4489</NumberedItem>-->
    44864490<NumberedItem>
    44874491<Text id="gli-oai-16">Switch to the <AutoText key="glidict::GUI.Create"/> panel and press the <b>build</b> button. During this stage, the <AutoText text="OAIPlugin"/> will extract the metadata in the <AutoText text="oai" type="italics"/> files and attach them to the associated <AutoText text="jpg" type="italics"/> files of the downloaded <b>backdrop</b> collection. You can see this once the collection has been built by switching to the <AutoText key="glidict::GUI.Enrich"/> panel and clicking on an oai file, as no metadata is set for such files. However, if you then click on a jpg file and scroll down, there will be metadata names that start with <Format>ex.dc</Format>. This refers to Greenstone-extracted Dublin Core metadata. <AutoText key="metadata::ex.dc.Description"/> and <AutoText key="metadata::ex.dc.Title"/> will be set to the values you had assigned the images in the tutorial <b>A Simple Image Collection</b>. Greenstone will have added additional <Format>ex.dc</Format> metadata in the form of <AutoText key="metadata::ex.dc.Identifier"/>, which is the source URL for this image.</Text>
Note: See TracChangeset for help on using the changeset viewer.