 W1R1 - README
 =============

 Ok, here's the README for the next release of W, W1R1, my experimental window
manager for MiNT/MiNTOS/MiNTNet. There's been a big change in how client-
server communication is done: It now uses sockets. That should both explain
and justify the major version number jump. Zero doesn't seem to be an
appropriate number for the minor version, so that's why this is R1, not R0.

 This file has been changed radically. It does no longer explain how to use W
or its clients but only how to make/install them. Sorry, but otherwise I would
have to write things twice, once here and once in the manpages. So if you want
specific info about a program see the manpage. Things that have changed are
also mentioned in CHANGES, so perhaps you should look there first if you are
upgrading from an older version.

 The rest of this README is structured in the following items:

 1) COPYING / WARRANTY
 2) INTRODUCTION / DISCLAIMER
 3) REQUIREMENTS / PROMISES
 4) HOW TO MAKE/INSTALL
 5) HOW TO USE
 6) NETWORKING
 7) BUGS / FEATURES
 8) OTHER NOTES
 9) THANKS

 And now to the first item:


 1) COPYING / WARRANTY
 =====================

 W is/was written by me, Torsten Scherer, itschere@techfak.uni-bielefeld.de
(TeSche) and I've been sitting at it for over a year now, measured from the
first attempts to compile some graphic routines. That is why I'm quite a bit
proud about it, even if you might only find it worth to laugh about... ;)

 The exact copying license for this version (W1R1) is:

- you MUST accept that there is no warranty whatsoever, including, but not
  limited to any details you can possibly imagine or not! everything which
  may accidentially or incidentially happen, either directly caused or
  indirectly triggered by the use of this program is only your problem!
  everything you do you're doing at your own risk!

- you MAY use W free of charge as long as you don't follow any commercial
  targets with it. commercial use requires my written agreement

- you MAY give away copies of it as long as you don't take money for it

- you MAY change the code for your private purpose as you like it. If you
  should give away copies of your modified versions you must clearly mark
  the changes as yours and leave my original copyright notes and comments 
  unchanged. I would also very much like it if you give it a different name

- you SHOULD send me the diffs if you think you've changed something nice or
  important

- you CAN send me programs you've written for W which I will include in the
  next release if I like them


 2) INTRODUCTION / DISCLAIMER
 ============================

 This chapter is here mainly to calm you down from expecting miracles... :)

 W is mainly the result of me trying to do some graphic routines, so it
almost only follows my ideas about graphic and window managers. You may
derive a certain influence by X11 from the style the server or its programs
are named, but that's in fact already the biggest common feature. Everything
else is only an attempt to satisfy *my* needs, and these do not include X11
combatibility. In fact, they don't include *any* compatibility at all.

 There's an experimental port of X11R5 available for MiNT since some weeks.
It definitely has got some problems, but if you're interested in X11 features
you should better keep an eye on that one than expecting these from W.

 Sorry to say this, but my time is somehow limited and I'd like to keep W as
simple and small as possible to fullfill some needs which can only implement
a very rude subset of X11 functionality. At least I'm quite sure it has got
some advantages over GEM/TOSWIN (or MINIWIN).

 What remains is quite some piece of code which was hacked up in hours I
can't remember where I took them from. Whenever you should encounter a bug
it is probably only a (to me) well known feature which only survived because
I decided I could live with it more or less and I didn't find enough hours
somewhere in a box to fix it.

 You may of course send me diffs to enhance the thing, but you'll find it
hard to convince me to turn it into something big like X.

 For the moment I only use the built-in TOS fonts, but since I lack an idea
how to read/convert them online without using VDI I provide them in files.
Since W currently only runs on Ataris these font files will probably not be
useful for anything else, so I don't expect any copyright problems. Any
clues? I'd really love to switch to some nicer fonts, perhaps some X fonts,
but I haven't found the time to convert them yet.


 3) REQUIREMENTS / PROMISES
 ==========================

 Now that I've tried to keep you cool about your expectations it's probably
the time to talk about W's expectations. :)

 W was designed to work in a MiNT/MiNTOS environment and will surely not
