Changeset 32900


Ignore:
Timestamp:
2019-03-13T22:24:56+13:00 (5 years ago)
Author:
ak19
Message:

Next set of 5 or 6 tutorials modified for upcoming GS3.09.

File:
1 edited

Legend:

Unmodified
Added
Removed

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

    r32899 r32900  
    37503750  &lt;/td&gt;<br />
    37513751</Format>
    3752 <Text id="0687-3b">Then, in <AutoText text="classifierNode"/> template for <AutoText text="VList"/>s, replace the contents of the final <Format>&lt;td&gt;</Format> table cell element with the following which can also be copied from the file <Path>titles_tweak_gs3.txt</Path>:</Text>
     3752<Text id="0687-3b">Then, in the <AutoText text="classifierNode"/> template for <AutoText text="VList"/>s, replace the contents of the final <Format>&lt;td&gt;...&lt;/td&gt;</Format> table cell element with the following which can also be copied from the file <Path>titles_tweak_gs3.txt</Path>:</Text>
    37533753<Format>
    37543754  &lt;td valign=&quot;top&quot;&gt;<br />
    … …  
    38083808<NumberedItem>
    38093809<Text id="0691">The <MajorVersion number="2"><AutoText key="coredm::_Global:labelDate_" type="italics"/></MajorVersion><MajorVersion number="3"><AutoText key="gs3::metadata_names::Date.buttonname"/>
    3810 </MajorVersion> list groups documents by date. Greenstone's internal date format is YYYYMMDD, for example 18580601, and this is crucial for the <AutoText text="DateList" /> classifier to correctly parse date metadata and generate an ordered date list. However, the date has been made to look nice by adding a <MajorVersion number="2"><AutoText text="[format:]"/> macro</MajorVersion><MajorVersion number="3">&quot;<AutoText text="format=formatDate"/>&quot; attribute</MajorVersion> to Date metadata in the format statement.</Text>
     3810</MajorVersion> list groups documents by date. Greenstone's internal date format is YYYYMMDD, for example 18580601, and this is crucial for the <AutoText text="DateList" /> classifier to correctly parse date metadata and generate an ordered date list. However, the date has been made to look nice by adding a <MajorVersion number="2"><AutoText text="[format:]"/> macro</MajorVersion><MajorVersion number="3"><AutoText text="format=&quot;formatDate&quot;"/> attribute</MajorVersion> to Date metadata in the format statement.</Text>
    38113811</NumberedItem>
    38123812<NumberedItem>
    … …  
    38433843</MajorVersion>
    38443844<MajorVersion number="3">
    3845 This can be done by selecting <AutoText text="global"/> in assigned format statements panel and clicking &lt;<AutoText text="Undo"/>&gt; a few times.</MajorVersion>
     3845This can be done by selecting <AutoText text="global"/> in assigned format statements panel and clicking &lt;<AutoText text="Undo"/>&gt; one or more times.</MajorVersion>
    38463846</Text>
    38473847</NumberedItem>
    … …  
    39213921</Comment>
    39223922<NumberedItem>
    3923 <Text id="0690h-1">In the <AutoText key="glidict::CDM.GUI.Formats"/> section, select <AutoText text="Search"/> in <AutoText key="glidict::CDM.FormatManager.Feature"/><MajorVersion number="3"> to adjust how search results are displayed.</MajorVersion><MajorVersion number="2">, and <AutoText text="VList"/> in <AutoText key="glidict::CDM.FormatManager.Part"/>. Click <AutoText key="glidict::CDM.FormatManager.Add" type="button"/> to add this format to the collection. The previous changes modified <AutoText text="VList"/>, so they will apply to all <AutoText text="VList"/>s that don't have specific format statements. These next changes are made to <AutoText text="SearchVList"/> so will only apply to search results. </MajorVersion></Text>
     3923<Text id="0690h-1">In the <AutoText key="glidict::CDM.GUI.Formats"/> section of the <AutoText key="glidict::GUI.Format"/> panel, select <AutoText text="Search"/> in <AutoText key="glidict::CDM.FormatManager.Feature"/><MajorVersion number="3"> to adjust how search results are displayed.</MajorVersion><MajorVersion number="2">, and <AutoText text="VList"/> in <AutoText key="glidict::CDM.FormatManager.Part"/>. Click <AutoText key="glidict::CDM.FormatManager.Add" type="button"/> to add this format to the collection. The previous changes modified <AutoText text="VList"/>, so they will apply to all <AutoText text="VList"/>s that don't have specific format statements. These next changes are made to <AutoText text="SearchVList"/> so will only apply to search results. </MajorVersion></Text>
    39243924<Text id="0690i">The extracted Title for the current section is specified as <Format><MajorVersion number="2">[ex.Title]</MajorVersion><MajorVersion number="3">&lt;gsf:metadata name=&quot;Title&quot;/&gt;</MajorVersion></Format> while the Title for the parent section is <Format><MajorVersion number="2">[parent:ex.Title]</MajorVersion><MajorVersion number="3">&lt;gsf:metadata name=&quot;Title&quot; select=&quot;parent&quot;/&gt;</MajorVersion></Format>. Since the same <AutoText text="SearchVList"/> format statement is used when searching both whole newspapers and newspaper pages, we need to make sure it works in both cases.</Text>
    39253925<MajorVersion number="2">
    … …  
    39273927</MajorVersion>
    39283928<MajorVersion number="3">
    3929 <Text id="0690j-3">Replace the lines comprising the final <Format>&lt;td&gt;</Format> table cell element with the following format statement (it can be copied and pasted from the file <Path>sample_files &rarr; niupepa &rarr; formats &rarr; search_tweak_gs3.txt</Path>):</Text>
     3929<Text id="0690j-3">Replace the lines comprising the final <Format>&lt;td&gt;...&lt;/td&gt;</Format> table cell element with the following format statement (it can be copied and pasted from the file <Path>sample_files &rarr; niupepa &rarr; formats &rarr; search_tweak_gs3.txt</Path>):</Text>
    39303930</MajorVersion>
    39313931<Format>
    … …  
    40514051</NumberedItem>
    40524052<NumberedItem>
    4053 <Text id="sc17">Save the file using <b>Filename </b> <AutoText text="12_3_6.item" type="italics"/>, and save as a plain text document. (If you are using Windows, make sure the file doesn't accidentally end up getting saved as <AutoText text="12_3_6.item.txt" type="italics"/>.) Back in the <AutoText key="glidict::GUI.Gather"/> panel of the Librarian Interface, locate the new file in the <b>Workspace</b> tree, and drag it into the collection, adding it to the <AutoText text="12"/> folder.</Text>
     4053<Text id="sc17">Save the file using <b>Filename </b> <AutoText text="12_3_6.item" type="italics"/>, and save as a plain text document. (If you are using Windows, make sure the file doesn't accidentally end up getting saved as <AutoText text="12_3_6.item.txt" type="italics"/>.) Back in the <AutoText key="glidict::GUI.Gather"/> panel of the Librarian Interface, locate the new file in the <b>Workspace</b> tree, and drag it into the collection, adding it into the <AutoText text="12"/> folder.</Text>
    40544054</NumberedItem>
    40554055<NumberedItem>
    … …  
    41534153</NumberedItem>
    41544154<NumberedItem>
    4155 <Text id="0707">During the copy operation, a popup window may appear asking whether to add <AutoText text="OAIPlugin" /> to the list of plug-ins used in the collection, because the Librarian Interface has not found an existing plug-in that can handle this file type. Press the <AutoText key="glidict::CDM.PlugInManager.QuickAdd" type="button"/> button to include it.</Text>
     4155<Text id="0707">If the <AutoText text="OAIPlugin" /> is not already in the <AutoText key="glidict::CDM.GUI.Plugins"/> list, then during the copy operation a popup window may appear asking whether to add <AutoText text="OAIPlugin" /> to the list of plug-ins used in the collection, because the Librarian Interface has not found an existing plug-in that can handle this file type. Press the <AutoText key="glidict::CDM.PlugInManager.QuickAdd" type="button"/> button to include it.</Text>
    41564156<Text id="0707a">The files for this collection consist of a set of images (in <Path>JCDLPICS &rarr; srcdocs</Path>) and a set of OAI records (in <Path>JCDLPICS</Path>) which contain metadata for the images.</Text>
    41574157</NumberedItem>
    … …  
    43324332<Comment>
    43334333<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>
    4334 <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>
     4334<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 serviceRack</Format> element. If you want to disable a collection from being accessible over OAI, edit the <Format>OAIPMH serviceRack</Format> element in that collection's collectionConfig.xml.</Text></MajorVersion>
    43354335<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>
    43364336</Comment>
    … …  
    43704370</NumberedItem>
    43714371<NumberedItem>
    4372 <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>
    4373 <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>
     4372<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 button links starting with "Identify", displayed at the top and in the lower part of the page.</Text>
     4373<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 button links.</Text>
    43744374</NumberedItem>
    43754375<NumberedItem>
    … …  
    43794379</NumberedItem>
    43804380<NumberedItem>
    4381 <Text id="oaiserver-19">You will see a couple of buttons next to each collection (or <AutoText text="Set"/>) listed here. The first is <b>Identifiers</b> and the second <b>Records</b>. Click on the <b>Identifiers</b> button for the <b>backdrop</b> Set. This will list all the IDs of the documents contained in your OAI collection.</Text>
    4382 <MajorVersion number="2">
    4383 <Text id="oaiserver-19b">If you look at the IDs, they look similar enough to Greenstone's internal document IDs, but with an additional prefix (<Format>oai:&lt;repositoryID&gt;:&lt;setname&gt;</Format>, where <Format>repositoryID</Format> was set by you in the <AutoText text="oai.cfg" type="italics"/> configuration file, and <Format>setname</Format> is the name of the collection).</Text>
     4381<Text id="oaiserver-19">You will see a couple of buttons next to each collection (or <AutoText text="Set"/>) listed here. The first is <b>Identifiers</b> and the second <b>Records</b>. Click on the <b>Identifiers</b> button for the <b>backdrop</b> Set. This will list all the OAI identifiers of the documents contained in your OAI collection.</Text>
     4382<MajorVersion number="2">
     4383<Text id="oaiserver-19b">If you look at the OAI identifiers, they look similar enough to Greenstone's internal document IDs, but with an additional prefix (<Format>oai:&lt;repositoryID&gt;:&lt;setname&gt;</Format>, where <Format>repositoryID</Format> was set by you in the <AutoText text="oai.cfg" type="italics"/> configuration file, and <Format>setname</Format> is the name of the collection).</Text>
    43844384</MajorVersion>
    43854385</NumberedItem>
    … …  
    43944394</MajorVersion>
    43954395<MajorVersion number="3">
    4396 <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>elementList</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>
     4396  <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 configurable file <Path>resources\oai\OAIConfig.xml.in</Path>, from which <Path>web\WEB-INF\classes\OAIConfig.xml</Path> is generated. If all (or most) of your collections will be using a different metadata format, you can edit the <Path>resources\oai\OAIConfig.xml.in</Path> file's <Format>elementList</Format> section to create mappings from the metadata fields you're using to the metadata fields in <AutoText text="oai_dc" type="italics"/>.</Text>
     4397  <Text id="oaiserver-22a">You can also specify mappings at collection level, overriding the mappings in <Format>OAIConfig.xml.in</Format> on a per-collection basis. So if a collection specifies metadata for a different metadata set format from the default mappings in <Format>OAIConfig.xml.in</Format>, 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>
    43974398<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 at its <Format>ListMetadataFormats</Format> section containing element mappings, which will explain and provide an example for how to specify such an oai mapping 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.Organization"/> 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>
    43984399<Format>&lt;element name=&quot;dc:publisher&quot;&gt;<br />
    … …  
    44144415<MajorVersion number="3">
    44154416<NumberedItem>
    4416 <Text id="gs-oai-13a">We want the Greenstone library to be accessible to the Open Archives Validator, however URLs that use <Format>localhost</Format> can only be accessed locally. Therefore, if your Greenstone server runs on <Format>localhost</Format> (as it does by default), then you will need to edit the <Format>tomcat.server</Format> property of your Greenstone installation's top-level file <AutoText text="build.properties" type="italics" /> and set this property to your domain name or your machine's IP address.</Text>
     4417<Text id="gs-oai-13a">We want the Greenstone library to be accessible to the Open Archives Validator, however URLs that use <Format>localhost</Format> can only be accessed locally. Therefore, if your Greenstone server runs on <Format>localhost</Format> (as it does by default), then you will need to stop the Greenstone server, edit the <Format>tomcat.server</Format> property of your Greenstone installation's top-level file <AutoText text="build.properties" type="italics" /> and set this property to your domain name or your machine's IP address. Finally, restart the Greenstone server.</Text>
    44174418</NumberedItem>
    44184419</MajorVersion>
    … …  
    44474448<MajorVersion number="3">
    44484449<NumberedItem>
    4449 <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="resources/oai/OAIConfig.xml" type="italics"/> file. Set the value of the <Format>adminEmail</Format> element to the email address where the validation results are to be sent. Also set the OAI <Format>repositoryIdentifier</Format> element. 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 ResumptionToken feature against the OAI Validator, you would set the <Format>resumeAfter</Format> element to a low value like 5).</Text>
    4450 </NumberedItem>
    4451 <NumberedItem>
    4452 <Text id="gs-oai-3-4">Start up the Greenstone 3 server application, or quit and relaunch it 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>
    4453 </NumberedItem>
    4454 </MajorVersion>
    4455 <NumberedItem>
    4456 <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>
     4450<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 <Path>resources\oai\OAIConfig.xml.in</Path> file. Set the value of the <Format>adminEmail</Format> element to the email address where the validation results are to be sent. Also set the OAI <Format>repositoryIdentifier</Format> element. 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 ResumptionToken feature against the OAI Validator, you would set the <Format>resumeAfter</Format> element to a low value like 5).</Text>
     4451</NumberedItem>
     4452<NumberedItem>
     4453<Text id="gs-oai-3-4">The modifications to OAIConfig.xml.in need to be brought into effect, so quit and relaunch the Greenstone 3 server application if it is already running. Otherwise, go to <Menu>Start &rarr; Greenstone &rarr; Greenstone3 Server</Menu> to start it up. 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>
     4454</NumberedItem>
     4455</MajorVersion>
     4456<NumberedItem>
     4457<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. Follow the instructions in their email in order to do so.</Text>
    44574458<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 that 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>
    44584459</NumberedItem>
    … …  
    46904691</NumberedItem>
    46914692<NumberedItem>
    4692 <Text id="0758"><b>Rebuild</b> the collection.</Text>
     4693<Text id="0758"><b>Rebuild</b> the collection. If you choose to preview it, things should look as before.</Text>
    46934694</NumberedItem>
    46944695<NumberedItem>
    … …  
    48404841</Heading>
    48414842<NumberedItem>
    4842 <Text id="0790a">If you're on Windows, open a DOS window to access the command-line prompt. This facility should be located somewhere within your <Menu>Start &rarr; Programs</Menu> menu, but details vary between different Windows systems. If you cannot locate it and you are running <AutoText text="Windows XP"/>, select <Menu>Start &rarr; Run</Menu> and enter <Command>cmd</Command> in the popup window that appears. In either <AutoText text="Windows Vista"/> or <AutoText text="Windows 7"/>, click the Start button and type <Command>cmd</Command> in the search box at the bottom of the Start menu.</Text>
     4843<Text id="0790a">If you're on Windows, open a DOS window to access the command-line prompt. This facility should be located somewhere within your <Menu>Start &rarr; Programs</Menu> menu, but details vary between different Windows systems. If you cannot locate it and you are running <AutoText text="Windows XP"/>, select <Menu>Start &rarr; Run</Menu> and enter <Command>cmd</Command> in the popup window that appears. In <AutoText text="Windows Vista"/> or <AutoText text="Windows 7"/>, click the Start button and type <Command>cmd</Command> in the search box at the bottom of the Start menu. On <AutoText text="Windows 10"/>, hold down the Windows key (located between the Ctrl and Alt keys) and press <Format>s</Format> to bring up the <AutoText text="Search Windows"/> box and type <Format>cmd</Format> in it.</Text>
    48434844<Text id="0790aa">If you're on a Unix system or on a Mac, open a terminal.</Text>
    48444845</NumberedItem>
Note: See TracChangeset for help on using the changeset viewer.