From b74360cd4a55e9f6e4b594c84d442339edeff86e Mon Sep 17 00:00:00 2001 From: Saturnus Numerius Date: Tue, 3 Jul 2018 11:31:49 -0400 Subject: Change formatting of colorscheme doc to markdown Makes the file easier to read in github while still maintaining the current easy-to-read format found in the raw file --- doc/colorschemes.md | 77 +++++++++++++++++++++++++++++++++++++++++++ doc/colorschemes.txt | 92 ---------------------------------------------------- 2 files changed, 77 insertions(+), 92 deletions(-) create mode 100644 doc/colorschemes.md delete mode 100644 doc/colorschemes.txt diff --git a/doc/colorschemes.md b/doc/colorschemes.md new file mode 100644 index 00000000..eb8bdef0 --- /dev/null +++ b/doc/colorschemes.md @@ -0,0 +1,77 @@ +# 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/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. -- cgit 1.4.1-2-gfad0 From 3c10cc590d7f0374177e21a75b8e763c3c161128 Mon Sep 17 00:00:00 2001 From: Saturnus Numerius Date: Wed, 4 Jul 2018 10:05:58 -0400 Subject: Made changes requested by @toonn Helps readability. --- doc/colorschemes.md | 23 ++++++++++++++--------- 1 file changed, 14 insertions(+), 9 deletions(-) diff --git a/doc/colorschemes.md b/doc/colorschemes.md index eb8bdef0..4116a843 100644 --- a/doc/colorschemes.md +++ b/doc/colorschemes.md @@ -1,19 +1,21 @@ -# Colorschemes +Colorschemes +============ This text explains colorschemes and how they work. -## Context Tags +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 +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. +of all tags, whose values are either `True` or `False`. -## Implementation in the GUI Classes +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()`. @@ -25,7 +27,8 @@ 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 +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 @@ -37,7 +40,7 @@ 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 +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 @@ -46,7 +49,8 @@ modify the draw-method of the widget to use that tag. Run `tc_colorscheme` to check if your colorschemes are valid. -## Specify a Colorscheme +Specify a Colorscheme +--------------------- Colorschemes are searched for in these directories: @@ -60,7 +64,8 @@ This means, use the colorscheme contained in either `~/.config/ranger/colorschemes/default.py` or `/path/to/ranger/colorschemes/default.py`. -## Adapt a colorscheme +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 -- cgit 1.4.1-2-gfad0 From 7b8087a24da8aa08347d3556c421a00351bf6419 Mon Sep 17 00:00:00 2001 From: Saturnus Numerius Date: Wed, 4 Jul 2018 15:58:14 -0400 Subject: Make more changes --- doc/colorschemes.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/doc/colorschemes.md b/doc/colorschemes.md index 4116a843..c7600700 100644 --- a/doc/colorschemes.md +++ b/doc/colorschemes.md @@ -6,7 +6,7 @@ This text explains colorschemes and how they work. Context Tags ------------ -Context Tags provide information about the context. If the tag `in_titlebar` is +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 @@ -16,16 +16,17 @@ 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 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 +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. +others as `False`, and passes it to the colorscheme's `use(context)` method. The Color Scheme ---------------- @@ -37,14 +38,14 @@ 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. +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 an own tag and +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. -- cgit 1.4.1-2-gfad0 From 4cefa8cccbc3ba4d87f10315caff75b7e43b3ea4 Mon Sep 17 00:00:00 2001 From: Toon Nolten Date: Thu, 5 Jul 2018 00:12:06 +0200 Subject: Update colorscheme docs path in setup.py `colorschemes.txt` markup was improved and the file got a `.md` extension to match. Fixes #1221 --- setup.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/setup.py b/setup.py index d7c54b00..edf48c4a 100755 --- a/setup.py +++ b/setup.py @@ -111,7 +111,7 @@ def main(): 'doc/rifle.1', ]), ('share/doc/ranger', [ - 'doc/colorschemes.txt', + 'doc/colorschemes.md', 'CHANGELOG.md', 'HACKING.md', 'README.md', -- cgit 1.4.1-2-gfad0 From 6a70583077425bbe165196cf09f49aca3cb222b8 Mon Sep 17 00:00:00 2001 From: Saturnus Numerius Date: Sat, 7 Jul 2018 12:09:26 -0400 Subject: Revamped context section of the colorscheme doc Added basic instruction on how to add a context key with a working example. --- doc/colorschemes.md | 69 ++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 63 insertions(+), 6 deletions(-) diff --git a/doc/colorschemes.md b/doc/colorschemes.md index c7600700..eaf90174 100644 --- a/doc/colorschemes.md +++ b/doc/colorschemes.md @@ -6,14 +6,71 @@ 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. +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. -There are a number of context tags, specified in `/ranger/gui/context.py` in the -constant `CONTEXT_KEYS`. +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. -A Context object, defined in the same file, contains attributes with the names -of all tags, whose values are either `True` or `False`. +```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 --------------------------------- -- cgit 1.4.1-2-gfad0 From 2a8565d175a58172983d410b36e8644d484c1cc8 Mon Sep 17 00:00:00 2001 From: Saturnus Numerius Date: Sat, 7 Jul 2018 12:22:19 -0400 Subject: Fixed some capitalization issues --- doc/colorschemes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/colorschemes.md b/doc/colorschemes.md index eaf90174..458cfc53 100644 --- a/doc/colorschemes.md +++ b/doc/colorschemes.md @@ -21,7 +21,7 @@ import ranger.gui.context # Add your key names ranger.gui.context.CONTEXT_KEYS.append('my_key') -# Set it to false (the default value) +# Set it to False (the default value) ranger.gui.context.Context.my_key = False # Or use an array for multiple names -- cgit 1.4.1-2-gfad0 From 4f0cb1333be76c888089c17ca508e7ef17f3400f Mon Sep 17 00:00:00 2001 From: Wojciech Siewierski Date: Sun, 15 Jul 2018 23:04:47 +0200 Subject: Fix a typo in the manpage --- doc/ranger.1 | 4 ++-- doc/ranger.pod | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/ranger.1 b/doc/ranger.1 index 5b3afa73..e141011f 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-06-07" "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 @@ -690,7 +690,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 , if +value are in [brackets]. The hotkey to toggle the setting is in , if a hotkey exists. .PP Settings can be changed in the file \fI~/.config/ranger/rc.conf\fR or on the diff --git a/doc/ranger.pod b/doc/ranger.pod index fcee60aa..3062fef5 100644 --- a/doc/ranger.pod +++ b/doc/ranger.pod @@ -675,7 +675,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 , if +value are in [brackets]. The hotkey to toggle the setting is in , if a hotkey exists. Settings can be changed in the file F<~/.config/ranger/rc.conf> or on the -- cgit 1.4.1-2-gfad0