Spatial Shell Call for Testers

6 files changed, 212 insertions, 1 deletions

diff --git a/.gitignore b/.gitignore
index 1e56470..700dcba 100644
--- a/.gitignore
+++ b/.gitignore
@@ -15,6 +15,7 @@ _opam
 logs/coqffi-tutorial.stderr
 logs/site--index.html.stderr
 logs/site--news--August2022.html.stderr
+logs/site--news--CFTSpatialShell.html.stderr
 logs/site--news--ColorlessThemes-0.2.html.stderr
 logs/site--news--MonthlyRetrospectives.html.stderr
 logs/site--news--November2022.html.stderr
@@ -53,6 +54,7 @@ logs/tangling-lp.stderr
 logs/coqffi-tutorial.stdout
 logs/site--index.html.stdout
 logs/site--news--August2022.html.stdout
+logs/site--news--CFTSpatialShell.html.stdout
 logs/site--news--ColorlessThemes-0.2.html.stdout
 logs/site--news--MonthlyRetrospectives.html.stdout
 logs/site--news--November2022.html.stdout
@@ -96,6 +98,7 @@ rss.json
 site/files/coqffi-tutorial.tar.gz
 site/index.html
 site/news/August2022.html
+site/news/CFTSpatialShell.html
 site/news/ColorlessThemes-0.2.html
 site/news/MonthlyRetrospectives.html
 site/news/November2022.html
