====== Converting Greenstone 2 collections to Greenstone 3 ======

While the indexes and databases of a Greenstone 3 collection are the same as for a Greenstone 2 version, the configuration files are very different.

A Greenstone 2 collection doesn't need to be rebuilt to work in Greenstone 3, but the two configuration files, etc/collect.cfg and index/build.cfg need to be converted to their Greenstone 3 equivalents etc/collectionConfig.xml and index/buildConfig.xml.

The easiest way to achieve this is to copy the Greenstone 2 collection into the Greenstone 3 collect folder, then open it in Greenstone 3's GLI. (The Greenstone 2 collection will need to have both a etc/collect.cfg file and an index/build.cfg file.) GLI will notice that it is a greenstone 2 collection and will create the Greenstone 3 versions of the configuration files.

The tricky part of the conversion process is converting the format statements. For Greenstone versions 3.06 and later a ''Format Conversion'' Wizard is provided to help you with this process. 

The Format Conversion wizard tries to automatically do the conversions itself, then presents you with the tentative Greenstone 3 format statements generated from the Greenstone 2 ones, one format statement at a time, so that you can adjust them within the Wizard itself, or accept the suggestions for now and adjust them in GLI's Format Features later.

Once you have adjusted or accepted the format statements, you can go to the Create panel and preview the collection. It does not need to be rebuilt at this stage. Depending on how the collection looks, you may need to go back to the Format panel and modify the format statements manually.

===== A complex example =====
Sometimes, the Greenstone 3 format statements generated are accurate but can be simplified further. For example, if you were to open the Small Beatles collection from the Greenstone 2 Multimedia tutorial in Greenstone 3.06 GLI, then the Format Conversion wizard will produce the following format statement for the ''documentNode'' template, and something similar for the VList classifier.
<code>
				<td valign="top">
					<gsf:switch>
						<gsf:metadata name="dc.Format"/>
						<gsf:when test="equals" test-value="Lyrics">
							<gsf:link type="document">_iconlyrics_</gsf:link>
						</gsf:when>
					</gsf:switch>
					<gsf:switch>
						<gsf:metadata name="dc.Format"/>
						<gsf:when test="equals" test-value="Discography">
							<gsf:link type="document">_icondisc_</gsf:link>
						</gsf:when>
					</gsf:switch>
					<gsf:switch>
						<gsf:metadata name="dc.Format"/>
						<gsf:when test="equals" test-value="Tablature">
							<gsf:link type="document">_icontab_</gsf:link>
						</gsf:when>
					</gsf:switch>
					<gsf:switch>
						<gsf:metadata name="dc.Format"/>
						<gsf:when test="equals" test-value="MARC">
							<gsf:link type="document">_iconmarc_</gsf:link>
						</gsf:when>
					</gsf:switch>
					<gsf:switch>
						<gsf:metadata name="dc.Format"/>
						<gsf:when test="equals" test-value="Images">
							<gsf:link type="source">
								<gsf:metadata name="thumbicon"/>
							</gsf:link>
						</gsf:when>
					</gsf:switch>
					<gsf:switch>
						<gsf:metadata name="dc.Format"/>
						<gsf:when test="equals" test-value="Supplementary">
							<gsf:link type="source">
								<gsf:metadata name="srcicon"/>
							</gsf:link>
						</gsf:when>
					</gsf:switch>
					<gsf:switch>
						<gsf:metadata name="dc.Format"/>
						<gsf:when test="equals" test-value="Audio">
							<gsf:link type="source">
								<gsf:switch>
									<gsf:metadata name="FileFormat"/>
									<gsf:when test="equals" test-value="MIDI">_iconmidi_</gsf:when>
									<gsf:otherwise>_iconmp3_</gsf:otherwise>
								</gsf:switch>
							</gsf:link>
						</gsf:when>
					</gsf:switch>
				</td>
</code>

Compare this format statement with the equivalent documentNode template in the manually-created collectionConfig.xml for the same collection in the Greenstone 3 Multimedia tutorial:

<code>
<td valign="top">
					<gsf:switch>
						<gsf:metadata name="dc.Format"/>
						<gsf:when test="equals" test-value="Lyrics">
							<gsf:link type="document">
								<gsf:icon file="lyrics.gif" select="collection"/>
							</gsf:link>
						</gsf:when>
						<gsf:when test="equals" test-value="Discography">
							<gsf:link type="document">
								<gsf:icon file="disc.gif" select="collection"/>
							</gsf:link>
						</gsf:when>
						<gsf:when test="equals" test-value="Tablature">
							<gsf:link type="document">
								<gsf:icon file="tab.gif" select="collection"/>
							</gsf:link>
						</gsf:when>
						<gsf:when test="equals" test-value="MARC">
							<gsf:link type="document">
								<gsf:icon file="marc.gif" select="collection"/>
							</gsf:link>
						</gsf:when>
						<gsf:when test="equals" test-value="Images">
							<gsf:link type="source">
								<gsf:metadata name="thumbicon"/>
							</gsf:link>
						</gsf:when>
						<gsf:when test="equals" test-value="Supplementary">
							<gsf:link type="source">
								<gsf:metadata name="srcicon"/>
							</gsf:link>
						</gsf:when>
						<gsf:when test="equals" test-value="Audio">
							<gsf:link type="source">
								<gsf:switch>
									<gsf:metadata name="FileFormat"/>
									<gsf:when test="equals" test-value="MIDI">
										<gsf:icon file="midi.gif" select="collection"/>
									</gsf:when>
									<gsf:otherwise>
										<gsf:metadata name="srcicon"/>
									</gsf:otherwise>
								</gsf:switch>
							</gsf:link>
						</gsf:when>
					</gsf:switch>
				</td>
				<td valign="top">
					<gsf:link type="document">