cooperate with GEM. If you don't have such an environment running you're lost.
New for this release is that is also requires MiNTNet, but, calm down, only
very few parts of it. :)

 But nobody can deny that its needs are growing... Here they are in detail:

 what it needs:
 --------------

- a ST or a TT, Falcon will only do if you run it in an ST/TT compatile
  screen mode

- probably at least 4 megs of memory (I don't consider it being of any use
  with less and I use it with 8 megs)

- a working MiNT/MiNTOS environment with the most recent MiNT version you can
  get. 1.12 will do, but older ones may cause problems. Note that I didn't
  include any checks because I'm lazy... ;)

- Stephen Ushers MiNTOS package. probably any version will do nicely as W
  doesn't use very much features of it, in fact only /etc/utmp. this is just
  mentioned to stress that this is the environment W was designed for

- Kay Roemers MiNTNet, version 0.60. sorry, the older ones had a `feature'
  concerning AF_UNIX sockets I don't want to write a work-around for

- Kay Roemers portlib.olb. don't know exactly which early version will do, I
  used PL9, but PL11 is already out

- last but not least: a working gcc. you should know which one to use. there
  have been many problems reported with many versions, which is why I still
  use 2.3.3

 what it offers you:
 -------------------

- a monochrome graphic window environment with some tools (wterm to run
  shells or other text programs plus some other nice things, but by far not
  the big variety you might know from X)

- a library with some (as I think) easy to use calls to write your own
  (monochrome) graphic programs if you should like to do so :)

 what it does *not* claim:
 -------------------------

- any kind of warranty

- any compatibility to anything

- a color server (in fact there's a version which runs on TT color screens,
  but even this one only uses one plane to do monochrome graphic)

 That's probably the most important thing you should know about. If you've
actually decided to compile it, here's the next item:


 4) HOW TO MAKE/INSTALL?
 =======================

 Well, that's simple (I think :). You seem to have already extracted the
archive to somewhere. Good. :) The place where you've extraced it must no
longer be the place where you want the binaries to sit later. Instead you
should edit the directories in `Makevars' to meed your taste (and perhaps make
some changes to `server/config.h' if you really know what you're doing).

 But first of all you should remove all traces of previous versions if you're
upgrading because there have been so many changes that old programs won't run,
old libraries and header files won't fit and old docs won't be correct.

 I assume that you've also already installed MiNTNet at this point. The server
needs to have sockdev.xdd installed and the make procedure will need the
includes and library in a place where gcc can find it automatically. You
should follow the installation procedure as described in MiNTNet. If you're
sure everything is fine then type:

 `make'

 Some clients may perhaps not compile on a non-68881 system because they need
float arithmetic and I don't have any kind of PML or so. But I've been reported
that it's fully sufficient to add an `-lpml' to ADDLDFLAGS. this of course
assumes you've got such a library...

 That's part one. Note that you must no longer give any server options in
`Makevars' because the single important one, -DMONOCHROME, is no longer used.
Instead both a `wcolor' and a `wmono' versions are created, plus a start tool
which decides which version to use.

 If the compilation ran through without errors (it really should! :) you should
install the whole stuff to the directories you've chosen in `Makevars' by
typing:

 `make install'

 That's part two. All the stuff will be copied to the directories given in
`Makevars' and the filemodes will be set up correctly. Note that you've got to
be `root' to install the package because `wterm' must be installed as setuid-
`root'. There hopefully isn't very much of a security risk, it just needs to
be able to create links from /dev to /pipe and the /etc/utmp mustn't any
longer be writeable by anybody.

 If you type `make clean' all object files will be erased, but not the
binaries. If you type `make veryclean' binaries will also be erased. There is
no specific make command to uninstall the binaries because I haven't felt the
need for it so far...

 The compiling procedure should have created a device driver xconout2.xdd and
the install procedure should have copied it to /c/mint. This driver enables
*one* wterm to catch output being written to the console by programs which
were started before W, including MiNT and its debugging output. You mustn't
install it, but if you don't do it some programs may trash your screen.

 If you've successfully compiled and installed everything and made sure the
binary directory is in your $PATH you may start it by typing:

 `startw'

 You'll then see what happens next... :)


 5) HOW TO USE
 =============

 If you haven't done anything else but `make install' you'll get some default
