Training for creation of formal metadata
	Workshop session three

Exercise 3: Using xtme

This exercise was originally written by Hugh Phillips while he worked for the Wisconsin State Cartographer's Office. I have modified it for this workshop by breaking it down into specific steps and color-coding the HTML. Unfortunately Netscape doesn't want to print the colored text in color.

In this part of the exercise you will explore some of the powerful functions of xtme, not with the intention of creating some metadata you will save, but rather with the idea of putting xtme through its paces. Although this exercise will demonstrate some of the functions and operational characteristics of xtme it is by no means an exhaustive demonstration. You should examine the metadata for xtme, tools/doc/editor.doc for other details.

1. Start up xtme without specifying a document to open:

   $ xtme
   

   A window called "Untitled" should open with a menu bar across the top.

   At the top of the window should be the word Metadata, under it a line going across the window (with a square at its right end), and finally the word Metadata again. If you put the pointer on the little square you can drag it to resize the two parts of the window.

2. Mouse click on Metadata in the upper window, causing the word to be highlighted. Hold down the left mouse button on Add on the menu bar, then drag down the list of choices until (all of the above) is highlighted, then release the mouse button. In the upper window you should now see the seven major sections of metadata listed hierarchically under the word Metadata.

   The upper window will always show the structural skeleton of the metadata, that is the metadata element names which are present. The lower window is the edit window in which you can type or paste values for metadata, unless the element highlighted in the upper window is a container element. If the latter is the case, then the lower window mirrors what is highlighted in the upper window and acts as a reminder that this element does not require a value to be entered. I may refer to the upper window as the "element window", and the lower window as the "value window" in the following material.

3. Before you go any further, you should give your file a name. Position the mouse pointer over the word File on the menu bar, hold down the left mouse button and drag down to Save As. A message box will pop up, prompting you for a file name. Let's use tester for the file name. Also, periodically during this exercise, you should revisit the File menu and select Save.

4. Highlight Identification_Information in the element window and notice that the element name is mirrored in the value window (it is a container element). Go to Add on the menu bar and hold down the left mouse button. Notice that the Add menu has now changed to reflect what can be added as elements under Identification_Information. Select (all of the above) again.

5. These new elements add hierarchically under Identification_Information in the element window. There are probably now more elements than the element window can display so a scroll bar may have appeared on the right side of it. To scroll the element window up or down position the mouse pointer over the dark part of the scroll bar, depress your middle mouse key and drag up or down.

6. Highlight Keywords in the element window, then from the Add menu, select Theme. With Theme highlighted in the element window, go to the Add menu and select Theme_Keyword_Thesaurus. This new element appears in the element window.

7. Notice that now the value window only has a caret in it. This indicates that this is an element which requires a value (it is not a container element). Mouse click in the value window (changes focus to lower window) then type in:

   GCMD Directory
   

8. We now need to add a Theme_Keyword, so we go back to the Add menu, but alas, Theme_Keyword is not available as a pick. In fact, all the menu says is Enter Value Below . Here is the reason:

   In order to add a child element, its parent must be selected in the element window.

   Select Theme in the element window and from the Add menu, select Theme_Keyword. It now appears in the element window, and in the value window, a lonely caret appears. Mouse click in the value window and give the caret some company by typing:

   atmospheric phenomena
   

9. We want to add another Theme_Keyword, and we could do it by repeating the above procedure. There is an easier way, though. Assuming that Theme_Keyword is still highlighted in the upper window, select Duplicate from the Edit menu. Another Theme_Keyword is added into the element window, and a caret appears in the value window. Mouse click in the value window and type:

   snow
   

10. Select Version from the Help menu. A new window should appear which gives hints about using xtme. Grab the title bar of this new window and drag it away from xtme's editing window so it doesn't obscure it. Select Dismiss from the Help window's menu bar to make the Help window go away.

11. Select Element from the Help menu and see that it gives the definition and production rules for the element selected in the element window. Select a different element and notice that the Help window reflects this newly selected element. What is displayed here comes from the help file specified when xtme is started (tools/doc/xtme.hlp in our case). The help file is a plain text file and you can add additional information to it if you so desire (see tools/doc/editor.doc for information on how to do this).

