Sync docs with i3 upstream (#133)

_docs/hacking-howto

@@ -28,9 +28,9 @@ https://mesonbuild.com/[The Meson Build system]; see
 https://mesonbuild.com/Quick-guide.html#compiling-a-meson-project[Quickstart
 Guide → Compiling a Meson project]. In case you’re unfamiliar:
 
-    $ mkdir -p build && cd build
-    $ meson ..
-    $ ninja
+    mkdir -p build
+    meson setup build
+    meson compile -C build
 
 === Build system features
 

_docs/i3bar-workspace-protocol

@@ -86,7 +86,7 @@ name (string)::
     the +name+ as you wish, effectively renaming the buttons of i3bar.
 visible (boolean)::
     Defaults to +false+ if not included. +focused+ takes precedence over it,
-    however +visible+ is important for more than one monitors.
+    however +visible+ is important for more than one monitor.
 focused (boolean)::
     Defaults to +false+ if not included. Generally, exactly one of the
     workspaces should be +focused+. If not, no button will have the
@@ -129,7 +129,7 @@ i3-msg -t subscribe -m '["workspace", "output"]' | {
     # avoids having an empty bar when starting up.
     i3-msg -t get_workspaces;
     # Then, while we receive events, update the workspace information.
-    while read; do i3-msg -t get_workspaces; done;
+    while read EVENT; do i3-msg -t get_workspaces; done;
 }
 ------------------------------
 
