introduce the sync IPC command

[i3/i3] / docs / layout-saving

diff --git a/docs/layout-saving b/docs/layout-saving
index 2b798df5ac645dc25cda0f282ff2c000ccb54a06..e90ecada87fdb35c3c4727d55b86faccaa812e74 100644 (file)
--- a/docs/layout-saving
+++ b/docs/layout-saving
@@ -52,7 +52,7 @@ it will be placed in the corresponding placeholder window. We say it gets
 
 Note: Swallowing windows into unsatisfied placeholder windows takes precedence
 over
-link:http://i3wm.org/docs/userguide.html#_automatically_putting_clients_on_specific_workspaces[assignment
+link:https://i3wm.org/docs/userguide.html#_automatically_putting_clients_on_specific_workspaces[assignment
 rules]. For example, if you assign all Emacs windows to workspace 1 in your i3
 configuration file, but there is a placeholder window on workspace 2 which
 matches Emacs as well, your newly started Emacs window will end up in the
@@ -164,7 +164,7 @@ a Chrome window:
 image:layout-saving-1.png["Restored layout",width=400,link="layout-saving-1.png"]
 
 The structure of this JSON file looks a lot like the +TREE+ reply, see
-http://build.i3wm.org/docs/ipc.html#_tree_reply for documentation on that. Some
+https://build.i3wm.org/docs/ipc.html#_tree_reply for documentation on that. Some
 properties are excluded because they are not relevant when restoring a layout.
 
 Most importantly, look at the "swallows" section of each window. This is where
@@ -229,5 +229,57 @@ Both deviations from the JSON standard are to make manual editing by humans
 easier. In case you are writing a more elaborate tool for manipulating these
 layouts, you can either use a JSON parser that supports these deviations (for
 example libyajl), transform the layout file to a JSON-conforming file, or
-link:http://cr.i3wm.org/[submit a patch] to make +i3-save-tree(1)+ optionally
-output standard-conforming JSON.
+link:https://github.com/i3/i3/blob/next/.github/CONTRIBUTING.md[submit a patch]
+to make +i3-save-tree(1)+ optionally output standard-conforming JSON.
+
+== Troubleshooting
+
+=== Restoring a vertically split workspace
+
+When using +i3-save-tree+ with the +--workspace+ switch, only the *contents* of
+the workspace will be dumped. This means that properties of the workspace
+itself will be lost.
+
+This is relevant for, e.g., a vertically split container as the base container of
+a workspace. Since the split mode is a property of the workspace, it will not be
+stored. In this case, you will have to manually wrap your layout in such a
+container:
+
+--------------------------------------------------------------------------------
+// vim:ts=4:sw=4:et
+{
+    // this is a manually added container to restore the vertical split
+    "layout": "splitv",
+    "percent": 0.5,
+    "type": "con",
+    "nodes": [
+
+        // the dumped workspace layout goes here
+
+    ]
+}
+--------------------------------------------------------------------------------
+
+=== Placeholders using window title matches don't swallow the window
+
+If you use the +title+ attribute to match a window and find that it doesn't
+work or only works sometimes, the reason might be that the application sets the
+title only after making the window visible. This will be especially true for
+programs running inside terminal emulators, e.g., +urxvt -e irssi+ when
+matching on +title: "irssi"+.
+
+One way to deal with this is to not rely on the title, but instead use, e.g.,
+the +instance+ attribute and running the program to set this window instance to
+that value:
+
+--------------------------------------------------------------------------------
+# Run irssi via
+# urxvt -name "irssi-container" -e irssi
+
+"swallows": [
+    {
+        "class": "URxvt",
+        "instance": "irssi-container"
+    }
+]
+--------------------------------------------------------------------------------