From: Michael Stapelberg Date: Sun, 29 Mar 2015 15:50:23 +0000 (+0200) Subject: update docs for 4.10 X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=5b1627c96e075e04c89ac9f271e58f0df9cc88d4;p=i3%2Fi3.github.io update docs for 4.10 --- diff --git a/_docs/hacking-howto b/_docs/hacking-howto index a591047..12d6b14 100644 --- a/_docs/hacking-howto +++ b/_docs/hacking-howto @@ -1012,7 +1012,7 @@ gets started in any way) and the window(s) which appear. Imagine for example using dmenu: The user starts dmenu by pressing Mod+d, dmenu gets started with PID 3390. The user then decides to launch Firefox, which -takes a long time. So he enters firefox into dmenu and presses enter. Firefox +takes a long time. So they enter firefox into dmenu and press enter. Firefox gets started with PID 4001. When it finally finishes loading, it creates an X11 window and uses MapWindow to make it visible. This is the first time i3 actually gets in touch with Firefox. It decides to map the window, but it has diff --git a/_docs/i3bar-protocol b/_docs/i3bar-protocol index 8fd51ae..6cb04bf 100644 --- a/_docs/i3bar-protocol +++ b/_docs/i3bar-protocol @@ -117,10 +117,8 @@ click_events:: === Blocks in detail full_text:: - The most simple block you can think of is one which just includes the - only required key, the +full_text+ key. i3bar will display the string - value parsed as - https://developer.gnome.org/pango/stable/PangoMarkupFormat.html[Pango markup]. + The +full_text+ will be displayed by i3bar on the status line. This is the + only required key. short_text:: Where appropriate, the +short_text+ (string) entry should also be provided. It will be used in case the status line needs to be shortened @@ -172,6 +170,10 @@ separator_block_width:: this gap, a separator line will be drawn unless +separator+ is disabled. Normally, you want to set this to an odd value (the default is 9 pixels), since the separator line is drawn in the middle. +markup:: + A string that indicates how the text of the block should be parsed. Set to + +"pango"+ to use https://developer.gnome.org/pango/stable/PangoMarkupFormat.html[Pango markup]. + Set to +"none"+ to not use any markup (default). If you want to put in your own entries into a block, prefix the key with an underscore (_). i3bar will ignore all keys it doesn’t understand, and prefixing diff --git a/_docs/layout-saving b/_docs/layout-saving index 2b798df..5897036 100644 --- a/_docs/layout-saving +++ b/_docs/layout-saving @@ -231,3 +231,31 @@ 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. + +== 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 + + ] +} +-------------------------------------------------------------------------------- diff --git a/_docs/userguide b/_docs/userguide index 45b05a0..3d935e4 100644 --- a/_docs/userguide +++ b/_docs/userguide @@ -1249,6 +1249,24 @@ bar { } -------------------------------------------------------------- +=== Custom separator symbol + +Specifies a custom symbol to be used for the separator as opposed to the vertical, +one pixel thick separator. Note that you may have to adjust the +sep_block_width+ +property. + +*Syntax*: +------------------------- +separator_symbol +------------------------- + +*Example*: +------------------------ +bar { + separator_symbol ":|:" +} +------------------------ + === Workspace buttons Specifies whether workspace buttons should be shown or not. This is useful if @@ -2011,6 +2029,27 @@ bindsym $mod+minus scratchpad show bindsym mod4+s [title="^Sup ::"] scratchpad show ------------------------------------------------ +=== Nop + +There is a no operation command +nop+ which allows you to override default +behavior. This can be useful for, e.g., disabling a focus change on clicks with +the middle mouse button. + +The optional +comment+ argument is ignored, but will be printed to the log file +for debugging purposes. + +*Syntax*: +--------------- +nop [] +--------------- + +*Example*: +---------------------------------------------- +# Disable focus change for clicks on titlebars +# with the middle mouse button +bindsym button2 nop +---------------------------------------------- + === i3bar control There are two options in the configuration of each i3bar instance that can be diff --git a/docs/hacking-howto.html b/docs/hacking-howto.html index 931f4e7..226e903 100644 --- a/docs/hacking-howto.html +++ b/docs/hacking-howto.html @@ -1544,7 +1544,7 @@ the window manager does not have any mapping between the process it starts (or gets started in any way) and the window(s) which appear.