diff --git a/site/img/spatial-shell-example.png b/site/img/spatial-shell-example.png
new file mode 100644
index 0000000..4e03e10
--- /dev/null
+++ b/site/img/spatial-shell-example.png
diff --git a/site/img/spatial-shell.png b/site/img/spatial-shell.png
new file mode 100644
index 0000000..cb348c2
--- /dev/null
+++ b/site/img/spatial-shell.png
diff --git a/site/index.org b/site/index.org
index 5df05ff..08b950d 100644
--- a/site/index.org
+++ b/site/index.org
@@ -31,5 +31,5 @@ let me know!].
   - [[https://github.com/coq-community/coqffi][~coqffi~]] is a tool that generates the necessary boilerplate to use
     OCaml functions in a Coq development, and configure the Coq
     extraction mechanism accordingly.
-  - [[https://github.com/lthms/spatial-sway][Spatial Sway]] is a daemon that enables a dynamic tiling management
+  - [[https://github.com/lthms/spatial-shell][Spatial Shell]] is a daemon that enables a dynamic tiling management
     workflow a la Material Shell and PaperWM.
diff --git a/site/news/CFTSpatialShell.org b/site/news/CFTSpatialShell.org
new file mode 100644
index 0000000..e713671
--- /dev/null
+++ b/site/news/CFTSpatialShell.org
@@ -0,0 +1,193 @@
+#+TITLE: Call For Testers: Spatial Shell
+
+In August, 2022, I discovered [[https://material-shell.com][Material Shell]]. A
+few weeks later, I had pieced together a working prototype of a dynamic tiling
+management “a la Material Shell” for [[https://swaywm.org][sway]]. By October,
+the project was basically fulfilling my main needs, and I had already started
+to use it on my workstation[fn::I tried so you do not have to: having my
+graphical session going crazy during a work meeting because of a software I had
+written.]. The project sat there for a while, until I rediscovered this thing
+called /holidays/.
+
+For a short week, I tried to address at many of the remaining issues and
+missing features that I was aware of. Then, I started to write
+[[https://lthms.github.io/spatial-shell/spatial.1.html][man pages]], which
+turned out to be the perfect opportunity to clean-up every clunkiness I could
+possibly found.
+
+I can’t help but finding the result rather nice, and I hope you will enjoy it
+too! [[https://github.com/lthms/spatial-shell][Spatial Shell]] works on my
+machine, which means it will definitely break on yours. But this is where the
+fun lies, right? At this point, I definitely think the project is ready to fall
+in the hands of (motivated) alpha testers.
+
+#+BEGIN_EXPORT html
+<nav id="generate-toc"></nav>
+<div id="history">site/news/CFTSpatialShell.org</div>
+#+END_EXPORT
+
+It would be fair to say that Spatial Shell does not bring any novel ideas to
+the table (neither from a user perspective, nor a developer one). Hopefully, it
+does implement well established ideas in a nice and reliable way, so sway users
+can enjoy Material Shell key ideas without having to install GNOME 3.
+
+Anyway, let me give a tour!
+
+* Spatial Model
+
+At its core, Spatial Shell allows you to navigate a gride of windows, wherein
+each workspace is a row. Each workspace can be configured to determine how many
+windows (cells) you can see at once. More precisely, Spatial Shell supports two
+layouts:
+
+- *Maximize:* One window is displayed at a time
+- *Column:* Several windows are displayed side by side, to your convenience
+
+The reason why *Maximize* is not a particular case of *Column*, but instead a
+layout on its own, is to easily allow you to switch to and back from maximizing
+the focused window. The following picture[fn::Created using
+[[https://excalidraw.com/][Excalidraw]].] summarizes one particular setup with
+tree workspaces, each configured differently.
+
+#+CAPTION: Spatial Shell allows users to configure the layout of each workspace individually.
+#+NAME:    fig:spatial-shell-example
+[[../img/spatial-shell-example.png]]
+
+- Workspace 1 contains three windows, and is configured to use the *Column*
+  layout to display at most three windows, so every windows are visible, with
+  the focus being on the leftmost one.
+- Workspace 2 contains four windows, and is configured to use the *Column*
+  layout to display at most two windows. As a consequence, two windows are not
+  visible.
+- Workspace 3 contains two windows, and is configured to use the *Maximize*
+  layout so only the focused window is visible.
+
+To help users know which window is currently holding the focus, Spatial Shell
+slightly reduces the opacity of unfocused windows (as poorly hinted by the gray
+backgrounds in the figure). Finally, Spatial Shell can also set a background
+for empty workspaces (using ~swaybg~ under the hood).
+
+And this is basically it. There is not much more to say about Spatial Shell
+features.
+
+* Configuration
+
+From an implementation and user experience perspective, Spatial Shell is taking
+inspiration from i3 and sway.
+
+More precisely, Spatial Shell comprises two executables:
+
+- [[https://lthms.github.io/spatial-shell/spatial.1.html][spatial(1)]], the
+  daemon implementing the spatial model described in the previous section, and
+- [[https://lthms.github.io/spatial-shell/spatialmsg.1.html][spatialmsg(1)]], a
+  client used to control the current instance of spatial.
+
+Assuming ~$spatial~ and ~$spatialmsg~ contains the pathes to spatial and
+spatialmsg binaries respectively, then the simplest sway configuration to start
+using Spatial Shell is the following
+
+#+begin_src
+exec $spatial
+
+# moving the focus
+bindsym $mod+h exec $spatialmsg "focus left"
+bindsym $mod+l exec $spatialmsg "focus right"
+bindsym $mod+k exec $spatialmsg "focus up"
+bindsym $mod+j exec $spatialmsg "focus down"
+
+# moving the focused window
+bindsym $mod+Shift+h exec $spatialmsg "move left"
+bindsym $mod+Shift+l exec $spatialmsg "move right"
+bindsym $mod+Shift+k exec $spatialmsg "move up"
+bindsym $mod+Shift+j exec $spatialmsg "move down"
+
+# toggle between Maximize and Column layout
+bindsym $mod+space exec $spatialmsg "toggle layout"
+
+# modify the number of windows to display in the Column layout
+bindsym $mod+i exec $spatialmsg "column count decrement"
+bindsym $mod+o exec $spatialmsg "column count increment"
+#+end_src
+
+By default, Spatial Shell sets the initial configuration of a workspace to
+the Column layout with two columns at most, and sets the opacity of the
+unfocused windows to 75%. This can be customized, either globally or per
+workspace, by creating a configuration file in
+~$XDR_RUNTIME_DIR/spatial/config~[fn::If unset, ~XDG_RUNTIME_DIR~ defaults to
+~$HOME/.config~.].
+
+For instance, my config file looks like that.
+
+#+begin_src
+[workspace=3] default layout maximize
+background "~/.config/spatial/wallpaper.jpg"
+unfocus opacity 85
+#+end_src
+
+See [[https://lthms.github.io/spatial-shell/spatial.5.html][spatial(5)]] for
+the list of commands supported by Spatial Shell.
+
+As a sidenote, readers familiar with sway will definetely pick the resemblance
+with sway and swaymsg, and it actually goes pretty deep. In a nutshell, swaymsg
+connects to a UNIX socket created by sway at startup time, to sends it commands
+(see [[https://lthms.github.io/spatial-shell/spatial.5.html][spatial(5)]])
+using a dedicated IPC protocol inherited from i3 (see
+[[https://lthms.github.io/spatial-shell/sway-ipc.7.html][sway-ipc(5)]]). Not
+only spatial also relies on sway IPC protocol to interact with sway and
+implement its spatial model, it creates a UNIX of its own, and supports its own
+set of commands
+([[https://lthms.github.io/spatial-shell/spatial-ipc.7.html][spatial-ipc.7.html]]).
+spatial does exactly the same thing.
+
+* Waybar Integration
+
+It is a common practice to use a so-called “bar” with sway, to display some
+useful information about the current state of the system. In the ~contrib/~
+directory of [[https://github.com/lthms/spatial-shell][Spatial Shell
+repository]], interested readers will find a configuration for
+[[https://github.com/Alexays/Waybar][Waybar]][fn::Readers familiar with
+Material Shell design will not be surprised by the general look and feel of
+this screenshot.]. This configuration is somewhat clunky at the moment, due to
+the limitations of the custom widget of Waybar which does not allow to have one
+widget defines several “buttons.” I am interested in investing a bit of time to
+see if I could write a native widget, similarly to sway’s one.
+
+That being said, the user experience with this integration is already pretty
+neat. As long as you don’t need more
+than 6 workspaces and 8 windows per workspaces, you are good to go!
+
+#+CAPTION: Mandatory screenshot of Spatial Shell, with the Waybar configuration.
+#+NAME:    fig:spatial-shell
+[[../img/spatial-shell.png]]
+
+* Building from Source
+
+As of April 2023, the only way to get Spatial Shell is to build it from source.
+
+You will need the following runtime dependencies:
+
+- sway (i3 might be supported at some point)
+- gmp (for bad reasons, fortunalety this will be removed at some point)
+- swaybg
+- waybar (if you want the full experience)
+
+You will need the following build dependencies:
+
+- opam
+- scdoc (for the man pages)
+
+Then, building and installing Spatial Shell is as simple as using the two
+following commands.
+
+#+begin_src
+make build-deps
+make install
+#+end_src
+
+The latter command will install Spatial Shell’s binaries in ~/usr/local/bin~,
+and the man pages in ~/usr/local/man~. You can remove them with ~make
+uninstall~.
+
+To install Waybar theme, copy ~contrib/waybar/spatialbar.py~ to
+~/usr/local/bin/spatialbar~ for instance, and the Waybar style and config file
+to ~$HOME/.config/waybar~.
diff --git a/site/news/index.html b/site/news/index.html
index 01554d2..eca97c6 100644
--- a/site/news/index.html
+++ b/site/news/index.html
@@ -1,5 +1,20 @@
 <h1>News</h1>
 
+<h2>2023</h1>
+
+<ul>
+  <li>
+    On <strong>April 27, 2022</strong>, Spatial Shell is ready for being
+    tested. It works on my machine, so it will most definitely breaks on yours!
+    See the <a href="CFTSpatialShell.html">Call for Testers post for more
+    details</a>.
+  </li>
+  <li>
+    On <strong>April 27, 2022</strong>, <code>coq-coqffi~beta8</code>
+    has been tagged.
+  </li>
+</ul>
+
 <h2>2022</h2>
 
 <ul>