Changeset 34529


Ignore:
Timestamp:
2020-11-06T23:49:48+13:00 (3 years ago)
Author:
ak19
Message:

Some additional changes to the GS3 tutorials that remained from Windows testing and some more that were needed after linux testing.

File:
1 edited

Legend:

Unmodified
Added
Removed

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

    r34517 r34529  
    20122012</MajorVersion>
    20132013<MajorVersion number="3">
    2014 <Text id="assoc-files-24b">The above change to the browse format statement, adds the equivalent document icon (a PDF icon in this case) next to the source icon (Word icon) for general classifiers. But the Titles classifier has its own separate format statement, listed as "C1 List" in <AutoText key="glidict::CDM.FormatManager.Feature"/>. So the same change indicated above needs to also be made to "C1 List" format statement. After doing so, preview the collection and browse the collection either by Titles or by Filenames.</Text> 
     2014<Text id="assoc-files-24b">The above change to the browse format statement, adds the equivalent document icon (a PDF icon in this case) next to the source icon (Word icon) for general classifiers. Preview the collection and browse the collection either by Titles or by Filenames.</Text> 
    20152015</MajorVersion> 
    20162016<Text id="assoc-files-24a">Preview the collection.</Text>
    … …  
    40104010<Text id="0690a"><MajorVersion number="2">Refresh in the web browser to view</MajorVersion><MajorVersion number="3"><b>Preview</b></MajorVersion> the new <MajorVersion number="2"><AutoText key="coredm::_Global:labelTitle_"/></MajorVersion><MajorVersion number="3"><AutoText key="gs3::metadata_names::Title.buttonname" /></MajorVersion> list.</Text>
    40114011<Text id="0687c">As a consequence of using the <AutoText text="bookshelf_type"/> option of the <AutoText text="List"/> classifier, bookshelf icons appear when titles are browsed. This revised format statement has the effect of specifying in brackets how many items are contained within a bookshelf<MajorVersion number="3"> for classifier nodes</MajorVersion>. <MajorVersion number="2">It works by exploiting the fact that only bookshelf icons define <Format>[numleafdocs]</Format> metadata.</MajorVersion> For document nodes, Title is not displayed. Instead, Volume, Number and Date information are displayed.</Text>
     4012<Text id="0687d">You may notice that the <AutoText text="Titles"/> browser shows the volume numbers in inverse order. To correct this, in the <AutoText key="glidict::GUI.Design"/> Pane, under <AutoText key="glidict::CDM.GUI.Classifiers"/>, configure the <AutoText text="titles" /> <AutoText text="List" /> classifier. Tick <AutoText text="sort_leaf_nodes_using"/> and set the metadata to <Format>ex.Volume</Format>. Rebuilding now will ensure the <i>ex.Volume</i> Number of each newspaper are listed in numeric order. This has the effect of also sorting the <i>ex.Number</i> value for each <i>ex.Volume</i>.</Text>
    40124013</NumberedItem>
    40134014<Heading>
    … …  
    46444645</MajorVersion>
    46454646<MajorVersion number="3">
    4646   <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-oaiserver.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>
    4647   <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>
     4647  <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-oaiserver.xml.in</Path>, from which <Path>web\WEB-INF\classes\OAIConfig-oaiserver.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-oaiserver.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>
     4648  <Text id="oaiserver-22a">You can also specify mappings at collection level, overriding the mappings in <Format>OAIConfig-oaiserver.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-oaiserver.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>
    46484649<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>
    46494650<Format>&lt;element name=&quot;dc:publisher&quot;&gt;<br />
    … …  
    46984699<MajorVersion number="3">
    46994700<NumberedItem>
    4700 <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>
    4701 </NumberedItem>
    4702 <NumberedItem>
    4703 <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>
     4701<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-oaiserver.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>
     4702</NumberedItem>
     4703<NumberedItem>
     4704<Text id="gs-oai-3-4">The modifications to OAIConfig-oaiserver.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>
    47044705</NumberedItem>
    47054706</MajorVersion>
    … …  
    48594860</NumberedItem>
    48604861<NumberedItem><Text id="ucp-11">Visit the <Link url="http://www.djvu.org/resources/djvu_digital_vs_super_hero_pdf.php">'DjVu-Digital vs. "Super Hero" PDF' page</Link>. The page compares a PDF sample document to its equivalent DjVu version and provides download links for both.</Text>
    4861 <Text id="ucp-11a">Download their <Link url="http://www.djvu.org/docs/superhero.djvu?djvuopts&amp;zoom=page">sample DjVu document</Link> into your <i>DjVu Collection</i>'s import folder.</Text>
     4862<Text id="ucp-11a">Download their <Link url="http://www.djvu.org/docs/superhero.djvu?djvuopts&amp;zoom=page">sample DjVu document</Link> into your <i>DjVu Collection</i>'s <b>import</b> folder at <MajorVersion number="2"><Path>Greenstone &rarr; collect &rarr; djvucoll &rarr; import</Path> </MajorVersion><MajorVersion number="3"><Path>Greenstone &rarr; web &rarr; sites &rarr; localsite &rarr; collect &rarr; djvucoll &rarr; import</Path></MajorVersion>.</Text>
    48624863</NumberedItem>
    48634864<NumberedItem><Text id="ucp-12">Back in GLI, in the <b>Collection</b> view of the <AutoText key="glidict::GUI.Gather"/> pane, right click and select <AutoText key="glidict::CollectionPopupMenu.Refresh"/>. You should now see your new document "superhero.djvu" ready to be built.</Text>
    … …  
    48964897</NumberedItem>
    48974898<Heading><Text id="ucp-24">Processing DjVu documents with the UnknownConverterPlugin</Text></Heading>
    4898 <NumberedItem><Text id="ucp-25">Now that you know how to run the <i>djvutxt</i> conversion tool from the commandline, open up the DjVu Collection in GLI. Go into the <AutoText key="glidict::GUI.Design"/> pane's <AutoText key="glidict::CDM.GUI.Plugins"/> section and add a new <AutoText text="UnknownConverterPlugin"/> instance. (There's already one in the Document Plugin pipeline, but it is not set up for processing djvu files.) Click the <AutoText key="glidict::CDM.PlugInManager.Configure" type="button"/> and set up the plugin as follows:</Text>
     4899<NumberedItem><Text id="ucp-25">Now that you know how to run the <i>djvutxt</i> conversion tool from the commandline, open up the DjVu Collection in GLI. Go into the <AutoText key="glidict::GUI.Design"/> pane's <AutoText key="glidict::CDM.GUI.Plugins"/> section and add a new <AutoText text="UnknownConverterPlugin"/> instance. (There's already one in the Document Plugin pipeline, but it is not set up for processing djvu files.) Press <AutoText key="glidict::CDM.PlugInManager.Configure" type="button"/> and set up the plugin as follows:</Text>
    48994900<BulletList>
    49004901<Bullet><Text id="ucp-26">set its <Format>convert_to</Format> field to <Format>text</Format></Text></Bullet>
    … …  
    55545555<Text id="ic-08a">Use the terminal to first run the incremental import stage:</Text>
    55555556<Format>perl -S incremental-import.pl -incremental -manifest manifests/add-new-files.xml <MajorVersion number="3">-site localsite</MajorVersion> incremen</Format>
    5556 <Text id="ic-08d">The build log output will end with the messages "3 documents were considered for processing" and "3 documents were processed and included in the collection." So this means just the 3 newly added documents were imported, just as specified by our manifest file add-new-files.xml.</Text>
     5557<Text id="ic-08d">The build log output will end with the messages</Text>
     5558<Format>* 3 documents were considered for processing<br />
     5559* 3 documents were processed and included in the collection"
     5560</Format>
     5561<Text id="ic-08e">This means just the 3 newly added documents were imported, just as specified by our manifest file add-new-files.xml.</Text>
    55575562<Text id="ic-08b">Once that <Format>incremental-import</Format> command has finished running, start off the incremental buildcol stage of the build process:</Text>
    55585563<Format>perl -S incremental-buildcol.pl -activate <MajorVersion number="3">-site localsite</MajorVersion> incremen</Format>
    … …  
    59025907</NumberedItem>
    59035908<NumberedItem>
    5904 <Text id="hp-05">Restart the server by clicking the <b>Restart Library</b> button in the small Greenstone Server window. (Any time you make changes to an <i>interfaceConfig.xml</i> file, you must restart the server for the changes to take effect.) When the server restarts, look at your home page again. Because <i>home-tutorial.xsl</i> does not yet exist, you should just see unformatted text. </Text>
     5909<Text id="hp-05">Restart the server by clicking the <b>Restart Library</b> button in the small Greenstone Server window. (Any time you make changes to an <i>interfaceConfig.xml</i> file, you must restart the server for the changes to take effect.) When the server restarts, look at your home page again. Because <i>home-tutorial.xsl</i> does not yet exist, you should see:</Text>
     5910<Format>Couldn't find and/or load the stylesheet "pages/home-tutorial.xsl" for a=p, sa=home, in collection.</Format>
    59055911</NumberedItem>
    59065912<NumberedItem>
    … …  
    61576163
    61586164
    6159 <Text id="hp-05">This <i>library servlet</i> defines the default Greenstone3 library (called <b>library</b>). As you can see, the <b>library_name</b> is <i>library</i>, the <b>site_name</b> is <i>localsite</i>, and the <b>interface_name</b> is <i>default</i>. If you look at the next servlet section, you will see that it has a library_name of <i>halftone-library</i>, uses <i>localsite</i> and the interface <i>halftone</i>. If you continue to scroll down, you will see several other library servlets defined. There are also other kinds of servlets, for example, you will see a servlet called <i>oaiserver</i>, which provides the functionality for the OAI server (located at <i>http://localhost:8383/greenstone3/oaiserver</i>).</Text>
     6165<Text id="hp-05">This <i>library servlet</i> defines the default Greenstone3 library (called <b>library</b>). As you can see, the <b>library_name</b> is <i>library</i>, the <b>site_name</b> is <i>localsite</i>, and the <b>interface_name</b> is <i>default</i>. If you look at the next servlet section, you will see that it has a library_name of <i>halftone-library</i>, uses <i>localsite</i> and the interface <i>halftone</i>. If you continue to scroll down, you will see several other library servlets definitions, albeit inactive as they're commented out. There are also other kinds of de-activeated servlets, such as <i>gateway</i>. These are beyond the scope of this tutorial.</Text>
    61606166</NumberedItem>
    61616167<NumberedItem>
    … …  
    65426548        <Tab n="2"/>&lt;xsl:variable name="collectionFolder" select="@name"/&gt;<br />
    65436549        <Tab n="2"/>&lt;xsl:variable name="collectionName" select="displayItemList/displayItem[@name='name']"/&gt;<br />
    6544         <Tab n="2"/>&lt;xsl:variable name="aboutImage" select="displayItemList/displayItem[@name='icon']"/&gt;<br />
     6550        <Tab n="2"/>&lt;xsl:variable name="homeImage" select="displayItemList/displayItem[@name='icon']"/&gt;<br />
     6551        <Tab n="2"/>&lt;xsl:variable name="aboutImage" select="displayItemList/displayItem[@name='smallicon']"/&gt;<br />
    65456552        <Tab n="2"/>&lt;xsl:variable name="collDesc" select="displayItemList/displayItem[@name='description']"/&gt;<br />
    65466553        <Tab n="2"/>&lt;xsl:variable name="numDocs" select="metadataList/metadata[@name='numDocs']"/&gt;<br /><br />
    … …  
    65536560        <Tab n="2"/>&lt;xsl:choose&gt;<br />
    65546561            <Tab n="3"/>&lt;xsl:when test="$collDesc"&gt;<br />
    6555                 <Tab n="4"/>&lt;p class="justify"&gt;&lt;xsl:value-of select="$collDesc"  disable-output-escaping="yes"/&gt;&lt;/p&gt;<br />
     6562                <Tab n="4"/>&lt;p class="justify"&gt;&lt;xsl:apply-templates select="displayItemList/displayItem[@name='description']"/&gt;&lt;/p&gt;<br />
    65566563            <Tab n="3"/>&lt;/xsl:when&gt;<br />
    65576564            <Tab n="3"/>&lt;xsl:otherwise&gt;<br />
    … …  
    66316638    <Tab n="3"/>&lt;/head&gt;<br/>
    66326639    <Tab n="3"/>&lt;body&gt;<br/>
    6633         <Tab n="4"/>&lt;xsl:apply-templates select="/page"/&gt;<br/>
     6640        <Tab n="4"/>&lt;div class="container" id="gs_content"&gt;
     6641            <Tab n="5"/>&lt;xsl:apply-templates select="/page"/&gt;<br/>
     6642        <Tab n="4"/>&lt;/div&gt;
    66346643        <Tab n="4"/>&lt;xsl:call-template name="gs_footer"/&gt;<br/>
    66356644    <Tab n="3"/>&lt;/body&gt;<br/>
    … …  
    66396648<Text id="ni3-03">Every page in our library uses this template. As you can see, it contains the basic structure of our HTML page. Inside the HTML header, the <b>create-html-header</b> template is called (<Format>&lt;xsl:call-template name="create-html-header"/&gt;</Format>). This is the template in <b>header.xsl</b> we edited in the previous tutorial. Inside the body of the HTML, we use two templates: <b>/page</b> and <b>gs_footer</b>. (The <b>/page</b> template is "applied" instead of called. The reason for this is complex and not relevant to this tutorial.)</Text>
    66406649<Text id="ni3-04"> The <b>/page</b> template is where the content of each individual page is. For the home page, it is the content we just added to <b>home.xsl</b>. Since the <b>perrin</b> interface does not have XSL files for any of the other page types, the content of all of the other pages depends on the default interface: on the collection's about page, it's the collection description; on search pages, it is the query boxes and search results; on document pages it is the document content, etc. </Text>
    6641 <Text id="ni3-04">The <b>gs_footer</b> template is where we will put our page's footer.</Text>
     6650<Text id="ni3-05">The <b>gs_footer</b> template is where we will put our page's footer.</Text>
    66426651</NumberedItem>
    66436652<NumberedItem>
    … …  
    66596668</NumberedItem>
    66606669<NumberedItem>
    6661 <Text id="ni3-08">You'll notice that the image slider and the highlighted items are right up against the edge of the page. In <b>main.xsl</b>, replace <Format>&lt;xsl:apply-templates select="/page"/&gt;</Format> with:</Text>
     6670<Text id="ni3-08">You'll notice that the image slider and the highlighted items are right up against the edge of the page. In <b>main.xsl</b>, replace
     6671<Format>
     6672    <Tab n="2"/>&lt;div class="container" id="gs_content"&gt;<br />
     6673        <Tab n="3"/>&lt;xsl:apply-templates select="/page"/&gt;<br />
     6674    <Tab n="2"/>&lt;/div&gt;<br />
     6675</Format>
     6676with:</Text>
    66626677<Format>
    66636678    <Tab n="2"/>&lt;div class="wrapper"&gt;<br/>
    … …  
    70067021</NumberedItem>
    70077022<NumberedItem>
    7008 <Text id="ni3-27">Save and close <b>main.xsl</b> and refresh the web browser to see the top bar. Click the <b>Login</b> button and log in as <b>admin</b> (if you hadn't already changed the password, use the default password of "admin") to see all of the links appear along the top, including links to the <b>Add User</b> page, to the <b>Administration</b> page, and to Logout.</Text>
     7023<Text id="ni3-28">Save and close <b>main.xsl</b> and refresh the web browser to see the top bar. Click the <b>Login</b> button and log in as <b>admin</b> (if you hadn't already changed the password, use the default password of "admin") to see all of the links appear along the top, including links to the <b>Add User</b> page, to the <b>Administration</b> page, and to Logout.</Text>
    70097024</NumberedItem>
    70107025<Heading>
Note: See TracChangeset for help on using the changeset viewer.