<!--
Defined in the global format statement
-->
						<xsl:call-template name="choose-title"/>
					</gsf:link>
				</td>
</code>

There are two significant differences between the two.

1. First, the automatically generated format statements refer to macros like ''_icondisc_'', ''_icontab_'', whereas the hand-written format statements make mention of icons using the form ''<gsf:icon file="tab.gif" select="collection"/>''. You could manually type these out in the Format Features section of the Greenstone 3 GLI. 

<!--**NOT YET WORKING:** Alternatively you could open up the Greenstone 3 ''collectionConfig.xml'' and create a ''<replaceList>'' for this collection and specify what each macro should resolve to:

<code>
	<replaceList  id="gs2-multimedia">
		<replace macro="_icondisc_" scope="metadata" text="&lt;gsf:icon file='disc.gif' select='collection'/&gt;" resolve="true"/>
		...
	</replaceList>
</code>

The above would resolve to:
<code><gsf:icon file="tab.gif" select="collection"/></code>
If the same macros were present in multiple collections, you would put the ''<replaceList>'' in ''web/sites/localsite/siteConfig.xml'' instead. Your icon images should then not be stored in the Multimedia collection but in a higher level images folder, and you would specify the path in the ''file'' attribute and set the ''select'' attribute to ''site''.
-->

2. The other thing to notice is that there are many individual ''<gsf:switch/>'' statements in the automatically generated format statement, all testing the value of ''dc.Format'' field and deciding what to do based on that, whereas the manually generated one has simplified this into a single ''<gsf:switch/>''. This simplification is only possible because all the individual switch statements are on the same variable, the ''dc.Format''.

Automatically generated format statement:
<code>
	<gsf:switch>
		<gsf:metadata name="dc.Format"/>
		<gsf:when test="equals" test-value="SOMETHING-1">
			do something 1
		</gsf:when>
	</gsf:switch>

	<gsf:switch>
		<gsf:metadata name="dc.Format"/>
		<gsf:when test="equals" test-value="SOMETHING-2">
			do something 2
		</gsf:when>
	</gsf:switch>

	...
</code>
The hand-written version looks like:
<code>
	<gsf:switch>
		<gsf:metadata name="dc.Format"/>

		<gsf:when test="equals" test-value="Something-1">
			do something 1
		</gsf:when>

		<gsf:when test="equals" test-value="Something-2">
			do something 2
		</gsf:when>

		...
	</gsf:switch>
</code>

===== Using a remote Greenstone server =====

The new Format Conversion Wizard only appears when you're working with GLI, not client-GLI. The client-GLI for GS3 will only perform the most basic initial step in the conversion process, which is to preserve the GS2 format statements in inactive XML tags in the new collection's collectionConfig.xml.

However, if you have a local Greenstone 3 installed, you can still manage to convert a remote collection's collect.cfg file to its GS3 equivalent. 

  - Open the GS2 collection on the remote GS3 server with client-GLI. Doing so for the first time will perform the preliminary conversion step of the GS2 collect.cfg into collectionConfig.xml.
  - Download the remote collection's ''etc/collectionConfig.xml'' file. If you open a remote collection, it is likely to download a zipped up a copy of the collection's etc folder and its contents into your client machine's .gli folder in the user area.
  - Open regular GLI of a GS3 installation on the client machine. Create a new empty collection. Quit GLI.
  - Go to the local GS3 installation's ''web/site/localsite/collection/<new-collection-name>/etc'' folder and place the downloaded ''collectionConfig.xml'' in here.
  - Start regular GLI again. Re-open the newly created collection and now it should present you with the Format Conversion Wizard to lead you through inspecting the automatic conversion of the GS2 format statements to GS3.
  - Once you're finished with the Wizard, go to the Format > Format features tab and copy all the format statements into a temporary text file.
  - Restart client-GLI and connect to the remote GS3 server.
  - Re-open the remote collection whose format statements need updating from GS2 to GS3.
  - Go to the Format Features tab.
  - Back in your temporary text file, copy over the format statement of each format feature into its correct section in the Format Features tab, replacing the text already there.
  - The collection including its updated ''collectionConfig.xml'' file is automatically saved.