Imagine for example using dmenu: The user starts dmenu by pressing Mod+d, dmenu gets started with PID 3390. The user then decides to launch Firefox, which -takes a long time. So he enters firefox into dmenu and presses enter. Firefox +takes a long time. So they enter firefox into dmenu and press enter. Firefox gets started with PID 4001. When it finally finishes loading, it creates an X11 window and uses MapWindow to make it visible. This is the first time i3 actually gets in touch with Firefox. It decides to map the window, but it has diff --git a/docs/i3bar-protocol.html b/docs/i3bar-protocol.html index 5092368..87f6853 100644 --- a/docs/i3bar-protocol.html +++ b/docs/i3bar-protocol.html @@ -196,10 +196,8 @@ full_text

- The most simple block you can think of is one which just includes the - only required key, the full_text key. i3bar will display the string - value parsed as - Pango markup. + The full_text will be displayed by i3bar on the status line. This is the + only required key.

@@ -301,6 +299,16 @@ separator_block_width is 9 pixels), since the separator line is drawn in the middle.

+
+markup +
+
+

+ A string that indicates how the text of the block should be parsed. Set to + "pango" to use Pango markup. + Set to "none" to not use any markup (default). +

+

If you want to put in your own entries into a block, prefix the key with an underscore (_). i3bar will ignore all keys it doesn’t understand, and prefixing diff --git a/docs/layout-saving.html b/docs/layout-saving.html index ec1594c..4eaffbe 100644 --- a/docs/layout-saving.html +++ b/docs/layout-saving.html @@ -273,6 +273,36 @@ output standard-conforming JSON.

+
+

4. Troubleshooting

+
+
+

4.1. 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
+
+    ]
+}
+
+
+
+
-

5.10. Workspace buttons

+

5.10. Custom separator symbol

+

Specifies a custom symbol to be used for the separator as opposed to the vertical, +one pixel thick separator. Note that you may have to adjust the sep_block_width +property.

+

Syntax:

+
+
+
separator_symbol <symbol>
+
+

Example:

+
+
+
bar {
+    separator_symbol ":|:"
+}
+
+
+
+

5.11. Workspace buttons

Specifies whether workspace buttons should be shown or not. This is useful if you want to display a statusline-only bar containing additional information.

The default is to show workspace buttons.

@@ -1341,7 +1359,7 @@ you want to display a statusline-only bar containing additional information.

-

5.11. Strip workspace numbers

+

5.12. Strip workspace numbers

Specifies whether workspace numbers should be displayed within the workspace buttons. This is useful if you want to have a named workspace that stays in order on the bar according to its number without displaying the number prefix.

@@ -1364,7 +1382,7 @@ workspaces to "1:I", "2:II", "3:III", "4:IV", …

-

5.12. Binding Mode indicator

+

5.13. Binding Mode indicator

Specifies whether the current binding mode indicator should be shown or not. This is useful if you want to hide the workspace buttons but still be able to see the current binding mode indicator. @@ -1384,7 +1402,7 @@ For an example of a mode definition, see [res

-

5.13. Colors

+

5.14. Colors

As with i3, colors are in HTML hex format (#rrggbb). The following colors can be configured at the moment:

@@ -2128,7 +2146,27 @@ bindsym mod4+s [title="^Sup ::"] scratchpad show
-

6.16. i3bar control

+

6.16. Nop

+

There is a no operation command nop which allows you to override default +behavior. This can be useful for, e.g., disabling a focus change on clicks with +the middle mouse button.

+

The optional comment argument is ignored, but will be printed to the log file +for debugging purposes.

+

Syntax:

+
+
+
nop [<comment>]
+
+

Example:

+
+
+
# Disable focus change for clicks on titlebars
+# with the middle mouse button
+bindsym button2 nop
+
+
+
+

6.17. i3bar control

There are two options in the configuration of each i3bar instance that can be changed during runtime by invoking a command through i3. The commands bar hidden_state and bar mode allow setting the current hidden_state