docs: update README.md

alexpasmantier · Nov 10, 2024 · 96976d9 · 96976d9
1 parent c7fbe26
commit 96976d9
Show file tree

Hide file tree

Showing 3 changed files with 148 additions and 16 deletions.
diff --git a/.config/config.toml b/.config/config.toml
@@ -1,53 +1,85 @@
-# Television configuration file
-# ----------------------------------------------------------------------------
-#
 # Ui settings
 # ----------------------------------------------------------------------------
 [ui]
 # Whether to use nerd font icons in the UI
+# This option requires a font patched with Nerd Font in order to properly
+# display glyphs (see https://www.nerdfonts.com/ for more information)
 use_nerd_font_icons = false
 # How much space to allocate for the UI (in percentage of the screen)
+# ┌───────────────────────────────────────┐
+# │                                       │
+# │            Terminal screen            │
+# │    ┌─────────────────────────────┐    │
+# │    │                             │    │
+# │    │                             │    │
+# │    │                             │    │
+# │    │       Television UI         │    │
+# │    │                             │    │
+# │    │                             │    │
+# │    │                             │    │
+# │    │                             │    │
+# │    └─────────────────────────────┘    │
+# │                                       │
+# │                                       │
+# └───────────────────────────────────────┘
 ui_scale = 80
 
 # Previewers settings
 # ----------------------------------------------------------------------------
 [previewers.file]
 # The theme to use for syntax highlighting
+# A list of available themes can be found in the https://github.com/sharkdp/bat
+# repository which uses the same syntax highlighting engine as television
 theme = "Catppuccin Mocha"
 
 # Keybindings
 # ----------------------------------------------------------------------------
 #
 # Channel mode keybindings
 [keybindings.Channel]
+# Quit the application
 esc = "Quit"
+# Scrolling through entries
 down = "SelectNextEntry"
-up = "SelectPrevEntry"
 ctrl-n = "SelectNextEntry"
+up = "SelectPrevEntry"
 ctrl-p = "SelectPrevEntry"
+# Scrolling the preview pane
 ctrl-d = "ScrollPreviewHalfPageDown"
 ctrl-u = "ScrollPreviewHalfPageUp"
+# Select an entry
 enter = "SelectEntry"
+# Copy the selected entry to the clipboard
 ctrl-y = "CopyEntryToClipboard"
+# Toggle the remote control mode
 ctrl-r = "ToggleRemoteControl"
+# Toggle the send to channel mode
 ctrl-s = "ToggleSendToChannel"
 
 # Remote control mode keybindings
 [keybindings.RemoteControl]
+# Quit the application
 esc = "Quit"
+# Scrolling through entries
 down = "SelectNextEntry"
 up = "SelectPrevEntry"
 ctrl-n = "SelectNextEntry"
 ctrl-p = "SelectPrevEntry"
+# Select an entry
 enter = "SelectEntry"
+# Toggle the remote control mode
 ctrl-r = "ToggleRemoteControl"
 
 # Send to channel mode keybindings
 [keybindings.SendToChannel]
+# Quit the application
 esc = "Quit"
+# Scrolling through entries
 down = "SelectNextEntry"
 up = "SelectPrevEntry"
 ctrl-n = "SelectNextEntry"
 ctrl-p = "SelectPrevEntry"
+# Select an entry
 enter = "SelectEntry"
+# Toggle the send to channel mode
 ctrl-s = "ToggleSendToChannel"
