diff options
author | Canop <cano.petrole@gmail.com> | 2021-02-25 20:42:48 +0100 |
---|---|---|
committer | Canop <cano.petrole@gmail.com> | 2021-02-25 20:42:48 +0100 |
commit | ee7c3198e1ec99246926f3d17b9f6bd248128aec (patch) | |
tree | e7feb3a0551a7ba5260a199aa8243b10f54eec00 /website/docs | |
parent | b3464bf7eec15ad575e351ce7e79244542de91fd (diff) |
documentation shows most parts both in Hjson and TOML
with tabs
Diffstat (limited to 'website/docs')
-rw-r--r-- | website/docs/conf_file.md | 93 | ||||
-rw-r--r-- | website/docs/conf_verbs.md | 139 | ||||
-rw-r--r-- | website/docs/css/tab-langs.css | 18 | ||||
-rw-r--r-- | website/docs/install-br.md | 9 | ||||
-rw-r--r-- | website/docs/js/tab-langs.js | 52 | ||||
-rw-r--r-- | website/docs/panels.md | 12 | ||||
-rw-r--r-- | website/docs/skins.md | 12 | ||||
-rw-r--r-- | website/docs/tricks.md | 24 | ||||
-rw-r--r-- | website/docs/verbs.md | 27 | ||||
-rw-r--r-- | website/docs/vim_mode.md | 5 |
10 files changed, 332 insertions, 59 deletions
diff --git a/website/docs/conf_file.md b/website/docs/conf_file.md index 4464997..c441d71 100644 --- a/website/docs/conf_file.md +++ b/website/docs/conf_file.md @@ -1,8 +1,20 @@ -# Opening the configuration file +# Hjson or TOML Two formats are allowed: [TOML](https://github.com/toml-lang/toml) and [Hjson](https://hjson.github.io/). +This documentation will often show you the same setting in both formats, with two tabs, like this: + +```Hjson +setting to use if your config file is in .hjson +``` +```TOML +setting to use if your config file is in .toml +``` + + +# Opening the configuration file + The main configuration file is called either `conf.toml` or `conf.hjson`. This default file's location follows the XDG convention, which depends on your system settings. This location in your case can be found on the help screen (use <kbd>?</kbd>). @@ -22,13 +34,12 @@ For example, if you want to see hidden files (the ones whose name starts with a If you almost always want those flags, you may define them as default in the configuration file file, with the `default_flags` setting. -In TOML: - - default_flags = "gh" - -In Hjson: - - default_flags: gh +```Hjson +default_flags: gh +``` +```TOML +default_flags = "gh" +``` Those flags can still be overridden at launch with the negating ones. For example if you don't want to see hidden files at a specific launch, do @@ -38,7 +49,10 @@ Those flags can still be overridden at launch with the negating ones. For exampl Broot usually captures the mouse so that you can click or double click on items. If you want to disable this capture, you may add this: -```toml +```Hjson +capture_mouse: false +``` +```TOML capture_mouse = false ``` @@ -49,24 +63,21 @@ You may map special paths to specific behaviors. You may especially want - to have some link to a directory to always automatically be handled as a normal directory - to exclude some path because it's on a slow device or non relevant -Example configuration in TOML: - -```toml -[special-paths] -"/media/slow-backup-disk" = "no-enter" -"/home/dys/useless" = "hide" -"/home/dys/my-link-I-want-to-explore" = "enter" -``` - -In Hjson: +Example configuration: -```css +```Hjson special_paths: { "/media/slow-backup-disk" : no-enter "/home/dys/useless" : hide "/home/dys/my-link-I-want-to-explore" : enter } ``` +```TOML +[special-paths] +"/media/slow-backup-disk" = "no-enter" +"/home/dys/useless" = "hide" +"/home/dys/my-link-I-want-to-explore" = "enter" +``` Be careful that those paths (globs, in fact) are checked a lot when broot builds trees and that defining a lot of paths will impact the overall speed. @@ -74,7 +85,14 @@ Be careful that those paths (globs, in fact) are checked a lot when broot builds It's possible to redefine the mode mappings, for example if you usually prefer to do exact searches: -```toml +```Hjson +"search-modes": { + <empty>: regex name + /: fuzzy path + z/: regex path +} +``` +```TOML [search-modes] "<empty>" = "regex name" "/" = "fuzzy path" @@ -87,7 +105,10 @@ Note: I'd insist on you not overwriting default mode mappings before you master When the background colors aren't rendered in your terminal, aren't visible enough, or just aren't clear enough for you, you may have the selected lines marked with triangles with -```toml +```Hjson +show_selection_mark: true +``` +```TOML show_selection_mark = true ``` @@ -106,7 +127,19 @@ You may change the order of file attributes in file lists: For example, if you prefer to have the branches left of the tree (as was the default in broot prior 0.18.1) you can use -```toml +```Hjson +cols_order: [ + mark + git + branch + permission + date + size + count + name +] +``` +```TOML cols_order = [ "mark", "git", @@ -127,7 +160,14 @@ broot doesn't support `LS_COLORS` which isn't available on all systems and is li But you can still give a color to files by extension: -```toml +```Hjson +ext_colors: { + png: "rgb(255, 128, 75)" + rs: "yellow" + toml: "ansi(105)" +} +``` +```TOML [ext-colors] png = "rgb(255, 128, 75)" rs = "yellow" @@ -148,7 +188,10 @@ It's possible to choose any of the standard themes listed [here](https://docs.rs * Solarized (dark) * Solarized (light) -```toml +```Hjson +syntax_theme: base16-ocean.light +``` +```TOML syntax_theme = "base16-ocean.light" ``` diff --git a/website/docs/conf_verbs.md b/website/docs/conf_verbs.md index 9c54885..9001265 100644 --- a/website/docs/conf_verbs.md +++ b/website/docs/conf_verbs.md @@ -3,23 +3,9 @@ The most important part of broot configuration is the `verbs` sections, which le # Verb Definition Attributes -You can define a new verb in the TOML configuration file inside the `verbs` list. +You can define a new verb in the configuration file inside the `verbs` list. -In conf.toml, a verb section looks like this: - -```toml -[[verbs]] -invocation = "edit" -key = "F2" -shortcut = "e" -apply_to = "file" -external = "nvim {file}" -leave_broot = false -``` - -In conf.hjson: - -```css +```Hjson { invocation: edit key: F2 @@ -29,6 +15,15 @@ In conf.hjson: leave_broot: false } ``` +```TOML +[[verbs]] +invocation = "edit" +key = "F2" +shortcut = "e" +apply_to = "file" +external = "nvim {file}" +leave_broot = false +``` The possible attributes are: @@ -54,7 +49,9 @@ The execution is defined either by `internal`, `external` or `cmd` so a verb mus If you want broot, for example, to execute `xterm -e "nvim {file}"`, you may either escape the quotes as `\"` or use the array format to separe parts. -So the two following verb definitons are equivalent: +So the two following verb definitions are equivalent. + +With escaping: ```hjson { @@ -62,6 +59,13 @@ So the two following verb definitons are equivalent: external: "xterm -e \"nvim {file}\"" } ``` +```toml +[[verbs]] +invocation = "xtv" +external = "xterm -e \"nvim {file}\"" +``` + +With an array: ```hjson { @@ -69,6 +73,11 @@ So the two following verb definitons are equivalent: external: ["xterm" "-e" "nvim {file}"] } ``` +```toml +[[verbs]] +invocation = "xtv" +external = ["xterm", "-e", "nvim {file}"] +``` # Shortcuts and Verb search @@ -104,6 +113,46 @@ It's possible to define a verb just to add a trigger key to an internal verb. For example you could add those mappings: +```hjson +verbs: [ + { + invocation: "root" + key: "F9" + internal: ":focus /" + } + { + invocation: "home" + key: "ctrl-H" + internal: ":focus ~" + } + { + key: "alt-j" + internal: ":line_down" + } + { + invocation: "top" + key: "F6" + internal: ":select_first" + } + { + invocation: "bottom" + key: "F7" + internal: ":select_last" + } + { + invocation: "open" + key: "crtl-O" + internal: ":open_stay" + } + { + invocation: "edit" + key: "F2" + shortcut: "e" + external: "$EDITOR +{line} {file}" + from_shell: true + } +] +``` ```toml [[verbs]] invocation = "root" @@ -181,6 +230,12 @@ name | expanded to But you may also define some arguments in the invocation pattern. For example: +```hjson +{ + invocation: "mkdir {subpath}" + external: "mkdir -p {directory}/{subpath}" +} +``` ```toml [[verbs]] invocation = "mkdir {subpath}" @@ -201,6 +256,13 @@ It also normalizes the paths it finds which eases the use of relative paths: Here's another example, where the invocation pattern defines two arguments by destructuring: +```hjson +{ + invocation: "blop {name}\\.{type}" + external: "mkdir {parent}/{type} && nvim {parent}/{type}/{name}.{type}" + from_shell: true +} +``` ```toml [[verbs]] invocation = "blop {name}\\.{type}" @@ -219,6 +281,13 @@ Notice the `\\.` in the invocation pattern ? That's because it is interpreted as The whole regular expression syntax may be useful for more complex rules. Let's say we don't want the type to contain dots, then we do this: +```hjson +{ + invocation: "blop {name}\\.(?P<type>[^.]+)" + external: "mkdir {parent}/{type} && nvim {parent}/{type}/{name}.{type}" + from_shell: true +} +``` ```toml [[verbs]] invocation = "blop {name}\\.(?P<type>[^.]+)" @@ -304,6 +373,24 @@ name | default binding | behavior You may add this kind of shortcuts: +```hjson +{ +key: "alt-b" +internal: ":input_go_word_left" +} +{ +key: "alt-f" +internal: ":input_go_word_right" +} +{ +key: "alt-l" +internal: ":input_del_word_left" +} +{ +key: "alt-r" +internal: ":input_del_word_right" +} +``` ```toml [[verbs]] key = "alt-b" @@ -334,6 +421,16 @@ It serves as base for several built-in commands, like `:home` whose execution is And you can add your own ones: +```hjson +{ +key: "ctrl-up" +internal: ":focus .." +} +{ +key: "ctrl-d" +internal: ":focus ~/dev" +} +``` ```toml [[verbs]] key = "ctrl-up" @@ -352,7 +449,15 @@ Such a sequence can contain some searches, some calls to internals, some calls t For example: +```Hjson +{ + name: "backup" + invocation: "bu {name}" + cmd: ":cp {file}-back_{name};:!focus {file}-back_{name}" + apply_to: directory +} ``` +```TOML [[verbs]] name = "backup" invocation = "bu {name}" diff --git a/website/docs/css/tab-langs.css b/website/docs/css/tab-langs.css new file mode 100644 index 0000000..640076c --- /dev/null +++ b/website/docs/css/tab-langs.css @@ -0,0 +1,18 @@ + +.lang-tab { + color: #555; + padding: 2px 5px; + cursor: pointer; + font-size: 90%; +} + +.lang-tab.active { + color: #333; + border-top: solid 1px #e1e4e5; + border-right: solid 1px #e1e4e5; + border-bottom: solid 3px #f8f8f8; + border-left: solid 1px #e1e4e5; + background: #f8f8f8; + cursor: auto; + z-index: 2; +} diff --git a/website/docs/install-br.md b/website/docs/install-br.md index 7afda52..cab0c3b 100644 --- a/website/docs/install-br.md +++ b/website/docs/install-br.md @@ -35,15 +35,6 @@ As a shortcut for [Nushell](https://www.nushell.sh/), define the following alias alias br [] { broot | trim | cd $it } -You can bind this command to a key sequence in the [configuration file](../conf_file): - -```toml -[[verbs]] -key = "alt-p" -shortcut = "pp" -execution = ":print_path" -``` - # `br` alias for Xonsh shell The shortcut for [xonsh](https://xon.sh/) shell can be installed with using [xontrib-broot](https://github.com/jnoortheen/xontrib-broot) diff --git a/website/docs/js/tab-langs.js b/website/docs/js/tab-langs.js new file mode 100644 index 0000000..60f5e3e --- /dev/null +++ b/website/docs/js/tab-langs.js @@ -0,0 +1,52 @@ + +(function main(){ + let groups = find_groups(["Hjson", "TOML"]); + console.log("groups:", groups); + for (let group of groups) { + add_tabs(group); + } +})(); + + +// find and group the pre/code elements with the matching languages +// return [[e]] +function find_groups(langs) { + let groups = []; + $("code").each(function(){ + let lang = langs.find( + lang => this.className.split(' ') + .map(c => c.toLowerCase()) + .includes(lang.toLowerCase()) + ); + if (!lang) return; + let pre = this.parentElement; + let last_group = groups[groups.length-1]; + let item = { lang, pre }; + if (last_group) { + if (last_group[last_group.length-1].pre == pre.previousElementSibling) { + last_group.push(item); + return; + } + } + groups.push([item]); + }); + return groups; +} + +function add_tabs(group) { + let $tabs = $("<div class=lang-tabs>"); + group.forEach((item, idx) => { + let $tab = $("<span class=lang-tab>").text(item.lang).appendTo($tabs); + if (idx) $(item.pre).hide(); + else $tab.addClass("active"); + $tab.click(function(){ + $tabs.find(".lang-tab").removeClass("active"); + group.forEach((_item, _idx) => { + if (_idx==idx) $(_item.pre).show(); + else $(_item.pre).hide(); + }); + this.classList.add("active"); + }); + }); + $tabs.insertBefore(group[0].pre); +} diff --git a/website/docs/panels.md b/website/docs/panels.md index f3fb76d..d2ab284 100644 --- a/website/docs/panels.md +++ b/website/docs/panels.md @@ -55,7 +55,17 @@ Two built-in verbs use those arguments: `:copy_to_panel` (alias `:cpp`) and `:mo The default configuration file contains this that you may uncomment to add <kbd>F5</kbd> and <kbd>F6</kbd> shortcuts: -```toml +```Hjson +# { +# key: F5 +# internal: ":copy_to_panel" +# } +# { +# key: F6 +# internal: ":move_to_panel" +# } +``` +```TOML # [[verbs]] # key = "F5" # internal = ":copy_to_panel" diff --git a/website/docs/skins.md b/website/docs/skins.md index b7b655e..8cd7539 100644 --- a/website/docs/skins.md +++ b/website/docs/skins.md @@ -9,9 +9,15 @@ To start with, you might want broot to use more of your terminal colors. Try adding this in your [config file](../conf_file): +```Hjson +skin: { + default: "none none" + ... +``` ```toml [skin] default = "none none" +... ``` The first `none` sets the terminal default foreground color as broot's default one, and the second one is for the background. @@ -102,6 +108,9 @@ These tree parts can be repeated, after a `/`, to define the style to use in non Example: +```hjson +directory: "ansi(208) None Bold / ansi(172) None" +``` ```toml directory = "ansi(208) None Bold / ansi(172) None" ``` @@ -132,6 +141,9 @@ The mapping between keys and screen parts may not always be obvious. Don't hesit If you want to set the background of broot transparent (i.e. to be the background of your terminal), you can set the default style like this: +```hjson +default: "gray(23) none / gray(20) none" +``` ```toml default = "gray(23) none / gray(20) none" ``` diff --git a/website/docs/tricks.md b/website/docs/tricks.md index 89cd201..1b0ca16 100644 --- a/website/docs/tricks.md +++ b/website/docs/tricks.md @@ -4,7 +4,18 @@ The goal here is to have a function you can use in shell to give you a path. **Step 1:** create a file `~/.config/select.toml` with this content: +```Hjson +verbs: [ + { + invocation: "ok" + key: "enter" + leave_broot: true + execution: ":print_path" + apply_to: "file" + } +] ``` +```TOML [[verbs]] invocation = "ok" key = "enter" @@ -99,7 +110,18 @@ You might still wish to change that, for example when you're on a server without Here's an example of configuration changing the behaviour on open: -```toml +```Hjson +verbs: [ + { + invocation: edit + key: enter + external: "$EDITOR {file}" + leave_broot: false + apply_to: file + } +] +``` +```TOML [[verbs]] invocation = "edit" key = "enter" diff --git a/website/docs/verbs.md b/website/docs/verbs.md index 0a9f441..8600d56 100644 --- a/website/docs/verbs.md +++ b/website/docs/verbs.md @@ -11,7 +11,11 @@ The `rm` verb executes the standard `rm` command. It's defined by this couple (invocation, external): -```toml +```Hjson +invocation: "rm" +external: "rm -rf {file}" +``` +```TOML invocation = "rm" external = "rm -rf {file}" ``` @@ -29,7 +33,11 @@ name | expanded to Several selection based arguments can be used. For example the (built-in) `:copy_to_panel` verb is defined as -```toml +```Hjson +invocation: "copy_to_panel" +external: "cp -r {file} {other-panel-directory}" +``` +```TOML invocation = "copy_to_panel" external = "cp -r {file} {other-panel-directory}" ``` @@ -45,9 +53,13 @@ As for filters, hitting <kbd>esc</kbd> clears the command. Some commands not only use the selection but also takes one or several argument(s). -For example mkdir is defined as +For example mkdir is virtually defined as -```toml +```Hjson +invocation: "mkdir {subpath}" +external: "mkdir -p {directory}/{subpath}" +``` +```TOML invocation = "mkdir {subpath}" external = "mkdir -p {directory}/{subpath}" ``` @@ -68,7 +80,12 @@ If you type an argument, the command to execute is computed and shown: In this screenshot, you didn't type `mkdir` or its start but `md`. That's because the complete definition of this verb includes this line: - shortcut = "md" +```Hjson +shortcut: "md" +``` +```TOML +shortcut = "md" +``` !!! Note The help screen lists the whole set of available verbs, including the ones coming from the configuration. diff --git a/website/docs/vim_mode.md b/website/docs/vim_mode.md index 9139545..fa32107 100644 --- a/website/docs/vim_mode.md +++ b/website/docs/vim_mode.md @@ -14,8 +14,11 @@ You need first to enable the "modal mode" with this line in the configuration: ```hjson modal: true ``` +```TOML +modal = true +``` -(or `modal = true` at the begining of the configuration if it's in TOML) +(note: it must be at the begining of the configuration if it's in TOML) If `modal` isn't set to `true`, the single letter shortcuts you define in configuration will be ignored (so you don't have to remove them if you don't want modality anymore). |