diff --git a/README.md b/README.md index 1295dd7..3d3cf52 100644 --- a/README.md +++ b/README.md @@ -26,34 +26,40 @@ A hackable, minimal, fast TUI file explorer

-Though [xplr](https://github.com/sayanarijit/xplr) strives to be fast and minimalist, its speciality is its hackability. +`xplr` is a terminal UI based file explorer that aims to increase our terminal +productivity by being a flexible, interactive orchestrator for the ever growing +awesome command-line utilities that work with the file-system. -Once you read the [documentation](https://github.com/sayanarijit/xplr/wiki), you should be able to configure the key bindings, -different run modes, and also the way it looks by modifying one single configuration file. +To achieve its goal, `xplr` strives to be a fast, minimal and more importantly, +hackable file explorer. +`xplr` is not meant to be a replacement for the standard shell commands or the +GUI file managers. Rather, it aims to integrate them all and expose an +intuitive, scriptable, keyboard controlled, real-time visual interface, also +being an ideal candidate for further integration, enabling the users to achieve +insane terminal productivity. Table of content ---------------- -- ### [Quickstart](https://github.com/sayanarijit/xplr/wiki/Quickstart) - -- ### [Features](https://github.com/sayanarijit/xplr/wiki/Features) - -- ### [Plugins](https://github.com/sayanarijit/xplr/wiki/Plugins) - -- ### [Hacks](https://github.com/sayanarijit/xplr/wiki/Hacks) - -- ### [Themes](https://github.com/sayanarijit/xplr/wiki/Themes) - -- ### [TODO](https://github.com/sayanarijit/xplr/wiki/TODO) - -- ### [Upgrade Guide](https://github.com/sayanarijit/xplr/wiki/Upgrade-Guide) - -- ### [Alternatives](https://github.com/sayanarijit/xplr/wiki/Alternatives) - -- ### [Community](https://github.com/sayanarijit/xplr/wiki/Community) - -- ### [Contribute](https://github.com/sayanarijit/xplr/wiki/Contribute) +- [Introduction](https://arijitbasu.in/xplr/en/introduction.html) +- [Quickstart](https://arijitbasu.in/xplr/en/quickstart.html) + - [Install](https://arijitbasu.in/xplr/en/install.html) + - [Post Install](https://arijitbasu.in/xplr/en/post-install.html) +- [Configuration](https://arijitbasu.in/xplr/en/configuration.html) + - [General Config](https://arijitbasu.in/xplr/en/general-config.html) + - [Modes](https://arijitbasu.in/xplr/en/modes.html) + - [Message](https://arijitbasu.in/xplr/en/message.html) + - [Layouts](https://arijitbasu.in/xplr/en/layouts.html) + - [Style](https://arijitbasu.in/xplr/en/style.html) +- [Default Key Bindings](https://arijitbasu.in/xplr/en/default-key-bindings.html) +- [TODO](https://arijitbasu.in/xplr/en/todo.html) +- [Hacks](https://github.com/sayanarijit/xplr/wiki/Hacks) +- [Themes](https://github.com/sayanarijit/xplr/wiki/Themes) +- [Alternatives](https://github.com/sayanarijit/xplr/wiki/alternatives.html) +- [Upgrade Guide](https://github.com/sayanarijit/xplr/wiki/upgrade-guide.html) +- [Community](https://github.com/sayanarijit/xplr/wiki/community.html) +- [Contribute](https://github.com/sayanarijit/xplr/wiki/contribute.html) ## Demo diff --git a/docs/en/book.toml b/docs/en/book.toml index dc05ff0..a136f54 100644 --- a/docs/en/book.toml +++ b/docs/en/book.toml @@ -4,3 +4,8 @@ title = "xplr book" description = "A hackable, minimal, fast TUI file explorer" src = "src" language = "en" + +[output.html] +site-url = "/xplr/" +git-repository-url = "https://github.com/sayanarijit/xplr" +edit-url-template = "https://github.com/sayanarijit/xplr/edit/main/docs/en/{path}" diff --git a/docs/en/src/configuration.md b/docs/en/src/configuration.md index 17f637f..b4c7631 100644 --- a/docs/en/src/configuration.md +++ b/docs/en/src/configuration.md @@ -16,12 +16,12 @@ that case, both `~/.config/xplr/init.lua` and `/etc/xplr/init.lua` will be ignored. -Loading Order -------------- +How Config is Loaded +-------------------- When xplr loads, it first executes the built-in [init.lua](https://github.com/sayanarijit/xplr/blob/main/src/init.lua) to set -the default values. It is then overwritten by another config file, if found +the default values, which is then overwritten by another config file, if found using the following lookup order: **--config /path/to/init.lua** > **~/.config/xplr/init.lua** > **/etc/xplr/init.lua** diff --git a/docs/en/src/install.md b/docs/en/src/install.md index d21316c..6ae4770 100644 --- a/docs/en/src/install.md +++ b/docs/en/src/install.md @@ -43,7 +43,7 @@ paru -S xplr-bin Git version: ``` -paru -S xplr-git # git version +paru -S xplr-git ``` ### Void Linux diff --git a/docs/en/src/message.md b/docs/en/src/message.md index 871f332..3c81801 100644 --- a/docs/en/src/message.md +++ b/docs/en/src/message.md @@ -12,14 +12,14 @@ You can send messages to an xplr session in the following ways: - Via [key bindings](modes.md#key-bindings) - Via [Lua function calls](#lua-function-calls) -- Via shell using the [input pipe](#input-pipe) +- Via shell command using the [input pipe](#input-pipe) Format ------ -To send messages using [key bindings](modes.md#key-bindings) or -[Lua functions calls](#lua-functions-calls), these are represented in +To send messages using the [key bindings](modes.md#key-bindings) or +[Lua functions calls](#lua-functions-calls), messages are represented in [Lua](https://www.lua.org/) syntax. For example: - "Quit" @@ -30,7 +30,7 @@ However, to send messages using the [input pipe](#input-pipe), they need to be represented using [YAML](http://yaml.org/) (or [JSON](https://www.json.org)) syntax. For example: -- Foo +- Quit - FocusPath: "/path/to/file" - Call: { command: bash, args: ["-c", "read -p test"] } @@ -46,7 +46,32 @@ When called the function receives a [special argument](#calllua-argument) that contains some useful information. The function can optionally return a list of messages which will be handled by xplr. -Example: +### CallLua Argument + +This is a special argument passed to the lua functions when called using the +`CallLua`, `CallLuaSilently` messages. + +It contains the following information: + +- version +- config +- pwd +- focused_node +- directory_buffer +- selection +- mode +- layout +- input_buffer +- pid +- session_path +- explorer_config +- history +- last_modes + +TODO: Document each. For now, refer to the +[rust doc](https://docs.rs/xplr/latest/xplr/app/struct.CallLuaArg.html#fields). + +### Example: ```lua -- Define the function @@ -64,7 +89,7 @@ end -- Map the function to a key (space) xplr.config.modes.builtin.default.key_bindings.on_key.space = { - help = "and & greet", + help = "ask name and greet", messages = { { CallLua = "custom.ask_name_and_greet" } } @@ -74,31 +99,6 @@ xplr.config.modes.builtin.default.key_bindings.on_key.space = { -- name. Enter your name to receive a nice greeting and to know your location. ``` -### CallLua Argument - -This is a special argument passed to the lua functions when called using the -`CallLua`, `CallLuaSilently` messages. - -It contains the following information: - -- version -- config -- pwd -- focused_node -- directory_buffer -- selection -- mode -- layout -- input_buffer -- pid -- session_path -- explorer_config -- history -- last_modes - -TODO: Document each. For now, refer to the -[rust doc](https://docs.rs/xplr/latest/xplr/app/struct.CallLuaArg.html#fields). - Environment Variables and Pipes ------------------------------- @@ -146,13 +146,13 @@ XPLR_PIPE_DIRECTORY_NODES_OUT=/run/user/1000/xplr/session/122278/pipe/directory_ The environment variables starting with `XPLR_PIPE_` are the temporary files called "pipe"s. -### Input pipe +#### Input pipe Current there is only one input pipe. - [XPLR_PIPE_MSG_IN](#xplr_pipe_msg_in) -### Output pipes +#### Output pipes `XPLR_PIPE_*_OUT` are the output pipes that contain data which cannot be exposed directly via environment variables, like multi-line string. @@ -164,33 +164,59 @@ exposed directly via environment variables, like multi-line string. - [XPLR_PIPE_HISTORY_OUT](#xplr_pipe_history_out) - [XPLR_PIPE_DIRECTORY_NODES_OUT](#xplr_pipe_directory_nodes_out) -### XPLR_PIPE_MSG_IN +#### XPLR_PIPE_MSG_IN Append new-line delimited messages to this pipe in [YAML](www.yaml.org) (or [JSON](www.json.org)) syntax. These messages will be read and handled by xplr after the command execution. -### XPLR_PIPE_SELECTION_OUT +#### XPLR_PIPE_SELECTION_OUT New-line delimited list of selected paths. -### XPLR_PIPE_GLOBAL_HELP_MENU_OUT +#### XPLR_PIPE_GLOBAL_HELP_MENU_OUT The full help menu. -### XPLR_PIPE_LOGS_OUT +#### XPLR_PIPE_LOGS_OUT New-line delimited list of logs. -### XPLR_PIPE_RESULT_OUT +#### XPLR_PIPE_RESULT_OUT New-line delimited result (selected paths if any, else the focused path) -### XPLR_PIPE_HISTORY_OUT +#### XPLR_PIPE_HISTORY_OUT New-line delimited list of last visited paths (similar to jump list in vim). -### XPLR_PIPE_DIRECTORY_NODES_OUT +#### XPLR_PIPE_DIRECTORY_NODES_OUT New-line delimited list of paths, filtered and sorted as displayed in the [files table](layouts.md#table). + + +### Example: + +```lua +xplr.config.modes.builtin.default.key_bindings.on_key.space = { + help = "ask name and greet", + messages = { + { + BashExec = [===[ + echo "What's your name?" + + read name + greeting="Hello $name!" + message="$greeting You are inside $PWD" + + echo LogSuccess: '"'$message'"' >> "${XPLR_PIPE_MSG_IN:?}" + ]===] + } + } +} + +-- Now, when you press "space" in default mode, you will be prompted for your +-- name. Enter your name to receive a nice greeting and to know your location. +``` + diff --git a/docs/en/src/modes.md b/docs/en/src/modes.md index e8566aa..00200b4 100644 --- a/docs/en/src/modes.md +++ b/docs/en/src/modes.md @@ -1,15 +1,17 @@ Modes ===== -xplr is a modal application. That means the users switch between different -modes, each containing a different set to key binding to avoid classes. The -modes can be configured using the `xplr.config.modes` Lua API. +xplr is a modal file explorer. That means the users switch between different +modes, each containing a different set to key bindings to avoid clashes. Users +can switch between these modes at run-time. + +The modes can be configured using the `xplr.config.modes` Lua API. + +It contains the following fields: - [builtin](#builtin) - [custom](#custom) -The users can switch between these modes at run-time. - builtin ------- @@ -48,10 +50,9 @@ custom Type: mapping of string and [Mode](#mode) - This is exposed by the `xplr.config.layouts.custom` API. -It allows the users to define any custom layout. +It allows the users to define custom modes. Example: