diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/colorschemes.md | 140 | ||||
| -rw-r--r-- | doc/colorschemes.txt | 92 | ||||
| -rw-r--r-- | doc/howto-publish-a-release.md | 2 | ||||
| -rw-r--r-- | doc/ranger.1 | 81 | ||||
| -rw-r--r-- | doc/ranger.pod | 98 | ||||
| -rw-r--r-- | doc/rifle.1 | 4 |
6 files changed, 311 insertions, 106 deletions
diff --git a/doc/colorschemes.md b/doc/colorschemes.md new file mode 100644 index 00000000..458cfc53 --- /dev/null +++ b/doc/colorschemes.md @@ -0,0 +1,140 @@ +Colorschemes +============ + +This text explains colorschemes and how they work. + +Context Tags +------------ + +Context tags provide information about the context and are Boolean values (`True` +or `False`). For example, if the tag `in_titlebar` is set, you probably want to +know about the color of a part of the titlebar now. + +The default context tags are specified in `/ranger/gui/context.py` in the +constant `CONTEXT_KEYS`. Custom tags can be specified in a custom plugin file in +`~/.config/ranger/plugins/`. The code to use follows. + +```python +# Import the class +import ranger.gui.context + +# Add your key names +ranger.gui.context.CONTEXT_KEYS.append('my_key') + +# Set it to False (the default value) +ranger.gui.context.Context.my_key = False + +# Or use an array for multiple names +my_keys = ['key_one', 'key_two'] +ranger.gui.context.CONTEXT_KEYS.append(my_keys) + +# Set them to False +for key in my_keys: + code = 'ranger.gui.context.Context.' + key + ' = False' + exec(code) +``` + +As you may or may not have guessed, this only tells ranger that they exist, not +what they mean. To do this, you'll have to dig around in the source code. As an +example, let's walk through adding a key that highlights `README.md` files +differently. All the following code will be written in a standalone plugin file. + +First, from above, we'll add the key `readme` and set it to `False`. + +```python +import ranger.gui.context + +ranger.gui.context.CONTEXT_KEYS.append('readme') +ranger.gui.context.Context.readme = False +``` + +Then we'll use the hook `hook_before_drawing` to tell ranger that our key is +talking about `README.md` files. + +```python +import ranger.gui.widgets.browsercolumn + +OLD_HOOK_BEFORE_DRAWING = ranger.gui.widgets.browsercolumn.hook_before_drawing + +def new_hook_before_drawing(fsobject, color_list): + if fsobject.basename === 'README.md': + color_list.append('readme') + + return OLD_HOOK_BEFORE_DRAWING(fsobject, color_list) + +ranger.gui.widgets.browsercolumn.hook_before_drawing = new_hook_before_drawing +``` + +Notice we call the old `hook_before_drawing`. This makes sure that we don't +overwrite another plugin's code, we just append our own to it. + +To highlight it a different color, just [add it to your colorscheme][1] + +[1]:#adapt-a-colorscheme + +Implementation in the GUI Classes +--------------------------------- + +The class `CursesShortcuts` in the file `/ranger/gui/curses_shortcuts.py` defines +the methods `color(*tags)`, `color_at(y, x, wid, *tags)` and `color_reset()`. +This class is a superclass of `Displayable`, so these methods are available almost +everywhere. + +Something like `color("in_titlebar", "directory")` will be called to get the +color of directories in the titlebar. This creates a `ranger.gui.context.Context` +object, sets its attributes `in_titlebar` and `directory` to True, leaves the +others as `False`, and passes it to the colorscheme's `use(context)` method. + +The Color Scheme +---------------- + +A colorscheme should be a subclass of `ranger.gui.ColorScheme` and define the +method `use(context)`. By looking at the context, this use-method has to +determine a 3-tuple of integers: `(foreground, background, attribute)` and return +it. + +`foreground` and `background` are integers representing colors, `attribute` is +another integer with each bit representing one attribute. These integers are +interpreted by the terminal emulator in use. + +Abbreviations for colors and attributes are defined in `ranger.gui.color`. Two +attributes can be combined via bitwise OR: `bold | reverse` + +Once the color for a set of tags is determined, it will be cached by default. If +you want more dynamic colorschemes (such as a different color for very large +files), you will need to dig into the source code, perhaps add a custom tag and +modify the draw-method of the widget to use that tag. + +Run `tc_colorscheme` to check if your colorschemes are valid. + +Specify a Colorscheme +--------------------- + +Colorschemes are searched for in these directories: + +- `~/.config/ranger/colorschemes/` +- `/path/to/ranger/colorschemes/` + +To specify which colorscheme to use, change the option `colorscheme` in your +rc.conf: `set colorscheme default`. + +This means, use the colorscheme contained in either +`~/.config/ranger/colorschemes/default.py` or +`/path/to/ranger/colorschemes/default.py`. + +Adapt a colorscheme +------------------- + +You may want to adapt a colorscheme to your needs without having a complete copy +of it, but rather the changes only. Say, you want the exact same colors as in +the default colorscheme, but the directories to be green rather than blue, +because you find the blue hard to read. + +This is done in the jungle colorscheme `ranger/colorschemes/jungle`, check it +out for implementation details. In short, I made a subclass of the default +scheme, set the initial colors to the result of the default `use()` method and +modified the colors how I wanted. + +This has the obvious advantage that you need to write less, which results in +less maintenance work and a greater chance that your colorscheme will work with +future versions of ranger. diff --git a/doc/colorschemes.txt b/doc/colorschemes.txt deleted file mode 100644 index 145cc94e..00000000 --- a/doc/colorschemes.txt +++ /dev/null @@ -1,92 +0,0 @@ -Colorschemes -============ - -This text explains colorschemes and how they work. - - -Context Tags ------------- - -Context Tags provide information about the context. If the tag -"in_titlebar" is set, you probably want to know about the color -of a part of the titlebar now. - -There are a number of context tags, specified in /ranger/gui/context.py -in the constant CONTEXT_KEYS. - -A Context object, defined in the same file, contains attributes with -the names of all tags, whose values are either True or False. - - -Implementation in the GUI Classes ---------------------------------- - -The class CursesShortcuts in the file /ranger/gui/curses_shortcuts.py -defines the methods color(*tags), color_at(y, x, wid, *tags) and -color_reset(). This class is a superclass of Displayable, so these -methods are available almost everywhere. - -Something like color("in_titlebar", "directory") will be called to -get the color of directories in the titlebar. This creates a -ranger.gui.context.Context object, sets its attributes "in_titlebar" and -"directory" to True, leaves the others as False, and passes it to the -colorscheme's use(context) method. - - -The Color Scheme ----------------- - -A colorscheme should be a subclass of ranger.gui.ColorScheme and -define the method use(context). By looking at the context, this use-method -has to determine a 3-tuple of integers: (foreground, background, attribute) -and return it. - -foreground and background are integers representing colors, -attribute is another integer with each bit representing one attribute. -These integers are interpreted by the used terminal emulator. - -Abbreviations for colors and attributes are defined in ranger.gui.color. -Two attributes can be combined via bitwise OR: bold | reverse - -Once the color for a set of tags is determined, it will be cached by -default. If you want more dynamic colorschemes (such as a different -color for very large files), you will need to dig into the source code, -perhaps add an own tag and modify the draw-method of the widget to use -that tag. - -Run tc_colorscheme to check if your colorschemes are valid. - - -Specify a Colorscheme ---------------------- - -Colorschemes are searched for in these directories: -~/.config/ranger/colorschemes/ -/path/to/ranger/colorschemes/ - -To specify which colorscheme to use, change the option "colorscheme" -in your rc.conf: -set colorscheme default - -This means, use the colorscheme contained in -either ~/.config/ranger/colorschemes/default.py or -/path/to/ranger/colorschemes/default.py. - - -Adapt a colorscheme -------------------- - -You may want to adapt a colorscheme to your needs without having -a complete copy of it, but rather the changes only. Say, you -want the exact same colors as in the default colorscheme, but -the directories to be green rather than blue, because you find the -blue hard to read. - -This is done in the jungle colorscheme ranger/colorschemes/jungle, -check it out for implementation details. In short, I made a subclass -of the default scheme, set the initial colors to the result of the -default use() method and modified the colors how I wanted. - -This has the obvious advantage that you need to write less, which -results in less maintenance work and a greater chance that your colorscheme -will work with future versions of ranger. diff --git a/doc/howto-publish-a-release.md b/doc/howto-publish-a-release.md index 572a2eb7..e8d669ce 100644 --- a/doc/howto-publish-a-release.md +++ b/doc/howto-publish-a-release.md @@ -31,7 +31,7 @@ Test everything Make a release commit --------------------- * [ ] Update the number in the `README` -* [ ] Update `__version__` and `VERSION` in `ranger/__init__.py` +* [ ] Update `__version__` and `__release__` in `ranger/__init__.py` * [ ] Update `__version__` in `ranger/ext/rifle.py` * [ ] `make man` * [ ] Write changelog entry diff --git a/doc/ranger.1 b/doc/ranger.1 index bd6116d1..060686b8 100644 --- a/doc/ranger.1 +++ b/doc/ranger.1 @@ -129,7 +129,7 @@ .\" ======================================================================== .\" .IX Title "RANGER 1" -.TH RANGER 1 "ranger-1.9.1" "2018-04-03" "ranger manual" +.TH RANGER 1 "ranger-1.9.1" "2018-07-15" "ranger manual" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -274,10 +274,10 @@ typing \fI"<tagname>\fR. 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. .PP -This default script is \fI~/.config/ranger/scope.sh\fR. It contains more +This default script is \fI\f(CI%rangerdir\fI/data/scope.sh\fR. It contains more documentation and calls to the programs \fIlynx\fR and \fIelinks\fR for html, \&\fIhighlight\fR for text/code, \fIimg2txt\fR for images, \fIatool\fR for archives, -\&\fIpdftotext\fR for PDFs and \fImediainfo\fR for video and audio files. +\&\fIpdftotext\fR or \fImutool\fR for PDFs and \fImediainfo\fR for video and audio files. .PP Install these programs (just the ones you need) and scope.sh will automatically use them. @@ -307,6 +307,13 @@ 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 +\fIterminology\fR +.IX Subsection "terminology" +.PP +This only works in terminology. It can render vector graphics, but works only locally. +.PP +To enable this feature, set the option \f(CW\*(C`preview_images_method\*(C'\fR to terminology. +.PP \fIurxvt\fR .IX Subsection "urxvt" .PP @@ -324,6 +331,14 @@ The same as urxvt but utilizing not only the preview pane but the whole terminal 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" +.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. +.PP +To enable this feature, set the option \f(CW\*(C`preview_images_method\*(C'\fR to kitty. .SS "\s-1SELECTION\s0" .IX Subsection "SELECTION" The \fIselection\fR is defined as \*(L"All marked files \s-1IF THERE ARE ANY,\s0 otherwise @@ -470,7 +485,7 @@ sample plugins in the \fI/usr/share/doc/ranger/examples/\fR directory, including hello-world plugin that describes this procedure. .SH "KEY BINDINGS" .IX Header "KEY BINDINGS" -Key bindings are defined in the file \fIranger/config/rc.conf\fR. Check this +Key bindings are defined in the file \fI\f(CI%rangerdir\fI/config/rc.conf\fR. Check this file for a list of all key bindings. You can copy it to your local configuration directory with the \-\-copy\-config=rc option. .PP @@ -642,6 +657,41 @@ Close the current tab. The last tab cannot be closed this way. A key chain that allows you to quickly change the line mode of all the files of the current directory. For a more permanent solution, use the command \&\*(L"default_linemode\*(R" in your rc.conf. +.IP ".n" 14 +.IX Item ".n" +Apply a new filename filter. +.IP ".d" 14 +.IX Item ".d" +Apply the typefilter \*(L"directory\*(R". +.IP ".f" 14 +.IX Item ".f" +Apply the typefilter \*(L"file\*(R". +.IP ".l" 14 +.IX Item ".l" +Apply the typefilter \*(L"symlink\*(R". +.IP ".|" 14 +Combine the two topmost filters from the filter stack in the \*(L"\s-1OR\*(R"\s0 +relationship, instead of the \*(L"\s-1AND\*(R"\s0 used implicitly. +.IP ".&" 14 +Explicitly combine the two topmost filters in the \*(L"\s-1AND\*(R"\s0 +relationship. Usually not needed though might be useful in more +complicated scenarios. +.IP ".!" 14 +Negate the topmost filter. +.IP ".r" 14 +.IX Item ".r" +Rotate the filter stack by N elements. Just confirm with enter to +rotate by 1, i.e. move the topmost element to the bottom of the stack. +.IP ".c" 14 +.IX Item ".c" +Clear the filter stack. +.IP ".*" 14 +Decompose the topmost filter combinator (e.g. \f(CW\*(C`.!\*(C'\fR, \f(CW\*(C`.|\*(C'\fR). +.IP ".p" 14 +.IX Item ".p" +Pop the topmost filter from the filter stack. +.IP ".." 14 +Show the current filter stack state. .SS "READLINE-LIKE \s-1BINDINGS IN THE CONSOLE\s0" .IX Subsection "READLINE-LIKE BINDINGS IN THE CONSOLE" .IP "^B, ^F" 14 @@ -675,7 +725,7 @@ scrolling to switch directories. .SH "SETTINGS" .IX Header "SETTINGS" This section lists all built-in settings of ranger. The valid types for the -value are in [brackets]. The hotkey to toggle the setting is in <brokets>, if +value are in [brackets]. The hotkey to toggle the setting is in <brakets>, if a hotkey exists. .PP Settings can be changed in the file \fI~/.config/ranger/rc.conf\fR or on the @@ -709,7 +759,7 @@ in ranger. .IP "automatically_count_files [bool]" 4 .IX Item "automatically_count_files [bool]" Should ranger count and display the number of files in each directory -as soon as it's visible? This gets slow with remote file sytems. Turning it +as soon as it's visible? This gets slow with remote file systems. Turning it off will still allow you to see the number of files after entering the directory. .IP "autosave_bookmarks [bool]" 4 @@ -771,6 +821,9 @@ Display the file size in the main column? .IP "display_size_in_status_bar [bool]" 4 .IX Item "display_size_in_status_bar [bool]" Display the file size in the status bar? +.IP "display_free_space_in_status_bar [bool]" 4 +.IX Item "display_free_space_in_status_bar [bool]" +Display the free disk space in the status bar? .IP "display_tags_in_all_columns [bool]" 4 .IX Item "display_tags_in_all_columns [bool]" Display tags in all columns? @@ -890,6 +943,10 @@ to disable this feature. Which script should handle generating previews? If the file doesn't exist, or use_preview_script is off, ranger will handle previews itself by just printing the content. +.IP "relative_current_zero [bool]" 4 +.IX Item "relative_current_zero [bool]" +When line_numbers is set to relative, show 0 on the current line if +true or show the absolute number of the current line when false. .IP "save_backtick_bookmark [bool]" 4 .IX Item "save_backtick_bookmark [bool]" Save the \f(CW\*(C`\`\*(C'\fR bookmark to disk. This bookmark is used to switch to the last @@ -952,6 +1009,11 @@ Abbreviate \f(CW$HOME\fR with ~ in the titlebar (first line) of ranger? .IP "unicode_ellipsis [bool]" 4 .IX Item "unicode_ellipsis [bool]" Use a unicode \*(L"...\*(R" character instead of \*(L"~\*(R" to mark cut-off filenames? +.IP "bidi_support [bool]" 4 +.IX Item "bidi_support [bool]" +Try to properly display file names in \s-1RTL\s0 languages (Hebrew, Arabic) by using +a \s-1BIDI\s0 algorithm to reverse the relevant parts of the text. +Requires the python-bidi pip package. .IP "update_title [bool]" 4 .IX Item "update_title [bool]" Set a window title? @@ -978,6 +1040,10 @@ Sets the state for the version control backend. The possible values are: Sets the view mode, which can be \fBmiller\fR to display the files in the traditional miller column view that shows multiple levels of the hierarchy, or \&\fBmultipane\fR to use multiple panes (one per tab) similar to midnight-commander. +.IP "w3m_delay [float]" 4 +.IX Item "w3m_delay [float]" +Delay in seconds before displaying an image with the w3m method. +Increase it in case of experiencing display corruption. .IP "wrap_scroll [bool]" 4 .IX Item "wrap_scroll [bool]" Enable scroll wrapping \- moving down while on the last item will wrap around to @@ -1432,6 +1498,9 @@ being bound despite the corresponding line being removed from the user's copy of the configuration file. This behavior may be disabled with an environment variable (see also: \fB\s-1ENVIRONMENT\s0\fR). Note: All other configuration files only read from one source; i.e. default \s-1OR\s0 user, not both. +\&\fIrc.conf\fR and \fIcommands.py\fR are additionally read from \fI/etc/ranger\fR if they +exist for system-wide configuration, user configuration overrides system +configuration which overrides the default configuration. .PP When starting ranger with the \fB\-\-clean\fR option, it will not access or create any of these files. diff --git a/doc/ranger.pod b/doc/ranger.pod index 4b0e90b1..48e6a41e 100644 --- a/doc/ranger.pod +++ b/doc/ranger.pod @@ -189,10 +189,10 @@ typing I<"<tagnameE<gt>>. 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. -This default script is F<~/.config/ranger/scope.sh>. It contains more +This default script is F<%rangerdir/data/scope.sh>. It contains more documentation and calls to the programs I<lynx> and I<elinks> for html, I<highlight> for text/code, I<img2txt> for images, I<atool> for archives, -I<pdftotext> for PDFs and I<mediainfo> for video and audio files. +I<pdftotext> or I<mutool> 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. @@ -220,6 +220,12 @@ 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 C<iterm2_font_width> and C<iterm2_font_height> to the desired values. +=head3 terminology + +This only works in terminology. It can render vector graphics, but works only locally. + +To enable this feature, set the option C<preview_images_method> to terminology. + =head3 urxvt This only works in urxvt compiled with pixbuf support. Does not work over ssh. @@ -236,6 +242,13 @@ window. To enable this feature, set the option C<preview_images_method> to urxvt-full. +=head3 kitty + +This only works on Kitty. It requires PIL (or pillow) to work. +Allows remote image previews, for example in an ssh session. + +To enable this feature, set the option C<preview_images_method> to kitty. + =head2 SELECTION The I<selection> is defined as "All marked files IF THERE ARE ANY, otherwise @@ -379,7 +392,7 @@ hello-world plugin that describes this procedure. =head1 KEY BINDINGS -Key bindings are defined in the file F<ranger/config/rc.conf>. Check this +Key bindings are defined in the file F<%rangerdir/config/rc.conf>. Check this file for a list of all key bindings. You can copy it to your local configuration directory with the --copy-config=rc option. @@ -607,6 +620,58 @@ A key chain that allows you to quickly change the line mode of all the files of the current directory. For a more permanent solution, use the command "default_linemode" in your rc.conf. +=item .n + +Apply a new filename filter. + +=item .d + +Apply the typefilter "directory". + +=item .f + +Apply the typefilter "file". + +=item .l + +Apply the typefilter "symlink". + +=item .| + +Combine the two topmost filters from the filter stack in the "OR" +relationship, instead of the "AND" used implicitly. + +=item .& + +Explicitly combine the two topmost filters in the "AND" +relationship. Usually not needed though might be useful in more +complicated scenarios. + +=item .! + +Negate the topmost filter. + +=item .r + +Rotate the filter stack by N elements. Just confirm with enter to +rotate by 1, i.e. move the topmost element to the bottom of the stack. + +=item .c + +Clear the filter stack. + +=item .* + +Decompose the topmost filter combinator (e.g. C<.!>, C<.|>). + +=item .p + +Pop the topmost filter from the filter stack. + +=item .. + +Show the current filter stack state. + =back =head2 READLINE-LIKE BINDINGS IN THE CONSOLE @@ -662,7 +727,7 @@ scrolling to switch directories. =head1 SETTINGS This section lists all built-in settings of ranger. The valid types for the -value are in [brackets]. The hotkey to toggle the setting is in <brokets>, if +value are in [brackets]. The hotkey to toggle the setting is in <brakets>, if a hotkey exists. Settings can be changed in the file F<~/.config/ranger/rc.conf> or on the @@ -693,7 +758,7 @@ in ranger. =item automatically_count_files [bool] Should ranger count and display the number of files in each directory -as soon as it's visible? This gets slow with remote file sytems. Turning it +as soon as it's visible? This gets slow with remote file systems. Turning it off will still allow you to see the number of files after entering the directory. @@ -767,6 +832,10 @@ Display the file size in the main column? Display the file size in the status bar? +=item display_free_space_in_status_bar [bool] + +Display the free disk space in the status bar? + =item display_tags_in_all_columns [bool] Display tags in all columns? @@ -904,6 +973,11 @@ Which script should handle generating previews? If the file doesn't exist, or use_preview_script is off, ranger will handle previews itself by just printing the content. +=item relative_current_zero [bool] + +When line_numbers is set to relative, show 0 on the current line if +true or show the absolute number of the current line when false. + =item save_backtick_bookmark [bool] Save the C<`> bookmark to disk. This bookmark is used to switch to the last @@ -983,6 +1057,12 @@ Abbreviate $HOME with ~ in the titlebar (first line) of ranger? Use a unicode "..." character instead of "~" to mark cut-off filenames? +=item bidi_support [bool] + +Try to properly display file names in RTL languages (Hebrew, Arabic) by using +a BIDI algorithm to reverse the relevant parts of the text. +Requires the python-bidi pip package. + =item update_title [bool] Set a window title? @@ -1013,6 +1093,11 @@ Sets the view mode, which can be B<miller> to display the files in the traditional miller column view that shows multiple levels of the hierarchy, or B<multipane> to use multiple panes (one per tab) similar to midnight-commander. +=item w3m_delay [float] + +Delay in seconds before displaying an image with the w3m method. +Increase it in case of experiencing display corruption. + =item wrap_scroll [bool] Enable scroll wrapping - moving down while on the last item will wrap around to @@ -1527,6 +1612,9 @@ being bound despite the corresponding line being removed from the user's copy of the configuration file. This behavior may be disabled with an environment variable (see also: B<ENVIRONMENT>). Note: All other configuration files only read from one source; i.e. default OR user, not both. +F<rc.conf> and F<commands.py> are additionally read from F</etc/ranger> if they +exist for system-wide configuration, user configuration overrides system +configuration which overrides the default configuration. When starting ranger with the B<--clean> option, it will not access or create any of these files. diff --git a/doc/rifle.1 b/doc/rifle.1 index ad32e4f4..c8c679ec 100644 --- a/doc/rifle.1 +++ b/doc/rifle.1 @@ -1,4 +1,4 @@ -.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== @@ -129,7 +129,7 @@ .\" ======================================================================== .\" .IX Title "RIFLE 1" -.TH RIFLE 1 "rifle-1.9.1" "05.03.2018" "rifle manual" +.TH RIFLE 1 "rifle-1.9.1" "2018-06-07" "rifle manual" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l |