From 1572be83be89f14a04226509bf1deaa4e06daf6c Mon Sep 17 00:00:00 2001
From: Jay Kamat <jaygkamat@gmail.com>
Date: Fri, 12 May 2017 13:28:53 -0700
Subject: [PATCH] Add documentation for pinning

---
 doc/help/commands.asciidoc | 19 +++++++++++++++++--
 doc/help/settings.asciidoc | 18 ++++++++++++++++++
 2 files changed, 35 insertions(+), 2 deletions(-)

diff --git a/doc/help/commands.asciidoc b/doc/help/commands.asciidoc
index 05d1cd5a5..3c14a00f3 100644
--- a/doc/help/commands.asciidoc
+++ b/doc/help/commands.asciidoc
@@ -82,6 +82,7 @@ It is possible to run or bind multiple commands by separating them with `;;`.
 |<<tab-move,tab-move>>|Move the current tab according to the argument and [count].
 |<<tab-next,tab-next>>|Switch to the next tab, or switch [count] tabs forward.
 |<<tab-only,tab-only>>|Close all tabs except for the current one.
+|<<tab-pin,tab-pin>>|Pin the current/[count]th tab.
 |<<tab-prev,tab-prev>>|Switch to the previous tab, or switch [count] tabs back.
 |<<unbind,unbind>>|Unbind a keychain.
 |<<undo,undo>>|Re-open a closed tab (optionally skipping [count] closed tabs).
@@ -334,7 +335,7 @@ Syntax: +:help [*--tab*] [*--bg*] [*--window*] ['topic']+
 Show help about a command or setting.
 
 ==== positional arguments
-* +'topic'+: The topic to show help for. 
+* +'topic'+: The topic to show help for.
 
  - :__command__ for commands.
  - __section__\->__option__ for settings.
@@ -893,13 +894,27 @@ How many tabs to switch forward.
 
 [[tab-only]]
 === tab-only
-Syntax: +:tab-only [*--prev*] [*--next*]+
+Syntax: +:tab-only [*--prev*] [*--next*] [*--force*]+
 
 Close all tabs except for the current one.
 
 ==== optional arguments
 * +*-p*+, +*--prev*+: Keep tabs before the current.
 * +*-n*+, +*--next*+: Keep tabs after the current.
+* +*-f*+, +*--force*+: Avoid confirmation for pinned tabs.
+
+[[tab-pin]]
+=== tab-pin
+Syntax: +:tab-pin+
+
+Pin the current/[count]th tab.
+
+==== count
+The tab index to pin
+
+==== note
+* Pinning a tab shrinks it to `tabs->pinned-width` size.
+* Attempting to close a pinned tab will cause a confirmation, unless `--force` is passed.
 
 [[tab-prev]]
 === tab-prev
diff --git a/doc/help/settings.asciidoc b/doc/help/settings.asciidoc
index b2479f959..ce9740278 100644
--- a/doc/help/settings.asciidoc
+++ b/doc/help/settings.asciidoc
@@ -124,6 +124,7 @@
 |<<tabs-wrap,wrap>>|Whether to wrap when changing tabs.
 |<<tabs-movable,movable>>|Whether tabs should be movable.
 |<<tabs-close-mouse-button,close-mouse-button>>|On which mouse button to close tabs.
+|<<tabs-pinned-width,pinned-width>>|The size of pinned tabs.
 |<<tabs-position,position>>|The position of the tab bar.
 |<<tabs-show-favicons,show-favicons>>|Whether to show favicons in the tab bar.
 |<<tabs-favicon-scale,favicon-scale>>|Scale for favicons in the tab bar. The tab size is unchanged, so big favicons also require extra `tabs->padding`.
@@ -131,6 +132,7 @@
 |<<tabs-indicator-width,indicator-width>>|Width of the progress indicator (0 to disable).
 |<<tabs-tabs-are-windows,tabs-are-windows>>|Whether to open windows instead of tabs.
 |<<tabs-title-format,title-format>>|The format to use for the tab title. The following placeholders are defined:
+|<<tabs-title-format-pinned,title-format-pinned>>|The format to use for the tab title, when it is pinned. The following placeholders are defined:
 |<<tabs-title-alignment,title-alignment>>|Alignment of the text inside of tabs
 |<<tabs-mousewheel-tab-switching,mousewheel-tab-switching>>|Switch between tabs using the mouse wheel.
 |<<tabs-padding,padding>>|Padding for tabs (top, bottom, left, right).
@@ -1183,6 +1185,14 @@ Valid values:
 
 Default: +pass:[middle]+
 
+[[tabs-pinned-width]]
+=== pinned-width
+The width for pinned tabs with a horizontal tabbar, in px.
+
+See `:tab-pin` for more details.
+
+Default: +43+
+
 [[tabs-position]]
 === position
 The position of the tab bar.
@@ -1252,6 +1262,14 @@ The format to use for the tab title. The following placeholders are defined:
 
 Default: +pass:[{index}: {title}]+
 
+[[tabs-title-format-pinned]]
+=== title-format-pinned
+The format to use for the tab title when it is pinned.
+
+The same syntax is used as `tabs->title-format`
+
+Default: +pass:[{index}]+
+
 [[tabs-title-alignment]]
 === title-alignment
 Alignment of the text inside of tabs