				CANDLEWEB V1.1

	See the Copyright.txt for details on copyright and
	licensing. This is the README file for the CandleWeb
	client. The CandleWeb client is an interpreter to the (awe)
	language which were designed to bring interactive and dynamic
	graphical presentations to the Web.  The client is available for
	both X11 and Win95. It has been compiled and tested on Irix 5.3,
	SunOS 4.1, and Linux.

	If you have any problems with downloading, installing or
	running CandleWeb or you find any holes in the documentation,
	please contact us at candleweb@candleweb.no so we can fix it.

Acknowledgments
	The CandleWeb client would not have been the same without software
	made available from several third parties.
	
	The CandleWeb client uses the World Wide Web Library of Common
	Code available from CERN. They ask us to restate the following
	statement :

	"This product includes computer software created and made
	available by CERN. This acknowledgement shall be mentioned in
	full in any product which includes the CERN computer software
	included herein or parts thereof."

	Specifically the the W3 Reference Library is required in
	order to use the CandleWeb client over the Web. We use version
	4.1 of the library, if you want to compile CandleWeb yourself
	you can fetch a patched version of the library from :
	ftp://thor.candleweb.no/pub/dist/


	We also use a library from the Independent JPEG Group (IJG) to
	decode JPEG images, currently v6 if the jpeg library. They ask us
	to include the following statement :
	"This software is based in part on the work of
	the Independent JPEG Group."


	We have also integrated some code from the pbmplus package in
	our source.

Using the CandleWeb client

	Once you have unpacked the archive file, you can start
	CandleWeb by typing candleweb [file], where file is an
	.awe file on your local system.  Now you can browse around on
	the Web by using Open URL from the File-menu. Note that Open URL
	will not pop up a dialog, merely change focus to the text-field
	showing the current URL (right below the menu bar). By editing
	this and then pushing return you can jump to the URLs you want.
	Choosing Reload from the File-menu will download the URL again,
	reflecting possible changes since last downloaded, and then start
	running it.  Back will take you back to the previous awe-file you
	visited.  View source will show the (awe) source-file of the
	current awe-program running. Print will send the client window
	to the printer specified by the PRINTER environment variable
	or the default printer.  Choosing Quit from the File menu
	terminates the CandleWeb client.

	Some starting points:
	http://www.candleweb.no/demos/stars.awe
	http://www.candleweb.no/demos/smg.awe

	As mentioned, these can be accessed with Open URL from the
	File menu.

	There are several command line options, and corresponding resources, 
        to control what access the (program) has to the local file system. 
	All access is, for security reasons, by default turned off. You 
	shouldn't turn access on if you don't trust the  program you are 
	loading. The options and resources are :
	"-ala", "*allowLocalAccess"   - Allow reading from the local 
					filesystem through the 'getc' 
					function. 
					
	"-alw", "*allowLocalWrite"    - Allow writing to the local 
					filesystem though the 'putc' 
					function.  
	
	"-perfect", "*perfectCols"    - Use a private colormap, and dithering 
					technique top achieve 2048 virtual 
					colors on 8-bit PseudoColor.  

	If you want to turn on both reading and writing you could invoke 
	the client like this :
	candleweb -ala 1 -alw 1

	To find out more about reading and writing read the documentation for 
	putc, getc and open.
 
The language (awe)

	The programs the CandleWeb client run are written in the
	language  which is an extension of a subset of the C
	programming language. It is a subset in the sence that not all
	features of ANSI C are allowed, although most of the
	functionality is there. The extension allows declaration of
	objects for input from and output to the terminal via the
	CandleWeb client-window.  The awe-file is first downloaded
	using the WWW-library. The resulting file is then interpreted
	on your local machine. References to other files (such as GIF-
	or JPEG-files) in the -program will be downloaded as they are
	encountered.   was designed to be easy to learn for
	programmers. Those interested in learning it should consult
	the -specification. Various documentation will continuously
	be put on http://www.candleweb.no/doc/doc.html (which is
	the Documentation-link from the homepage).

Invoking CandleWeb from your favorite browser.

	Mosaic, Netscape, w3 and other browsers read the same
	configuration files to map unknown datatypes to external
	clients. The first configuration file is the mime-types
	file. Make sure ~/.mime-types contains the line :
	application/x-candleweb awe

	The second file is the mailcap file. Make sure ~/.mailcap
	contains the line : application/x-candleweb; candleweb %s

	(If either of them does not exist, you must create it).
	There are also system wide mime-types and mailcap files, put the
	lines there if you're your own sysadmin :-)

	NB. Note that if you want to run (Awe) programs of your HTTP server, 
	you have make sure that the server returns the right MIME type
	(application/x-candleweb) for (Awe) files.

	You can also read about installation on the CandleWeb homepage:
	http://www.candleweb.no/

	After this installation you can start awe-files directly from
	your favourite browser. CandleWeb will start automatically and
	run the selected awe-file. A collection of demos can be tried
	out by opening the URL
	http://www.candleweb.no/demos/demos.html with your browser
	and following the links (or just follow the links from the
	homepage).


The CandleWeb mailing list.

	We have setup a mailing list dedicated to CandleWeb at
	candleweb-talk@candleweb.no.  You can subscribe to it by sending a 
	message	with 'subscribe candleweb-talk' in the body to 
	Majordomo@candleweb.no. More information about available commands 
	can be retrieved by sending a message with 'help' in the body to 
	Majordomo@candleweb.no.


Compiling the source.

	This section will try to describe how to successfully compile the
	source to the CandleWeb client. The source currently requires X11
	and Motif to compile. We have successfully compiled the source for
	Linux, Irix, SunOS and Ultrix. It shouldn't be hard to port the
	source to other X based platforms. Patches to support other
	architectures are welcome. If you don't have the source
	distribution, fetch it from :
		http://www.candleweb/dist/candleweb.tar.gz
	This should always be the most recent release of the source.


	The World Wide Web interface requires the use of the WWW library from
	W3 Consortium. We currently use version 4.1b1 of the library. We have 
	applied some patches to the library in order to get it to work 
	properly with CandleWeb. You can get the patched version from :

		http://www.candleweb.no/dist/w3c-libwww-current.tar.gz

	The original version is available from :
		ftp://ftp.w3.org/pub/libwww/w3c-libwww-4.1b1.tar.gz


	* Please note that CandleWeb will not work properly with the version 
	at ftp.w3.org. 


	To decode JPEG images we use a library from the Independent JPEG
	Group (IJG). As of version 1.1 of CandleWeb we distribute a subset of 
	the jpeg library with the CandleWeb source. The full version can
	be retrieved from the following	places :
		ftp://ftp.uu.net/graphics/jpeg/jpegsrc.v6.tar.gz
		http://www.candleweb.no/dist/jpegsrc.v6a.tar.gz

	After installing libwww on your system you have to let 'make'
	know where to find it. This is done by adjusting the variables in
	the 'MakeVars' file to point to the approriate directories.

	The 'MakeVars' file is also the place to go when you want to change
	things like debugging, optimization, profiling and so on.

	When all the above is done, you can type 'make depend' in the shell
	to create approriate dependencies between .c files and .h files.
	This step is important if you want to do any development on the
	source.

	Now you should hopefully be able to type 'make' and wait for the
	compilation process to finish without errors. Error reports are
	welcome, fixes are even more welcomed. The executable file should
	reside in the main/ subdirectory when the compilation has finished.  

---
This file was written by Svein Arne Johansen (svein@candleweb.no) and
Gunnar Rnning(gunnar@candleweb.no).
