update docs for 4.24

_docs/debugging

@@ -10,7 +10,7 @@ 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.23
+== Verify you are using i3 ≥ 4.24
 
 Only the latest major version of i3 is supported. To verify which version
 you are running, use:

_docs/ipc

@@ -10,15 +10,22 @@ workspace bar.
 
 The method of choice for IPC in our case is a unix socket because it has very
 little overhead on both sides and is usually available without headaches in
-most languages. In the default configuration file, the ipc-socket gets created
-in +/tmp/i3-%u.XXXXXX/ipc-socket.%p+ where +%u+ is your UNIX username, +%p+ is
-the PID of i3 and XXXXXX is a string of random characters from the portable
-filename character set (see mkdtemp(3)). You can get the socketpath from i3 by
-executing +i3 --get-socketpath+, which will print the path to the standard
-output (plus a newline).
+most languages.
+By default i3 will set the path of the IPC socket based on:
 
-All i3 utilities, like +i3-msg+ and +i3-input+ will read the +I3_SOCKET_PATH+
-X11 property, stored on the X11 root window.
+1. The +ipc-socket+ configuration directive if it is used
+2. The +I3SOCK+ environmental variable if it is set
+3. +$XDG_RUNTIME_DIR/i3/ipc-socket.%p+ if the directory is available where +%p+
+   is the PID of i3 and XXXXXX is a string of random characters
+4. +/tmp/i3-%u.XXXXXX/ipc-socket.%p+ where +%u+ is your UNIX username
+
+You can get the socketpath from i3 by executing +i3 --get-socketpath+, which
+will print the path to the standard output (plus a newline) or by reading the
++I3SOCK+ environmental variable.
+
+All i3 utilities, like +i3-msg+ and +i3-input+ will determine the path of the
+IPC socket frome the +I3SOCK+ environmental variable if it is set or the
++I3_SOCKET_PATH+ X11 property, stored on the X11 root window.
 
 [WARNING]
 .Use an existing library!
