From: Michael Stapelberg Date: Thu, 30 Apr 2009 15:27:58 +0000 (+0200) Subject: Some more work on the how to hack documentation X-Git-Tag: 3.a-bf1~19 X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=44803b0026e13f68d14a4d0fcda9e2cd76dd18cc;p=i3%2Fi3 Some more work on the how to hack documentation --- diff --git a/docs/Makefile b/docs/Makefile index 720f6387..e69aefc5 100644 --- 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 index 00000000..fc3c8db7 Binary files /dev/null and b/docs/bigpicture.png differ diff --git a/docs/bigpicture.xcf b/docs/bigpicture.xcf new file mode 100644 index 00000000..ead00719 Binary files /dev/null and b/docs/bigpicture.xcf differ diff --git a/docs/hacking-howto b/docs/hacking-howto index 74715bcb..ad8b9ab4 100644 --- a/docs/hacking-howto +++ b/docs/hacking-howto @@ -1,7 +1,7 @@ Hacking i3: How To ================== Michael Stapelberg -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.