Changeset 28635 for documentation/trunk/tutorials
- Timestamp:
- 2013-11-18T15:45:44+13:00 (10 years ago)
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
documentation/trunk/tutorials/xml-source/tutorial_en.xml
r28630 r28635 1549 1549 <Content> 1550 1550 <Comment> 1551 <Text id="assoc-files-1"><Synopsis>This tutorial demonstrates how to combine different versions of the same document together in Greenstone.</Synopsis> As an example, two identical articles about Greenstone are used, one is in PDF format, the other in Word.</Text> 1552 </Comment> 1551 <Text id="assoc-files-1"><Synopsis>This tutorial demonstrates how to link different versions of the same document together in Greenstone.</Synopsis> As an example, two identical articles about Greenstone are used; one is in PDF format, the other in Word.</Text> 1552 </Comment> 1553 <!-- 1553 1554 <Comment> 1554 1555 <Text id="assoc-files-2">The key to how this collection is set up is that the Word and PDF versions of the document deliberately have the same filename—only the file extension is different. This is something that is quite simple to achieve in practice, as it reflects common practice when a document is published in PDF form. This convention is then exploited by the <Format>associate_ext</Format> plugin option at build-time in Greenstone, an option that allows variants of a document to be grouped together and treated by Greenstone as a single document, based on similarity of filename.</Text> … … 1557 1558 <Text id="assoc-files-3">In the example collection of this tutorial, we set this option in the WordPlugin to be <Format>pdf</Format>. The result of this setting is that it makes the Word version of the document the dominant form in the collection that is built—the text that Greenstone extracts for indexing purposes comes from the Word document—and any PDF version of the document with the same filename is bound to it as an associated file.</Text> 1558 1559 </Comment> 1560 --> 1559 1561 <NumberedItem> 1560 1562 <Text id="assoc-files-4">Start a new collection called <b>Associated Files Example</b>, by selecting File → New. Enter an appropriate description for your collection.</Text> 1561 1563 </NumberedItem> 1562 1564 <NumberedItem> 1563 <Text id="assoc-files-5">Copy the files pdf03.pdf and word03.doc provided in sample_files → Word_and_PDF → Documents into your new collection. Do this by dragging these files across from the filesystem view on the left of the <AutoText key="glidict::GUI.Gather"/> panel into the collection view on the right.</Text> 1564 </NumberedItem> 1565 <NumberedItem> 1566 <Text id="assoc-files-6">In the collection view, right-click on each file you just copied and choose Rename to rename them to greenstone1.pdf and greenstone1.doc, respectively. This sets the input documents up to be in line with the objective of this tutorial: to work with documents of different formats that are named similarly and have identical contents.</Text> 1567 </NumberedItem> 1568 <NumberedItem> 1569 <Text id="assoc-files-7">Go to the <AutoText key="glidict::GUI.Design"/> panel. In <AutoText key="glidict::CDM.GUI.Indexes"/>, delete the index for ex.Source, and in <AutoText key="glidict::CDM.GUI.Classifiers"/>, delete the Browsing Classifier for ex.Source too, since we will not be making use of them.</Text> 1570 </NumberedItem> 1571 <NumberedItem> 1572 <Text id="assoc-files-8">In <AutoText key="glidict::CDM.GUI.Plugins"/>, select the <AutoText text="WordPlugin"/> and press the <AutoText key="glidict::CDM.PlugInManager.Configure" type="button"/> button. 1573 In the resulting popup, scroll down to find the associate_ext option, and set this option to <AutoText text="pdf" type="italics"/>.</Text> 1574 <Text id="assoc-files-9">Note 1: as this is an option that is categorized under the <AutoText text="BasePlugin"/> heading, it is therefore an option that is available across all the plugins provided by Greenstone. In our example, we happen to be binding a PDF document to a Word document, however it could equally be used to bind MP3 versions of files to PNG artwork of album covers.</Text> 1575 <Text id="assoc-files-10">Note 2: More than one filename extension can be provided as part of this option, separated by a comma. For example, setting the value of the associate_ext in <AutoText text="TextPlugin"/> to <AutoText text="avi,png" type="italics"/> would allow both an AVI video file (say an oral history interview) and a PNG image (say a picture of the interviewee taken at the time of the recording) to bind to a text version of the document (say representing a transcript of the interview). Both AVI and PNG versions of the file can be present at the same time, or alternatively only one of the two file types need be present, or neither, and Greenstone will process the situation accordingly.</Text> 1576 <Text id="assoc-files-11">Note 3: The option <Format>associate_ext</Format> is in fact a simplified version of a more general option <Format>associate_tail_re</Format>. Using regular expression syntax, the latter provides a more powerful way of manipulating filenames. Rather than focus on just the filename extension, with <Format>associate_tail_re</Format>, one is able to group files together that share a similar filename root, but might start to differ in characters before the filename extension. For instance, the Word version of the document might be <Format>my-article.doc</Format> but the PDF version might be <Format>my-article-ver13.pdf</Format> reflecting the fact that the PDF file is saved in version 1.3 of this format. Using <Format>associate_tail_re</Format> (and a little bit of regular expression know-how!), such differences can be surmounted, and the two files still processed automatically as different versions of the same document.</Text> 1577 </NumberedItem> 1578 <NumberedItem> 1579 <Text id="assoc-files-12">If you're working with structured Word documents that contain formatted headings and you want better structured and formatted HTML versions of the documents to be generated by Greenstone from the Word format, optionally set the <Format>windows_scripting</Format> option for the <AutoText text="WordPlugin"/> if building on Windows. Alternatively, you can turn on the <Format>open_office_scripting</Format> option if this extension has been added to your Greenstone installation and if either OpenOffice or LibreOffice is available on your system.</Text> 1580 <Text id="assoc-files-13">If you're using windows scripting, optionally set the <AutoText text="level1_heading" type="italics"/> to <i>heading\s*1</i>, or whatever is appropriate for your documents if they use style information for headings that deviate from the norm for Word. Repeat as is needed for <AutoText text="level2_heading" type="italics"/> and so forth. For more details on how to control sections within a Word document, see the <TutorialRef id="enhanced_word"/> tutorial.</Text> 1581 </NumberedItem> 1582 <NumberedItem> 1583 <Text id="assoc-files-14">In GLI, or otherwise, assign appropriate dc.Title and dc.Creator metadata to both your documents. Since the contents are identical, you can select the 2 documents in the <AutoText key="glidict::GUI.Enrich"/> panel, then set dc.Title and dc.Creator simultaneously for both.</Text> 1584 </NumberedItem> 1585 <NumberedItem> 1586 <Text id="assoc-files-15">Building the collection at this point will have the effect that internally Greenstone will have captured this relationship between the different file versions of the same documents; however, until we make some adjustments to the format statements, none of this will be visible to the end-user. The collection built at this point (with default settings) allows a user to search the text from the Word document, browse by title metadata and so on, but when it comes to the point of viewing a document there will only be the choice of viewing the Word version of the document, or the HTML version that Greenstone automatically generates by processing the Word document.</Text> 1587 <Text id="assoc-files-16">To go beyond this, the key change to make is to alter the part of the <MajorVersion number="2">default VList statement that says:</MajorVersion><MajorVersion number="3"><AutoText text="documentNode"/> template of the <AutoText text="Browse" /> format statement which chooses between <Format>thumbicon</Format> and <Format>srcicon</Format>, and replace this with a reference to <Format>equivDocIcon</Format> instead.</MajorVersion></Text> 1565 <Text id="assoc-files-5">Copy the files pdf03.pdf and word03.doc provided in sample_files → Word_and_PDF → Documents into your new collection. Do this by dragging these files across from the filesystem view on the left of the <AutoText key="glidict::GUI.Gather"/> panel into the <b>Collection view</b> on the right.</Text> 1566 </NumberedItem> 1567 <NumberedItem> 1568 <Text id="assoc-files-6">In the collection view, right-click on each file and select <b>Rename</b>, renaming them greenstone1.pdf and greenstone1.doc, respectively.</Text> 1569 </NumberedItem> 1570 <NumberedItem> 1571 <Text id="assoc-files-14">In the <AutoText key="glidict::GUI.Enrich"/> panel, assign appropriate <b>dc.Title</b> and <b>dc.Creator</b> metadata to the documents. Since the contents are identical, you can select both documents and set metadata for them simultaneously.</Text> 1572 </NumberedItem> 1573 <Heading> 1574 <Text id="assoc-files-h1">Associating one document with another</Text> 1575 </Heading> 1576 <NumberedItem> 1577 <Text id="assoc-files-8">In <AutoText key="glidict::CDM.GUI.Plugins"/>, select the <AutoText text="WordPlugin"/> and press the <AutoText key="glidict::CDM.PlugInManager.Configure" type="button"/> button.In the resulting popup, scroll down to find the <Format>associate_ext</Format> option, and set this option to <AutoText text="pdf" type="italics"/>. Now, for Word documents, Greenstone will look for documents with the exact same name but the PDF file extension. These PDF's will not be processed separately; instead, they will be associated with their equivalent Word documents. (Alternatively, you could make the PDF document the primary document, by setting the <Format>associate_ext</Format> option in the <AutoText text="PDFPlugin"/> to <AutoText text="doc" type="italics"/>.)</Text> 1578 </NumberedItem> 1579 <NumberedItem> 1580 <Text id="assoc-files-12">Build the collection. Notice that only one document was considered for processing and included in the collection. Since the PDF version of the document is an associated document, it is not processed.</Text> 1581 </NumberedItem> 1582 <Heading> 1583 <Text id="assoc-files-h2">Linking to associated documents</Text> 1584 </Heading> 1585 <NumberedItem> 1586 <Text id="assoc-files-15">Greenstone has internally associated the PDF version with the Word version of the document. However, with the default format statement, the end-user will have no idea that the PDF version exists. The collection built at this point (with default settings) only gives the user the choice of viewing either the Word version or the Greenstone-generated HTML version of the document. They are not given the option to view the PDF version.</Text> 1587 <Text id="assoc-files-16">To allow users to view the PDF version of the document,<MajorVersion number="2">change the default VList statement from this:</MajorVersion><MajorVersion number="3"> edit the <AutoText text="documentNode"/> template of the <AutoText text="Browse" /> to reference the <Format>equivDocIcon</Format> with a link to the PDF document <Format>equivDocLink</Format>.</MajorVersion></Text> 1588 1588 <MajorVersion number="2"> 1589 1589 <Format> … … 1594 1594 <td valign="top">[ex.equivDocLink][ex.equivDocIcon][ex./equivDocLink]</td> 1595 1595 </Format> 1596 </MajorVersion>1597 1596 <Text id="assoc-files-19">Two things occur in this replacement. The main difference is the switch from using <AutoText text="ex.srclink" type="italics"/> and <AutoText text="ex.srcicon" type="italics"/> that provides the link to the primary source document (which is the Word document), and replace it with a hyperlink around an icon to the document that Greenstone has associated as an equivalent document (which is the PDF version). The icon Greenstone chooses to show is based on the filename extension of the matching file it has found. In this case <img src="../tutorial_files/ipdf.gif"/>.</Text> 1598 <MajorVersion number="2">1599 1597 <Text id="assoc-files-20">The second (more minor) change in this edit is to simplify the statement a bit. The original uses an <Format>{Or}</Format> statement to show a thumbnail version of the document, if Greenstone has one, in preference over the source icon. Since in this collection we have no thumbnails generated, it has been simplified by eliminating the <Format>{Or}</Format> combination and going straight to the <AutoText text="ex.equivDocIcon" type="italics"/> metadata item.</Text> 1600 1598 <Text id="assoc-files-21">To make the change then, switch to the <AutoText key="glidict::GUI.Format"/> panel and edit the format statement for VList (All).</Text> … … 1617 1615 </MajorVersion> 1618 1616 <MajorVersion number="3"> 1619 <Text id="assoc-files-20-3">The second (more minor) change in this edit is to simplify the statement a bit. The original uses a <Format><gsf:choose-metadata/></Format> statement to show a thumbnail version of the document, if Greenstone has one, in preference over the source icon. Since in this collection we have no thumbnails generated, it has been simplified by eliminating the <Format><gsf:choose-metadata/></Format> combination and going straight to the <AutoText text="ex.equivDocIcon" type="italics"/> metadata item.</Text>1620 <Text id="assoc-files-21-3">To make the change then, switch to the <AutoText key="glidict::GUI.Format"/> panel and edit the <AutoText text="documentNode"/> template of the <AutoText text="Browse" /> format statement</Text>1621 1617 <table> 1622 1618 <th> … … 1627 1623 <td valign="bottom"> 1628 1624 <Format> 1629 <td valign="top"><br /> 1630 <Tab n="1"/><gsf:link type="source"><br /> 1631 <Tab n="2"/><gsf:choose-metadata><br /> 1632 <Tab n="3"/><gsf:metadata name="thumbicon"/><br /> 1633 <Tab n="3"/><gsf:metadata name="srcicon"/><br /> 1634 <Tab n="2"/></gsf:choose-metadata><br /> 1635 <Tab n="1"/></gsf:link><br /> 1636 </td><br /> 1637 <td valign="top"><br /> 1638 <Tab n="1"/><gsf:link type="document"><br /> 1639 <Tab n="2"/><xsl:call-template name="choose-title"/><br /> 1640 <Tab n="1"/></gsf:link><br /> 1641 <Tab n="1"/><gsf:switch><br /> 1642 <Tab n="2"/><gsf:metadata name="Source"/><br /> 1643 <Tab n="2"/><gsf:when test="exists"><br /> 1644 <Tab n="3"/><br/><i>(<gsf:metadata name="Source"/>)</i><br /> 1645 <Tab n="2"/></gsf:when><br /> 1646 <Tab n="1"/></gsf:switch><br /> 1647 </td> 1625 <gsf:template match="documentNode"><br /> 1626 <Tab n="1"/><td valign="top"><br /> 1627 <Tab n="2"/><gsf:link type="document"><br /> 1628 <Tab n="3"/><gsf:icon type="document"/><br /> 1629 <Tab n="2"/></gsf:link><br /> 1630 <Tab n="1"/></td><br /> 1631 <Tab n="1"/><td valign="top"><br /> 1632 <Tab n="2"/><gsf:link type="source"><br /> 1633 <Tab n="3"/> <gsf:choose-metadata><br /> 1634 <Tab n="4"/> <gsf:metadata name="thumbicon"/><br /> 1635 <Tab n="4"/> <gsf:metadata name="srcicon"/><br /> 1636 <Tab n="3"/></gsf:choose-metadata><br /> 1637 <Tab n="2"/></gsf:link><br /> 1638 <Tab n="1"/></td><br /><br /><br /><br /><br /><br /> 1639 <Tab n="1"/><td valign="top"><br /> 1640 <Tab n="2"/><gsf:link type="document"><br /> 1641 <!--<br /> 1642 Defined in the global format statement<br /> 1643 --><br /> 1644 <Tab n="3"/> <xsl:call-template name="choose-title"/><br /> 1645 <Tab n="3"/> <gsf:switch><br /> 1646 <Tab n="3"/><gsf:metadata name="Source"/><br /> 1647 <Tab n="4"/><gsf:when test="exists"><br /> 1648 <Tab n="5"/><br/><br /> 1649 <Tab n="5"/><i>(<gsf:metadata name="Source"/>)</i><br /> 1650 <Tab n="4"/></gsf:when><br /> 1651 <Tab n="3"/></gsf:switch><br /> 1652 <Tab n="2"/></gsf:link><br /> 1653 <Tab n="1"/></td><br /> 1654 </gsf:template><br /> 1648 1655 </Format> 1649 1656 </td> 1650 1657 <td valign="bottom"> 1651 1658 <Format> 1652 <td valign="top"><br /> 1653 <highlight><Tab n="1"/><gsf:metadata name="equivDocLink"/><br /> 1654 <Tab n="1"/><gsf:metadata name="equivDocIcon"/><br /> 1655 <Tab n="1"/><gsf:metadata name="/equivDocLink"/><br /> 1656 </highlight> 1657 </td><br /> 1658 <td valign="top"><br /> 1659 <Tab n="1"/><gsf:link type="document"><br /> 1660 <Tab n="2"/><xsl:call-template name="choose-title"/><br /> 1661 <Tab n="1"/></gsf:link><br /> 1662 <Tab n="1"/><gsf:switch> 1663 <highlight><br /> 1664 <Tab n="2"/><gsf:metadata name="dc.Creator"/><br /> 1665 <Tab n="2"/><gsf:when test="exists"><br /> 1666 <Tab n="3"/><br/><gsf:metadata name="dc.Creator" separator=", "/><br /> 1667 <Tab n="2"/></gsf:when> 1668 </highlight><br /> 1669 <Tab n="1"/></gsf:switch><br /> 1670 </td> 1659 <gsf:template match="documentNode"><br /> 1660 <Tab n="1"/><td valign="top"><br /> 1661 <Tab n="2"/><gsf:link type="document"><br /> 1662 <Tab n="3"/><gsf:icon type="document"/><br /> 1663 <Tab n="2"/></gsf:link><br /> 1664 <Tab n="1"/></td><br /> 1665 <Tab n="1"/><td valign="top"><br /> 1666 <Tab n="2"/><gsf:link type="source"><br /> 1667 <Tab n="3"/> <gsf:choose-metadata><br /> 1668 <Tab n="4"/> <gsf:metadata name="thumbicon"/><br /> 1669 <Tab n="4"/> <gsf:metadata name="srcicon"/><br /> 1670 <Tab n="3"/></gsf:choose-metadata><br /> 1671 <Tab n="2"/></gsf:link><br /> 1672 <Tab n="1"/></td><br /> 1673 <highlight><Tab n="1"/><td valign="top"><br /> 1674 <Tab n="2"/><gsf:metadata name="equivDocLink"/><br /> 1675 <Tab n="3"/><gsf:metadata name="equivDocIcon"/><br /> 1676 <Tab n="2"/><gsf:metadata name="/equivDocLink"/><br /> 1677 <Tab n="1"/></td><br /></highlight> 1678 <Tab n="1"/><td valign="top"><br /> 1679 <Tab n="2"/><gsf:link type="document"><br /> 1680 <!--<br /> 1681 Defined in the global format statement<br /> 1682 --><br /> 1683 <Tab n="3"/> <xsl:call-template name="choose-title"/><br /> 1684 <Tab n="3"/> <gsf:switch><br /> 1685 <Tab n="3"/><gsf:metadata name="Source"/><br /> 1686 <Tab n="4"/><gsf:when test="exists"><br /> 1687 <Tab n="5"/><br/><br /> 1688 <Tab n="5"/><i>(<gsf:metadata name="Source"/>)</i><br /> 1689 <Tab n="4"/></gsf:when><br /> 1690 <Tab n="3"/></gsf:switch><br /> 1691 <Tab n="2"/></gsf:link><br /> 1692 <Tab n="1"/></td><br /> 1693 </gsf:template><br /> 1671 1694 </Format> 1672 1695 </td> … … 1675 1698 <br /> 1676 1699 </MajorVersion> 1677 <Text id="assoc-files-24">Note: When Greenstone encounters a file that matches the provided <Format>associate_ext</Format> value (<Format>pdf</Format> in our case), it sets the metadata value <AutoText text="ex.equivDocIcon"/> for that document to be the macro <i>_iconXXX_</i>, where <i>XXX</i> is whatever the filename extension is (so <AutoText text="_iconpdf_" type="italics"/> in our case). As long as there is an existing macro defined for that combination of the word <i>icon</i> and the filename extension, then a suitable icon will be displayed when the document appears in a VList. For <i>pdf</i> the displayed icon will be <img src="../tutorial_files/ipdf.gif"/>. <b>Build</b> the collection if you hadn't already done so and <b>preview</b> it now.</Text>1700 <Text id="assoc-files-24">Note: When Greenstone encounters a file that matches the provided <Format>associate_ext</Format> value (<Format>pdf</Format> in our case), it sets the metadata value <AutoText text="ex.equivDocIcon"/> for that document to be the macro <i>_iconXXX_</i>, where <i>XXX</i> is whatever the filename extension is (so <AutoText text="_iconpdf_" type="italics"/> in our case). As long as there is an existing macro defined for that combination of the word <i>icon</i> and the filename extension, then a suitable icon will be displayed when the document appears in a VList. For <i>pdf</i> the displayed icon will be <img src="../tutorial_files/ipdf.gif"/>.</Text> 1678 1701 </NumberedItem> 1679 1702 </Content>
Note:
See TracChangeset
for help on using the changeset viewer.
