Add README

This gives us some documentation. It is currently for this testing series
only, and will have to be re-written for release.

diff --git a/README b/README
new file mode 100644 (file)
index 0000000..e031321
--- /dev/null
+++ b/README
@@ -0,0 +1,158 @@
+This is an in-development, future version of Tilda. There will be bugs.
+
+
+REQUIREMENTS
+================================================================================
+GTK+ >= 2.8
+VTE (only 0.16.12 tested)
+DBus >= 1.0
+DBus-GLib (only 0.74 tested)
+
+
+BUILDING FROM SOURCE
+================================================================================
+This version of Tilda is not autoconf'd yet, so it will not detect missing
+dependencies above. This is not a priority right now, sorry.
+
+There is a (poorly) hand-written Makefile available with the sources. It works
+for me. Give it a try with: make
+
+
+RUNNING TILDA
+================================================================================
+This version of Tilda has no configuration wizard, which means that you will
+have to configure it by hand. I'm concentrating on Tilda features first, rather
+than the wizard.
+
+The configuration defaults are now stored in share-tilda.conf, rather than being
+hardcoded into the binary. They will be installed in /usr/share/tilda when the
+project is autoconf'd, but that is not yet the case. Please DO NOT modify this
+file. Override the defaults as specified below in CONFIGURING.
+
+Tilda can be run by starting the executable tilda in its checkout directory. If
+you do not start it in the correct directory, it will not be able to load the
+configuration defaults.
+
+
+CONFIGURING
+================================================================================
+Since this version of Tilda does not currently have a wizard, you must configure
+it by hand (or use the defaults).
+
+The configuration file should be named tilda.conf and should reside in the same
+directory as this README file, otherwise it will not be found.
+
+The configuration file is in standard key file format, which is the same used
+for freedesktop.org .desktop files, as well as many others. It resembles the
+Microsoft Windows INI file format. See the following for more details:
+http://library.gnome.org/devel/glib/stable/glib-Key-value-file-parser.html
+
+The current tilda has some per-program settings, some per-window settings, and
+some per-terminal settings. The new configuration format allows you to override
+a setting for just a specific window or terminal, if you please. This is done
+using groups.
+
+So, an example file which sets the default font for ALL terminals to
+"Courier 12", but overrides it to "Courier 18" just for the second terminal
+would be as follows:
+
+[Global]
+font = Courier 12
+
+[Window0/Terminal1]
+font = Courier 18
+
+From this simple example, you can notice that the windows and terminals are
+numbered from 0. And that the font property (which is terminal-specific) can be
+overridden for any terminal you want.
+
+Now for another example. This time we will set the global font to "Courier 12"
+as before, but change all of the fonts for window 1 to "Courier 18". This means
+that ALL terminals that are part of the second window will have a "Courier 18"
+font.
+
+[Global]
+font = Courier 12
+
+[Window1]
+font = Courier 18
+
+From this example, you can see that terminal-specific settings can be part of a
+window setting-group, and they will override all of that window's terminals.
+
+Note, however, that setting a window-specific setting in a terminal
+setting-group will have no effect. So the following:
+
+[Global]
+height = 300
+width = 600
+
+[Window0/Terminal0]
+height = 600
+width = 1200
+
+Will not work. The height and width for all windows will be 300 and 600,
+respectively.
+
+Also note that sections must have unique names. So having two [Window0] sections
+is meaningless. Look at the GKeyFile implementation for what will happen.
+
+
+DEFAULT KEY
+================================================================================
+Until the wizard is in place, there is currently a hack in the source to start
+the keys at F3, and keep moving up. (The algorithm is window number + 3). When
+the wizard is working, it will prompt you, but the wizard is not done yet.
+Sorry.
+
+You will want to override your key. Use the following in your tilda.conf file to
+get the old Tilda default behavior.
+
+[Window0]
+key = F1
+
+[Window1]
+key = F2
+
+[Window2]
+key = F3
+
+Et cetera, for as many windows as you want or need.
+
+
+NEW BEHAVIOR
+================================================================================
+This version of Tilda is completely configurable over DBus. If you have a DBus
+browser, for example qdbusviewer (installed with Trolltech QT4), you can
+customize Tilda's behavior at runtime.
+
+This version of Tilda is designed to be run single-instance, like a daemon. It
+now handles many Tilda windows. You can add them by running the AddWindow()
+method across DBus. This is easy to do with a DBus browser, or via dbus-send,
+which is installed with DBus.
+
+To add a window with dbus-send, the following command will work:
+dbus-send --print-reply --dest=net.sourceforge.Tilda \
+                       /net/sourceforge/Tilda \
+                       net.sourceforge.Tilda.Controller.AddWindow
+
+Likewise, to set the font property on Window0/Terminal0:
+dbus-send --print-reply --dest=net.sourceforge.Tilda \
+                       /net/sourceforge/Tilda/Window0/Terminal0 \
+                       org.freedesktop.DBus.Properties.Set \
+                       string:'' \
+                       string:'font' \
+                       variant:string:'Courier 12'
+
+Tilda will complain if you try to give it the wrong data types, etc. You cannot
+set enums over DBus. I'm working on it. Sorry.
+
+
+BUG REPORTS / FEATURE REQUESTS
+================================================================================
+Please send them to tilda@irasnyder.com, but put [tilda-gobject] in the subject
+line.
+
+Thank you!
+
+# vim: set ft=txt tw=80 noet noai nocindent nosmartindent ts=4 sw=4 sts=4: