summary refs log tree commit diff stats
path: root/doc
diff options
context:
space:
mode:
authorhut <hut@lavabit.com>2013-02-22 04:46:09 +0100
committerhut <hut@lavabit.com>2013-02-22 04:46:09 +0100
commitbf6a3d6d6c11a85c37322e713b3c7a6eb2a484fc (patch)
tree776b05d2e7ed9ae03a3fb1115b8ae023e5bebbdd /doc
parent4d48d33ca5529464dadbb2fc70888da4cd9d24fa (diff)
parentc1138eb006c6daaa9b88204b0695f18d55e027dc (diff)
downloadranger-bf6a3d6d6c11a85c37322e713b3c7a6eb2a484fc.tar.gz
Merge branch 'master' into vcs
Conflicts:
	ranger/gui/widgets/browsercolumn.py
Diffstat (limited to 'doc')
-rw-r--r--doc/HACKING2
-rw-r--r--doc/ranger.195
-rw-r--r--doc/ranger.pod108
3 files changed, 106 insertions, 99 deletions
diff --git a/doc/HACKING b/doc/HACKING
index 72dc94bc..36320b71 100644
--- a/doc/HACKING
+++ b/doc/HACKING
@@ -18,7 +18,7 @@ Patches
 
 Send patches, created with "git format-patch", to the email adress
 
-    romanz@lavabit.com
+    hut@lavabit.com
 
 If you plan to do major changes, or many changes over time, I encourage
 you to create a fork on GitHub, Gitorious or any other site.
diff --git a/doc/ranger.1 b/doc/ranger.1
index 663b786a..6c30d19f 100644
--- a/doc/ranger.1
+++ b/doc/ranger.1
@@ -124,7 +124,7 @@
 .\" ========================================================================
 .\"
 .IX Title "RANGER 1"
-.TH RANGER 1 "ranger-1.5.5" "02/18/2013" "ranger manual"
+.TH RANGER 1 "ranger-1.5.5" "02/22/2013" "ranger manual"
 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 .\" way too many mistakes in technical documents.
 .if n .ad l
@@ -226,7 +226,7 @@ typing \fI"<tagname>\fR.
 .SS "\s-1PREVIEWS\s0"
 .IX Subsection "PREVIEWS"
 By default, only text files are previewed, but you can enable external preview
