From 234ed6c99b03eca5a95e686cda298eae33d40c2f Mon Sep 17 00:00:00 2001 From: Michael Stapelberg Date: Sun, 21 Mar 2010 01:50:10 +0100 Subject: [PATCH] docs: merge spelling and grammar fixes by sasha (Thanks!) --- CMDMODE | 19 +++-- DEPENDS | 7 +- PACKAGE-MAINTAINER | 21 +++-- docs/debugging | 42 +++++----- docs/hacking-howto | 40 +++++----- docs/ipc | 16 ++-- docs/multi-monitor | 40 +++++----- docs/userguide | 185 +++++++++++++++++++++++---------------------- i3.config | 2 +- i3.welcome | 13 ++-- man/i3-input.man | 8 +- man/i3-msg.man | 3 +- man/i3.man | 14 ++-- 13 files changed, 216 insertions(+), 194 deletions(-) diff --git a/CMDMODE b/CMDMODE index 7d8f6f23..95cb5bc1 100644 --- a/CMDMODE +++ b/CMDMODE @@ -2,7 +2,8 @@ - Command mode --------------------- -This is the grammar for the command mode (your configuration file uses these commands, too). +This is the grammar for the 'command mode' (your configuration file +uses these commands, too). left := | right := | @@ -17,15 +18,17 @@ cmd := [ ] [ | ] with := { [ ] }+ jump := [ "[/]" | [ ] ] focus := focus [ | floating | tiling | ft ] -(travels the focus stack backwards the given amount of times (by default 1), so - it selects the window which had the focus before you focused the current one when - specifying "focus 1". - The special values 'floating' (select the next floating window), 'tiling' - (select the next tiling window), 'ft' (if the current window is floating, - select the next tiling window and vice-versa) are also valid) + (travels the focus stack backwards, number of times (by default 1). + So by specifying "focus 1" it selects the window which last had the focus + before you focused the current one window. + The following 3 special values are also valid: + 'floating' (select the next floating window). + 'tiling' (select the next tiling window). + 'ft' (toggle tiling/floating: if the current window is floating, + select the next tiling window and vice-versa) special := [ exec | kill | exit | restart ] -input := [ | | | | ] +input := [ | | | | ] you can cancel command mode by pressing escape anytime. diff --git a/DEPENDS b/DEPENDS index 31947bf9..b7a6fefb 100644 --- a/DEPENDS +++ b/DEPENDS @@ -1,6 +1,7 @@ -You need the following libraries. The version given is to be understand as the minimum -version. However, if any of these libraries changes the API, i3 may not compile anymore. -In that case, please try using the versions mentioned below until a fix is provided. +You need the following libraries. The version given is to be understood as the +minimum version required. However, if any of these libraries changes the API, +i3 may not compile anymore. In that case, please try using the versions +mentioned below until a fix is provided. * xcb-proto-1.3 (2008-12-10) * libxcb-1.1.93 (2008-12-11) diff --git a/PACKAGE-MAINTAINER b/PACKAGE-MAINTAINER index c5c10038..40222803 100644 --- a/PACKAGE-MAINTAINER +++ b/PACKAGE-MAINTAINER @@ -1,11 +1,15 @@ Dear package maintainer, -thanks for packaging i3. By doing so, you are improving your distribution and i3 in general. +thanks for packaging i3. By doing so, you are improving your distribution +and i3 in general. -Please read the file DEPENDS now, so you know which libraries are necessary and where to -get them from if your distribution does not already have packages for them. +Please read the file DEPENDS now, so you know which libraries are necessary +and where to get them from if your distribution does not already have +packages for them. + +Please make sure the manpage for i3 will be properly created and installed +in your package. -Please make sure the manpage for i3 will be properly created and installed in your package. On debian, this looks like this: # Compilation @@ -17,10 +21,11 @@ On debian, this looks like this: mkdir -p $(CURDIR)/debian/i3-wm/usr/share/man/man1 cp man/i3.1 $(CURDIR)/debian/i3-wm/usr/share/man/man1 -If you got any questions, ideas, hints, problems or whatever, please do not -hesitate to contact me. I will help you out. Just drop me an E-Mail (find the address at -http://michael.stapelberg.de/Kontakt, scroll down to bottom), contact me using the same -address in jabber or ask on our IRC channel (#i3 on irc.twice-irc.de). +If you have any questions, ideas, hints, problems or whatever, please do not +hesitate to contact me. I will help you out. Just drop me an E-Mail (find the +address at http://michael.stapelberg.de/Kontakt, scroll down to bottom), +contact me using the same address in jabber or ask on our IRC channel: +(#i3 on irc.twice-irc.de). Thanks again for your efforts, Michael diff --git a/docs/debugging b/docs/debugging index f2a92739..ca680f24 100644 --- a/docs/debugging +++ b/docs/debugging @@ -1,5 +1,5 @@ Debugging i3: How To -================== +==================== Michael Stapelberg April 2009 @@ -13,22 +13,22 @@ debugging and/or need further help, do not hesitate to contact us! == Enabling logging i3 spits out much information onto stdout. To have a clearly defined place -where logfiles will be saved, you should redirect stdout and stderr in -xsession. While you’re at it, putting each run of i3 in a separate logfile with -date/time in it is a good idea to not get confused about the different logfiles -later on. +where log files will be saved, you should redirect stdout and stderr in +xsession. While you’re at it, putting each run of i3 in a separate log file +with date/time in it is a good idea to not get confused about the different +log files later on. -------------------------------------------------------------------- exec /usr/bin/i3 >/home/michael/i3/i3log-$(date +'%F-%k-%M-%S') 2>&1 -------------------------------------------------------------------- -== Enabling coredumps +== Enabling core dumps -When i3 crashes, often you have the chance of getting a coredump (an image of -the memory of the i3 process which can be loaded into a debugger). To get a -core-dump, you have to make sure that the user limit for core dump files is set +When i3 crashes, often you have the chance of getting a 'core dump' (an image +of the memory of the i3 process which can be loaded into a debugger). To get a +core dump, you have to make sure that the user limit for core dump files is set high enough. Many systems ship with a default value which even forbids core -dumps completely. To disable the limit completely and thus enable coredumps, +dumps completely. To disable the limit completely and thus enable core dumps, use the following command (in your .xsession, before starting i3): ------------------- @@ -49,7 +49,7 @@ process id (%p) in it. You can save this setting across reboots using == Compiling with debug symbols -To actually get useful coredumps, you should make sure that your version of i3 +To actually get useful core dumps, you should make sure that your version of i3 is compiled with debug symbols, that is, that they are not stripped during the build process. You can check whether your executable contains symbols by issuing the following command: @@ -72,15 +72,15 @@ stripping. If nothing helps, please build i3 from source. == Generating a backtrace Once you have made sure that your i3 is compiled with debug symbols and that -coredumps are enabled, you can start getting some sense out of the coredumps. +core dumps are enabled, you can start making sense out of the core dumps. -Because the coredump depends on the original executable (and its debug +Because the core dump depends on the original executable (and its debug symbols), please do this as soon as you encounter the problem. If you -re-compile i3, your coredump might be useless afterwards. +re-compile i3, your core dump might be useless afterwards. Please install +gdb+, a debugger for C. No worries, you don’t need to learn it now. Start gdb using the following command (replacing the actual name of the -coredump of course): +core dump of course): ---------------------------- gdb $(which i3) core.i3.3849 @@ -92,13 +92,13 @@ Then, generate a backtrace using: backtrace full -------------- -== Sending bugreports/debugging on IRC +== Sending bug reports/debugging on IRC -When sending bugreports, please paste the relevant part of the log (if in +When sending bug reports, please paste the relevant part of the log (if in doubt, please send us rather too much information than too less) and the whole -backtrace (if there was a coredump). +backtrace (if there was a core dump). When debugging with us in IRC, be prepared to use a so called nopaste service -such as http://nopaste.info because pasting large amounts of text in IRC -sometimes leads to incomplete lines (servers have line length limitations) or -flood kicks. +such as http://nopaste.info or http://pastebin.com because pasting large +amounts of text in IRC sometimes leads to incomplete lines (servers have line +length limitations) or flood kicks. diff --git a/docs/hacking-howto b/docs/hacking-howto index 017e0d0b..dff074cb 100644 --- a/docs/hacking-howto +++ b/docs/hacking-howto @@ -24,8 +24,9 @@ some events which normal clients usually don’t handle. In the case of i3, the tasks (and order of them) are the following: . Grab the key bindings (events will be sent upon keypress/keyrelease) -. Iterate through all existing windows (if the window manager is not started as the first - client of X) and manage them (= reparent them, create window decorations) +. Iterate through all existing windows (if the window manager is not started as + the first client of X) and manage them (reparent them, create window + decorations, etc.) . When new windows are created, manage them . Handle the client’s `_WM_STATE` property, but only the `_WM_STATE_FULLSCREEN` . Handle the client’s `WM_NAME` property @@ -35,8 +36,8 @@ In the case of i3, the tasks (and order of them) are the following: . Handle button (as in mouse buttons) presses for focus/raise on click . Handle expose events to re-draw own windows such as decorations . React to the user’s commands: Change focus, Move windows, Switch workspaces, -Change the layout mode of a container (default/stacking), Start a new application, -Restart the window manager + Change the layout mode of a container (default/stacking/tabbed), start a new + application, restart the window manager In the following chapters, each of these tasks and their implementation details will be discussed. @@ -46,8 +47,8 @@ will be discussed. Traditionally, there are two approaches to managing windows: The most common one nowadays is floating, which means the user can freely move/resize the windows. The other approach is called tiling, which means that your window -manager distributing windows to use as much space as possible while not -overlapping. +manager distributes windows to use as much space as possible while not +overlapping each other. The idea behind tiling is that you should not need to waste your time moving/resizing windows while you usually want to get some work done. After @@ -90,8 +91,9 @@ When moving terminal 2 to the bottom, the table will be expanded again. |======== You can really think of the layout table like a traditional HTML table, if -you’ve ever designed one. Especially col- and rowspan work equally. Below you -see an example of colspan=2 for the first container (which has T1 as window). +you’ve ever designed one. Especially col- and rowspan work similarly. Below, +you see an example of colspan=2 for the first container (which has T1 as +window). [width="15%",cols="^asciidoc"] |======== @@ -112,7 +114,7 @@ Contains data definitions used by nearly all files. You really need to read this first. include/*.h:: -Contains forward definitions for all public functions, aswell as +Contains forward definitions for all public functions, as well 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). @@ -131,7 +133,7 @@ Contains all functions which are specific to a certain client (make it fullscreen, see if its class/name matches a pattern, kill it, …). src/commands.c:: -Parsing commands and actually execute them (focussing, moving, …). +Parsing commands and actually executing them (focusing, moving, …). src/config.c:: Parses the configuration file. @@ -143,7 +145,7 @@ src/floating.c:: Contains functions for floating mode (mostly resizing/dragging). src/handlers.c:: -Contains all handlers for all kind of X events (new window title, new hints, +Contains all handlers for all kinds of X events (new window title, new hints, unmapping, key presses, button presses, …). src/ipc.c:: @@ -212,7 +214,7 @@ screen you are currently on. === Workspace A workspace is identified by its number. Basically, you could think of -workspaces as different desks in your bureau, if you like the desktop +workspaces as different desks in your office, if you like the desktop methaphor. They just contain different sets of windows and are completely separate of each other. Other window managers also call this ``Virtual desktops''. @@ -288,7 +290,7 @@ So, why do we need to grab keycodes actively? Because X does not set the state-property of keypress/keyrelease events properly. The Mode_switch bit is not set and we need to get it using XkbGetState. This means we cannot pass X our combination of modifiers containing Mode_switch when grabbing the key and -therefore need to grab the keycode itself without any modiffiers. This means, +therefore need to grab the keycode itself without any modifiers. This means, if you bind Mode_switch + keycode 38 ("a"), i3 will grab keycode 38 ("a") and check on each press of "a" if the Mode_switch bit is set using XKB. If yes, it will handle the event, if not, it will replay the event. @@ -344,7 +346,7 @@ moved/resized so that the currently active layout (default/stacking/tabbed mode) is rendered correctly. To move/resize windows, a window is ``configured'' in X11-speak. -Some applications, such as MPlayer obivously assume the window manager is +Some applications, such as MPlayer obviously assume the window manager is stupid and try to configure their windows by themselves. This generates an event called configurerequest. i3 handles these events and tells the window the size it had before the configurerequest (with the exception of not yet mapped @@ -374,7 +376,7 @@ characters (every special character contained in your font). == Size hints -Size hints specify the minimum/maximum size for a given window aswell as its +Size hints specify the minimum/maximum size for a given window as well as its aspect ratio. 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 @@ -447,10 +449,10 @@ floating windows: (+grabwin+) * Another window, 2px width and as high as your screen (or vice versa for horizontal resizing) is created. Its background color is the border color and - it is only there to signalize the user how big the container will be (it + it is only there to inform the user how big the container will be (it creates the impression of dragging the border out of the container). * The +drag_pointer+ function of +src/floating.c+ is called to grab the pointer - and enter an own event loop which will pass all events (expose events) but + and enter its own event loop which will pass all events (expose events) but motion notify events. This function then calls the specified callback (+resize_callback+) which does some boundary checking and moves the helper window. As soon as the mouse button is released, this loop will be @@ -497,7 +499,7 @@ http://git-scm.com/documentation 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 +maybe already implemented, not possible for some 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 @@ -519,4 +521,4 @@ apply to the branch, preserving your commit message and name: git format-patch origin ----------------------- -Just send us the generated file via mail. +Just send us the generated file via email. diff --git a/docs/ipc b/docs/ipc index 117050a3..4e46bc9e 100644 --- a/docs/ipc +++ b/docs/ipc @@ -28,10 +28,10 @@ my $sock = IO::Socket::UNIX->new(Peer => '/tmp/i3-ipc.sock'); To send a message to i3, you have to format in the binary message format which i3 expects. This format specifies a magic string in the beginning to ensure -the integrity of messages (to prevent follow-up errors). Afterwards follows -the length of the payload of the message as 32-bit integer and the type of -the message as 32-bit integer (the integers are not converted, so they are -in native byte order). +the integrity of messages (to prevent follow-up errors). Following the magic +string comes the length of the payload of the message as 32-bit integer, and +the type of the message as 32-bit integer (the integers are not converted, so +they are in native byte order). The magic string currently is "i3-ipc" and will only be changed when a change in the IPC API is done which breaks compatibility (we hope that we don’t need @@ -75,11 +75,11 @@ sub format_ipc_command { } $sock->write(format_ipc_command("exit")); ------------------------------------------------------------- +------------------------------------------------------------------------------ == Receiving replies from i3 -Replies of i3 usually consist of a simple string (the length of the string +Replies from i3 usually consist of a simple string (the length of the string is the message_length, so you can consider them length-prefixed) which in turn contain the JSON serialization of a data structure. For example, the GET_WORKSPACES message returns an array of workspaces (each workspace is a map @@ -240,8 +240,8 @@ that the requests to i3 are processed in order. This means, the following situation can happen: You send a GET_WORKSPACES request but you receive a "workspace" event before receiving the reply to GET_WORKSPACES. If your program does not want to cope which such kinds of race conditions (an -event based library may not have a problem here), I advise to create a separate -connection to receive events. +event based library may not have a problem here), I suggest you create a +separate connection to receive events. === Subscribing to events diff --git a/docs/multi-monitor b/docs/multi-monitor index 9affb0cc..ec0256c0 100644 --- a/docs/multi-monitor +++ b/docs/multi-monitor @@ -3,22 +3,23 @@ The multi-monitor situation Michael Stapelberg March 2010 -…or: oh no, I have an nvidia graphics card! +…or: oh no, I have an nVidia graphics card! == The quick fix -If you are using the nvidia binary graphics driver, you need to use the -+--force-xinerama+ flag when starting i3, like so (in your xsession): +If you are using the nVidia binary graphics driver (also known as 'blob') +you need to use the +--force-xinerama+ flag (in your .xsession) when starting +i3, like so: .Example: ---------------------------------------------- -exec i3 --force-xinerama -V >>~/.i3/i3log 2>&1 +exec i3 --force-xinerama -V >>~/.i3/i3log 2>&1 ---------------------------------------------- == The explanation Starting with version 3.ε, i3 uses the RandR (Rotate and Resize) API instead -of Xinerama. This is due to the reason that RandR provides more information +of Xinerama. The reason for this, is that RandR provides more information about your outputs and connected screens than Xinerama does. To be specific, the code which handled on-the-fly screen reconfiguration (meaning without restarting the X server) was a very messy heuristic and most of the time did @@ -27,29 +28,30 @@ Xinerama offers (just a list of screen resolutions, no identifiers for the screens or any additional information). Xinerama simply was not designed for dynamic configuration. -So, RandR came up as a more powerful alternative (RandR 1.2 to be specific). +So RandR came along, as a more powerful alternative (RandR 1.2 to be specific). It offers all of Xinerama’s possibilities and lots more. Using the RandR API made our code much more robust and clean. Also, you can now reliably assign workspaces to output names instead of some rather unreliable screen identifier (position inside the list of screens, which could change, and so on…). -As RandR is around for about three years, it seemed like a very good idea to -us and it still is a very good one. What we did not expect, however, was the -nVidia binary driver. It still does not support RandR (as of March 2010), even -though nVidia announced that it will support RandR eventually. What does this -mean for you, if you are stuck with the binary driver for some reason (say -the free drivers don’t work with your card)? First of all, you are stuck with -TwinView and cannot use +xrandr+. While this ruins the user experience, the -more grave problem is that the nVidia driver not only does not support dynamic -configuration using RandR, it also does not even expose correct multi-monitor -information via the RandR API. So, in some setups, i3 will not find any -screens, in others it will find one large screen which actually contains both -of your physical screens (but it will not know that these are two screens). +As RandR has been around for about three years as of this writing, it seemed +like a very good idea to us, and it still is a very good one. What we did not +expect, however, was the nVidia binary driver. It still does not support RandR +(as of March 2010), even though nVidia has announced that it will support RandR +eventually. What does this mean for you, if you are stuck with the binary +driver for some reason (say the free drivers don’t work with your card)? First +of all, you are stuck with TwinView and cannot use +xrandr+. While this ruins +the user experience, the more grave problem is that the nVidia driver not only +does not support dynamic configuration using RandR, it also does not expose +correct multi-monitor information via the RandR API. So, in some setups, i3 +will not find any screens; in others, it will find one large screen which +actually contains both of your physical screens (but it will not know that +these are two screens). For this very reason, we decided to implement the following workaround: As long as the nVidia driver does not support RandR, an option called +--force-xinerama+ is available in i3. This option gets the list of screens -*once* when starting and never updates it. As the nVidia driver cannot do +*once* when starting, and never updates it. As the nVidia driver cannot do dynamic configuration anyways, this is not a big deal. == See also diff --git a/docs/userguide b/docs/userguide index 5a313c92..f4a27743 100644 --- a/docs/userguide +++ b/docs/userguide @@ -21,8 +21,8 @@ image:keyboard-layer1.png["Keys to use with Mod1 (alt)",width=600,link="keyboard image:keyboard-layer2.png["Keys to use with Shift+Mod1",width=600,link="keyboard-layer2.png"] As i3 uses keycodes in the default configuration, it does not matter which -keyboard layout you actually use. The key positions are what matters (of course you can -also use keysymbols, see below). +keyboard layout you actually use. The key positions are what matters (of course +you can also use keysymbols, see below). The red keys are the modifiers you need to press (by default), the blue keys are your homerow. @@ -40,7 +40,8 @@ image:single_terminal.png[Single terminal] It is important to keep in mind that i3 uses a table to manage your windows. At the moment, you have exactly one column and one row which leaves you with one -cell. In this cell there is a container which is where your new terminal is opened. +cell. In this cell there is a container, which is where your new terminal is +opened. If you now open another terminal, you still have only one cell. However, the container in that cell holds both of your terminals. So, a container is just a @@ -52,12 +53,12 @@ image:two_terminals.png[Two terminals] To move the focus between the two terminals, you use the direction keys which you may know from the editor +vi+. However, in i3, your homerow is used for these keys (in +vi+, the keys are shifted to the left by one for compatibility -with most keyboard layouts). Therefore, +Mod1+J+ is left, +Mod1+K+ is down, +Mod1+L+ -is up and `Mod1+;` is right. So, to switch between the terminals, use +Mod1+K+ or -+Mod1+L+. +with most keyboard layouts). Therefore, +Mod1+J+ is left, +Mod1+K+ is down, ++Mod1+L+ is up and `Mod1+;` is right. So, to switch between the terminals, +use +Mod1+K+ or +Mod1+L+. To create a new row/column (and a new cell), you can simply move a terminal (or -any other window) to the direction you want to expand your table. So, let’s +any other window) in the direction you want to expand your table. So, let’s expand the table to the right by pressing `Mod1+Shift+;`. image:two_columns.png[Two columns] @@ -118,8 +119,8 @@ another workspace, press +Mod1+num+ where +num+ is the number of the workspace you want to use. If the workspace does not exist yet, it will be created. A common paradigm is to put the web browser on one workspace, communication -applications (+mutt+, +irssi+, ...) on another one and the ones with which you -work on the third one. Of course, there is no need to follow this approach. +applications (+mutt+, +irssi+, ...) on another one, and the ones with which you +work, on the third one. Of course, there is no need to follow this approach. If you have multiple screens, a workspace will be created on each screen at startup. If you open a new workspace, it will be bound to the screen you @@ -135,10 +136,10 @@ it does not yet exist. === Resizing columns/rows -To resize columns or rows just grab the border between the two columns/rows +To resize columns or rows, just grab the border between the two columns/rows and move it to the wanted size. Please keep in mind that each cell of the table holds a +container+ and thus you cannot horizontally resize single windows. If -you need applications with different horizontal sizes place them in seperate +you need applications with different horizontal sizes, place them in seperate cells one above the other. See <> for how to configure i3 to be able to resize @@ -146,7 +147,7 @@ columns/rows with your keyboard. === Restarting i3 inplace -To restart i3 inplace (and thus get into a clean state if there is a bug or +To restart i3 inplace (and thus get into a clean state if there is a bug, or to upgrade to a newer version of i3) you can use +Mod1+Shift+r+. Be aware, though, that this kills your current layout and all the windows you have opened will be put in a default container in only one cell. Saving layouts will be @@ -173,7 +174,7 @@ by pressing +Mod1+Control+k+ (or snap container 2 rightwards). Floating mode is the opposite of tiling mode. The position and size of a window are not managed by i3, but by you. Using this mode violates the tiling paradigm but can be useful for some corner cases like "Save as" dialog -windows or toolbar windows (GIMP or similar). +windows, or toolbar windows (GIMP or similar). You can enable floating mode for a window by pressing +Mod1+Shift+Space+. By dragging the window’s titlebar with your mouse you can move the window @@ -235,18 +236,19 @@ A keyboard binding makes i3 execute a command (see below) upon pressing a specific key. i3 allows you to bind either on keycodes or on keysyms (you can also mix your bindings, though i3 will not protect you from overlapping ones). -* A keysym (key symbol) is a description for a specific symbol, like "a" or "b", - but also more strange ones like "underscore" instead of "_". These are the ones - you use in Xmodmap to remap your keys. To get the current mapping of your - keys, use +xmodmap -pke+. +* A keysym (key symbol) is a description for a specific symbol, like "a" + or "b", but also more strange ones like "underscore" instead of "_". These + are the ones you use in Xmodmap to remap your keys. To get the current + mapping of your keys, use +xmodmap -pke+. * Keycodes do not need to have a symbol assigned (handy for some hotkeys on some notebooks) and they will not change their meaning as you switch to a different keyboard layout (when using +xmodmap+). My recommendation is: If you often switch keyboard layouts but you want to keep -your bindings in the same physical location on the keyboard use keycodes. If you -don’t switch layouts and want a clean and simple config file, use keysyms. +your bindings in the same physical location on the keyboard, use keycodes. +If you don’t switch layouts, and want a clean and simple config file, use +keysyms. *Syntax*: ---------------------------------- @@ -287,9 +289,9 @@ use the same key you use for managing windows (Mod1 for example). Then you can press Mod1, click into a window using your left mouse button, and drag it to the position you want. -When holding the floating modifier, you can resize a floating window by pressing -the right mouse button on it and moving around while holding it. If you hold the -shift button as well, the resize will be proportional. +When holding the floating modifier, you can resize a floating window by +pressing the right mouse button on it and moving around while holding it. If +you hold the shift button as well, the resize will be proportional. *Syntax*: -------------------------------- @@ -359,13 +361,13 @@ configuration file and run it before starting i3 (for example in your [[assign_workspace]] -It is recommended that you match on window classes whereever possible because -some applications first create their window and then worry about setting the +It is recommended that you match on window classes wherever possible because +some applications first create their window, and then worry about setting the correct title. Firefox with Vimperator comes to mind. The window starts up -being named Firefox and only when Vimperator is loaded the title changes. As -i3 will get the title as soon as the application maps the window (mapping means -actually displaying it on the screen), you’d need to have to match on Firefox -in this case. +being named Firefox, and only when Vimperator is loaded does the title change. +As i3 will get the title as soon as the application maps the window (mapping +means actually displaying it on the screen), you’d need to have to match on +'Firefox' in this case. You can prefix or suffix workspaces with a `~` to specify that matching clients should be put into floating mode. If you specify only a `~`, the client will @@ -389,11 +391,11 @@ assign "xv/MPlayer" → ~ Note that the arrow is not required, it just looks good :-). If you decide to use it, it has to be a UTF-8 encoded arrow, not "->" or something like that. -=== Automatically starting applications on startup +=== Automatically starting applications on i3 startup By using the +exec+ keyword outside a keybinding, you can configure which -commands will be performed by i3 on initial startup (not when restarting inplace -however). These commands will be run in order. +commands will be performed by i3 on initial startup (not when restarting i3 +in-place however). These commands will be run in order. *Syntax*: ------------ @@ -420,7 +422,7 @@ the second screen and so on). workspace output ---------------------------------- -The output is the name of the RandR output you attach your screen to. On a +The 'output' is the name of the RandR output you attach your screen to. On a laptop, you might have VGA1 and LVDS1 as output names. You can see the available outputs by running +xrandr --current+. @@ -441,7 +443,7 @@ workspace workspace output name --------------------------------------- -For more details about the output-part of this command, see above. +For more details about the 'output' part of this command, see above. *Examples*: -------------------------- @@ -486,15 +488,15 @@ Colors are in HTML hex format (#rrggbb), see the following example: client.focused #2F343A #900000 #FFFFFF -------------------------------------- -Note that for the window decorations the color around the child window is the -background color and the border color is only the two thin lines at the top of +Note that for the window decorations, the color around the child window is the +background color, and the border color is only the two thin lines at the top of the window. === Interprocess communication i3 uses unix sockets to provide an IPC interface. This allows third-party -programs to get information like the current workspaces to display a workspace -bar, and to control i3. +programs to get information from i3, such as the current workspaces +(to display a workspace bar), and to control i3. To enable it, you have to configure a path where the unix socket will be stored. The default path is +/tmp/i3-ipc.sock+. @@ -504,14 +506,14 @@ stored. The default path is +/tmp/i3-ipc.sock+. ipc-socket /tmp/i3-ipc.sock ---------------------------- -You can then use the +i3-msg+ application to perform any command listed in the next -section. +You can then use the +i3-msg+ application to perform any command listed in +the next section. === Disable focus follows mouse If you have a setup where your mouse usually is in your way (like a touchpad on your laptop which you do not want to disable completely), you might want -to disable focus follows mouse and control focus only by using your keyboard. +to disable 'focus follows mouse' and control focus only by using your keyboard. The mouse will still be useful inside the currently active window (for example to click on links in your browser window). @@ -550,13 +552,13 @@ bindsym Mod1+Shift+f fg bindsym Mod1+t t -------------- -=== Focussing/Moving/Snapping clients/containers/screens +=== Focusing/Moving/Snapping clients/containers/screens To change the focus, use one of the +h+, +j+, +k+ and +l+ commands, meaning -left, down, up, right (respectively). To focus a container, prefix it with +wc+, -to focus a screen, prefix it with +ws+. +left, down, up, right (respectively). To focus a container, prefix it with ++wc+. To focus a screen, prefix it with +ws+. -The same principle applies for moving and snapping, just prefix the command +The same principle applies for moving and snapping: just prefix the command with +m+ when moving and with +s+ when snapping: *Examples*: @@ -590,9 +592,9 @@ To change to a specific workspace, the command is just the number of the workspace, e.g. +1+ or +3+. To move the current client to a specific workspace, prefix the number with an +m+. -You can also switch to the next and previous workspace with the -commands +nw+ and +pw+, which is handy, for example, if you have workspace -1, 3, 4 and 9 and you want to cycle through them with a single key combination. +You can also switch to the next and previous workspace with the commands +nw+ +and +pw+, which is handy, for example, if you have workspace 1, 3, 4 and 9 and +you want to cycle through them with a single key combination. *Examples*: ------------------------- @@ -645,11 +647,11 @@ bindsym Mod1+r mode resize === Jumping to specific windows -Often when in a multi-monitor environment, you want to quickly jump to a specific -window. For example while working on workspace 3 you may want to jump to -your mailclient to mail your boss that you’ve achieved some important goal. Instead -of figuring out how to navigate to your mailclient, it would be more convenient to -have a shortcut. +Often when in a multi-monitor environment, you want to quickly jump to a +specific window. For example, while working on workspace 3 you may want to +jump to your mail client to email your boss that you’ve achieved some +important goal. Instead of figuring out how to navigate to your mailclient, +it would be more convenient to have a shortcut. *Syntax*: ---------------------------------------------------- @@ -657,8 +659,9 @@ jump ["]window class[/window title]["] jump workspace [ column row ] ---------------------------------------------------- -You can either use the same matching algorithm as in the +assign+ command (see above) -or you can specify the position of the client if you always use the same layout. +You can either use the same matching algorithm as in the +assign+ command +(see above) or you can specify the position of the client if you always use +the same layout. *Examples*: -------------------------------------- @@ -673,9 +676,9 @@ bindsym Mod1+a jump "urxvt/VIM" This feature is like the jump feature: It allows you to directly jump to a specific window (this means switching to the appropriate workspace and setting focus to the windows). However, you can directly mark a specific window with -an arbitrary label and use it afterwards. You do not need to ensure -that your windows have unique classes or titles, and you do not need to change -your configuration file. +an arbitrary label and use it afterwards. You do not need to ensure that your +windows have unique classes or titles, and you do not need to change your +configuration file. As the command needs to include the label with which you want to mark the window, you cannot simply bind it to a key. +i3-input+ is a tool created @@ -702,16 +705,16 @@ seperate bindings for a specific set of labels and then only use those labels. === Traveling the focus stack -This mechanism can be thought of as the opposite of the +jump+ command. It travels -the focus stack and jumps to the window which had focus previously. +This mechanism can be thought of as the opposite of the +jump+ command. +It travels the focus stack and jumps to the window which had focus previously. *Syntax*: -------------- focus [number] | floating | tiling | ft -------------- -Where +number+ by default is 1 meaning that the next client in the focus stack will -be selected. +Where +number+ by default is 1 meaning that the next client in the focus stack +will be selected. The special values have the following meaning: @@ -720,8 +723,8 @@ floating:: tiling:: The next tiling window is selected. ft:: - If the current window is floating, the next tiling window will be selected - and vice-versa. + If the current window is floating, the next tiling window will be + selected; and vice-versa. === Changing border style @@ -772,9 +775,9 @@ You can make i3 reload its configuration file with +reload+. You can also restart i3 inplace with the +restart+ command to get it out of some weird state (if that should ever happen) or to perform an upgrade without having to restart your X session. However, your layout is not preserved at the moment, meaning -that all open windows will be in a single container in default layout. To exit -i3 properly, you can use the +exit+ command, however you don’t need to (e.g., -simply killing your X session is fine as well). +that all open windows will end up in a single container in default layout +after the restart. To exit i3 properly, you can use the +exit+ command, +however you don’t need to (simply killing your X session is fine as well). *Examples*: ---------------------------- @@ -791,33 +794,33 @@ As you can see in the goal list on the website, i3 was specifically developed with support for multiple monitors in mind. This section will explain how to handle multiple monitors. -When you have only one monitor things are simple. You usually start with +When you have only one monitor, things are simple. You usually start with workspace 1 on your monitor and open new ones as you need them. When you have more than one monitor, each monitor will get an initial -workspace. The first monitor gets 1, the second gets 2 and a possible third would -get 3. When you switch to a workspace on a different monitor, i3 will switch -to that monitor and then switch to the workspace. This way, you don’t need -shortcuts to switch to a specific monitor, and you don’t need to remember where -you put which workspace. New workspaces will be opened on the currently active -monitor. It is not possible to have a monitor without a workspace. - -The idea of making workspaces global is based on the observation that most users -have a very limited set of workspaces on their additional monitors. They are -often used for a specific task (browser, shell) or for monitoring several -things (mail, IRC, syslog, …). Thus, using one workspace on one monitor and -"the rest" on the other monitors often makes sense. However, as you can -create an unlimited number of workspaces in i3 and tie them to specific screens, -you can have the "traditional" approach of having X workspaces per screen by -changing your configuration (using modes, for example). +workspace. The first monitor gets 1, the second gets 2 and a possible third +would get 3. When you switch to a workspace on a different monitor, i3 will +switch to that monitor and then switch to the workspace. This way, you don’t +need shortcuts to switch to a specific monitor, and you don’t need to remember +where you put which workspace. New workspaces will be opened on the currently +active monitor. It is not possible to have a monitor without a workspace. + +The idea of making workspaces global is based on the observation that most +users have a very limited set of workspaces on their additional monitors. +They are often used for a specific task (browser, shell) or for monitoring +several things (mail, IRC, syslog, …). Thus, using one workspace on one monitor +and "the rest" on the other monitors often makes sense. However, as you can +create an unlimited number of workspaces in i3 and tie them to specific +screens, you can have the "traditional" approach of having X workspaces per +screen by changing your configuration (using modes, for example). === Configuring your monitors -To help you get going if you have never used multiple monitors before, here is a -short overview of the xrandr options which will probably be of interest to you. -It is always useful to get an overview of the current screen configuration. +To help you get going if you have never used multiple monitors before, here is +a short overview of the xrandr options which will probably be of interest to +you. It is always useful to get an overview of the current screen configuration. Just run "xrandr" and you will get an output like the following: --------------------------------------------------------------------------------------- +------------------------------------------------------------------------------- $ xrandr Screen 0: minimum 320 x 200, current 1280 x 800, maximum 8192 x 8192 VGA1 disconnected (normal left inverted right x axis y axis) @@ -837,9 +840,9 @@ course, it is the internal flat panel) but +VGA1+ is not. If you have a monitor connected to one of the ports but xrandr still says "disconnected", you should check your cable, monitor or graphics driver. -The maximum resolution you can see at the end of the first line -is the maximum combined resolution of your monitors. By default, it is usually -too low and has to be increased by editing +/etc/X11/xorg.conf+. +The maximum resolution you can see at the end of the first line is the maximum +combined resolution of your monitors. By default, it is usually too low and has +to be increased by editing +/etc/X11/xorg.conf+. So, say you connected VGA1 and want to use it as an additional screen: ------------------------------------------- @@ -848,7 +851,7 @@ xrandr --output VGA1 --auto --left-of LVDS1 This command makes xrandr try to find the native resolution of the device connected to +VGA1+ and configures it to the left of your internal flat panel. When running "xrandr" again, the output looks like this: ------------------------------------------------------------------------------------------ +------------------------------------------------------------------------------- $ xrandr Screen 0: minimum 320 x 200, current 2560 x 1024, maximum 8192 x 8192 VGA1 connected 1280x1024+0+0 (normal left inverted right x axis y axis) 338mm x 270mm @@ -869,7 +872,7 @@ LVDS1 connected 1280x800+1280+0 (normal left inverted right x axis y axis) 261mm 720x400 85.0 640x400 85.1 640x350 85.1 ------------------------------------------------------------------------------------------ +------------------------------------------------------------------------------- Please note that i3 uses exactly the same API as xrandr does, so it will see only what you can see in xrandr. diff --git a/i3.config b/i3.config index 7b838512..56cb2704 100644 --- a/i3.config +++ b/i3.config @@ -107,7 +107,7 @@ bind Mod1+36 exec /usr/bin/urxvt bind Mod1+Shift+24 kill # Mod1+v starts dmenu and launches the selected application -# for now, we don’t have an own launcher +# for now, we don’t have a launcher of our own. bind Mod1+55 exec /usr/bin/dmenu_run # Mod1+Shift+e exits i3 diff --git a/i3.welcome b/i3.welcome index 9c9861e9..72717ee7 100644 --- a/i3.welcome +++ b/i3.welcome @@ -1,6 +1,6 @@ 1.) Welcome to i3! -This message provides you with an overview of the default keybindings to use i3. +This message provides an overview of the default keybindings to use i3. Please also make sure to have a look at the man page and the user's guide: http://i3.zekjur.net/docs/userguide.html @@ -8,7 +8,8 @@ http://i3.zekjur.net/docs/userguide.html 2.) Configuration Files /etc/i3/config is the default configuration. It is recommended to copy it and -afterwards edit it to suit your needs (you can especially disable this message): +afterwards edit it to suit your needs (in particular, you may want to disable +this message): cp /etc/i3/config ~/.i3/config @@ -17,7 +18,7 @@ afterwards edit it to suit your needs (you can especially disable this message): The following explanation is related to the QWERTY layout, but as the default configuration uses keycodes instead of keysymbols for binding, you still have -to press the same keys, regardless of your keyboard layout. +to press the same physical keys, regardless of your keyboard layout. The Mod1 key is usually bound to the "Alt" key on your keyboard. @@ -28,15 +29,15 @@ The directional keys are j(left), k(down), l(up) and ;(right). You can also use the arrow keys on your keyboard, if you prefer them. Mod1+ moves the focus to the window in the given direction -Mod1+Shift+ moves the window to the given direction, +Mod1+Shift+ moves the window to the given direction Mod1+ opens the corresponding workspace -Mod1+Shift+ moves a window to the wished workspace +Mod1+Shift+ moves a window to the selected workspace Mod1+h sets the mode of a container to stacking Mod1+e sets the mode back to default Mod1+f toggles fullscreen mode for the current window Mod1+Shift+Space toggles floating mode for the current window Mod1+Shift+q closes a window -Mod1+Shift+r restarts i3 in-place (you will lose your layout, though) +Mod1+Shift+r restarts i3 in-place (at this time, you will lose your layout) Mod1+Shift+e exits i3 If you have any questions, please don't hesitate to ask! diff --git a/man/i3-input.man b/man/i3-input.man index b53406ff..29668027 100644 --- a/man/i3-input.man +++ b/man/i3-input.man @@ -1,11 +1,12 @@ i3-input(1) ========= + Michael Stapelberg v3.delta, November 2009 == NAME -i3-input - interactively take a command for i3 +i3-input - interactively take a command for i3 window manager == SYNOPSIS @@ -13,8 +14,9 @@ i3-input [-s ] [-p ] [-l ] [-P ] [-v] == DESCRIPTION -i3-input is a tool to take commands (or parts of a command) and then send it -to i3. This is useful for example for the mark/goto command. +i3-input is a tool to take commands (or parts of a command) composed by +the user, and send it/them to i3. This is useful, for example, for the +mark/goto command. == EXAMPLE diff --git a/man/i3-msg.man b/man/i3-msg.man index a2b17683..dedf7dc4 100644 --- a/man/i3-msg.man +++ b/man/i3-msg.man @@ -1,11 +1,12 @@ i3-msg(1) ========= + Michael Stapelberg v3.delta, November 2009 == NAME -i3-msg - send messages to i3 +i3-msg - send messages to i3 window manager == SYNOPSIS diff --git a/man/i3.man b/man/i3.man index dd3f6333..5877f143 100644 --- a/man/i3.man +++ b/man/i3.man @@ -132,7 +132,8 @@ support that, the window will be killed and it depends on the application what happens. Mod1+Shift+r:: -Restarts i3 in place (without losing any windows, but the layout). +Restarts i3 in place (without losing any windows, but at this time, the layout +and placement of windows is not retained). Mod1+Shift+e:: Exits i3. @@ -283,14 +284,15 @@ exec /usr/bin/i3 >> ~/.i3/logfile == TODO -There is still lot of work to do. Please check our bugtracker for up-to-date information -about tasks which are still not finished. +There is still lot of work to do. Please check our bugtracker for up-to-date +information about tasks which are still not finished. == SEE ALSO -You should have a copy of the userguide (featuring nice screenshots/graphics which is why this -is not integrated into this manpage), the debugging guide and the "how to hack" guide. If you -are building from source, run +make -C docs+. +You should have a copy of the userguide (featuring nice screenshots/graphics +which is why this is not integrated into this manpage), the debugging guide, +and the "how to hack" guide. If you are building from source, run: + +make -C docs+ You can also access these documents online at http://i3.zekjur.net/ -- 2.39.5