Some more work on the how to hack documentation

diff --git a/docs/Makefile b/docs/Makefile
index 720f6387c8af1a575bd5487ab6df6d6c850e84d9..e69aefc56ddb513a1da8bccd077754f548f13026 100644 (file)
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -2,7 +2,7 @@
 all: hacking-howto.html debugging.html
 
 hacking-howto.html: hacking-howto
-       asciidoc -n $<
+       asciidoc -a toc -n $<
 
 debugging.html: debugging
        asciidoc -n $<

diff --git a/docs/bigpicture.png b/docs/bigpicture.png
new file mode 100644 (file)
index 0000000..fc3c8db
Binary files /dev/null and b/docs/bigpicture.png differ

diff --git a/docs/bigpicture.xcf b/docs/bigpicture.xcf
new file mode 100644 (file)
index 0000000..ead0071
Binary files /dev/null and b/docs/bigpicture.xcf differ

diff --git a/docs/hacking-howto b/docs/hacking-howto
index 74715bcbaf406f3e4a104c8cd1f7e7569e6182d2..ad8b9ab4ecc7bae8bbe0038853696d72be9929b5 100644 (file)
--- a/docs/hacking-howto
+++ b/docs/hacking-howto
@@ -1,7 +1,7 @@
 Hacking i3: How To
 ==================
 Michael Stapelberg <michael+i3@stapelberg.de>
-March 2009
+May 2009
 
 This document is intended to be the first thing you read before looking and/or touching
 i3’s source code. It should contain all important information to help you understand
@@ -103,7 +103,9 @@ include/data.h::
 Contains data definitions used by nearly all files. You really need to read this first.
 
 include/*.h::
-Contains forward definitions for all public functions.
+Contains forward definitions for all public functions, aswell as doxygen-compatible
+comments (so if you want to get a bit more of the big picture, either browse all
+header files or use doxygen if you prefer that).
 
 src/commands.c::
 Parsing commands
@@ -140,19 +142,27 @@ src/xinerama.c::
 See include/data.h for documented data structures. The most important ones are explained
 right here.
 
-TODO: We need a slick graphic here
+image:bigpicture.png[The Big Picture]
+
+So, the hierarchy is:
+
+. *Virtual screens* (Screen 0 in this example)
+. *Workspaces* (Workspace 1 in this example)
+. *Table* (There can only be one table per Workspace)
+. *Container* (left and right in this example)
+. *Client* (The two clients in the left container)
 
 === Virtual screens
 
 A virtual screen (type `i3Screen`) is generated from the connected screens obtained
-through Xinerama. The difference to the raw Xinerama monitors as seen when using xrandr(1)
+through Xinerama. The difference to the raw Xinerama monitors as seen when using +xrandr(1)+
 is that it falls back to the lowest common resolution of the logical screens.
 
 For example, if your notebook has 1280x800 and you connect a video projector with
-1024x768, set up in clone mode (xrandr \--output VGA \--mode 1024x768 \--same-as LVDS),
+1024x768, set up in clone mode (+xrandr \--output VGA \--mode 1024x768 \--same-as LVDS+),
 i3 will have one virtual screen.
 
-However, if you configure it using xrandr \--output VGA \--mode 1024x768 \--right-of LVDS,
+However, if you configure it using +xrandr \--output VGA \--mode 1024x768 \--right-of LVDS+,
 i3 will generate two virtual screens. For each virtual screen, a new workspace will be
 assigned. New workspaces are created on the screen you are currently on.
 
@@ -291,7 +301,15 @@ is re-rendered.
 
 == Size hints
 
-TODO
+Size hints specify the minimum/maximum size for a given window aswell as its aspect ratio.
+At the moment, as i3 does not have a floating mode yet, only the aspect ratio is parsed.
+This is important for clients like mplayer, who only set the aspect ratio and resize their
+window to be as small as possible (but only with some video outputs, for example in Xv,
+while when using x11, mplayer does the necessary centering for itself).
+
+So, when an aspect ratio was specified, i3 adjusts the height of the window until the
+size maintains the correct aspect ratio. For the code to do this, see src/layout.c,
+function resize_client().
 
 == Rendering (src/layout.c, render_layout() and render_container())
 
@@ -373,3 +391,30 @@ direction to move a window respectively or snap.
 * Forgetting to call `xcb_flush(conn);` after sending a request. This usually leads to
   code which looks like it works fine but which does not work under certain conditions.
 
+== Using git / sending patches
+
+For a short introduction into using git, see TODO.
+
+When you want to send a patch because you fixed a bug or implemented a cool feature (please
+talk to us before working on features to see whether they are maybe already implemented, not
+possible because of some reason or don’t fit into the concept), please use git to create
+a patchfile.
+
+First of all, update your working copy to the latest version of the master branch:
+
+--------
+git pull
+--------
+
+Afterwards, make the necessary changes for your bugfix/feature. Then, review the changes
+using +git diff+ (you might want to enable colors in the diff using +git config diff.color auto+).
+When you are definitely done, use +git commit -a+ to commit all changes you’ve made.
+
+Then, use the following command to generate a patchfile which we can directly apply to
+the branch, preserving your commit message and name:
+
+-----------------------
+git format-patch origin
+-----------------------
+
+Just send us the generated file via mail.