Some more work on the how to hack documentation

next
Michael Stapelberg 2009-04-30 17:27:58 +02:00
parent b4fcd3f81f
commit 44803b0026
4 changed files with 53 additions and 8 deletions

View File

@ -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 $<

BIN
docs/bigpicture.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 9.0 KiB

BIN
docs/bigpicture.xcf Normal file

Binary file not shown.

View File

@ -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
i3s 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 dont 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 youve 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.