README For X Setup 0.2
----------------------

This is a very early alpha version of a setup utility for XFree86.  
To be useful it needs some more configuration files.  I will try to put
some together but I can't really test them, not having every possible
combination of VGA card and monitor.   They are not hard
to make out of an XF86Config file (c.f. end of this README)  If there's
anybody out there interested in putting together some config files for it,
TESTING THEM and e-mailing them to me: chrisw@adl.dmt.csiro.au, it
would be much appreciated.

2. What Limitations Does The Program Have At Present?
-----------------------------------------------------

- It only supports a very small number of VGA cards/configurations.  (This
  is probably not that hard to remedy)

- The user interface could do with some more work.

- It assumes that serial mice are using /dev/mouse as the mouse device.
  (Slackware ordinarily links this to /dev/cuaXX)

- It doesn't allow you to set baud rate, Emulate3Buttons etc. for mice that
  require it.

- It assumes that /usr/lib/X11 is a symlink to /usr/X11R6/lib/X11

- It shows all VGA cards and configurations in a single menu rather than
  allowing you to select the VGA card, *then* the resolution.

I hope to fix most of these before long.   The file format shouldn't change.



3. How it works.
----------------

It combines two files in /usr/lib/X11/xsetup to create /usr/lib/X11/XF86Config,
renaming the old XF86Config file to XF86Config.old first.

The first file is XF86Config.tmpl which contains the FontPaths and Pointer
sections.  

When xsetup is run, it reads /usr/lib/X11/xsetup/video.index for a list
of entries of the form:

filename:description

where 'filename' is the basename of the file in /usr/lib/X11/xsetup.
eg. "et4000.640x480x8" and the description part if what the user sees in
the xsetup menu.

It then does something like:

/lib/cpp -DMOUSE_TYPE=<whatever> /usr/lib/X11/xsetup/XF86Config.tmpl filename-from video.index >/usr/lib/X11/XF86Config


4. Creating New Configurations
------------------------------
If you understand XF86Config and cpp(1) this should be easy.  Essentially,
all you do is:

(a) Copy everything after the "Pointer" section in your XF86Config file into
    a file with a name like "foovga.1024x768ix8" or whatever and move it
    into /usr/lib/X11/xsetup.  Make sure that you edit the screen section
    so that the right resolution is listed first.  (actually - make it the
    *only* mode in the list)


(b) Add an entry containing the above filename and the description to the
    /usr/lib/X11/xsetup/video.index file.


I am using the following conventions for filenames:

<VGA_card_name>.<resolution>[optional 'i' for interlace]x<bit-planes>

eg. for an et4000 in 1024x768 interlaced with 256 colours (8 planes) you'd
use:

et4000.1024x768ix8

For non-interlace, drop the 'i' -> et4000.1024x768x8

The description should include the maker of the card, chipset, resolution
and number of colours and if it does not use the standard VESA timings
you should put "custom" in there to warn the user.

If you have more than one configuration (say with different monitor timings)
add some kind of qualifier to the filename.  eg. "et4000x1024x768x8.a" and
"et4000x1024x768.b".

You can use cpp commands to include various sections of the file, monitor
timings etc. if you want to avoid duplicating it all for each of the
different resolutions.  For example, et4000.cf contains the clocks and
"Graphics Device" section for the ET4000 and is included into all of
the ET4000 config files.

VESA.cf contains some VESA timings which should be used in preference to
VGA-card/monitor-specific timings.

i.e. just:

#include "VESA.cf" into the monitor section of your config file.

---------------------------------------------------------------------------
NOTE - there is one other catch:  The # characters used for comments in
the XF86Config file will break cpp(1) so you need to replace them all
with the string XCOMM, which is defined in XF86Config.tmpl and expands
to a #.
---------------------------------------------------------------------------


5. UPLOADING NEW CONFIGURATIONS
----------------------------
I would greatly appreciate people creating configuration files for their
own brand of card/monitor and uploading them to ftp.adl.dmt.csiro.au in
the /pub/eidelon/incoming area.   I have no easy way of doing this myself
because I don't have every possible combination of VGA card and monitor.
I'm not sure, I seriously expect this to happen, but ultimately it
could make X a bit easier to get going ... ;-)

Alternatively, e-mail me at: chrisw@adl.dmt.csiro.au


6. Modifying The Source.
------------------------
It was thrown together from a distance using "TextViews" which is my
user interface toolkit for ASCII terminals.  Sooner or later I will get
around to documenting TextViews and uploading it, and the source may 
suddenly become useful ...