12. Select Output from the Help menu. The Help window now displays all of the metadata elements that you have added, and all of the values that you have entered. The Output window reflects exactly the structure of your current metadata document which is just a plain ASCII document. Very nice.

    Note! Output doesn't update while you are entering values, but it will as soon as you select Update from its menu bar.

13. View is pretty self explanatory. It controls the hierarchical depth of metadata elements which are visible in the element window. In the View menu All levels, 1 level, 2 levels, and 3 levels affect all elements. Hide and Show operate relative to the currently selected element and only affect the children of the currently selected element. All levels makes all elements to the lowest hierarchical depth visible in the element window. 1 level makes only the first hierarchical elements (like Identification_Information and Distribution_Information) visible. If an element has children which are not visible this will be indicated by the presence of a + sign to the left of the element name. Show reveals one more hierarchical depth below the currently selected element (assuming there are actually elements to be made visible). Hide conceals all children elements of the currently selected element.

14. Select All Levels from the View menu, then select the Keywords element in the element window. From the Add menu choose Temporal. Select the Keywords element again, then choose Stratum from the menu. Select the Keywords element again, then choose Place. So now the Keywords fragment of our metadata tree looks like so:

    Keywords
      Theme
        Theme_Keyword
        Theme_Keyword
        Theme_Keyword
      Temporal
      Stratum
      Place
    

    Notice that these elements do not reflect the order in which they are given in the Add menu, the order in which they are listed in the CSDGM. There is nothing in the CSDGM that says anything about the order of sibling metadata elements, so really there is nothing really wrong here. However for consistency and to keep elements of metadata placed in the order people come to expect them when reviewing metadata, it would be helpful to reorder these Keyword elements into the more standard order of Theme, Place, Stratum, Temporal. Swap will do this.

