From f6ac7e334743f04fa3bbc7c1ad713762d4076c73 Mon Sep 17 00:00:00 2001 From: Michael Stapelberg Date: Wed, 30 Sep 2015 08:58:51 +0200 Subject: [PATCH] update docs for 4.11 --- _docs/debugging | 59 +++- _docs/hacking-howto | 56 ++-- _docs/ipc | 32 +- _docs/testsuite | 21 ++ _docs/userguide | 670 +++++++++++++++++++++++++++------------- docs/debugging.html | 92 +++++- docs/hacking-howto.html | 59 ++-- docs/ipc.html | 58 +++- docs/testsuite.html | 22 +- docs/userguide.html | 648 +++++++++++++++++++++++++++++--------- 10 files changed, 1286 insertions(+), 431 deletions(-) diff --git a/_docs/debugging b/_docs/debugging index dcc5497..873c6fb 100644 --- a/_docs/debugging +++ b/_docs/debugging @@ -10,10 +10,10 @@ Thank you for being interested in debugging i3. It really means something to us to get your bug fixed. If you have any questions about the process and/or need further help, do not hesitate to contact us! -== Verify you are using i3 ≥ 4.10.4 +== Verify you are using i3 ≥ 4.11 -Only the latest major version of i3 is supported, i.e. version 4.7 currently. -To verify which version you are running, use: +Only the latest major version of i3 is supported. To verify which version +you are running, use: --------------- $ i3 --moreversion 2>&- || i3 --version @@ -67,8 +67,44 @@ fly: i3-msg 'debuglog on; shmlog on; reload' --------------------------------------- +== Reproducing the problem + +Before submitting an issue, please make sure to close down on the problem as +much as you can yourself. Here are some steps you should consider: + +* Find a deterministic, reliable way to reproduce the problem and provide it + with your bug report. +* Try using the default i3 config to reproduce the problem. If the issue does + not appear with the default config, gradually adapt it to track down what + change(s) to the config introduce the problem. +* Reproduce the problem with a minimal setup, i.e., only use as few applications, + windows and steps as necessary. +* In addition, try to stick to applications that are common and, even more + importantly, free / open source. +* Before obtaining the log file, restart i3 in-place, execute the steps to + reproduce the problem and then save the logs. This keeps the log file as + small as possible and necessary. + +Please be aware that we cannot support compatibility issues with closed-source +software, as digging into compatibility problems without having access to the +source code is too time-consuming. Additionally, experience has shown that +often, the software in question is responsible for the issue. Please raise an +issue with the software in question, not i3. + == Obtaining the debug logfile +[CAUTION] +================================================================================ +Logs may contain sensitive information, so please inspect the log before +submitting it. Logs may be viewed by anyone, once posted. If you choose to +redact the log, make an effort not to discard information which may be relevant +to the issue you are reporting. + +The best way to avoid submitting such information is to only run the necessary +steps to reproduce the behavior when saving the log file. This will also make +analyzing the log file easier. +================================================================================ + No matter whether i3 misbehaved in some way without crashing or whether it just crashed, the logfile provides all information necessary to debug the problem. @@ -121,3 +157,20 @@ When debugging with us in IRC, be prepared to use a so called nopaste service 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. + +== Debugging i3bar + +To debug i3bar problems, add +verbose yes+ to all +bar {}+ blocks in your i3 +config, reload your config and then restart all i3bar instances like this: + +--------------------------------------------------------------------- +$ i3 reload +$ killall i3bar +$ for c in $(i3-msg -t get_bar_config | python -c \ + 'import json,sys;print("\n".join(json.load(sys.stdin)))'); do \ + (i3bar --bar_id=$c >i3bar.$c.log 2>&1) & \ + done; +--------------------------------------------------------------------- + +There will now be +i3bar.*.log+ files in your current directory that you can provide +in your bug report. diff --git a/_docs/hacking-howto b/_docs/hacking-howto index 12d6b14..d6e2b67 100644 --- a/_docs/hacking-howto +++ b/_docs/hacking-howto @@ -404,10 +404,14 @@ can reconfigure themselves). == _NET_WM_STATE -Only the _NET_WM_STATE_FULLSCREEN atom is handled. It calls -``toggle_fullscreen()'' for the specific client which just configures the -client to use the whole screen on which it currently is. Also, it is set as -fullscreen_client for the i3Screen. +Only the _NET_WM_STATE_FULLSCREEN and _NET_WM_STATE_DEMANDS_ATTENTION atoms +are handled. + +The former calls ``toggle_fullscreen()'' for the specific client which just +configures the client to use the whole screen on which it currently is. +Also, it is set as fullscreen_client for the i3Screen. + +The latter is used to set, read and display urgency hints. == WM_NAME @@ -629,8 +633,8 @@ unmapped if it should not be visible anymore. +WM_STATE+ will be set to +x_draw_decoration+ draws window decorations. It is run for every leaf container (representing an actual X11 window) and for every non-leaf container which is in a stacked/tabbed container (because stacked/tabbed containers -display a window decoration for split containers, which at the moment just says -"another container"). +display a window decoration for split containers, which consists of a representation +of the child container's names. Then, parameters are collected to be able to determine whether this decoration drawing is actually necessary or was already done. This saves a substantial @@ -686,9 +690,9 @@ all commands. In earlier versions of i3, interpreting these commands was done using lex and yacc, but experience has shown that lex and yacc are not well suited for our command language. Therefore, starting from version 4.2, we use a custom parser -for user commands (not yet for the configuration file). +for user commands and the configuration file. The input specification for this parser can be found in the file -+parser-specs/commands.spec+. Should you happen to use Vim as an editor, use ++parser-specs/*.spec+. Should you happen to use Vim as an editor, use :source parser-specs/highlighting.vim to get syntax highlighting for this file (highlighting files for other editors are welcome). @@ -729,11 +733,14 @@ features. This is its definition: # workspace next|prev|next_on_output|prev_on_output # workspace back_and_forth # workspace +# workspace number state WORKSPACE: direction = 'next_on_output', 'prev_on_output', 'next', 'prev' -> call cmd_workspace($direction) 'back_and_forth' -> call cmd_workspace_back_and_forth() + 'number' + -> WORKSPACE_NUMBER workspace = string -> call cmd_workspace_name($workspace) ---------------------------------------------------------------- @@ -772,6 +779,10 @@ workspace :: single quotes), but just called string. Other possible tokens are word (the same as string, but stops matching at a whitespace) and end (matches the end of the input). +workspace number :: + The workspace command has to be followed by the keyword +number+. It + then transitions into the state +WORKSPACE_NUMBER+, where the actual + parameter will be read. === Introducing a new command @@ -952,30 +963,35 @@ http://web.archive.org/web/20121024222556/http://www.spheredev.org/wiki/Git_for_ or, for more documentation, see http://git-scm.com/documentation Please talk to us before working on new features to see whether they will be -accepted. There are a few things which we don’t want to see in i3, e.g. a -command which will focus windows in an alt+tab like way. +accepted. A good way for this is to open an issue and asking for opinions on it. +Even for accepted features, this can be a good way to refine an idea upfront. However, +we don't want to see certain features in i3, e.g., switching window focus in an +Alt+Tab like way. When working on bugfixes, please make sure you mention that you are working on -it in the corresponding bugreport at https://github.com/i3/i3/issues In case -there is no bugreport yet, please create one. +it in the corresponding bug report at https://github.com/i3/i3/issues. In case +there is no bug report yet, please create one. -After you are done, please submit your work for review at https://github.com/i3/i3 +After you are done, please submit your work for review as a pull request at +https://github.com/i3/i3. Do not send emails to the mailing list or any author directly, and don’t submit them in the bugtracker, since all reviews should be done in public at -http://cr.i3wm.org/. In order to make your review go as fast as possible, you +https://github.com/i3/i3. In order to make your review go as fast as possible, you could have a look at previous reviews and see what the common mistakes are. === Which branch to use? -Work on i3 generally happens in two branches: “master” and “next”. Since -“master” is what people get when they check out the git repository, its -contents are always stable. That is, it contains the source code of the latest -release, plus any bugfixes that were applied since that release. +Work on i3 generally happens in two branches: “master” and “next” (the latter +being the default branch, the one that people get when they check out the git +repository). + +The contents of “master” are always stable. That is, it contains the source code +of the latest release, plus any bugfixes that were applied since that release. New features are only found in the “next” branch. Therefore, if you are working -on a new feature, use the “next” branch. If you are working on a bugfix, use -the “next” branch, too, but make sure your code also works on “master”. +on a new feature, use the “next” branch. If you are working on a bugfix, use the +“next” branch, too, but make sure your code also works on “master”. == Thought experiments diff --git a/_docs/ipc b/_docs/ipc index ff7c8aa..5113d79 100644 --- a/_docs/ipc +++ b/_docs/ipc @@ -520,21 +520,23 @@ statusline:: Text color to be used for the statusline. separator:: Text color to be used for the separator. -focused_workspace_text/focused_workspace_bg:: - Text color/background color for a workspace button when the workspace +focused_workspace_text/focused_workspace_bg/focused_workspace_border:: + Text/background/border color for a workspace button when the workspace has focus. -active_workspace_text/active_workspace_bg:: - Text color/background color for a workspace button when the workspace +active_workspace_text/active_workspace_bg/active_workspace_border:: + Text/background/border color for a workspace button when the workspace is active (visible) on some output, but the focus is on another one. You can only tell this apart from the focused workspace when you are using multiple monitors. -inactive_workspace_text/inactive_workspace_bg:: - Text color/background color for a workspace button when the workspace +inactive_workspace_text/inactive_workspace_bg/inactive_workspace_border:: + Text/background/border color for a workspace button when the workspace does not have focus and is not active (visible) on any output. This will be the case for most workspaces. -urgent_workspace_text/urgent_workspace_bar:: - Text color/background color for workspaces which contain at least one +urgent_workspace_text/urgent_workspace_bg/urgent_workspace_border:: + Text/background/border color for workspaces which contain at least one window with the urgency hint set. +binding_mode_text/binding_mode_bg/binding_mode_border:: + Text/background/border color for the binding mode indicator. *Example of configured bars:* @@ -580,11 +582,14 @@ human_readable (string):: build date and branch name. When you need to display the i3 version to your users, use the human-readable version whenever possible (since this is what +i3 --version+ displays, too). +loaded_config_file_name (string):: + The current config path. *Example:* ------------------- { "human_readable" : "4.2-169-gf80b877 (2012-08-05, branch \"next\")", + "loaded_config_file_name" : "/home/hwangcc23/.i3/config", "minor" : 2, "patch" : 0, "major" : 4 @@ -768,8 +773,8 @@ The +binding (object)+ field contains details about the binding that was run: command (string):: The i3 command that is configured to run for this binding. -mods (array of strings):: - The modifier keys that were configured with this binding. +event_state_mask (array of strings):: + The group and modifier keys that were configured with this binding. input_code (integer):: If the binding was configured with +bindcode+, this will be the key code that was given for the binding. If the binding is a mouse binding, it will be @@ -787,7 +792,7 @@ input_type (string):: "change": "run", "binding": { "command": "nop", - "mods": [ + "event_state_mask": [ "shift", "ctrl" ], @@ -822,4 +827,7 @@ Python:: * https://github.com/whitelynx/i3ipc (not maintained) * https://github.com/ziberna/i3-py (not maintained) Ruby:: - * http://github.com/badboy/i3-ipc + * https://github.com/veelenga/i3ipc-ruby + * https://github.com/badboy/i3-ipc (not maintained) +Rust:: + * https://github.com/tmerr/i3ipc-rs diff --git a/_docs/testsuite b/_docs/testsuite index 29a3521..8fdb963 100644 --- a/_docs/testsuite +++ b/_docs/testsuite @@ -160,6 +160,27 @@ $ ./complete-run.pl --parallel=1 --keep-xserver-output This will show the output of Xephyr, which is the X server implementation we use for testing. +==== Coverage testing + +Coverage testing is possible with +lcov+, the front-end for GCC's coverage +testing tool +gcov+. The testcases can generate a nice html report that tells +you which functions and lines were covered during a run of the tests. You can +use this tool to judge how effective your tests are. + +To use test coverage tools, first compile with coverage enabled. + +--------------------------------------------------- +COVERAGE=1 make +--------------------------------------------------- + +Then run the tests with the +--coverage-testing+ flag. + +--------------------------------------------------- +./complete-run.pl --coverage-testing +--------------------------------------------------- + +Then open +latest/i3-coverage/index.html+ in your web browser. + ==== IPC interface The testsuite makes extensive use of the IPC (Inter-Process Communication) diff --git a/_docs/userguide b/_docs/userguide index 820f539..13dae4f 100644 --- a/_docs/userguide +++ b/_docs/userguide @@ -23,6 +23,13 @@ image:keyboard-layer2.png["Keys to use with Shift+$mod",width=600,link="keyboard The red keys are the modifiers you need to press (by default), the blue keys are your homerow. +Note that when starting i3 without a config file, i3-config-wizard will offer +you to create a config file in which the key positions (!) match what you see +in the image above, regardless of the keyboard layout you are using. If you +prefer to use a config file where the key letters match what you are seeing +above, just decline i3-config-wizard’s offer and base your config on ++/etc/i3/config+. + == Using i3 Throughout this guide, the keyword +$mod+ will be used to refer to the @@ -256,8 +263,9 @@ workspace node’s orientation will be changed to +vertical+. The terminal windo you moved down is directly attached to the workspace and appears on the bottom of the screen. A new (horizontal) container was created to accommodate the other two terminal windows. You will notice this when switching to tabbed mode -(for example). You would end up having one tab called "another container" and -the other one being the terminal window you moved down. +(for example). You would end up having one tab with a representation of the split +container (e.g., "H[urxvt firefox]") and the other one being the terminal window +you moved down. [[configuring]] == Configuring i3 @@ -319,7 +327,7 @@ and fall back to a working font. *Syntax*: ------------------------------ font -font pango:[family list] [style options] [size] +font pango: [