programs started. You can customize the startup procedure, but that's explained
in the manpage at greater extend, so you should better have a look at them.

 The library should give you an easy-to-use interface to the server functions
if you want to write your own programs. From W1R1 on there's also a -mbaserel
version again. Sorry, but this is probably not the right point to explain
how to use libraries and such. If you want to know how to use the calls take
a look at the manpages, or the sample programs if you like.


 6) NETWORKING
 =============

 Well, W1 uses sockets for client <> server communication, so you may think
you can run it over a network. This is true as far as you're thinking about
a MiNTNet Network, say, two ST's connected by a serial like. I haven't yet
tested this because I lack a second ST, but it should run. Much slower, of
course...

 The library looks for an environment variable WDISPLAY to get a server to
connect to. This variable must either directly hold an IP adress or the name
of the server if MiNTNet can resolve this to an adress. However, the server
currently binds to 127.0.0.1 only, which is why you will have to recompile
it with a different adress given in main.c. Sorry, this will probably change
in the next release. For now it's probably only run with local connections,
but I'm prepared...


 7) BUGS / FEATURES
 ==================

 Most of the technical appologies are redundant now as the dirty tricks only
dealt with semaphore problems when you can't assure that only one process is
using the code and variables at the time. Socket communication should
eliminate these problems, and hopefully it doesn't introduce too many new
ones. :)

 This versions seems to run stable for me. At least I'm using it for over two
weeks now without greater problems (in fact I'm currenty typing this README in
a wterm :) What remains are the smaller problems:

- due to socket overhead events may get lost if they come too quick and the
  client is busy. I've only seen this in wterm when it's busy scrolling and
  it doesn't offend me very much. A possible hack would be to increase the
  number of events the library can buffer, but completely avoiding this
  problem would involve major changes

- server exit should also be protected by an alert box to force the user to
  confirm it

- no range checks are done for the graphic operations, so the things lives
  from polite clients


 8) OTHER NOTES
 ==============

 The `wterm' terminal emulator uses its own terminal type, which is based on
VT52, but has got some extensions for additional attributes. A sample termcap
entry in provided in the file `termcap.wterm' in the main directory of the
archive. Note that it again contains definitions for lines and columns. They
obviously must be present, even if they're overridden by `struct winsize'
later. For me each curses program now runs without environment variables.

 I think from this release on I can assure that the communication won't change
that much that you must recomile your clients for each new release, but one
can never be sure. If I decide that introducing some new feature would make
a change necessary I probably wont't hesitate to do it, so keep your code!


 9) THANKS
 =========

 to my famous testers:

Benjamin Lorenz (benni@phil15.uni-sb.de, benni@schlunz.dfki.uni-sb.de <- TT!)
for being the first one to really `use' W, spending an enourmous amount of
time tracking down bugs, his `wload' client and always encouraging me,
allthough he now seems to be drifting off into the Linux68k edge... ;)

Kay Roemer (roemer@informatik.uni-frankfurt.de)
for some bugfixes, but mainly for the great speedups he's done to the bitblk
routine and wapfel. Not to mention his MiNTNet without which I would have
left the MiNT scene already I assume.

Torsten Will (itwill@techfak.uni-bielefeld.de)
who hasn't got anything to do with Atari, MiNT or W at all, but who happens to
share a flat with me and has really beared lots of discussions about what
features would be implementable with reasonable effort. and then he's written
a second module for the screen saver...


 ?) QUESTIONS
 ============

 Did I forget something important?


that's it,
enjoy it,
ciao,
and a happy new year,
TeSche, Bielefeld, the 30th December 1994
--
Torsten Scherer (TeSche, Schiller...), itschere@techfak.uni-bielefeld.de
Faculty of Technology, University of Bielefeld, Germany, Europe, Earth...