15. Swap exchanges the currently selected element with its nearest sibling element above it. Select the Place element, then Swap from the Edit menu. Repeat the operation twice more, moving the Place element above the Theme element (notice that all of Theme's children were swapped with it). Select Theme, then Swap from the Edit menu to place Theme and Place in the standard order.

16. Cut (from the Edit menu) removes the currently selected element and all its children. What is cut is still an X-selection and is available to be pasted, thus forming an alternate way to swap items without having to swap repeatedly. Cut the Temporal element from the metadata.

17. Paste (from the Edit Menu) attempts to paste the current X-selection (if it is a metadata subtree) appropriately relative to the currently selected element. If a sibling element is selected as a target the subtree is pasted immediately below the selected element. If a sibling isn't selected, but rather a parent element or the child of a sibling, then the element is placed at the bottom of all its siblings. For example:
    1. Select Keywords in the element window, then select Paste from the Edit menu. Temporal is placed underneath Stratum. Cut Temporal again.

    2. Select one of the Theme_Keyword elements, then select Paste from the Edit menu. Temporal is placed underneath Stratum. Cut Temporal again.

    3. Select Place, then select Paste from the Edit menu. Temporal is placed underneath Place (a high speed swap!). Cut Temporal again.

       Paste is good about not letting you paste a subtree where it shouldn't go. For example, select the Spatial_Domain element, then Paste from the Edit menu. Nothing should have appeared under Spatial_Domain, and if you were watching the window you started xtme from, there was probably a message stating "No place to paste this information." Nothing happened because Temporal is not a valid child element of Spatial_Domain. Select the Keywords element again, then Paste from the Edit menu to put Temporal back where it belongs before you lose it.

18. Copy makes a copy of the currently selected element and its subtree children available as an X-selection without removing it from the existing tree (very different from Cut).

    Select the Theme element, then select Copy from the Edit menu. Select the Keywords element, then select Paste from the Edit menu. The Theme element and its children appear below Temporal. Select Output from the Help menu, and see that the values for the children of both instances of Theme are identical.

19. Clear "zeroes out" the values for the elements under the currently selected element without removing the metadata element skeleton.

    Select the second instance of the element Theme , then select Clear from the Edit menu. Select Output from the Help menu and observe that the Theme_Keyword_Thesaurus and Theme_Keyword elements no longer have values (under the second instance of Theme only, the first instance is unchanged).

20. Prune removes all elements below the currently selected element whose children are all devoid of values (that is, there is no entered metadata in them, only the metadata element names are there). Hmmm... Remember back when we worked with cns, we showed that it could clean up an irregular metadata record pretty well, but that our record still contained a number of empty elements which cns also passed on but that mp complained about because they were empty? This is a quick job for xtme.
    1. Close whatever document you were working on, then make a copy of that metadata file that was processed with cns and call it prunetest

       $ cd kygs
       $ cp output prunetest
       

    2. Now open this document up with xtme

       $ xtme prunetest
       

    3. Select 1 level from the View menu and then select Metadata_Reference_Information. Show the details of this element by holding down the Alt key and pressing the 6 on the numeric keypad or by selecting Show from the View menu.

    4. Select (all of the above) from the Add menu to put additional empty elements into this section.

    5. Select Output from the Help menu and scroll down to the end of the document. In the Metadata_Reference_Information section you will see the new empty elements. Select the Metadata element in the element window, then select Prune from the Edit menu. Update the output window. Notice that the empty elements are all gone.

    6. Save prunetest, then quit xtme.

    7. Run prunetest through mp

       $ mp -c kygs.cfg prunetest -e prunetest.err
       

    8. Look at the error file, prunetest.err. Now there is an improvement - down to 30 errors from the former 36!

    9. Go back to the examples subdirectory

       $ cd ..
       

21. Serious mucking about - pasting into xtme from other X-Windows

    Open your tester document with xtme

    $ xtme tester
    

    Under the Description element in Identification_Information, add an Abstract element. From the value window you will see that Abstract is an element that requires a value. We are going to paste it in from another source.
    1. Open an xterm window and launch vi with the hap/abstract document:

       $ vi hap/abstract
       

    2. Highlight any or all or the paragraph of this document, by dragging your mouse or by marking the beginning point (left mouse button) and end point (right mouse button). By this process, this material is made available as an X-selection and can be pasted into another X-Window.

    3. The empty Abstract value window in xtme looks inviting. Mouse click in the Abstract value window, then with the mouse pointer still in that window, depress your middle mouse button. This should paste what you just highlighted into the value window.

22. If what you have highlighted has hierarchical metadata structure, you can also paste it as an element into the element window, that is, you can paste a subtree.
    1. Close the abstract document then open hap/csdgmtab.txt with vi (in an xterm window):

       $ vi hap/csdgmtab.txt
       

    2. Highlight from Time_Period_of_Content to Currentness_Reference under Identification_Information in your vi window.

    3. Mouse click back into the element window of xtme, and select the Citation element with your left mouse button.

    4. Now press your middle mouse button. The section you just highlighted should be pasted in under Citation . Note that the middle mouse button is the only way to accomplish this; Paste from the Edit menu will not work for this operation!

23. Okay, now lets do something similar from another xtme session.
    1. Close your vi window, then start up another xtme session with the hap/csdgmtab.txt document:

       $ xtme hap/csdgmtab.txt
       

    2. Cut the Distribution_Information element from your tester document in your first xtme session.

    3. Highlight Distribution_Information in the csdgmtab.txt document (second xtme session) then select Copy from the Edit menu of that session.

    4. Mouse click back into the first xtme element window and select Entity_and_Attribute_Information .

    5. Press your middle mouse button. The full Distribution_Information with all subtree children should now be appearing in your tester document.

24. You may notice that text doesn't wrap automatically in the value window. Text that goes beyond the right margin turns into a black smudge on the window edge. To get a paragraph to wrap in this window, place the cursor within the paragraph then strike a Control b, that is, the Control key and the 'b' key together. If you think about it as you are typing you can just enter a carriage return before you get to the end of the line.

25. You will shortly grow tired of using the backspace key to perform deletions in the value window. When that happens, you should know that you can select and delete a section of text in the value window by dragging the mouse across it, then pressing the Control-w key combination.

26. When you have finished editing a metadata file with xtme, select Save, then Quit from the File menu.

27. This completes the exercise.