From 427466b4a7e0016f0f61c22b74f84d35ad71974d Mon Sep 17 00:00:00 2001 From: "Ira W. Snyder" Date: Wed, 30 Jan 2008 11:29:55 -0800 Subject: [PATCH] Add README This gives us some documentation. It is currently for this testing series only, and will have to be re-written for release. --- README | 158 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 158 insertions(+) create mode 100644 README diff --git a/README b/README new file mode 100644 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: -- 2.34.1