5. Setting up Pliny

Pliny is now at version 1.1.0. Although we have found this version of Pliny to be very stable and reliable, unfortunately it will almost certainly still contain bugs. Please report them to me if you find any. Beyond bug reporting, however, I'd be very glad to hear about your reaction to Pliny. There are bound to be improvements to the way Pliny works that you might suggest. Please email me at john.bradley@kcl.ac.uk if you have any ideas.

Pliny runs as a set of plugins inside a computer program called Eclipse: http://www.eclipse.org. There are currently two ways to install Pliny to try it out:

  • Standalone: If you are using either a Windows or Macintosh machine then we have versions that you can install that allows Pliny to run on its own, needing only a suitable version of Java. The installatioin processes differ between the Macintosh and Windows (because the established ways to install applications differs for the two systems), so be sure you are reading the instructions for your machine. Setting up Pliny on Windows is described here, and for the Macintosh here.
  • From within Eclipse If you are currently an Eclipse user and have Eclipse (version 3.2 or more recent) installed on your computer, you can try it out there. Running Pliny in this way has been tested on Macintosh OS X and Windows machines, and should work on Linux machines as well. Note, however, that the optional GEF component is required in your Eclipse installation to run Pliny. See instructions below for installing GEF with Eclipse's update manager. Here is the section for installing Pliny within Eclipse.

Installing Pliny standalone under Windows

These are the instructions for installing Pliny on a windows machine. Please see the instructions below for installing Pliny on the Macintosh.

Installing Java

Under Windows, Pliny requires the Java Runtime Environment (version 1.4.2 or higher). If you already have a suitable version of Java installed on your computer skip this step. To install Java:

  1. Open your web browser,
  2. Enter the following URL into the address field: http://www.java.com
  3. Click on Free Java Download, and
  4. Follow the installation instructions.

This will load the current version of Java which at the time of writing was 1.6.0.

Installing Pliny

