Software Installation

Software Packages

EarthStones' software is packaged as one of these four self-extracting 
files: 

JDoc.exe: 	the HTML document-rendering software.
JSite.exe: 	the website description and deployment software, 
	  	plus JDoc.
JDocDemo.exe: 	an evaluation copy of JDoc.
JSiteDemo.exe: 	an evaluation copy of JSite.


JDoc and JSite share much of EarthStones' Java class library. The 
software package you received  contains the class files (along with 
source code and html example files) necessary to implement each product's 
features. The documentation supports all four packages. If you have 
downloaded JDoc, you will find that some of the discussion does refer to 
features not included in this package.

Installation

By default (except for zip files), your EarthStones files are installed 
into a 
		[drive]:\Program Files\EarthStones 

subdirectory of your default drive. This name is entirely arbitrary and
you have an opportunity to change it at the beginning of the installation 
process. The files within this directory are in turn organized into four 
subdirectories: 
classes:The java class (byte-code) files. The subdirectory/file structure 
	within this subdirectories to locations appropriate to your 
	system.
docs: 	EarthStones' documentation, in HTML format. Although you may move 
	this entire directory to another location, its directory 
	substructure must be preserved for the hyperlinks to work. (If 
	you do move this directory, the files EarthStones\contents.html 
	and EarthStones\EarthStones Documentation must also be updated to 
	work properly.)
html: 	This subdirectory contains a number of example HTML files 
	described in the product documentation which will help you get 
	EarthStones' software up-and-running. 
source: This Java source code is provided to assist programmers in ]
	utilizing EarthStones' class libraries and can be moved into a 
	directory convienient for your development system.
images: This directory contains some default images (e.g., logos and 
	bullets) which EarthStones' classes expect to find in an images 
	subdirectory under the web site's root directory (the directory 
	set by the Site class' baseDirectory variable).

Access to Documentation

The remainder of this document describes how to set up EarthStones' 
software on both your development system and your web server. All other 
product documentation is available in HTML format in the EarthStones\docs 
subdirectory. Double-clicking on the file EarthStones\contents.html will 
bring up a table of contents for this documentation. The shortcut 
EarthStones\EarthStones Documentation can also be copied to your desktop
or placed in a Start menu folder to provide quick access. 

Adding JDoc/JSite to your Development System

If you will be using only the ready-to-run applets supplied with your 
EarthStones software you may skip this and the next sections and proceed 
to the instructions for setting up JDoc/JSite on your web server.

To customize and extend EarthStones' class library your Java development 
system must be able to locate its .class files. 

If you are using third-party development tools such as Symantec's 
	VisualCafe or Microsoft's J++, check your product's documentation 
	to determine how you can specify the location of Java class files. 
	For example, in VisualCafe the Projects|Options|Directories tab 
	allows you to specify a Class Path for each development project.

If you are compiling from the command line using Sun's javac.exe, you can 
	use the command-line option 
		-classpath .;[drive]:\EarthStones\classes 
	to direct the compiler to add the path to its class search path.

Finally, you may add a clause to your system's environment CLASSPATH 
	variable to reflect the path to EarthStones' class library (e.g., 
	.;[drive]:\EarthStones\classes). See cautionary note in 
	Troubleshooting section below.

The next section contains additional information related to the second 
and third options.

Configuring your System to Run Java Applications

To run the Java console application JDocViewerApp included with JSite and 
JDoc packages you must have the Java Developers Kit 1.0.2 installed on 
your computer and configured properly. 

If you do not already have Java installed you must first download it 
(free) from Sun's website at http://java.sun.com/products/jdk/1.0.2/ and 
follow the installation directions. It will typically install into a 
directory such as C:\Program Files\Java, which we will assume here for 
illustration purposes.

Next, your system's environment settings must indicate where to look for 
java.exe. To accomplish this, insure that the clause
                   ;C:\Program Files\Java\bin
appears in the system's Path variable. Select Start|Settings|Control Panel 
and double-click the System icon. Select the Environment tab and click on 
the Path item in the listbox. If necessary, you can now edit the path 
variable to append the above code. Click Set. Make sure that you do not 
otherwise change the existing Path settings.

Finally, before closing this dialog, you must also set the environment's 
CLASSPATH variable to point to the locations of EarthStones' class files 
by adding the clause
             ;C:\Program Files\EarthStones\classes
to any code that may already be present. Click Set and Close or Apply.

If you have done all of this correctly, your system will now look for 
java.exe in the directory C:\Program Files\Java\bin and java.exe will 
look for an application class file such as JDocViewerApp.class in the 
directory C:\Program Files\EarthStones\classes\earthstones.

Setting up JDoc/JSite on your Web Server

Class files which are not part of Sun's core Java API are typically not 
available on a web server and must be supplied by the web developer. To 
make EarthStones' class library accessible to your web server, the 
contents of the EarthStones\classes subdirectory (which currently 
contains earthstones and symantec subdirectories) must be copied to the 
server directory referenced by the codebase attribute of the <applet> tag. 
(See Deploying JDoc/Getting Started: Rendering HTML in product 
documentation for discussion of <applet> tag attributes code and 
codebase.) For example, if the <applet> tag includes the attribute 
assignment codebase="java", the contents of the EarthStones\classes 
subdirectory (typically subdirectories named earthstones and symantec) 
must be copied to the server's java subdirectory. Note that all 
subdirectory and file names must be copied exactly (i.e., same case) 
because most web servers use case-sensitive file systems.

Setup Troubleshooting

The following notes may help you fix or avoid some common (and 
not-so-common) problems: 

Because a DOS windows's environment is set at the time the window is 
	opened, if you make any changes to the Path or CLASSPATH 
	variables you must start a new DOS window before these changes 
	will be in effect.

Although the DOS file system (unlike Unix) is not case-sensitive, Java, 
	on the other  hand, is a case-sensitive language. This means that, 
	even if you have set the environment correctly as outlined above, 
	typing the commands java earthstones.jDocDemoApp or 
	earthstones.JDocViewerApp will work just fine. Java leaves it up 
	to the host's file system (case-sensitive or not) to point to the 
	location of its class files (in our example, 
	C:\Program Files\EarthStones\classes). But it then goes about its 
	own case-sensitive business when looking for classes within this 
	directory (e.g., the file earthstones.JDocViewerApp.class).

Multiple clauses within a Path or CLASSPATH specification must be 
	separated by a semicolon but have no intervening spaces. The 
	latter is the case because spaces are allowed in long file names 
	in Win 95/NT (but not in Unix). This means that you must use DOS 
	short (8.3 format) names for any directories or files which 
	contain an embedded space (e.g., Progra~1 for Program Files, 
	DataFi~1 for Data Files). The semicolon at the end of the path 
	specification is optional and will be dropped when the path is 
	set.

Finally, a note of caution about setting the CLASSPATH variable. When the
	environment's CLASSPATH variable is modified, any applet or 
	application using the Java Virtual Machine on this system will 
	use this path to find the .class files specified in  the Java 
	code. This means that if you use a browser on your development 
	system to access and test an installation on your server, you may 
	be inadvertently using .class files located on your local disk 
	instead of those on the server. As a result, it is easy to end up
	with the baffling situation in which updated .class files 
	uploaded to the server are never found by your browser, even if 
	you switch browsers, empty any browser caches, etc.
