Provide more documentation to make it easier for people to contribute to

2005-01-02  Elijah Newren  <newren@gmail.com>

	Provide more documentation to make it easier for people to
	contribute to Metacity

	* HACKING: Add lots of information to extend this document: more
	on relevant standards and X properties, lots of information on
	debugging and testing, and add a list of some other important
	things to read; also move some information to
	src/code-overview.txt and organize this file into sections.

	* src/code-overview.txt: New file including some small parts from
	the old HACKING file and lots of new stuff.  This file gives a
	brief overview of some of the bigger structures and files, with
	guides for a variety of task categories providing places to start
	looking in the code and things to look for.

1 files changed, 185 insertions, 0 deletions

diff --git a/doc/code-overview.txt b/doc/code-overview.txt
new file mode 100644
index 00000000..450f7a82
--- /dev/null
+++ b/doc/code-overview.txt
@@ -0,0 +1,185 @@
+This is not meant to be comprehensive by any means.  Rather it is
+meant as just a brief overview of some of the bigger structures and
+files, with guides for a variety of task categories providing places
+to start looking in the code and things to look for.
+
+Overview
+  Jobs of various files
+  Major data structures and their relationships
+  Getting started -- where to look
+
+
+Jobs of various files
+  src/window.c is where all the guts of the window manager live. This is
+  basically the only remotely scary file.
+
+  src/frames.c is the GtkWidget that handles drawing window frames.
+
+  src/core.h defines the interface used by the GTK portion of the window
+  manager to talk to the other portions. There's some cruft in here that's
+  unused, since nearly all window operations have moved out of this file so
+  frameless apps can have window operations.
+
+  src/ui.h defines the interface the plain Xlib portion of the window
+  manager uses to talk to the GTK portion.
+
+  src/theme.c and src/theme-parser.c have the theme system; this is
+  well-modularized from the rest of the code, since the theme viewer app
+  links to these files in addition to the WM itself.
+
+Major data structures and their relationships
+  Major structs have a "Meta" prefix, thus MetaDisplay, MetaScreen,
+  MetaWindow, etc.  This serves as a way of namespacing in C.  It also has
+  the side effect of avoiding conflicts with common names that X already
+  uses such as Display, Screen, Window, etc.  Note that when I refer to a
+  display below, I'm meaning a MetaDisplay and not a Display.
+
+  Don't confuse displays and screens.  While Metacity can run with multiple
+  displays, it is kind of useless since you might as well just run two
+  copies of Metacity.  However, having multiple screens per display is
+  useful and increasingly common (known as "multiscreen" and "xinerama"
+  setups, where users make use of more than one monitor).  You should
+  basically think of a display as a combination of one or more monitors
+  with a single keyboard (...and usually only one mouse).
+
+  There is also a significant difference between multiscreen and xinerama
+  as well.  Basically, each MetaScreen is a root window (root node in the
+  tree of windows).  With Xinerama, a single root window appears to span
+  multiple monitors, whereas with multiscreen a root window is confined to
+  a single monitor.  To re-emphasize the distinction between a display and
+  a screen, the pointer and keyboard are shared between all root windows
+  for a given display.
+
+  The display keeps track of a lot of various global quantities, but in
+  particular has a compositor and a list (GList) of screens.
+
+  A compositor is an opaque structure (only defined in compositor.c),
+  meaning that you'll only reference the API for it.  It handles (or will
+  handle) cool stuff with the new X extensions, such as smooth resizing and
+  alpha transparency.
+
+  A screen keeps track of a number of quantities as well, in particular a
+  stack and a list of workspaces.
+
+  A stack is basically a list of windows, and the depth order they have
+  relative to each other (which thus determines which windows are on top
+  and which are obscured).
+
+  A workspace mostly contains a list of windows for the workspace, but also
+  has a few other quantities as well (a list of struts which are areas
+  where windows should not be placed and an mru_list or "most recently used
+  window list").
+
+  A window has a huge list of quantities for keeping track of things about
+  a window on the screen.  (We want to avoid making this list larger
+  because the memory for all these quantities is per window.)  One item in
+  particular that a window has, though, is a frame.
+
+  A frame is the decorations that surround the window (i.e. the titlebar and
+  the minimize and close buttons and the part that you can use to resize),
+  and contains a handful of variables related to that, but no other major
+  structures.
+
+Getting started -- where to look
+  Getting started on developing free software projects can often be like
+  being dropped off in a town that is unknown to you and being told to make
+  a map, when various road and building signs are missing or fading.  To
+  try to alleviate that initial difficulty in orientation, below I list a
+  variety of general task categories with file, function, variable, and x
+  property names that may be useful to fixing bugs or writing features that
+  fall within that category.
+
+  First, though, it's useful to note that most event and message passing
+  goes through display.c:event_callback(), so that's often a good place to
+  start reading for general familiarity with the code (actually, I'd
+  suggest skipping down to the first switch statement within that
+  function).  Of course, not all events go through that function, as there
+  are a few other places that handle events too such as frames.c.
+
+  Anyway, without further ado, here are the categories and (hopefully)
+  useful things to look at for each:
+
+    Focus issues (i.e. issues with which window is active):
+      doc/how-to-get-focus-right.txt
+      meta_workspace_focus_default_window
+      _NET_ACTIVE_WINDOW
+      _NET_WM_USER_TIME
+      meta_window_focus
+      meta_display_(set_input|focus_the_no)_focus_window
+      XSetInputFocus (only for purposes of understanding how X focus/input works)
+      CurrentTime (mostly, you should just think "Bad; don't use it")
+
+    Compositor stuff (X extension for eye candy like transparency):
+      compositor.c
+      The luminocity module in CVS
+
+    Window depth (i.e. stacking or lowering/raising) issues:
+      stack.c
+      _NET_CLIENT_LIST_STACKING
+      transient_for
+      WM_TRANSIENT_FOR
+      meta_window_(raise|lower)
+      _NET_WM_WINDOW_TYPE
+      _NET_WM_MOUSE_ACTION/_NET_WM_TAKE_ACTIVITY? (aren't yet in EWMH)
+
+    Window placement issues:
+      place.c
+      constraints.c
+      _NET_WM_STRUT
+      WM_SIZE_HINTS
+
+    Moving and resizing issues:
+      constraints.c
+      update_move
+      update_resize
+      meta_window_handle_mouse_grab_op_event
+      _NET_MOVERESIZE_WINDOW
+      _NET_WM_STRUT
+
+    Drag and drop issues:
+      the XDND protocol (see http://www.newplanetsoftware.com/xdnd/ and
+        http://freedesktop.org/Standards/XDND)
+      _NET_WM_MOUSE_ACTION/_NET_WM_TAKE_ACTIVITY (aren't yet in EWMH)
+      A general pointer: what causes the difficulty here is that when the
+        application receives a mouse click to start a drag, it does a grab
+        so that the window manager doesn't get any further events; thus
+        correcting things require standards so that applications and window
+        managers can collaborate correctly
+
+    Theme issues: ???
+      doc/theme-format.txt
+      theme.c
+      theme-parser.c
+      (ui.c, core.c, frames.c, frame.c?  I dunno...)
+
+    Session management issues: ???
+      session.c
+      http://www.x.org/X11R6.8.1/doc/SM/xsmp.pdf ?
+      http://www.x.org/X11R6.8.1/doc/SM/SMlib.pdf ?
+      meta_window_apply_session_info
+
+    Tasklist and Workspace switcher issues:
+      window-props.c
+      various functions in screen.c (especially ones using XChangeProperty)
+      xprops.c
+      The libwnck module in cvs
+      meta_window_client_message
+      Lots of the EWMH
+
+    Window and workspace selection/changing issues:
+      tabpopup.c
+      keybindings.c, functions: *_workspace*, *_tab_*
+      meta_screen_ensure_*_popup
+      display.c, functions: *_tab*
+
+    Key and mouse binding actions:
+      keybindings.c
+      meta_frames_button_(press|release)_event
+      display.c: event_callback, but only the (Key|Button)_(Press|Release) cases
+
+    Xinerama and multiscreen: ???
+      In general, just search for Xinerama, but in particular see
+      screen.c
+      window.c
+      place.c
+      constraints.c