@@ -139,7 +139,7 @@ i3-msg -t subscribe -m '["workspace", "output"]' | {
 #!/bin/sh
 i3-msg -t subscribe -m '["workspace", "output"]' | {
     i3-msg -t get_workspaces;
-    while read; do i3-msg -t get_workspaces; done;
+    while read EVENT; do i3-msg -t get_workspaces; done;
 } | jq --unbuffered -c '[ .[] | select(.name != "foo" or .focused) ]'
 ------------------------------
 
@@ -153,7 +153,7 @@ might mean that you are getting an empty bar until enough events are written.
 #!/bin/sh
 i3-msg -t subscribe -m '["workspace", "output"]' | {
     i3-msg -t get_workspaces;
-    while read; do i3-msg -t get_workspaces; done;
+    while read EVENT; do i3-msg -t get_workspaces; done;
 } | jq --unbuffered -c '
     def fake_ws(name): {
         name: name,
@@ -169,7 +169,7 @@ i3-msg -t subscribe -m '["workspace", "output"]' | {
 #!/bin/sh
 i3-msg -t subscribe -m '["workspace", "output"]' | {
     i3-msg -t get_workspaces;
-    while read; do i3-msg -t get_workspaces; done;
+    while read EVENT; do i3-msg -t get_workspaces; done;
 } | jq --unbuffered -c 'sort_by(.name) | reverse'
 ------------------------------
 
@@ -179,6 +179,6 @@ i3-msg -t subscribe -m '["workspace", "output"]' | {
 #!/bin/sh
 i3-msg -t subscribe -m '["workspace", "output"]' | {
     i3-msg -t get_workspaces;
-    while read; do i3-msg -t get_workspaces; done;
+    while read EVENT; do i3-msg -t get_workspaces; done;
 } | jq --unbuffered -c '[ .[] | .name |= . + " foo" ]'
 ------------------------------

_docs/testsuite

@@ -76,30 +76,20 @@ used to install the testsuite. Many users prefer to use the more modern
 The tests additionally require +Xephyr(1)+ to run a nested X server. Install
 +xserver-xephyr+ on Debian or +xorg-server-xephyr+ on Arch Linux.
 
-.Installing testsuite dependencies using cpanminus (preferred)
+.Installing testsuite dependencies using cpanminus
 --------------------------------------------------------------------------------
-$ cd ~/i3/testcases
-$ sudo apt-get install cpanminus
-$ sudo cpanm .
+# Install testsuite system-level dependencies. Xvfb is optional but recommended.
+$ sudo apt-get install xcb-proto cpanminus xvfb xserver-xephyr
+# Install dependencies in ~/perl5 local library
+$ cpanm --local-lib=~/perl5 local::lib App::cpanminus Module::Install
+# Activate the local library
+$ eval $(perl -I ~/perl5/lib/perl5/ -Mlocal::lib)
+$ cd ~/i3/testcases/
+$ cpanm .
 $ cd ~/i3/AnyEvent-I3
-$ sudo cpanm Module::Install
-$ sudo cpanm .
+$ cpanm .
 --------------------------------------------------------------------------------
 
-If you don’t want to use cpanminus for some reason, the same works with cpan:
-
-.Installing testsuite dependencies using cpan
---------------------------------------------------------------------------------
-$ cd ~/i3/testcases
-$ sudo cpan .
-$ cd ~/i3/AnyEvent-I3
-$ sudo cpan Module::Install
-$ sudo cpan .
---------------------------------------------------------------------------------
-
-In case you don’t have root permissions, you can also install into your home
-directory, see https://michael.stapelberg.de/cpan/
-
 === Mechanisms
 
 ==== Script: complete-run
@@ -119,48 +109,57 @@ tests are run under Xvfb.
 ---------------------------------------
 $ cd ~/i3
 
-$ mkdir -p build && cd build
+$ mkdir -p build
 
-$ meson ..
+$ meson setup build
+$ cd build
 
-$ ninja
+$ meson compile
 # output omitted because it is very long
 
-$ cd testcases
-
 $ ./complete-run.pl
 # output omitted because it is very long
 All tests successful.
 Files=78, Tests=734, 27 wallclock secs ( 0.38 usr  0.48 sys + 17.65 cusr  3.21 csys = 21.72 CPU)
 Result: PASS
 
-$ ./complete-run.pl t/04-floating.t
-[:3] i3 startup: took 0.07s, status = 1
-[:3] Running t/04-floating.t with logfile testsuite-2011-09-24-16-06-04-4.0.2-226-g1eb011a/i3-log-for-04-floating.t
-[:3] t/04-floating.t finished
-[:3] killing i3
-output for t/04-floating.t:
-ok 1 - use X11::XCB::Window;
-ok 2 - The object isa X11::XCB::Window
-ok 3 - Window is mapped
-ok 4 - i3 raised the width to 75
-ok 5 - i3 raised the height to 50
-ok 6 - i3 did not map it to (0x0)
-ok 7 - The object isa X11::XCB::Window
-ok 8 - i3 let the width at 80
-ok 9 - i3 let the height at 90
-ok 10 - i3 mapped it to x=1
-ok 11 - i3 mapped it to y=18
-ok 12 - The object isa X11::XCB::Window
-ok 13 - i3 let the width at 80
-ok 14 - i3 let the height at 90
-1..14
+$ ./complete-run.pl t/005-floating.t
+Running tests under Xvfb display :99
+Starting 1 Xephyr instances, starting at :100...
+
+Rough time estimate for this run: 9.65 seconds
+
+Writing logfile to 'testsuite-2024-05-01-21-33-45-4.23-28-g5834b7e8/complete-run.log'...
+[:100] i3/testcases/t/005-floating.t: finished
+completed 0 of 1 tests
 
 All tests successful.
-Files=1, Tests=14,  0 wallclock secs ( 0.01 usr  0.00 sys +  0.19 cusr  0.03 csys =  0.23 CPU)
+Files=1, Tests=13,  0 wallclock secs ( 0.00 usr +  0.00 sys =  0.00 CPU)
 Result: PASS
 
-$ less latest/i3-log-for-04-floating.t
+The slowest tests are:
+	i3/testcases/t/005-floating.t with 0.07 seconds
+
+Test output:
+[:100] i3/testcases/t/005-floating.t: starting
+[:100] i3/testcases/t/005-floating.t: finished
+output for i3/testcases/t/005-floating.t:
+ok 1 - An object of class 'X11::XCB::Window' isa 'X11::XCB::Window'
+ok 2 - Window is mapped
+ok 3 - i3 raised the width to 75
+ok 4 - i3 raised the height to 50
+ok 5 - i3 did not map it to (0x0)
+ok 6 - An object of class 'X11::XCB::Window' isa 'X11::XCB::Window'
+ok 7 - i3 let the width at 80
+ok 8 - i3 let the height at 90
+ok 9 - i3 mapped it to x=20
+ok 10 - i3 mapped it to y=20
+ok 11 - An object of class 'X11::XCB::Window' isa 'X11::XCB::Window'
+ok 12 - i3 let the width at 80
+ok 13 - i3 let the height at 90
+1..13
+
+$ less latest/i3-log-for-005-floating.t
 ----------------------------------------
 
 If your attempt to run the tests with a bare call to ./complete-run.pl fails, try this:
@@ -172,37 +171,34 @@ $ ./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.
 
-===== make command: +make check+
-Make check runs the i3 testsuite.
-You can still use ./testcases/complete-run.pl to get the interactive progress output.
+===== ninja command: +ninja test+
++ninja test+ runs the i3 testsuite.
+You can still use ./complete-run.pl to get the interactive progress output.
 
-.Example invocation of +make check+
+.Example invocation of +ninja test+
 ---------------------------------------
 $ cd ~/i3
 
-$ mkdir -p build && cd build
+$ mkdir -p build
 
-$ meson ..
+$ meson setup build
+$ cd build
 
-$ ninja
-# output omitted because it is very long
+$ ninja test
+[1/102] Generating config.h with a custom command
+[1/2] Running all tests.
+1/1 complete-run OK              34.39s
 
-$ make check
-# output omitted because it is very long
-PASS: testcases/complete-run.pl
-============================================================================
-Testsuite summary for i3 4.13
-============================================================================
-# TOTAL: 1
-# PASS:  1
-# SKIP:  0
-# XFAIL: 0
-# FAIL:  0
-# XPASS: 0
-# ERROR: 0
-============================================================================
-
-$ less test-suite.log
+Ok:                 1
+Expected Fail:      0
+Fail:               0
+Unexpected Pass:    0
+Skipped:            0
+Timeout:            0
+
+Full log written to i3/build/meson-logs/testlog.txt
+
+$ less latest/complete-run.log
 ----------------------------------------
 
 ==== Coverage testing

_docs/userguide

@@ -743,8 +743,11 @@ This option determines which border style *new* windows will have.  The default
 +normal+. Note that default_floating_border applies only to windows which are starting out as
 floating windows, e.g., dialog windows, but not windows that are floated later on.
 
-Setting border style to +pixel+ eliminates title bars. The border style +normal+ allows you to
-adjust edge border width while keeping your title bar.
+Setting border style to +pixel+ eliminates title bars in split layouts. The border style
++normal+ allows you to adjust edge border width while keeping your title bar.
+
+The title bar is always visible in stacking and tabbed layouts, and this cannot be changed
+through configuration.
 
 *Syntax*:
 ---------------------------------------------
@@ -789,35 +792,18 @@ The "smart_no_gaps" setting hides edge-specific borders of a container if the
 container is the only container on its workspace and the gaps to the screen edge
 are +0+.
 
-*Syntax*:
------------------------------------------------
-hide_edge_borders none|vertical|horizontal|both|smart|smart_no_gaps
------------------------------------------------
-
-*Example*:
-----------------------
-hide_edge_borders vertical
-----------------------
-
 [[_smart_borders]]
-=== Smart borders
-
-Smart borders will draw borders on windows only if there is more than one window
-in a workspace. This feature can also be enabled only if the gap size between
-window and screen edge is +0+.
++hide_edge_borders+ has replaced the old +smart_borders+ syntax. Use the former
+instead of the latter.
 
 *Syntax*:
 -----------------------------------------------
-smart_borders on|off|no_gaps
+hide_edge_borders none|vertical|horizontal|both|smart|smart_no_gaps
 -----------------------------------------------
 
 *Example*:
 ----------------------
-# Activate smart borders (always)
-smart_borders on
-
-# Activate smart borders (only when there are effectively no gaps)
-smart_borders no_gaps
+hide_edge_borders vertical
 ----------------------
 
 [[for_window]]

docs/hacking-howto.html

@@ -66,9 +66,9 @@ <h2 id="_building_i3">1. Building i3</h2>
 Guide → Compiling a Meson project</a>. In case you’re unfamiliar:</p></div>
 <div class="literalblock">
 <div class="content">
-<pre><tt>$ mkdir -p build &amp;&amp; cd build
-$ meson ..
-$ ninja</tt></pre>
+<pre><tt>mkdir -p build
+meson setup build
+meson compile -C build</tt></pre>
 </div></div>
 <div class="sect2">
 <h3 id="_build_system_features">1.1. Build system features</h3>

docs/i3bar-workspace-protocol.html

@@ -138,7 +138,7 @@ <h3 id="_workspace_objects_in_detail">1.1. Workspace objects in detail</h3>
 <dd>
 <p>
     Defaults to <tt>false</tt> if not included. <tt>focused</tt> takes precedence over it,
-    however <tt>visible</tt> is important for more than one monitors.
+    however <tt>visible</tt> is important for more than one monitor.
 </p>
 </dd>
 <dt class="hdlist1">
@@ -211,7 +211,7 @@ <h3 id="_re_create_the_default_behaviour_of_i3bar">2.2. Re-create the default be
     # avoids having an empty bar when starting up.
     i3-msg -t get_workspaces;
     # Then, while we receive events, update the workspace information.
-    while read; do i3-msg -t get_workspaces; done;
+    while read EVENT; do i3-msg -t get_workspaces; done;
 }</tt></pre>
 </div></div>
 </div>
@@ -222,7 +222,7 @@ <h3 id="_hide_workspace_named_tt_foo_tt_unless_if_it_is_focused">2.3. Hide works
 <pre><tt>#!/bin/sh
 i3-msg -t subscribe -m '["workspace", "output"]' | {
     i3-msg -t get_workspaces;
-    while read; do i3-msg -t get_workspaces; done;
+    while read EVENT; do i3-msg -t get_workspaces; done;
 } | jq --unbuffered -c '[ .[] | select(.name != "foo" or .focused) ]'</tt></pre>
 </div></div>
 <div class="paragraph"><p>Important! Make sure you use the <tt>--unbuffered</tt> flag with <tt>jq</tt>, otherwise you
@@ -236,7 +236,7 @@ <h3 id="_show_empty_workspaces_tt_foo_tt_and_tt_bar_tt_on_lvds1_even_if_they_do_
 <pre><tt>#!/bin/sh
 i3-msg -t subscribe -m '["workspace", "output"]' | {
     i3-msg -t get_workspaces;
-    while read; do i3-msg -t get_workspaces; done;
+    while read EVENT; do i3-msg -t get_workspaces; done;
 } | jq --unbuffered -c '
     def fake_ws(name): {
         name: name,
@@ -253,7 +253,7 @@ <h3 id="_sort_workspaces_in_reverse_alphanumeric_order">2.5. Sort workspaces in
 <pre><tt>#!/bin/sh
 i3-msg -t subscribe -m '["workspace", "output"]' | {
     i3-msg -t get_workspaces;
-    while read; do i3-msg -t get_workspaces; done;
+    while read EVENT; do i3-msg -t get_workspaces; done;
 } | jq --unbuffered -c 'sort_by(.name) | reverse'</tt></pre>
 </div></div>
 </div>
@@ -264,7 +264,7 @@ <h3 id="_append_foo_to_the_name_of_each_workspace">2.6. Append "foo" to the name
 <pre><tt>#!/bin/sh
 i3-msg -t subscribe -m '["workspace", "output"]' | {
     i3-msg -t get_workspaces;
-    while read; do i3-msg -t get_workspaces; done;
+    while read EVENT; do i3-msg -t get_workspaces; done;
 } | jq --unbuffered -c '[ .[] | .name |= . + " foo" ]'</tt></pre>
 </div></div>
 </div>