-scripts by setting the option \f(CW\*(C`use_preview_script\*(C'\fR and \f(CW\*(C`preview_files\*(C'\fR to True.
+scripts by setting the option \f(CW\*(C`use_preview_script\*(C'\fR and \f(CW\*(C`preview_files\*(C'\fR to true.
 .PP
 This default script is \fI~/.config/ranger/scope.sh\fR. It contains more
 documentation and calls to the programs \fIlynx\fR and \fIelinks\fR for html,
@@ -235,6 +235,14 @@ documentation and calls to the programs \fIlynx\fR and \fIelinks\fR for html,
 .PP
 Install these programs (just the ones you need) and scope.sh will automatically
 use them.
+.PP
+Independently of the preview script, there is a feature to preview images
+by drawing them directly into the terminal.  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\*(C'\fR to true.
 .SS "\s-1SELECTION\s0"
 .IX Subsection "SELECTION"
 The \fIselection\fR is defined as \*(L"All marked files \s-1IF\s0 \s-1THERE\s0 \s-1ARE\s0 \s-1ANY\s0, otherwise
@@ -270,6 +278,10 @@ are in different directories:
 .PP
 Macros for file paths are generally shell-escaped so they can be used in the
 \&\f(CW\*(C`shell\*(C'\fR command.
+.PP
+Additionally, if you create a key binding that uses <any>, a special statement
+which accepts any key, then the macro \f(CW%any\fR (or \f(CW%any0\fR, \f(CW%any1\fR, \f(CW%any2\fR, ...) can be
+used in the command to get the key that was pressed.
 .SS "\s-1BOOKMARKS\s0"
 .IX Subsection "BOOKMARKS"
 Type \fBm<key>\fR to bookmark the current directory. You can re-enter this
@@ -390,30 +402,42 @@ Reload everything
 .IP "^L" 14
 .IX Item "^L"
 Redraw the screen
+.IP "i" 14
+.IX Item "i"
+Display the current file in a bigger window.
+.IP "E" 14
+.IX Item "E"
+Edit the current file in \f(CW$EDITOR\fR (\*(L"nano\*(R" by default)
 .IP "S" 14
 .IX Item "S"
 Open a shell in the current directory
 .IP "?" 14
 Opens this man page
+.IP "<octal>=, +<who><what>, \-<who><what>" 14
+.IX Item "<octal>=, +<who><what>, -<who><what>"
+Change the permissions of the selection.  For example, \f(CW\*(C`777=\*(C'\fR is equivalent to
+\&\f(CW\*(C`chmod 777 %s\*(C'\fR, \f(CW\*(C`+ar\*(C'\fR does \f(CW\*(C`chmod a+r %s\*(C'\fR, \f(CW\*(C`\-ow\*(C'\fR does \f(CW\*(C`chmod o\-w %s\*(C'\fR etc.
 .IP "yy" 14
 .IX Item "yy"
-Yank the selection to the \*(L"copy\*(R" buffer and mark them as to be copied
+Copy (yank) the selection, like pressing Ctrl+C in modern \s-1GUI\s0 programs.
 .IP "dd" 14
 .IX Item "dd"
-Cut the selection to the \*(L"copy\*(R" buffer and mark them as to be moved
+Cut the selection, like pressing Ctrl+X in modern \s-1GUI\s0 programs.
 .IP "pp" 14
 .IX Item "pp"
-Paste the files from the \*(L"copy\*(R" buffer here (by moving or copying, depending on
-how they are marked.) By default, this will not overwrite existing files.  To
-overwrite them, use \fIpo\fR.
+Paste the files which were previously copied or cut, like pressing Ctrl+V in
+modern \s-1GUI\s0 programs.
+.IP "po" 14
+.IX Item "po"
+Paste the copied/cut files, overwriting existing files.
 .IP "m\fIX\fR" 14
 .IX Item "mX"
 Create a bookmark with the name \fIX\fR
 .IP "`\fIX\fR" 14
 .IX Item "`X"
 Move to the bookmark with the name \fIX\fR
-.IP "n, N" 14
-.IX Item "n, N"
+.IP "n" 14
+.IX Item "n"
 Find the next file.  By default, this gets you to the newest file in the
 directory, but if you search something using the keys /, cm, ct, ..., it will
 get you to the next found entry.
@@ -427,6 +451,11 @@ Change the sort method (like in mutt)
 .IX Item "zX"
 Change settings.  See the settings section for a list of settings and their
 hotkey.
+.IP "u\fI?\fR" 14
+.IX Item "u?"
+Universal undo-key.  Depending on the key that you press after \*(L"u\*(R", it either
+restores closed tabs (uq), removes tags (ut), clears the copy/cut buffer (ud),
+starts the reversed visual mode (uV) or clears the selection (uv).
 .IP "f" 14
 .IX Item "f"
 Quickly navigate by entering a part of the filename.
@@ -435,10 +464,11 @@ Quickly navigate by entering a part of the filename.
 Mark a file.
 .IP "v" 14
 .IX Item "v"
-Toggle the mark-status of all files, unmark all files.
-.IP "V, uv" 14
-.IX Item "V, uv"
-Unmark all files
+Toggle the mark-status of all files
+.IP "V" 14
+.IX Item "V"
+Starts the visual mode, which selects all files between the starting point and
+the cursor until you press \s-1ESC\s0.  To unselect files in the same way, use \*(L"uV\*(R".
 .IP "/" 14
 Search for files in the current directory.
 .IP ":" 14
@@ -456,32 +486,6 @@ Go to the next or previous tab. You can also use \s-1TAB\s0 and \s-1SHIFT+TAB\s0
 .IP "gc, ^W" 14
 .IX Item "gc, ^W"
 Close the current tab.  The last tab cannot be closed this way.
-.SS "\s-1MIDNIGHT\s0 COMMANDER-LIKE \s-1BINDINGS\s0"
-.IX Subsection "MIDNIGHT COMMANDER-LIKE BINDINGS"
-.IP "<F1>" 14
-.IX Item "<F1>"
-Display Help.
-.IP "<F3>" 14
-.IX Item "<F3>"
-Display the file.
-.IP "<F4>" 14
-.IX Item "<F4>"
-Edit the file.
-.IP "<F5>" 14
-.IX Item "<F5>"
-Copy the file.
-.IP "<F6>" 14
-.IX Item "<F6>"
-Cut the file.
-.IP "<F7>" 14
-.IX Item "<F7>"
-Open the console with \*(L":mkdir \*(R".
-.IP "<F8>" 14
-.IX Item "<F8>"
-Prompt for deletion of the selected files.
-.IP "<F10>" 14
-.IX Item "<F10>"
-Exit ranger.
 .SS "READLINE-LIKE \s-1BINDINGS\s0 \s-1IN\s0 \s-1THE\s0 \s-1CONSOLE\s0"
 .IX Subsection "READLINE-LIKE BINDINGS IN THE CONSOLE"
 .IP "^B, ^F" 14
@@ -951,7 +955,7 @@ Creates an empty file with the name \fIfilename\fR, unless it already exists.
 Filters the current directory for files containing the letters in the
 string, possibly with other letters in between.  The filter is applied as
 you type.  When only one directory is left, it is entered and the console
-is automatially reopened, allowing for fast travel.
+is automatically reopened, allowing for fast travel.
 To close the console, press \s-1ESC\s0 or execute a file.
 .IP "tunmap [\fIkeys ...\fR]" 2
 .IX Item "tunmap [keys ...]"
@@ -1036,10 +1040,14 @@ These environment variables have an effect on ranger:
 ranger sets this environment variable to \*(L"1\*(R" or increments it if it already
 exists.  External programs can determine whether they were spawned from ranger
 by checking for this variable.
+.IP "\s-1RANGER_LOAD_DEFAULT_RC\s0" 8
+.IX Item "RANGER_LOAD_DEFAULT_RC"
+If this variable is set to \s-1FALSE\s0, ranger will not load the default rc.conf.
+This can save time if you copied the whole rc.conf to ~/.config/ranger/ and
+don't need the default one at all.
 .IP "\s-1EDITOR\s0" 8
 .IX Item "EDITOR"
-Defines the editor to be used for the \*(L"E\*(R" key.  Defaults to the first installed
-program out of \*(L"vim\*(R", \*(L"emacs\*(R" and \*(L"nano\*(R".
+Defines the editor to be used for the \*(L"E\*(R" key.  Defaults to \*(L"nano\*(R".
 .IP "\s-1SHELL\s0" 8
 .IX Item "SHELL"
 Defines the shell that ranger is going to use with the :shell command and
@@ -1047,8 +1055,7 @@ the \*(L"S\*(R" key.  Defaults to \*(L"/bin/sh\*(R".
 .IP "\s-1TERMCMD\s0" 8
 .IX Item "TERMCMD"
 Defines the terminal emulator command that ranger is going to use with the
-:terminal command and the \*(L"t\*(R" run flag.  Defaults to \*(L"x\-terminal-emulator\*(R" or
-\&\*(L"xterm\*(R"
+:terminal command and the \*(L"t\*(R" run flag.  Defaults to \*(L"xterm\*(R".
 .IP "\s-1XDG_CONFIG_HOME\s0" 8
 .IX Item "XDG_CONFIG_HOME"
 Specifies the directory for configuration files. Defaults to \fI\f(CI$HOME\fI/.config\fR.
diff --git a/doc/ranger.pod b/doc/ranger.pod
index 43275b95..2a314e74 100644
--- a/doc/ranger.pod
+++ b/doc/ranger.pod
@@ -131,7 +131,7 @@ typing I<"<tagnameE<gt>>.
 =head2 PREVIEWS
 
 By default, only text files are previewed, but you can enable external preview
-scripts by setting the option C<use_preview_script> and C<preview_files> to True.
+scripts by setting the option C<use_preview_script> and C<preview_files> to true.
 
 This default script is F<~/.config/ranger/scope.sh>. It contains more
 documentation and calls to the programs I<lynx> and I<elinks> for html,
@@ -141,6 +141,14 @@ I<pdftotext> for PDFs and I<mediainfo> for video and audio files.
 Install these programs (just the ones you need) and scope.sh will automatically
 use them.
 
+Independently of the preview script, there is a feature to preview images
+by drawing them directly into the terminal.  This does not work over ssh,
+requires certain terminals (tested on "xterm" and "urxvt") and is incompatible
+with tmux, although it works with screen.
+
+To enable this feature, install the program "w3m" and set the option
+C<preview_images> to true.
+
 =head2 SELECTION
 
 The I<selection> is defined as "All marked files IF THERE ARE ANY, otherwise
@@ -174,6 +182,10 @@ are in different directories:
 Macros for file paths are generally shell-escaped so they can be used in the
 C<shell> command.
 
+Additionally, if you create a key binding that uses <any>, a special statement
+which accepts any key, then the macro %any (or %any0, %any1, %any2, ...) can be
+used in the command to get the key that was pressed.
+
 =head2 BOOKMARKS
 
 Type B<m<keyE<gt>> to bookmark the current directory. You can re-enter this
@@ -303,6 +315,14 @@ Reload everything
 
 Redraw the screen
 
+=item i
+
+Display the current file in a bigger window.
+
+=item E
+
+Edit the current file in $EDITOR ("nano" by default)
+
 =item S
 
 Open a shell in the current directory
@@ -311,19 +331,27 @@ Open a shell in the current directory
 
 Opens this man page
 
+=item <octal>=, +<who><what>, -<who><what>
+
+Change the permissions of the selection.  For example, C<777=> is equivalent to
+C<chmod 777 %s>, C<+ar> does C<chmod a+r %s>, C<-ow> does C<chmod o-w %s> etc.
+
 =item yy
 
-Yank the selection to the "copy" buffer and mark them as to be copied
+Copy (yank) the selection, like pressing Ctrl+C in modern GUI programs.
 
 =item dd
 
-Cut the selection to the "copy" buffer and mark them as to be moved
+Cut the selection, like pressing Ctrl+X in modern GUI programs.
 
 =item pp
 
-Paste the files from the "copy" buffer here (by moving or copying, depending on
-how they are marked.) By default, this will not overwrite existing files.  To
-overwrite them, use I<po>.
+Paste the files which were previously copied or cut, like pressing Ctrl+V in
+modern GUI programs.
+
+=item po
+
+Paste the copied/cut files, overwriting existing files.
 
 =item mI<X>
 
@@ -333,7 +361,7 @@ Create a bookmark with the name I<X>
 
 Move to the bookmark with the name I<X>
 
-=item n, N
+=item n
 
 Find the next file.  By default, this gets you to the newest file in the
 directory, but if you search something using the keys /, cm, ct, ..., it will
@@ -352,6 +380,12 @@ Change the sort method (like in mutt)
 Change settings.  See the settings section for a list of settings and their
 hotkey.
 
+=item uI<?>
+
+Universal undo-key.  Depending on the key that you press after "u", it either
+restores closed tabs (uq), removes tags (ut), clears the copy/cut buffer (ud),
+starts the reversed visual mode (uV) or clears the selection (uv).
+
 =item f
 
 Quickly navigate by entering a part of the filename.
@@ -362,11 +396,12 @@ Mark a file.
 
 =item v
 
-Toggle the mark-status of all files, unmark all files.
+Toggle the mark-status of all files
 
-=item V, uv
+=item V
 
-Unmark all files
+Starts the visual mode, which selects all files between the starting point and
+the cursor until you press ESC.  To unselect files in the same way, use "uV".
 
 =item /
 
@@ -376,7 +411,6 @@ Search for files in the current directory.
 
 Open the console.
 
-
 =item Alt-I<N>
 
 Open a tab. N has to be a number from 0 to 9. If the tab doesn't exist yet, it
@@ -396,44 +430,6 @@ Close the current tab.  The last tab cannot be closed this way.
 
 =back
 
-=head2 MIDNIGHT COMMANDER-LIKE BINDINGS
-
-=over 14
-
-=item <F1>
-
-Display Help.
-
-=item <F3>
-
-Display the file.
-
-=item <F4>
-
-Edit the file.
-
-=item <F5>
-
-Copy the file.
-
-=item <F6>
-
-Cut the file.
-
-=item <F7>
-
-Open the console with ":mkdir ".
-
-=item <F8>
-
-Prompt for deletion of the selected files.
-
-=item <F10>
-
-Exit ranger.
-
-=back
-
 =head2 READLINE-LIKE BINDINGS IN THE CONSOLE
 
 =over 14
@@ -1000,7 +996,7 @@ Creates an empty file with the name I<filename>, unless it already exists.
 Filters the current directory for files containing the letters in the
 string, possibly with other letters in between.  The filter is applied as
 you type.  When only one directory is left, it is entered and the console
-is automatially reopened, allowing for fast travel.
+is automatically reopened, allowing for fast travel.
 To close the console, press ESC or execute a file.
 
 =item tunmap [I<keys ...>]
@@ -1121,10 +1117,15 @@ ranger sets this environment variable to "1" or increments it if it already
 exists.  External programs can determine whether they were spawned from ranger
 by checking for this variable.
 
+=item RANGER_LOAD_DEFAULT_RC
+
+If this variable is set to FALSE, ranger will not load the default rc.conf.
+This can save time if you copied the whole rc.conf to ~/.config/ranger/ and
+don't need the default one at all.
+
 =item EDITOR
 
-Defines the editor to be used for the "E" key.  Defaults to the first installed
-program out of "vim", "emacs" and "nano".
+Defines the editor to be used for the "E" key.  Defaults to "nano".
 
 =item SHELL
 
@@ -1134,8 +1135,7 @@ the "S" key.  Defaults to "/bin/sh".
 =item TERMCMD
 
 Defines the terminal emulator command that ranger is going to use with the
-:terminal command and the "t" run flag.  Defaults to "x-terminal-emulator" or
-"xterm"
+:terminal command and the "t" run flag.  Defaults to "xterm".
 
 
 =item XDG_CONFIG_HOME