Urlopen v0.8						10.Oct.98

    Urlopen is a web access library, similar in concept to libwww from CERN.
    It is intended to be simpler to understand and use than libwww.
    Similarly, urlproxy is simpler to use as a proxy server than CERN httpd.

    Urlcat is a simple program, built using the urlopen library, which
    will cat the contents of a URL to stdout.

    Urlproxy is a simple proxy server, built using the urlopen library,
    which accepts proxied requests from browsers and makes the appropriate
    web requests.  It is particularly useful in combination with the -term
    command line option.  See the README.proxy file in this directory for
    more information.  See the tmosaic script in this directory for a
    sample of how to use it.

    The latest version of urlopen is most likely to be found in
       ftp://ftp.alumni.caltech.edu/pub/mcbeath/web/urlopen/

    Urlopen has the following features:

	- Written in C, easy to compile.

	- Simple interface model: UrlOpen(url) opens a url and returns
	  a url stream; UrlGetFile() turns that into a FILE* for use with
	  standard read calls, or UrlGetLine() gets a line at a time.
	  (See url_read() in urlcat.c to see how it is used.)
	  Or, use the url stream functions UrlUgetc etc., which have the
	  same interface as fgetc etc., but which allow more control at
	  the block-read level (e.g. outputs "N of M bytes" messages).

	- Simple access to meta-information about the file (e.g.
	  content-type) via call to UrlGetMeta().

	- Defined access types:
	  - file
	  - ftp
	  - gopher
	  - http
	  - localfile

	- Support for proxy mode.

	- Support for filename extension typing.

	- Support for type/command dictionary for viewer support,
	  including reading $HOME/.mailcap file.

	- Support for content-type to icon mapping (for FTP and Gopher
	  HTML generation with in-line images).

	- Copyright allows commercial use without fee.

    As compared to libwww, urlopen has the following limitations:

	- Not as many access types are implemented.

	- Probably not as smart about decoding ftp directories.

	- No Access Authorization or selective access control support.

	- More primitive use of HTTP protocol.

    To unpack urlopen:
    1. gunzip urlopen.tgz
       This will produce urlopen.tar.  gzip and gunzip are Gnu compression
       programs, widely available.  Use archie to find a site near you.
       If you don't have archie, you can look in ftp://usc.edu/pub/gzip/
    2. tar xvf urlopen.tar
       This will create the directory "urlopen" containing the kit.
    3. cd urlopen
       This puts you into the directory, where you can compile and test.

    To compile urlopen (and urlcat, urlproxy):
    1. If you want to use TERM, check the TERMDIR and TERMLIB definitions
       in Makefile.  You may have to change TERMDIR, or you can make a
       symlink in the location pointed to by Makefile.
       If you don't have TERM on your system, you can ignore these lines.
    2. Do a "make" in this directory.  This will build the urlopen library
       and the urlcat/urlproxy program.

    To test urlopen:
    1. Enter just the command "urlcat" to see the command line options
       for the urlcat program.
    2. Use urlcat to cat this README file onto a tmp file:
	 urlcat localfile:README > tmp
    3. Diff the two files.  They should be the same.
	 diff README tmp
    4. Pick your favorite URL and give it as an argument to urlcat.  You
       may want to direct the output into a file.  If you use the -verbose
       option, those messages go to stderr, so you can still redirect the
       output into a file:
	 urlcat -verbose \
	    ftp://ftp.alumni.caltech.edu/pub/mcbeath/web/urlopen/README > tmp

    Urlopen has been compiled and run on the following machines:
	DEC Alpha OSF1 v3.2
	Dell Unix 2.2 (SVR4) + gcc 2.5.8 (Intel x86)
	DG AViiON Pentium v4.11
	HP-UX 9.1
	HP-UX 10.1
	Linux (Intel x86)
	RS6000 AIX v4
	SGI IRIX v5.2
	Solaris 2.4 x86
	Sparc Solaris 2.4
	Sparc Solaris 2.5 + gcc 2.7.2
	Sparc SunOS 4.1.3
    If you compile on a platform not in this list, please let me know.

    For information about libwww from CERN see
    - CERN's html converter page
	http://www.w3.org/hypertext/WWW/Library/Status.html

    Advertisement: GLOBEhelp is a commercial web browser for X/Motif from
    Globetrotter Software.  It uses urlopen for web access.  Although it
    does not support forms, tables, or frames, GLOBEhelp is sold on a
    fixed-fee non-royalty basis.  You get source plus the right to compile
    on any platform for a modest fee.
    For more information from Globetrotter:
	http://www.globetrotter.com/
	info@globes.com
	(408)370-2800
	FAX:(408)370-2884

    Author: Jim McBeath (also author of miftran and GLOBEhelp)
    jimmc@globes.com  jimmc@alumni.caltech.edu
    http://www.alumni.caltech.edu/~jimmc/