The editors of this collection are Human Info NGO, HumanityCD Ltd, and participating organizations. Contact us at Humanitarian and Development Libraries Project, Oosterveldiaan 196, B-2610 Antwerp, Belgium, Tel 32-3-448.05.54, Fax 32-3-449.75.74, email [email protected].
The DLS collection is fairly complex. If you're just starting out you might prefer to look at some other collections first (e.g. Word and PDF demonstration, or the Greenstone Archives, or the Simple Image collection).
The collection configuration file, collectionConfig.xml, like all collection configuration files, begins with the creator metadata element that gives the email address of the collection's creator, and another metadata ("public") that determines whether the collection will appear on the home page of the Greenstone installation. Note that setting "public" to "false" only removes it from the home page; it will still be accessible in the library to anyone that knows the URL to the collection.
Plugins. The "plugin" lines in the collection configuration file give the plugins used by the collection. The documents in the DLS collection are in HTML, so HTMLPlugin must be included. The description_tags option processes tags in the text that define sections and section titles as described below.
The other plugins, GreenstoneXMLPlugin, MetadataXMLPlugin, ArchivesInfPlugin, and DirectoryPlugin, are used by Greenstone for internal purposes and are standard in almost all collections.
Searchable indexes. The block of lines starting with indexes specifies what searchable indexes will be available. In this collection there are three: you can see them when you pull down the "Search for" menu on the collection's search page. The first index is called "chapters", the second "section titles", and the third "entire documents". The names of these three indexes are given by three properties (section_text, section_Title and document_text) in the translatable collectionConfig.properties file located in the collection's resources subfolder.
The contents of the indexes -- that is, the specification of what it is that will be searched -- are defined by the indexes line at the beginning of this block. This specifies three indexes, two at the section level (beginning with section:) and one at the document level (beginning with document:). The difference is that a multi-word query will only match a section-level index if all query terms appear in the same section, whereas it will match a document-level index if the terms appear anywhere within the document (which typically comprises several sections). The first and third indexes are section:text and document:text, and the :text means that the full text of sections and documents respectively will be searched. The second is section:Title, which means that Title metadata will be searched -- in this case, section titles (rather than document titles). The three indexes appear in the order in which they are specified on the indexes line.
Classifiers. The block of lines labeled classify define the browsing indexes, called "classifiers" in Greenstone. There are four of them, corresponding to four buttons on the navigation bar at the top of each page in the collection (e.g. the search page): subjects, titles, organisations, and howto The search button comes first, then come the four classifiers, in order.
The first classifier provides access by subject. It is a Hierarchy classifier whose hierarchy is defined in the file etc/dls.Subject.txt (the hfile argument); this file is discussed below. This classifier is based on dls.Subject metadata, and when several books appear at a leaf of the hierarchy they are sorted by dls.Title metadata (as you can see when you open classifier browser CL1.4.1). The second classifier provides access by title. It is also a Hierarchy classifier, this time based on dls.AZList metadata, whose hierarchy is defined in etc/dls.AZList.txt. This file is discussed below. The third provides access by organization: it is a List classifier based on dls.Organization metadata. The -bookshelf_type always option creates a new bookshelf for each organization, even if only one document belongs to that category. The fourth provides access by "Howto" text: it is a List classifier based on dls.Keyword metadata. The -bookshelf_type never option prevents bookshelves being created even if two documents share the same keywords.
Cover images. Greenstone looks for a cover image for each document, whose name is the same as the document's but with a .jpg extension. This image is associated with the document, and may be displayed on the document page (see below). Cover images can be switched off by setting the -no_cover_image flag for each plugin.
Format statements. The format elements (<format;>, <browse>, <search> and <display> XML elements), called "format statements", govern how various parts of the collection should be displayed. The VList format statement applies to lists of items displayed vertically, such as the lists of titles, subjects and organisations, and the table of contents for the target documents. It is overridden for the search results list by the SearchVList format statement, and also for the Howto classifier by the CL4VList statement (CL4 specifies the fourth classifier).
The DocumentText statement governs how the document text is formatted, with Title metadata ([Title]) in HTML heading format followed by the text of the document [Text]. By default, cover images are shown with each document (DocumentImages), and the DocumentButtons are available: the Expand Text, Expand Contents, Detach and Highlight buttons are shown with each document.
Greenstone 3 uses XML for format statements, allowing librarians with XML experience to more easily understand and use format statements than Greenstone 2 which worked with a custom way of specifying format statements. For more information on understanding format statements and writing your own format statements for collections, refer to Greenstone 3 Format Statements on the Greenstone wiki.
Collection-level metadata. The <displayItem> elements under the top-level <displayItemList> in the configuration file are also standard in all Greenstone collections. They give general information about the collection, defining its name, and a description that appears on its home page. The description text (defined in the translatable resources/collectionConfig.properties files) can be seen on the DLS collection's home page (this text is part of it).
Language translations. In the collection configuration file, lines that look like <displayItem assigned="true" dictionary="collectionConfig" key="..." name="..."/> allow for translatable collection-level metadata, that are defined in the resources/collectionConfig.properties text files and can be translated in the same location such as by creating French and Spanish versions (in resources/collectionConfig_fr.properties and resources/collectionConfig_es.properties, respectively). Note that we advise translators to go through the GTI (Greenstone Translation Interface) system if they want to contribute translations to Greenstone as used by everyone, such as translations to Greenstone's demo collections and these documented example collections. The properties files allow for accented characters (e.g. French é). The files are in UTF-8, and these characters are represented by multi-byte sequences (<C3><A9> in this case). Alternatively they could be represented by their HTML entity names (like & eacute ;). It makes no difference for how they appear on the screen.
Description tags. The description tags recognized by HTMLPlugin are inserted into the HTML source text of the documents to define where sections begin and end, and to specify section titles. They look like this:
<!-- <Section> <Description> <Metadata name="Title"> Realizing human rights for poor people: Strategies for achieving the international development targets </Metadata> </Description> --> (text of section goes here) <!-- </Section> -->The <!-- ... --> markers are used to ensure that these tags are marked as comments in HTML and therefore do not affect document formatting. In the Description part other kinds of metadata can be specified, but this is not done for the style of collection we are describing here. Exactly the same specification (including the <!-- ... --> markers) can be used in Word documents too.
Metadata Files. Metadata for all documents in the DLS collection is provided in metadata.xml files, one per document folder. In this collection's import/r0087e is the metadata.xml file for one book -- Income generation and money management: training women as entrepreneurs -- which is a block of about ten lines encased in <FileSet> ... </FileSet> tags. It defines dls.Title, dls.Language, dls.Subject and dls.AZList metadata. More than one value can be specified for any metadata item. For example, this book has two dls.Subject classifications. Both of these are stored as metadata values for this particular document (because mode=accumulate is specified; the alternative, and the default, is mode=override).
Hierarchy files. Hierarchy files contain a succession of lines each of which has three items. The first item is a text string which is matched against the metadata that occurs in the metadata.xml file described above. The second item is a number that defines the position in the hierarchy. The third item is a text string that describes the node of the hierarchy on the web pages that Greenstone generates.
For example, the following shows three lines from the subject hierarchy file etc/dls.Subject.txt.
"Animal Husbandry and Animal Product Processing " 7 "Animal Husbandry and Animal Product Processing " "Animal Husbandry and Animal Product Processing|Cattle " 7.1 "Cattle " "Animal Husbandry and Animal Product Processing|Other animals (micro-livestock, little known animals, silkworms, reptiles, frogs, snails, game, etc.) " 7.2 "Other animals (micro-livestock, little known animals, silkworms, reptiles, frogs, snails, game, etc.) "
These three lines define one top level bookshelf (at position 7), titled "Animal Husbandry and Animal Product Processing ", with two bookshelves underneath it, titled "Cattle " and "Other animals (micro-livestock, little known animals, silkworms, reptiles, frogs, snails, game, etc.) " respectively.
In this case, the first strings (and therefore the entries in metadata.xml files) contain the entire hierarchy values. Levels in the hierarchy are separated by "|". They could be used directly by a Hierarchy classifier without the use of the hierarchy file. However, then the entries would be ordered alphabetically, not in the special order defined by the file.
The etc/dls.AZList.txt hierarchy file used by the titles classifier contains a similar structure. Ordinarily, a titles browser would use a List (or AZList) classifier. In this case, we want to predefine the A-Z groupings, and include a separate entry for periodicals, as can be seen in classifier browser here.