Pliny has been packaged using the IzPack installer. To install Pliny first you must fetch the installer bundle, then you must run the installer to set up Pliny for you:

  1. Click here (http://pliny.cch.kcl.ac.uk/pliny-standalone-1.1.0.jar) to fetch the Pliny installer, and store it on your computer.
  2. Locate the installer and double-click on it to start it up. The installer will appear as a wizard, with a sequence of screens to go through. Near the end of the installation is a screen for "Shortcuts". We recommend that you choose the option to create a short-cut on your desktop -- this will make it easy to start Pliny whenever you wish to use it.

    Note that some Vista users have reported problems installing Pliny. If you have problems, the easiest solution is to change the destination where the Pliny files are to be put from C:\Program Files\Pliny to C:\Pliny when asked during the installation.

  3. After the IzPack installer is completed you will find a Pliny icon under Start/All Programs, and (if you requested it) on the desktop. When you start Pliny the first time it will take somewhat longer to start than usual since there will be some first-time setting up that it has to do. Please be patient.
  4. The first time you start Pliny it will start up its Welcome Screen which will in turn point you to its own tutorial materials. You will probably find that Pliny is quite unlike other software you have used before, and we strongly suggest that you work through the tutorials provided to help you get started using it. The Welcome screen will point you to good starting points among them. You can close the Welcome screen to start using Pliny whenever you are ready, and you can subsequently bring the welcome screen back by choosing help/welcome from the menu bar. Alternatively, all the help material (including the starting tutorials mentioned on the welcome screen) are available under help/help contents from the menu bar.

There is an email discussion list for Pliny users. If you would like to join it, please visit https://lists.sourceforge.net/lists/listinfo/pliny-users.

Installing Pliny standalone on the Macintosh

The packaging of Pliny for the Macintosh would benefit from some further work. We hope to provide better packaging for the Macintosh in the future. Please contact me at john.bradley@kcl.ac.uk if you run into problems. It has been tested, albeit so far only to a very limited extent, on PowerPC and Intel Macintosh machines, and only runs under OS X, up to an including the latest "Snow-Leopard" release. Users of 64bit machines using Java 1.6, however, might have problems. Please contact John Bradley (at john.bradley@kcl.ac.uk) if you are having difficulties.

Installing Java

Pliny requires the Java Runtime Environment (on the Macintosh, version 1.5.0 or higher). If you already have a suitable version of Java installed on your computer skip this step. To install Java:

  1. Open your web browser,
  2. Enter the following URL into the address field: http://www.java.com
  3. Click on Free Java Download, and
  4. Follow the installation instructions.

This will load the current version of Java which at the time of writing was 1.6.0.

Installing Pliny

Pliny has been packaged as a Macintosh application:

  1. Click here (http://pliny.cch.kcl.ac.uk/pliny-app-1.1.0.tar.gz) to fetch the Pliny installer, and store it on your computer.
  2. Double click on the archive file to unpack it.
  3. The unpacking process will generate a folder called Pliny which contains the Pliny application. Drag the entire folder into your machine's Applications folder to install it. It is now ready to use. Start it by opening the Pliny folder and double-clicking on the Pliny icon you find there. Beginning with 1.0.1 the Pliny application is dockable. To add it in the dock drag the Pliny icon you find in the Pliny folder (not the folder itself) to the dock. You can then start Pliny by clicking on the icon in the dock.
  4. The first time you start Pliny it will start up its Welcome Screen which will in turn point you to its own tutorial materials. You will probably find that Pliny is quite unlike other software you have used before, and we strongly suggest that you work through the tutorials provided to help you get started using it. The Welcome screen will point you to good starting points among them. You can close the Welcome screen to start using Pliny whenever you are ready, and you can subsequently bring the welcome screen back by choosing help/welcome from the menu bar. Alternatively, all the help material (including the starting tutorials mentioned on the welcome screen) are available under help/help contents from the menu bar.

There is an email discussion list for Pliny users. If you would like to join it, please visit https://lists.sourceforge.net/lists/listinfo/pliny-users.

Installing Pliny within Eclipse

Here is how to install Pliny if you already have Eclipse set up on your computer. This version of Pliny has been developed with Eclipse version 3.3, but also works with Eclipse 3.2, 3.4 and 3.5, and ought to continue to work under Eclipse 3.1. One would also expect that it would continue to work with newer versions of Eclipse as they become available (although not with older ones). Pliny can be added to your Eclipse setup by using Eclipse's update manager. However, before you can do this you need to be sure that the optional component for Eclipse called GEF (Graphical Editing Framework) is first installed in your Eclipse copy, since it is required by Pliny. If it is not already installed, follow the instructions in "Pliny requires GEF" before proceeding to use the update manager to install Pliny.

Pliny requires GEF

Pliny has been tested with versions 3.1, 3.1.1 and 3.1.2, 3.2 and 3.3 of GEF. If you are running version 3.1 or 3.1.1 of Eclipse you probably want version 3.1.1 of GEF.

The most straightforward way to add GEF to Eclipse is to use GEF's update site which is at http://download.eclipse.org/tools/gef/update-site/releases/. Follow the instructions below (for Eclipse version 3.2) if you need unsure how to use an update page to add something to your version of Eclipse:

  • Choose Help/Software Updates/Find and Install from Eclipse's menu.
  • The Install/Update wizard will appear. Choose Search for new features to install.
  • The Install wizard will appear. Click on the New Remote Site... button.
  • The "New Update Site" dialog box will appear. Type in GEF Update as the name, and http://download.eclipse.org/tools/gef/update-site/releases/ as the URL.
  • Click on the OK button and then the Finish button to continue with the update.
  • The Update Site Mirrors dialog box might appear. Choose the mirror site nearest to you from the list.
  • The Updates dialog box will appear. Choose "GEF Update" as the item you want to install and click on the Finish button.

Eclipse will fetch the GEF objects for you and install them. Restart Eclipse to be sure that they are operational for the next step.

Alternatively, if you do not wish to use the update manager, you can fetch the GEF files and install them yourself. A warning, however, I have received reports that this manual method does not seem to always work for Eclipse on the Macintosh. If you are running version 3.2 of Eclipse and wish to try out Pliny with version 3.2 of GEF, then you can get the files you need from here. You can get a version of GEF for Eclipse 3.1 from here.

Once you have a copy of the GEF zip file, unzip it to recreate the set of folders it contains. Shut down Eclipse if you are currently running it. Open the set of folders. Inside the Eclipse folder will be a couple of files, and three folders called features, plugins and readme. Drag the contents of each folder to the corresponding folder name in your Eclipse installation folder.

Using the Update Manager to install Pliny

Having been sure that your Eclipse installation now contains GEF, follow these steps to install Pliny:

  • Start up Eclipse. It must be at least version 3.1, preferrably 3.2 or more recent. It has also been tested on 3.3 and 3.4, although not yet version 3.5
  • From the Help menu choose "Software Updates..." then "Find and Install..."
  • The Install/Update wizard will begin. Choose "search for new features to install", and push the "next" button
  • The 2nd screen of the wizard appears. Click on the "New Remote Site..." button, and fill in the little dialog box that appears with the following values:
    • Name: Pliny
    • URL: http://pliny.cch.kcl.ac.uk/update

    ... then click the OK button. On the main Install/Update wizard screen you should see a new site added, named Pliny. Be sure that the box in front if it is checked, and uncheck other boxes that might also be checked unless you wish to do other updates to your Eclipse environment at the same time. When done click on the "Finish" button.

  • Eclipse will switch to the "Update" wizard and will show you the Pliny name -- showing that it is one item (perhaps the only one) that it could install now. Check the box to show that you want to proceed with the installation and push the Next button.
  • Eclipse will discover that there are three "features" to install, the main material for Pliny, and two supporting features. Tell Eclipse to install them all.
  • Pliny is licensed under the freeware Eclipse Public License: http://www.eclipse.org/legal/epl-v10.html. To indicate that you accept the terms of the license choose the "I accept" item below it, and click the "Next" button.
  • Eclipse asks you where it should put the Pliny software components it is going to download for you. Unless you have very good reasons to do otherwise, you should let it put the Pliny plugins in the regular place where all Eclipse plugins go. Click the "Finish" button.
  • Eclipse will now take a moment to fetch the materials over the internet. Because the objects have not been "digitally signed", Eclipse will warn you of this and ask if you want to proceed. To proceed, simply click on "Install All".
  • Pliny will be installed on your machine. Eclipse should then be restarted, and you should find Pliny icons among those displaying in the toolbar at the top of the Eclipse window.
  • Although it is not essential, we suggest that you use the "Pliny Perspective" when using Pliny. To set it up, choose "Window/Open Perspective/Other" and choose "Pliny" from the list of perspectives.

There is an email discussion list for Pliny users. If you would like to join it, please visit https://lists.sourceforge.net/lists/listinfo/pliny-users.

Finding out how to get started using Pliny

Once you have installed Pliny you will need to find out how to use it. There is some introductory materials in the Pliny help pages that have been integrated with Eclipse. To see them, choose "Help/Help Contents" from Eclipse's main menu. The Eclipse help screen will appear. Among the list of general categories down the left side of the screen will be Pliny ("Pliny" will be the only option in the standalone installation version). Click on the name itself to open it. Inside the help category "Getting Started with Pliny" are two sections -- the first ("Pliny and Eclipse") introduces some basic Eclipse ways of doing things that are also used in Pliny. The second ("Pliny Tutorials") provides some tutorials that will help you begin to use Pliny. Review the first one "Using Pliny with Non-digital Materials" even if you do not intend to use Pliny in this way (with non-digital (say, print) materials).

You will find that the documentation is not completed. I'm working on it!

But its not working for me!?!?

There is an email discussion list for Pliny users. If you would like to join it, please visit https://lists.sourceforge.net/lists/listinfo/pliny-users.

Get in touch with me if you are having problems with Pliny. My email address is john.bradley@kcl.ac.uk.

John Bradley
Center for Computing in the Humanities
King's College London