diff --git a/README.md b/README.md
@@ -4,29 +4,29 @@
 ![GitHub License](https://img.shields.io/github/license/alexpasmantier/television)
 
 
-# 📺 television
+# 📺  television
 | ![television.png](https://github.com/user-attachments/assets/cffc3556-c9f3-4704-8303-8bddf661d139) | 
 |:--:| 
 | *The revolution will (not) be televised.* |
 
-## 📺 About
+## About
 `Television` is a very fast general purpose fuzzy finder TUI written in Rust. 
 
 It is inspired by the neovim [telescope](https://github.com/nvim-telescope/telescope.nvim) plugin and is designed to be fast, efficient, simple to use and easily extensible. It is built on top of [tokio](https://github.com/tokio-rs/tokio), [ratatui](https://github.com/ratatui/ratatui) and the *nucleo* matcher used by the [helix](https://github.com/helix-editor/helix) editor.
 
 
-## 📺 Installation
+## Installation
 ```bash
 cargo install television
 ```
 
-## 📺 Usage
+## Usage
 ```bash
 tv [channel] #[default: files] [possible values: env, files, git-repos, text, alias]
 ```
-By default, `television` will search through files in the current directory.
+By default, `television` will launch with the `files` channel on.
 
-## 📺 Built-in Channels
+## Built-in Channels
 The following channels are currently available:
 - `Files`: search through files in a directory tree.
 - `Text`: search through textual content in a directory tree.
@@ -36,7 +36,7 @@ The following channels are currently available:
 - `Stdin`: search through lines of text from stdin.
 
 
-## 📺 Design
+## Design
 #### Channels
 **Television**'s design is primarily based on the concept of **Channels**.
 
@@ -59,3 +59,104 @@ Entries returned by different channels can be previewed in a separate pane. This
 contents of a file, the value of an environment variable, etc. Because entries returned by different channels may
 represent different types of data, **Television** allows for channels to declare the type of previewer that should be
 used. Television comes with a set of built-in previewers that can be used out of the box and will grow over time.
+
+
+## Customization
+You may wish to customize the behavior of `television` by providing your own configuration file. The configuration file
+is a simple TOML file that allows you to customize the behavior of `television` in a number of ways.
+
+|Platform|Value|
+|--------|-----|
+|Linux|`$XDG_CONFIG_HOME/television/config.toml` or `$HOME/.config/television/config.toml`|
+|macOS|`$HOME/Library/Application Support/television/config.toml`|
+|Windows|`{FOLDERID_LocalAppData}\television\config`|
+
+Any of these paths may be overriden by setting the `TELEVISION_CONFIG` environment variable to the path of your desired configuration folder.
+
+#### Default Configuration
+```toml
+# Ui settings
+# ----------------------------------------------------------------------------
+[ui]
+# Whether to use nerd font icons in the UI
+# This option requires a font patched with Nerd Font in order to properly
+# display glyphs (see https://www.nerdfonts.com/ for more information)
+use_nerd_font_icons = false
+# How much space to allocate for the UI (in percentage of the screen)
+# ┌───────────────────────────────────────┐
+# │                                       │
+# │            Terminal screen            │
+# │    ┌─────────────────────────────┐    │
+# │    │                             │    │
+# │    │                             │    │
+# │    │                             │    │
+# │    │       Television UI         │    │
+# │    │                             │    │
+# │    │                             │    │
+# │    │                             │    │
+# │    │                             │    │
+# │    └─────────────────────────────┘    │
+# │                                       │
+# │                                       │
+# └───────────────────────────────────────┘
+ui_scale = 80
+
+# Previewers settings
+# ----------------------------------------------------------------------------
+[previewers.file]
+# The theme to use for syntax highlighting
+# A list of available themes can be found in the https://github.com/sharkdp/bat
+# repository which uses the same syntax highlighting engine as television
+theme = "Catppuccin Mocha"
+
+# Keybindings
+# ----------------------------------------------------------------------------
+# Channel mode keybindings
+[keybindings.Channel]
+# Quit the application
+esc = "Quit"
+# Scrolling through entries
+down = "SelectNextEntry"
+ctrl-n = "SelectNextEntry"
+up = "SelectPrevEntry"
+ctrl-p = "SelectPrevEntry"
+# Scrolling the preview pane
+ctrl-d = "ScrollPreviewHalfPageDown"
+ctrl-u = "ScrollPreviewHalfPageUp"
+# Select an entry
+enter = "SelectEntry"
+# Copy the selected entry to the clipboard
+ctrl-y = "CopyEntryToClipboard"
+# Toggle the remote control mode
+ctrl-r = "ToggleRemoteControl"
+# Toggle the send to channel mode
+ctrl-s = "ToggleSendToChannel"
+
+# Remote control mode keybindings
+[keybindings.RemoteControl]
+# Quit the application
+esc = "Quit"
+# Scrolling through entries
+down = "SelectNextEntry"
+up = "SelectPrevEntry"
+ctrl-n = "SelectNextEntry"
+ctrl-p = "SelectPrevEntry"
+# Select an entry
+enter = "SelectEntry"
+# Toggle the remote control mode
+ctrl-r = "ToggleRemoteControl"
+
+# Send to channel mode keybindings
+[keybindings.SendToChannel]
+# Quit the application
+esc = "Quit"
+# Scrolling through entries
+down = "SelectNextEntry"
+up = "SelectPrevEntry"
+ctrl-n = "SelectNextEntry"
+ctrl-p = "SelectPrevEntry"
+# Select an entry
+enter = "SelectEntry"
+# Toggle the send to channel mode
+ctrl-s = "ToggleSendToChannel"
+```
diff --git a/crates/television/config.rs b/crates/television/config.rs
@@ -54,11 +54,10 @@ pub struct PreviewersConfig {
     pub env_var: EnvVarPreviewerConfig,
 }
 
-impl Into<PreviewerConfig> for PreviewersConfig {
-    fn into(self) -> PreviewerConfig {
-        PreviewerConfig::default().file(previewers::FilePreviewerConfig::new(
-            self.file.theme.clone(),
-        ))
+impl From<PreviewersConfig> for PreviewerConfig {
+    fn from(val: PreviewersConfig) -> Self {
+        PreviewerConfig::default()
+            .file(previewers::FilePreviewerConfig::new(val.file.theme.clone()))
     }
 }