Added KDE3 version of KDE Guidance utilities

git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/applications/kde-guidance@1102646 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 189 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..89ebc0d
--- /dev/null
+++ b/README
@@ -0,0 +1,189 @@
+!!! Warning: Read this through to the end. These tools can be dangerous. !!!
+
+Guidance 0.8.0
+~~~~~~~~~~~~~~
+by Simon Edwards <simon@simonzone.com>, Sebastian Kügler <sebas@vizzzion.org>
+& Yuriy Kozlov <yuriy.kozlov@gmail.com>, Martin Böhm <martin.bohm@kubuntu.org>
+
+
+Introduction
+------------
+Guidance is a collection of system administration tools for Linux/KDE systems
+that is designed to be:
+
+  * Update to date
+  * High quality, designed with user friendliness as high priority. (That is
+    to say that the tools should get the job done quickly, accurately and with
+    as little effort as possible.)
+  * Use KDE and "fit in" with KDE.
+  * Maintainable. 
+  * Free Software
+
+  
+Warning
+-------
+These tools often require root access and modify important system files in
+order to do their job. There is a very real chance that these tools can
+destroy your computer and your data. Backup your data! Also especially
+backup up /etc/passwd, /etc/shadow and /etc/fstab. If you don't know what
+I'm talking about now then you probably shouldn't try using Guidance yet.
+You should have some idea how to fix 
+
+We accept no responsibility in the event that something goes terribly wrong.
+You have been warned.
+
+
+Status
+------
+The tools that make up Guidance are in different stages of development and
+have only been tested on Mandrake.
+
+* userconfig - User & Group configuration. Supports /etc/passwd and
+  /etc/shadow right now.
+  
+* serviceconfig - System services configuration utility. Feature complete.
+  Works on Mandrake, Debian, (K)ubuntu Gentoo and maybe Red Hat out of the box.
+
+* mountconfig - Mount point configuration utility. Feature complete and
+  stable.
+
+* displayconfig - Display and graphics card configuration utility. Feature
+  complete but it only tested on Kubuntu right now.
+
+* wineconfig - Wine configuration utility.
+
+* grubconfig - Grub boot loader configuration utility. beta quality now.
+
+
+Requirements
+------------
+* Linux.
+
+* Python. 2.4 recommended. You probably already have Python installed, and if
+  not then it will most definately be available for you distribution of choice.
+
+* PyQt / PyKDE. Version 3.7 or higher. PyQt and PyKDE are distributed with
+  KDE as part of kde-bindings since version 3.3. 
+  
+  For versions of KDE before 3.3 it is possible to install PyQt/PyKDE
+  directly. The homepage for PyQt and PyKDE is:
+
+    http://www.riverbankcomputing.co.uk/pykde/index.php
+    
+  Packages for most popular distributions are available here:
+  
+    http://sourceforge.net/project/showfiles.php?group_id=61057
+
+* KDE 3.
+
+* "PyKDE Extensions" is needed for installation. It is available here:
+  http://www.simonzone.com/software/pykdeextensions/
+  This is also a runtime requirement!
+
+* libpythonize. If you don't want the tools to appear on the KDE Control
+  Center of you just don't want to bother with libpythonize, then you can
+  build Guidance with this command: 
+
+    python setup.py install build_kcm --no-kcontrol
+
+  libpythonize is only needed for the KDE Control Center. 
+
+* You also need to have the development files from your X-server installed,
+  XFree86 or Xorg. Most distributions package these files up in a package
+  called XFree86-devel, or Xorg-devel, or libxorg-X11-devel or some similar.
+
+* Specifically, the following packages are needed on Kubuntu:
+
+    build-essential
+    python-sip4-dev
+    libxxf86vm-dev
+    libxrender-dev
+    libxrandr-dev
+    libpythonize0-dev
+    pyqt-tools
+    libtool
+    kde-devel
+
+
+Installation
+------------
+As root run:
+
+  ./setup.py install
+
+This will test for a working installation of PyQt/PyKDE and automatically
+install the files using the same installation prefix as KDE. You will need
+to have a working Python install before you can even run the setup.py script.
+
+displayconfig-hwprobe installation
+----------------------------------
+displayconfig-hwprobe.py is a small program that should be run at boottime
+before Xorg is started. It scans the PCI bus looking for graphics cards and
+compares the list it finds to the previous time it was run. If the two lists
+of hardware are different then "dpkg-reconfigure xserver-xorg" is automatically
+run in non-interactive mode to generate a new xorg.conf based on the new
+hardware.
+
+The philosophy is that it is better to have a system with a raw but working
+xorg.conf and X server, than to keep the old configuration and a Xorg that
+won't startup. Swapping a graphics card should not "break" the OS.
+
+The setup.py script currently does not install displayconfig-hwprobe.py by
+itself. For now this must be done by the packager. displayconfig-hwprobe.py
+should be put in /etc/init.d and installed to run at boot time with a command
+like this:
+
+    update-rc.d displayconfig-hwprobe.py start 18 3 .
+
+displayconfig-hwprobe.py only supports Kubuntu right now. Perhaps in the
+future displayconfig-hwprobe will be expanded to detect hardware and generate
+an xorg.conf by itself.
+
+More information about displayconfig-hwprobe.py and the files it uses is
+inside displayconfig-hwprobe.py. Currently the hardware data is written to
+/var/lib/guidance/guidance-gfxhardware-snapshot. IMPORTANT: The directory
+/var/lib/guidance/ should be created before using displayconfig-hwprobe.py.
+
+
+Running
+-------
+Installation should add a couple of entries to the KDE Control Center in the
+System section (displayconfig will show up in Peripherals). It is also possible 
+to run the commands outside of the KDE Control Center from the shell as root:
+
+  * serviceconfig
+  * userconfig
+  * mountconfig
+  * displayconfig
+  * wineconfig
+  * grubconfig
+  
+Reporting Bugs
+--------------
+Bug reports and feedback can be sent to simon@simonzone.com . Do make sure
+that say which version of Guidance you are using and also what Linux
+distribution you are using, and also how you installed SIP, PyQt, PyKDE. Also
+if any error messages are printing to the console, email those too. By
+running these tools from the command line you can often get useful (to me)
+debug information. That kind of information is valuable.
+
+
+Deinstallation
+--------------
+As root run:
+
+  ./setup.py uninstall
+
+  
+Thanks go to
+------------
+Jim Bublitz
+David Boddie
+Sebastian Kügler
+Theo Houtman
+Pete Andrews (gamma correction system)
+
+
+-- 
+Simon Edwards 
+<simon@simonzone.com>