Embryo Project Article Editing - Tutorial 1

This tutorial describes how to load a text (in docx-format) into Vogon and export it as XHTML (Embryo Project format).

The Short Story

  1. Load relationships into Vogon.
  2. Load PID list into Vogon.
  3. Load Word-file (docx-format, using this template) into Vogon.
  4. Add metadata.
  5. Run relationship finder.
  6. Run PID finder.
  7. Export XHTML file.

The Long Story

Before you start editing an article with Vogon make sure that the article text is final (you can't modify the text in Vogon), is in docx-format (Microsoft Word) and that the text has the right format. "The right format" means that all paragraphs have the correct stylename as it is defined in this template. If you don't use this template make sure that there are only the following five types of styles used:

  • EmbryoTitle - title of article
  • EmbryoText - text of article
  • EmbryoAuthor - author of article
  • EmbryoReferenceHeader - "Sources" header
  • EmbryoReference - references of article
Also make sure that links that you want to be turned into HTML links are defines as such in the document.

Set up Vogon

  1. If you haven't already done so, download Vogon here.
  2. Unzip the file and put the unzipped folder in your "Applications" directory.
  3. Start Vogon by double-clicking on the application symbol.
  4. You will be asked to select a workspace. The workspace is a folder on your computer where all the files Vogon creates and uses are stored. Browse your filesystem and create a new folder somewhere convenient for you. Choose this folder as you workspace and click "OK."

    Next time you start Vogon you can reuse the same workspace or create a new one.
  5. Switch to the "Embryo Project Article Editing" perspective by selection Perspective >> Embryo Project Article Editing from the main menu.
  6. Vogon should now look like this:

    You're now prepared to start editing Embryo Project articles.

Load relationships and PIDs

First thing you have to do before you can load articles in Vogon is loading relationships and PIDs. You have to do that only once for each workspace you're using. Relationships and PIDs should be listed in Excel files with the following format.

  • Relationships:
    • First row contains column headings.
    • Column 1: Type that relationships apply to (e.g. People, Place, etc.). This will be the name of the ontology that will be created for the relationships for this type. The type should be only listed once in the first row.
    • Column 2: Type of the other end of a relationship. (This column is up to now not used and could be left blank.)
    • Column 3: Relationship name (e.g. hasTeacher, used, etc.).
    • Column 4: Relationship definition (e.g. for hasTeacher: student of, taught by, educated by, advised by)

    Example entry:
    Object 1Object 2relationship expressionrelationship definitions
    PEOPLEPeoplehasTeacherstudent of, taught by, educated by, advised by
    hasStudenthad students, taught, educated, supervised
    ORGANIZATIONPeoplehasGraduateawarded a degree to, graduated, educated
    fundedfunded, gave grant to, awarded fellowship to

  • PID list:
    • First row contains column headings.
    • Column 1: PID
    • Column 2: Term represented by PID (this term should be unique, meaning that there are no two list entries with the same term but a different PID)
    • Column 3: State (A or I?)
    • Column 4: Creation date
    • Column 5: Link to article (e.g. http://embryo.asu.edu/view/embryo:128165). This is only necessary if link differs from standard link.

    Example entry:
    PIDLabelStateCreatedLink
    123905Gregory Goodwin PincusA10/02/2007 20:28:50http://embryo.asu.edu/view/embryo:123905
    123916In Vitro FertilizationA10/02/2007 20:28:52 

To load relationships do the following:

  1. From the main menu select Editing >> Load Excel Relationship File.
  2. Select Excel relationship file and hit Open.
  3. Loaded relationships will be shown at the right side of your Vogon window, in a "view" called "Loaded Relations."

To load a PID list do the following:

  1. From the main menu select Editing >> Load PID Excel list.
  2. Select Excel PID file and hit Open.
  3. A progress bar will be shown while PIDs are loaded. Once laoding is done the following view will appear at the bottom of your Vogon window.

    You can sort the list by label or PID by clicking on the corresponding column header.

Load Articles and Find Relationships

To edit an Embryo Project article do the following:

  1. Choose Editing >> Load Article from the main menu.
  2. Select article to load and hit Open. After the article is loaded it is opened in an editor.

    Terms that were highlighted in the Word-file should be hightlighed in Vogon, too.
  3. Now, that the article is loaded, first thing you have to do is telling Vogon to find relationships that are specified in the text. To specify a relationship, the term that has the relationship must be highlighted in the Word-file and the relationships have to be added after the term in the format [relationship1, relationship2]:
    In the 1940s, John von Neumann [usedBy] formalized the idea of cellular automata.
    Tell Vogon to find relationships by clicking the button that looks like price tag with an arrow.
  4. A dialog will be shown that asks you to select the ontologies you want to include. Usually, you want to include all the ones that are loaded (all the ones you had in your relationships Excel-file), what means that Vogon is looking for all relationships that are specified in the ontologies. So, simply click Finish.
  5. When Vogon is done, you should see that the editor the article is shown in has unsaved changes. This means that Vogon added the relationships that it found to your article file (the internal file not the Word-file). An editor with unsaved changes has a little star next to its title:
  6. Click on one of the highlighted words with a relationship. On the bottom of your window, in a view called "Link Information" on the left side, the relationships that Vogon found for this term are shown.
  7. You can add and delete relationships by using the two buttons below the list of relationships.
  8. Save the article/editor by selecting File >> Save from the main menu. The star next to the editor title should disappear.

Find PIDs

Vogon also tries to help you with finding PIDs for highlighted terms.

  1. In the article editor, click on the button that looks like four little heads.
  2. When Vogon is done searching PIDs it will open a view called "PID Finder Results." This view will show a list of all highlighted terms and the finder results for the terms. A green check mark followed by a PID means Vogon found an entry in the PID list that exactly matches the highlighted term. A red cross means Vogon couldn't find a match.
  3. To copy all found PIDs to your article file, click the "thumbs up"-button in the top right corner.
  4. The article editor should again have unsaved changes now.
  5. Click on the "Link Information"-tab to show the "Link Information"-view.
  6. Some of the hightlighted terms should now have a PID shown in the PID field in the "Link Information"-view.
  7. Save your editor.

Edit PIDs and URLs

Since Vogon will probably not find all highlighted terms and you may want to add external URLs to some of the highlighted terms, you can edit the links for the highlighted terms directly.

  1. Click on the highlighted term you want to edit the link for.
  2. Make sure the "Link Information"-view is shown. If it is not shown and you can only see its tab, click on the tab. If you closed the view earlier by clicking on the red cross next to "Link Information", you can reopen it by selecting Window >> Show View >> Link Information.
  3. The "Link Information"-view tells you which term is currently selected in the upper left corner. Make sure that the term that you want to edit is select.
  4. The "Link Information"-view has two fields on the right side: a field for a PID and a field for an URL. In the PID field enter the PID you want to link or enter an URL you want to link into the URL field. If both fields are filled, the PID is linked. To view the website for the entered PID click on the button labeled "Show Embryo article with this PID." To view the website with the URL entered in the URL field click on the button labeled "Show URL in browser."
  5. Save your editor.

Create XHTML-file

Once you're done editing all links for the highlighted terms of you're article, you can generate the XHTML-file for you're article.

  1. First, you have to configure the generation process. Select Editing >> Embryo Export Configuration… from the main menu.
  2. A dialog will open that looks like that:
  3. Up to now, there is one configuration option: "Add <br>-tag before every link in the sources section". If you select the checkbox in front of this option, a line break will be added before every link that appears in the sources section of an article.
  4. Click Finish.
  5. Click on the second button in the left upper corner of the editor.
  6. A dialog opens that asks you select an export type. Select "Embryo project XHTML article file."
  7. Click Next….
  8. Vogon will now ask you where to save the XHTML-file that will be generated. It suggests the filename that the original Word-file has. If you don't change that suggestion or just edit the filename, the generated file will be stored in your workspace (the folder you created in the beginning of this tutorial) in a folder called embryo_export. If you want the generated file to be stored somewhere else, click Save as… and select another folder in your file system (and you may change the suggested filename).

    Warning: If there is already a file with the same filename in the folder the generated file will be saved to, this file be overwritten!
  9. Click Finish.
  10. If you now navigate to the folder you've selected in step 8 (or if you just specified a filename to folder your workspace/embryo_export), you will find a XHTML-file of your article with the name you've specified.
Congratulations, you've just created your first Embryo article XHTML file!