@@ -997,9 +1004,18 @@ if ($is_event) {
 === workspace event
 
 This event consists of a single serialized map containing a property
-+change (string)+ which indicates the type of the change ("focus", "init",
-"empty", "urgent", "reload", "rename", "restored", "move"). A
-+current (object)+ property will be present with the affected workspace
++change (string)+ which indicates the type of the change.
+
+* +empty+ – the workspace has become empty
+* +focus+ – the workspace has received input focus
+* +init+ – the workspace has been created
+* +move+ – the workspace has been moved to a different output
+* +reload+ – i3 config has been reloaded
+* +rename+ – the workspace's name has changed
+* +restored+ – the workspace's layout has changed to a previously saved layout
+* +urgent+ – the workspace has become urgent or lost its urgent status  
+
+A +current (object)+ property will be present with the affected workspace
 whenever the type of event affects a workspace (otherwise, it will be +null+).
 
 When the change is "focus", an +old (object)+ property will be present with the

_docs/userguide

@@ -216,6 +216,10 @@ Drop on container::
     This happens when the mouse is relatively near the center of a container.
     If the mouse is released, the result is exactly as if you had run the
     +move container to mark+ command. See <<move_to_mark>>.
+    If the swap modifier is pressed before initiating the drag (+tiling_drag
+    swap_modifier+ set to Shift by default), the containers are swapped
+    instead. In that case, the result is exactly as if you had run the +swap
+    container with mark+ command. See <<swapping_containers>>.
 Drop as sibling::
     This happens when the mouse is relatively near the edge of a container. If
     the mouse is released, the dragged container will become a sibling of the
@@ -354,15 +358,6 @@ keyboard layout. To start the wizard, use the command +i3-config-wizard+.
 Please note that you must not have +~/.i3/config+, otherwise the wizard will
 exit.
 
-Since i3 4.0, a new configuration format is used. i3 will try to automatically
-detect the format version of a config file based on a few different keywords,
-but if you want to make sure that your config is read with the new format,
-include the following line in your config file:
-
----------------------
-# i3 config file (v4)
----------------------
-
 [[include]]
 === Include directive
 
@@ -512,8 +507,8 @@ 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.
 
-Some tools (such as +import+ or +xdotool+) might be unable to run upon a
-KeyPress event, because the keyboard/pointer is still grabbed. For these
+Some tools (such as +xdotool+) might be unable to run upon a
+KeyPress event, because the keyboard is still grabbed. For these
 situations, the +--release+ flag can be used, which will execute the command
 after the keys have been released.
 
@@ -1229,19 +1224,21 @@ mouse_warping none
 When you are in fullscreen mode, some applications still open popup windows
 (take Xpdf for example). This is because these applications might not be aware
 that they are in fullscreen mode (they do not check the corresponding hint).
-There are three things which are possible to do in this situation:
+i3 supports four options for this situation:
 
-1. Display the popup if it belongs to the fullscreen application only. This is
-   the default and should be reasonable behavior for most users.
-2. Just ignore the popup (don’t map it). This won’t interrupt you while you are
-   in fullscreen. However, some apps might react badly to this (deadlock until
-   you go out of fullscreen).
-3. Leave fullscreen mode.
+1. +smart+: Display the popup if it belongs to the fullscreen application only.
+   This is the default and should be reasonable behavior for most users.
+2. +ignore+: Just ignore the popup (don’t map it). This won’t interrupt you
+   while you are in fullscreen. However, some apps might react badly to this
+   (deadlock until you go out of fullscreen).
+3. +leave_fullscreen+: Leave fullscreen mode.
+4. +all+: Since i3 4.24: Display all floating windows regardless to which
+   application they belong to.
 
 *Syntax*:
------------------------------------------------------
-popup_during_fullscreen smart|ignore|leave_fullscreen
------------------------------------------------------
+---------------------------------------------------------
+popup_during_fullscreen smart|ignore|leave_fullscreen|all
+---------------------------------------------------------
 
 *Example*:
 ------------------------------
@@ -1427,10 +1424,16 @@ You can configure how to initiate the tiling drag feature (see <<tiling_drag>>).
 
 The default is +modifier+.
 
+Since i3 4.24, you can configure a modifier key which, when pressed, will swap
+instead of moving containers when dropping directly onto another container.
+Defaults to +Shift+. Note that you have to be pressing both the floating
+modifer and the swap modifier before the drag is initiated.
+
 *Syntax*:
 --------------------------------
 tiling_drag off
 tiling_drag modifier|titlebar [modifier|titlebar]
+tiling_drag swap_modifier <modifier>
 --------------------------------
 
 *Examples*:
@@ -1443,6 +1446,14 @@ tiling_drag modifier titlebar
 
 # Disable tiling drag altogether
 tiling_drag off
+
+# Use Control to swap containers
+tiling_drag swap_modifier Control
+
+# Setting the swap_modifier to be the same key as the floating modifier will
+# always swap without the need to hold two keys
+floating_modifier Mod4
+tiling_drag swap_modifier Mod4
 --------------------------------
 
 [[gaps]]
@@ -2472,7 +2483,7 @@ bindsym $mod+u focus parent
 bindsym $mod+g focus mode_toggle
 
 # Focus the next output (effectively toggles when you only have two outputs)
-bindsym $mod+x move workspace to output next
+bindsym $mod+x focus output next
 
 # Focus the output right to the current one
 bindsym $mod+x focus output right
@@ -2544,6 +2555,7 @@ bindsym $mod+c move absolute position center
 bindsym $mod+m move position mouse
 -------------------------------------------------------
 
+[[swapping_containers]]
 === Swapping containers
 
 Two containers can be swapped (i.e., move to each other's position) by using

docs/debugging.html

@@ -3,7 +3,7 @@
 <head>
 <link rel="icon" href="/favicon.ico">
 <meta name="viewport" content="width=device-width, initial-scale=1">
-<meta name="generator" content="AsciiDoc 10.2.0" />
+<meta name="generator" content="AsciiDoc 10.2.1" />
 <title>i3: Debugging i3: How To</title>
 <link rel="stylesheet" href="/css/style.css" type="text/css" />
 <link rel="stylesheet" href="/css/xhtml11.css" type="text/css" />
@@ -47,7 +47,7 @@ <h1>Debugging i3: How To</h1>
 </div>
 </div>
 <div class="sect1">
-<h2 id="_verify_you_are_using_i3_4_23">1. Verify you are using i3 ≥ 4.23</h2>
+<h2 id="_verify_you_are_using_i3_4_24">1. Verify you are using i3 ≥ 4.24</h2>
 <div class="sectionbody">
 <div class="paragraph"><p>Only the latest major version of i3 is supported. To verify which version
 you are running, use:</p></div>

docs/hacking-howto.html

@@ -3,7 +3,7 @@
 <head>
 <link rel="icon" href="/favicon.ico">
 <meta name="viewport" content="width=device-width, initial-scale=1">
-<meta name="generator" content="AsciiDoc 10.2.0" />
+<meta name="generator" content="AsciiDoc 10.2.1" />
 <title>i3: Hacking i3: How To</title>
 <link rel="stylesheet" href="/css/style.css" type="text/css" />
 <link rel="stylesheet" href="/css/xhtml11.css" type="text/css" />

docs/i3bar-protocol.html

@@ -3,7 +3,7 @@
 <head>
 <link rel="icon" href="/favicon.ico">
 <meta name="viewport" content="width=device-width, initial-scale=1">
-<meta name="generator" content="AsciiDoc 10.2.0" />
+<meta name="generator" content="AsciiDoc 10.2.1" />
 <title>i3: i3bar input protocol</title>
 <link rel="stylesheet" href="/css/style.css" type="text/css" />
 <link rel="stylesheet" href="/css/xhtml11.css" type="text/css" />

docs/i3bar-workspace-protocol.html

@@ -3,7 +3,7 @@
 <head>
 <link rel="icon" href="/favicon.ico">
 <meta name="viewport" content="width=device-width, initial-scale=1">
-<meta name="generator" content="AsciiDoc 10.2.0" />
+<meta name="generator" content="AsciiDoc 10.2.1" />
 <title>i3: i3bar workspace buttons protocol</title>
 <link rel="stylesheet" href="/css/style.css" type="text/css" />
 <link rel="stylesheet" href="/css/xhtml11.css" type="text/css" />

docs/ipc.html

@@ -3,7 +3,7 @@
 <head>
 <link rel="icon" href="/favicon.ico">
 <meta name="viewport" content="width=device-width, initial-scale=1">
-<meta name="generator" content="AsciiDoc 10.2.0" />
+<meta name="generator" content="AsciiDoc 10.2.1" />
 <title>i3: IPC interface (interprocess communication)</title>
 <link rel="stylesheet" href="/css/style.css" type="text/css" />
 <link rel="stylesheet" href="/css/xhtml11.css" type="text/css" />
@@ -49,14 +49,37 @@ <h1>IPC interface (interprocess communication)</h1>
 workspace bar.</p></div>
 <div class="paragraph"><p>The method of choice for IPC in our case is a unix socket because it has very
 little overhead on both sides and is usually available without headaches in
-most languages. In the default configuration file, the ipc-socket gets created
-in <tt>/tmp/i3-%u.XXXXXX/ipc-socket.%p</tt> where <tt>%u</tt> is your UNIX username, <tt>%p</tt> is
-the PID of i3 and XXXXXX is a string of random characters from the portable
-filename character set (see mkdtemp(3)). You can get the socketpath from i3 by
-executing <tt>i3 --get-socketpath</tt>, which will print the path to the standard
-output (plus a newline).</p></div>
-<div class="paragraph"><p>All i3 utilities, like <tt>i3-msg</tt> and <tt>i3-input</tt> will read the <tt>I3_SOCKET_PATH</tt>
-X11 property, stored on the X11 root window.</p></div>
+most languages.
+By default i3 will set the path of the IPC socket based on:</p></div>
+<div class="olist arabic"><ol class="arabic">
+<li>
+<p>
+The <tt>ipc-socket</tt> configuration directive if it is used
+</p>
+</li>
+<li>
+<p>
+The <tt>I3SOCK</tt> environmental variable if it is set
+</p>
+</li>
+<li>
+<p>
+<tt>$XDG_RUNTIME_DIR/i3/ipc-socket.%p</tt> if the directory is available where <tt>%p</tt>
+   is the PID of i3 and XXXXXX is a string of random characters
+</p>
+</li>
+<li>
+<p>
+<tt>/tmp/i3-%u.XXXXXX/ipc-socket.%p</tt> where <tt>%u</tt> is your UNIX username
+</p>
+</li>
+</ol></div>
+<div class="paragraph"><p>You can get the socketpath from i3 by executing <tt>i3 --get-socketpath</tt>, which
+will print the path to the standard output (plus a newline) or by reading the
+<tt>I3SOCK</tt> environmental variable.</p></div>
+<div class="paragraph"><p>All i3 utilities, like <tt>i3-msg</tt> and <tt>i3-input</tt> will determine the path of the
+IPC socket frome the <tt>I3SOCK</tt> environmental variable if it is set or the
+<tt>I3_SOCKET_PATH</tt> X11 property, stored on the X11 root window.</p></div>
 <div class="admonitionblock">
 <table><tr>
 <td class="icon">
@@ -1673,9 +1696,50 @@ <h3 id="_available_events">5.2. Available events</h3>
 <div class="sect2">
 <h3 id="_workspace_event">5.3. workspace event</h3>
 <div class="paragraph"><p>This event consists of a single serialized map containing a property
-<tt>change (string)</tt> which indicates the type of the change ("focus", "init",
-"empty", "urgent", "reload", "rename", "restored", "move"). A
-<tt>current (object)</tt> property will be present with the affected workspace
+<tt>change (string)</tt> which indicates the type of the change.</p></div>
+<div class="ulist"><ul>
+<li>
+<p>
+<tt>empty</tt> – the workspace has become empty
+</p>
+</li>
+<li>
+<p>
+<tt>focus</tt> – the workspace has received input focus
+</p>
+</li>
+<li>
+<p>
+<tt>init</tt> – the workspace has been created
+</p>
+</li>
+<li>
+<p>
+<tt>move</tt> – the workspace has been moved to a different output
+</p>
+</li>
+<li>
+<p>
+<tt>reload</tt> – i3 config has been reloaded
+</p>
+</li>
+<li>
+<p>
+<tt>rename</tt> – the workspace&#8217;s name has changed
+</p>
+</li>
+<li>
+<p>
+<tt>restored</tt> – the workspace&#8217;s layout has changed to a previously saved layout
+</p>
+</li>
+<li>
+<p>
+<tt>urgent</tt> – the workspace has become urgent or lost its urgent status
+</p>
+</li>
+</ul></div>
+<div class="paragraph"><p>A <tt>current (object)</tt> property will be present with the affected workspace
 whenever the type of event affects a workspace (otherwise, it will be <tt>null</tt>).</p></div>
 <div class="paragraph"><p>When the change is "focus", an <tt>old (object)</tt> property will be present with the
 previous workspace.  When the first switch occurs (when i3 focuses the

docs/layout-saving.html

@@ -3,7 +3,7 @@
 <head>
 <link rel="icon" href="/favicon.ico">
 <meta name="viewport" content="width=device-width, initial-scale=1">
-<meta name="generator" content="AsciiDoc 10.2.0" />
+<meta name="generator" content="AsciiDoc 10.2.1" />
 <title>i3: Layout saving in i3</title>
 <link rel="stylesheet" href="/css/style.css" type="text/css" />
 <link rel="stylesheet" href="/css/xhtml11.css" type="text/css" />

docs/multi-monitor.html

@@ -3,7 +3,7 @@
 <head>
 <link rel="icon" href="/favicon.ico">
 <meta name="viewport" content="width=device-width, initial-scale=1">
-<meta name="generator" content="AsciiDoc 10.2.0" />
+<meta name="generator" content="AsciiDoc 10.2.1" />
 <title>i3: The multi-monitor situation</title>
 <link rel="stylesheet" href="/css/style.css" type="text/css" />
 <link rel="stylesheet" href="/css/xhtml11.css" type="text/css" />

docs/testsuite.html

@@ -3,7 +3,7 @@
 <head>
 <link rel="icon" href="/favicon.ico">
 <meta name="viewport" content="width=device-width, initial-scale=1">
-<meta name="generator" content="AsciiDoc 10.2.0" />
+<meta name="generator" content="AsciiDoc 10.2.1" />
 <title>i3: i3 testsuite</title>
 <link rel="stylesheet" href="/css/style.css" type="text/css" />
 <link rel="stylesheet" href="/css/xhtml11.css" type="text/css" />