Add debianisation code and automatic build script
[wmaker-crm.git] / debian / README.Debian
1 Window Maker for DEBIAN
2 =======================
3
4 This is Debian GNU/Linux's prepackaged version of Window Maker, yet
5 another window manager, written mostly from scratch by Alfredo Kojima
6 in an attempt to provide as much of the useful OpenStep functionality
7 as possible under X11.  It is the natural step after AfterStep.
8
9 There are some changes in the paths, added support for Debian menu
10 system, improved user configuration (from the sysadmin point of view).
11  
12 To run Window Maker put this at the end of ~/.xsession:
13
14 exec /usr/bin/wmaker
15
16 and remove other exec lines if present.  I have done my best to
17 overcome certain glitches and gotchas regarding Window Maker
18 installation. /usr/bin/wmaker is a shell script that tries to
19 make sure things are properly set up.  Take a look at it to see what's
20 going on.  Please read wmaker(1x).
21
22
23 Other sources for documentation
24 -------------------------------
25
26 * The Window Maker web site
27   http://www.windowmaker.info/
28
29   You can find all sorts of information here. It's kept very up to
30   date.
31
32 * The Window Maker manual written by Alfredo Kojima
33   ftp://ftp.windowmaker.info/pub/wmaker/docs/
34
35   Please note the manual documents version 0.10.x of Window Maker, and
36   many features/changes have occured since then.  To find out what has
37   changed, please read file:/usr/share/doc/wmaker/NEWS.gz and
38   file:/usr/share/doc/wmaker/changelog.gz.  A new version of this manual is
39   being developed.  If you want to contribute to the manual please
40   contact wm-user@windowmaker.info
41
42 * The Window Maker mailing list
43   http://www.windowmaker.info/lists.html
44
45   There's a Window Maker mailing list.  There you can ask questions about
46   Window Maker and *related* applications (s/n is _way_ low nowadays
47   due to unrelated discussions).
48
49   Please read the archives before asking!
50
51 * The Window Maker FAQ
52   http://www.dpo.uab.edu/~grapeape/wmfaq.html
53
54   This is NOT file:/usr/share/doc/wmaker/FAQ.gz, but another document.
55   It contains information about several aspects of Window Maker that are
56   not covered on the FAQ included alongside with this Readme.
57
58 * The Window Maker Configuration documents
59   ftp://ftp.windowmaker.info/pub/wmaker/docs/WindowMaker-*-Config.txt.gz
60
61   This documents the files found on ~/GNUstep/Defaults/. It's kept as
62   up to date as possible.
63
64 As a sidenote, I can't package these files with wmaker because they
65 don't have a copyright statement that permits redistribution.
66
67
68 IF YOU ARE UPGRADING FROM 0.6.3 or earlier
69 ------------------------------------------
70
71   * The directory name has changed form gnustep to GNUstep
72   * The format of the style files and Window Maker file has
73     changed.
74
75 IF YOU ARE UPGRADING FROM 0.14.1 or earlier (but newer than 0.6.3)
76 ------------------------------------------------------------------
77
78   * The Fiend has been renamed to Clip (in order to avoid hurting
79     certain people's feelings... does that ring a bell or
80     what?!?).  Look up "Fiend" in the dictionary... therefore, every
81     keyword on Defaults/WindowMaker that says "Fiend" has to be
82     replaced by "Clip".  The installation package tries to fix this
83     globally, i.e, both in the system wide files and the user's files.
84   * The ~/GNUstep/Library/WindowMaker/Style directory is no longer
85     called that, but "Styles" instead.  Update accordingly.  The wrapper
86     script tries to be smart about this...
87
88 IF YOU ARE UPGRADING FROM 0.15.0 or earlier
89 -------------------------------------------
90
91   * WindowPlaceOrigin syntax changed. The old was:
92       WindowPlaceOrigin = "64, 64"
93     The new one is:
94       WindowPlaceOrigin = (64, 64)
95     The installation package also fixes this.
96
97 IF YOU ARE UPGRADING FROM 0.17.3 or earlier
98 -------------------------------------------
99
100   * Please note there's a new Icons directory under ~/GNUstep/Library,
101     and a new key IconPath. Read the section on paths.
102
103 IF YOU ARE UPGRADING FROM 0.17.5 or earlier
104 -------------------------------------------
105
106   * Pandora's Box has been opened: Beware that some features of recent
107     releases may not be compatible with those of 0.17.5; PLEASE read
108     the NEWS file and the ChangeLog.  If you don't have problems
109     upgrading, consider it a gift from the gods.  PLEASE NOTE: WPrefs
110     is a work in progress.  SAVE YOUR CONFIGURATION. READ THE READMEs.
111   * Please note that WPrefs' Menu Guru REQUIERES a menu in "Property
112     List" format to work properly.  It's very likely that you have an
113     old format menu.  There's a script called wm-oldmenu2new alongside
114     this file that converts your menu to the new format.  It's a hack,
115     it won't be installed anywhere else.
116
117
118 Debian specific notes
119 ---------------------
120
121 Debian prepackaged version of Window Maker will search
122 ~/GNUstep/Library/WindowMaker and etc/X11/WindowMaker (in that order)
123 for its configuration files. It will read defaults from files in
124 ~/GNUstep/Defaults and /etc/GNUstep/Defaults. The files in the
125 WindowMaker directories are preprocessed using cpp. It will read both
126 WindowMaker directories searching for #included files.
127
128 WindowMaker makes a (little) difference between Pixmaps and Icons, and
129 there are two configurable options for setting the paths Window Maker
130 would search Pixmaps and Icons in, namely, PixmapPath and
131 IconPath. The compiled in defaults are:
132
133     PixmapPath = (
134       "~/pixmaps",
135       "~/GNUstep/Library/WindowMaker/Pixmaps",
136       "/usr/local/share/WindowMaker/Pixmaps",
137       "/usr/share/WindowMaker/Pixmaps",
138       "/usr/local/share/pixmaps",
139       "/usr/share/pixmaps",
140       "/usr/X11R6/include/X11/pixmaps"
141     );
142     
143     IconPath = (
144       "~/pixmaps",
145       "~/GNUstep/Library/Icons",
146       "/usr/local/share/WindowMaker/Icons",
147       "/usr/share/WindowMaker/Icons",
148       "/usr/local/share/icons",
149       "/usr/share/icons",
150       "/usr/X11R6/include/X11/pixmaps"
151     );
152
153 Please note that the internal default doesn't include the "Pixmaps"
154 paths anymore, but you are free to modify your Window Maker file in any
155 way you see fit.  Please note that the /usr/X11R6/include/X11/pixmaps
156 is not going to be supported in future releases.
157
158 Other Window Maker packages should put pixmaps in
159 /usr/share/WindowMaker/Pixmaps and icons in
160 /usr/share/WindowMaker/Icons, ONLY.
161
162 The structure Window Maker tries to use is like this:
163
164 GNUstep
165   +.AppInfo
166   +Defaults
167   +Library
168      +WindowMaker
169         + Backgrounds [*]
170         + IconSets [*]
171         + Pixmaps
172         + Sounds
173         + Styles [*]
174         + Themes [*]
175      +Icons
176
177 Please note Icons are not considered Window Maker-only resources.
178
179 [*] these directories are OPEN_MENU'ed WITH the right
180 application. That means you can put the *file* "Great Debian Theme" on
181 Themes, it will show up in the menu, and will be opened using
182 setstyle, which installs it, i.e., sets that theme as the current
183 theme.
184
185 If you don't like the arrangement of the Appearance menu, you can put
186 a file "appearance.menu" in ~/GNUstep/Library/WindowMaker, and it will
187 override the default one. Look at /etc/X11/WindowMaker/appearance.menu
188 for an example.
189
190 Shortcuts
191 ---------
192
193 Thanks to a suggestion, there's support for Shortcuts.  If you want to
194 have Shift F1 launch an XTerm, you can:
195
196 $ cp /usr/lib/menu/xterm /etc/menu
197 $ sensible-editor /etc/menu/xterm
198
199 add:
200
201         shortcut=Shift+F1
202
203 and run update-menus.
204
205 Sound Support
206 -------------
207
208 This version of Window Maker is compiled with sound support. The sound
209 server is available as a separate package, but may not be in sync with
210 the current release.
211
212 Changing the menus (or "WPrefs segfaults when I click the cute menu icon")
213 --------------------------------------------------------------------------
214
215 First of all, I have this urge to say that it doesn't segfault for
216 me.  It gives me a nice warning about being unable to use my current
217 menu.
218
219 The problem is that wmaker now is capable of using a new type of menu,
220 namely a PropList menu.  It looks something like this:
221
222 (
223   Applications,
224   (Debian, OPEN_MENU, menu.hook),
225   (
226     WorkSpace,
227     (Appearance, OPEN_MENU, appearance.menu),
228     (Workspaces, WORKSPACE_MENU),
229     ("Arrange Icons", ARRANGE_ICONS),
230     ("Hide Others", HIDE_OTHERS),
231     ("Show All Windows", SHOW_ALL),
232     ("Clear Session", CLEAR_SESSION),
233     ("Save Session", EXEC, "")
234   ),
235   (About..., INFO_PANEL),
236   (Exit, SHUTDOWN)
237 )
238
239 That cute looking menu button (let's call it by its name: the Menu
240 Guru) in WPrefs expects to find a menu in this format.  I considered
241 changing the menu-method to something that spits out a menu in this
242 format (it's quite easy) but there's a little tiny problem: see that
243 line that reads "OPEN_MENU" in the example above... well, it happens
244 that appearance.menu has to be in the old format.  That means that if
245 I make the menu method produce a new style menu, that menu has to be
246 the root menu.  And that is not a good idea (the reason is left as an
247 exercise to the reader, take into account the people that aren't using
248 menu.hook as the root menu in the first place).
249
250 Still want to use WPrefs to edit you menu? Cut and paste the example
251 above into ~/GNUstep/Defaults/WMRootMenu, start WPrefs, click the Menu
252 Guru (the 9th icon, left to right).  Now go read the docs.  That's the
253 reason they are there.
254
255 Marcelo E. Magallon <mmagallo@debian.org>, Thr, 1 Apr 1999 18:47:30 -0600