Merge branch 'master' into feat-update-icon-title

1 files changed, 89 insertions, 53 deletions

diff --git a/doc/ranger.1 b/doc/ranger.1
index 2f233c95..a6e20b4c 100644
--- a/doc/ranger.1
+++ b/doc/ranger.1
@@ -133,12 +133,11 @@
 .\" ========================================================================
 .\"
 .IX Title "RANGER 1"
-.TH RANGER 1 "ranger-1.9.2" "2019-06-18" "ranger manual"
+.TH RANGER 1 "ranger-1.9.2" "2019-10-02" "ranger manual"
 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 .\" way too many mistakes in technical documents.
 .if n .ad l
 .nh
-.SH "NAME"
 ranger \- visual file manager
 .SH "SYNOPSIS"
 .IX Header "SYNOPSIS"
@@ -290,18 +289,6 @@ Independently of the preview script, there is a feature to preview images
 by drawing them directly into the terminal. To enable this feature, set the
 option \f(CW\*(C`preview_images\*(C'\fR to true and enable one of the image preview modes:
 .PP
-\fIw3m\fR
-.IX Subsection "w3m"
-.PP
-This does not work over ssh, requires certain terminals (tested on \*(L"xterm\*(R" and
-\&\*(L"urxvt\*(R") and is incompatible with tmux, although it works with screen.
-.PP
-To enable this feature, install the program \*(L"w3m\*(R" and set the option
-\&\f(CW\*(C`preview_images_method\*(C'\fR to w3m.
-.PP
-When using a terminal with a nonzero border which is not automatically detected, the w3m preview will be misaligned.
-Use the \f(CW\*(C`w3m_offset\*(C'\fR option to manually adjust the image offset. This should be the same value as the terminal's border value.
-.PP
 \fIiTerm2\fR
 .IX Subsection "iTerm2"
 .PP
@@ -314,6 +301,14 @@ This feature relies on the dimensions of the terminal's font.  By default, a
 width of 8 and height of 11 are used.  To use other values, set the options
 \&\f(CW\*(C`iterm2_font_width\*(C'\fR and \f(CW\*(C`iterm2_font_height\*(C'\fR to the desired values.
 .PP
+\fIkitty\fR
+.IX Subsection "kitty"
+.PP
+This only works in Kitty. It requires \s-1PIL\s0 (or pillow) to work.
+Allows remote image previews, for example in an ssh session.
+.PP
+To enable this feature, set the option \f(CW\*(C`preview_images_method\*(C'\fR to kitty.
+.PP
 \fIterminology\fR
 .IX Subsection "terminology"
 .PP
@@ -321,6 +316,16 @@ This only works in terminology. It can render vector graphics, but works only lo
 .PP
 To enable this feature, set the option \f(CW\*(C`preview_images_method\*(C'\fR to terminology.
 .PP
+\fIueberzug\fR
+.IX Subsection "ueberzug"
+.PP
+U\*:berzug is a command line utility which draws images on terminals using child
+windows. It requires \s-1PIL\s0 (or pillow) and relies on X11. This makes it
+compatible (in a limited way, i.e., tmux splits are not supported) with many
+terminals and tmux but not the Linux console or Wayland.
+.PP
+To enable this feature, set the option \f(CW\*(C`preview_images_method\*(C'\fR to ueberzug.
+.PP
 \fIurxvt\fR
 .IX Subsection "urxvt"
 .PP
@@ -339,13 +344,17 @@ window.
 .PP
 To enable this feature, set the option \f(CW\*(C`preview_images_method\*(C'\fR to urxvt-full.
 .PP
-\fIkitty\fR
-.IX Subsection "kitty"
+\fIw3m\fR
+.IX Subsection "w3m"
 .PP
-This only works on Kitty. It requires \s-1PIL\s0 (or pillow) to work.
-Allows remote image previews, for example in an ssh session.
+This does not work over ssh, requires certain terminals (tested on \*(L"xterm\*(R" and
+\&\*(L"urxvt\*(R") and is incompatible with tmux, although it works with screen.
 .PP
-To enable this feature, set the option \f(CW\*(C`preview_images_method\*(C'\fR to kitty.
+To enable this feature, install the program \*(L"w3m\*(R" and set the option
+\&\f(CW\*(C`preview_images_method\*(C'\fR to w3m.
+.PP
+When using a terminal with a nonzero border which is not automatically detected, the w3m preview will be misaligned.
+Use the \f(CW\*(C`w3m_offset\*(C'\fR option to manually adjust the image offset. This should be the same value as the terminal's border value.
 .SS "\s-1SELECTION\s0"
 .IX Subsection "SELECTION"
 The \fIselection\fR is defined as \*(L"All marked files \s-1IF THERE ARE ANY,\s0 otherwise
@@ -432,6 +441,10 @@ the end of a command when needed, while preventing editors to strip spaces off
 the end of the line automatically.
 .PP
 To write a literal %, you need to escape it by writing %%.
+.PP
+Note that macros are expanded twice when using chain. For example, to insert
+a space character in a chained command, you would write %%space:
+ chain command1; command2%%space
 .SS "\s-1BOOKMARKS\s0"
 .IX Subsection "BOOKMARKS"
 Type \fBm<key>\fR to bookmark the current directory. You can re-enter this
@@ -687,6 +700,9 @@ Open the console with the most recent command.
 .IX Item "Alt-N"
 Open a tab. N has to be a number from 0 to 9. If the tab doesn't exist yet, it
 will be created.
+.IP "Alt-l, Alt-r" 14
+.IX Item "Alt-l, Alt-r"
+Shift a tab left, respectively right.
 .IP "gn, ^N" 14
 .IX Item "gn, ^N"
 Create a new tab.
@@ -967,6 +983,13 @@ all directories above the current one as well?
 .IP "mouse_enabled [bool] <zm>" 4
 .IX Item "mouse_enabled [bool] <zm>"
 Enable mouse input?
+.IP "nested_ranger_warning [string]" 4
+.IX Item "nested_ranger_warning [string]"
+Warn at startup if \f(CW\*(C`RANGER_LEVEL\*(C'\fR is greater than 0, in other words give a
+warning when you nest ranger in a subshell started by ranger. Allowed values
+are \f(CW\*(C`true\*(C'\fR, \f(CW\*(C`false\*(C'\fR and \f(CW\*(C`error\*(C'\fR. The special value \f(CW\*(C`error\*(C'\fR promotes the
+warning to an error, this is usually shown as red text but will crash ranger
+when run with the \f(CW\*(C`\-\-debug\*(C'\fR flag.
 .IP "one_indexed [bool]" 4
 .IX Item "one_indexed [bool]"
 Start line numbers from 1.  Possible values are:
@@ -1104,6 +1127,10 @@ Sets the state for the version control backend. The possible values are:
 \& local      display only local state.
 \& enabled    display both, local and remote state. May be slow for hg and bzr.
 .Ve
+.IP "vcs_msg_length [int]" 4
+.IX Item "vcs_msg_length [int]"
+Length to truncate first line of the commit messages to when shown in
+the statusbar.  Defaults to 50.
 .IP "viewmode [string]" 4
 .IX Item "viewmode [string]"
 Sets the view mode, which can be \fBmiller\fR to display the files in the
@@ -1188,6 +1215,7 @@ ranger.  For your convenience, this is a list of the \*(L"public\*(R" commands i
 \& terminal
 \& tmap key command
 \& touch filename
+\& trash
 \& travel pattern
 \& tunmap keys...
 \& unmap keys...
@@ -1233,33 +1261,27 @@ example, \fB+ar\fR allows reading for everyone, \-ow forbids others to write and
 777= allows everything.
 .Sp
 See also: man 1 chmod
-.IP "cmap \fIkey\fR \fIcommand\fR" 2
-.IX Item "cmap key command"
-Binds keys for the console. Works like the \f(CW\*(C`map\*(C'\fR command.
 .IP "console [\-p\fIN\fR] \fIcommand\fR" 2
 .IX Item "console [-pN] command"
 Opens the console with the command already typed in.  The cursor is placed at
 \&\fIN\fR.
+.IP "copymap  \fIkey\fR \fInewkey\fR [\fInewkey2\fR ...]" 2
+.IX Item "copymap key newkey [newkey2 ...]"
+.PD 0
 .IP "copycmap \fIkey\fR \fInewkey\fR [\fInewkey2\fR ...]" 2
 .IX Item "copycmap key newkey [newkey2 ...]"
-See \f(CW\*(C`copymap\*(C'\fR
-.IP "copymap \fIkey\fR \fInewkey\fR [\fInewkey2\fR ...]" 2
-.IX Item "copymap key newkey [newkey2 ...]"
-Copies the keybinding \fIkey\fR to \fInewkey\fR in the \*(L"browser\*(R" context.  This is a
-deep copy, so if you change the new binding (or parts of it) later, the old one
-is not modified.
-.Sp
-To copy key bindings of the console, taskview, or pager use \*(L"copycmap\*(R",
-\&\*(L"copytmap\*(R" or \*(L"copypmap\*(R".
 .IP "copypmap \fIkey\fR \fInewkey\fR [\fInewkey2\fR ...]" 2
 .IX Item "copypmap key newkey [newkey2 ...]"
-See \f(CW\*(C`copymap\*(C'\fR
 .IP "copytmap \fIkey\fR \fInewkey\fR [\fInewkey2\fR ...]" 2
 .IX Item "copytmap key newkey [newkey2 ...]"
-See \f(CW\*(C`copymap\*(C'\fR
-.IP "cunmap [\fIkeys...\fR]" 2
-.IX Item "cunmap [keys...]"
-Removes key mappings of the console. Works like the \f(CW\*(C`unmap\*(C'\fR command.
+.PD
+Copies the keybinding \fIkey\fR to \fInewkey\fR in the \*(L"browser\*(R" context.  This is a
+deep copy, so if you change the new binding (or parts of it) later, the old one
+is not modified. For example, \fIcopymap j down\fR will make the key sequence
+\&\*(L"down\*(R" move the cursor down one item.
+.Sp
+To copy key bindings of the console, pager or taskview use \*(L"copycmap\*(R",
+\&\*(L"copypmap\*(R" or \*(L"copytmap\*(R" respectively.
 .IP "default_linemode [\fIpath=regexp\fR | \fItag=tags\fR] \fIlinemodename\fR" 2
 .IX Item "default_linemode [path=regexp | tag=tags] linemodename"
 Sets the default linemode.  See \fIlinemode\fR command.
@@ -1365,16 +1387,24 @@ See the \fIranger.core.linemode\fR module for some examples.
 .IX Item "load_copy_buffer"
 Load the copy buffer from \fI~/.config/ranger/copy_buffer\fR.  This can be used to
 pass the list of copied files to another ranger instance.
-.IP "map \fIkey\fR \fIcommand\fR" 2
+.IP "map  \fIkey\fR \fIcommand\fR" 2
 .IX Item "map key command"
+.PD 0
+.IP "cmap \fIkey\fR \fIcommand\fR" 2
+.IX Item "cmap key command"
+.IP "pmap \fIkey\fR \fIcommand\fR" 2
+.IX Item "pmap key command"
+.IP "tmap \fIkey\fR \fIcommand\fR" 2
+.IX Item "tmap key command"
+.PD
 Assign the key combination to the given command.  Whenever you type the
 key/keys, the command will be executed.  Additionally, if you use a quantifier
 when typing the key, like 5j, it will be passed to the command as the attribute
 \&\*(L"self.quantifier\*(R".
 .Sp
 The keys you bind with this command are accessible in the file browser only,
-not in the console, task view or pager.  To bind keys there, use the commands
-\&\*(L"cmap\*(R", \*(L"tmap\*(R" or \*(L"pmap\*(R".
+not in the console, pager or taskview.  To bind keys there, use the commands
+\&\*(L"cmap\*(R", \*(L"pmap\*(R" or \*(L"tmap\*(R".
 .IP "mark \fIpattern\fR" 2
 .IX Item "mark pattern"
 Mark all files matching the regular expression pattern.
@@ -1408,16 +1438,10 @@ of applications is generated by the external file opener \*(L"rifle\*(R" and can
 displayed when pressing \*(L"r\*(R" in ranger.
 .Sp
 Note that if you specify an application, the mode is ignored.
-.IP "pmap \fIkey\fR \fIcommand\fR" 2
-.IX Item "pmap key command"
-Binds keys for the pager. Works like the \f(CW\*(C`map\*(C'\fR command.
 .IP "prompt_metadata [\fIkeys ...\fR]" 2
 .IX Item "prompt_metadata [keys ...]"
 Prompt the user to input metadata with the \f(CW\*(C`meta\*(C'\fR command for multiple keys in
 a row.
-.IP "punmap [\fIkeys ...\fR]" 2
-.IX Item "punmap [keys ...]"
-Removes key mappings of the pager. Works like the \f(CW\*(C`unmap\*(C'\fR command.
 .IP "quit" 2
 .IX Item "quit"
 Closes the current tab, if there's only one tab. Otherwise quits if there are no tasks in progress.
@@ -1544,12 +1568,19 @@ Scroll the file preview by \fIvalue\fR lines.
 .IP "terminal" 2
 .IX Item "terminal"
 Spawns the \fIx\-terminal-emulator\fR starting in the current directory.
-.IP "tmap \fIkey\fR \fIcommand\fR" 2
-.IX Item "tmap key command"
-Binds keys for the taskview. Works like the \f(CW\*(C`map\*(C'\fR command.
 .IP "touch \fIfilename\fR" 2
 .IX Item "touch filename"
 Creates an empty file with the name \fIfilename\fR, unless it already exists.
+.IP "trash" 2
+.IX Item "trash"
+Move all files in the selection to the trash using rifle. Rifle tries to use a
+trash manager like \fItrash-cli\fR if available but will fall back to moving files
+to either \fI\f(CI$XDG_DATA_HOME\fI/ranger\-trash\fR or \fI~/.ranger/ranger\-trash\fR. This is
+a less permanent version of \fIdelete\fR, relying on the user to clear out the
+trash whenever it's convenient. While having the possibility of restoring
+trashed files until this happens. ranger will ask for a confirmation if you
+attempt to trash multiple (marked) files or non-empty directories. This can be
+changed by modifying the setting \*(L"confirm_on_delete\*(R".
 .IP "travel \fIpattern\fR" 2
 .IX Item "travel pattern"
 Filters the current directory for files containing the letters in the
@@ -1559,13 +1590,18 @@ is automatically reopened, allowing for fast travel.
 To close the console, press \s-1ESC\s0 or execute a file.
 .Sp
 This command is based on the \fIscout\fR command and supports all of its options.
-.IP "tunmap [\fIkeys ...\fR]" 2
-.IX Item "tunmap [keys ...]"
-Removes key mappings of the taskview. Works like the \f(CW\*(C`unmap\*(C'\fR command.
-.IP "unmap [\fIkeys\fR ...]" 2
+.IP "unmap  [\fIkeys\fR ...]" 2
 .IX Item "unmap [keys ...]"
+.PD 0
+.IP "cunmap [\fIkeys\fR ...]" 2
+.IX Item "cunmap [keys ...]"
+.IP "punmap [\fIkeys\fR ...]" 2
+.IX Item "punmap [keys ...]"
+.IP "tunmap [\fIkeys\fR ...]" 2
+.IX Item "tunmap [keys ...]"
+.PD
 Removes the given key mappings in the \*(L"browser\*(R" context.  To unmap key bindings
-in the console, taskview, or pager use \*(L"cunmap\*(R", \*(L"tunmap\*(R" or \*(L"punmap\*(R".
+in the console, pager, or taskview use \*(L"cunmap\*(R", \*(L"punmap\*(R" or \*(L"tunmap\*(R".
 .IP "unmark \fIpattern\fR" 2
 .IX Item "unmark pattern"
 Unmark all files matching a regular expression pattern.