diff options
-rw-r--r-- | .gitignore | 3 | ||||
-rw-r--r-- | CONTRIBUTING.md | 69 | ||||
-rw-r--r-- | Cargo.toml | 3 | ||||
-rw-r--r-- | Makefile.toml | 18 | ||||
-rw-r--r-- | docs/MANPAGE.md | 195 |
5 files changed, 256 insertions, 32 deletions
diff --git a/.gitignore b/.gitignore index f211f382b..541370214 100644 --- a/.gitignore +++ b/.gitignore @@ -2,4 +2,5 @@ *.new .vscode .vim -.DS_Store
\ No newline at end of file +.DS_Store +/assets/man/zellij.1
\ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 96659dce4..b8efe437b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,11 +2,11 @@ Thanks for considering to contribute to Zellij! -**First**: if you're unsure or afraid of anything, just ask on our -[Discord server][discord-invite-link] or submit the issue or pull request anyway. -You won't be yelled at for giving it your best effort. The worst that can happen -is that you'll be politely asked to change something. We appreciate any sort -of contributions, and don't want a wall of rules to get in the way of that. +**First**: if you're unsure or afraid of anything, just ask on our [Discord +server][discord-invite-link] or submit the issue or pull request anyway. You +won't be yelled at for giving it your best effort. The worst that can happen is +that you'll be politely asked to change something. We appreciate any sort of +contributions, and don't want a wall of rules to get in the way of that. # Code of Conduct @@ -14,9 +14,12 @@ Before contributing please read our [Code of Conduct](CODE_OF_CONDUCT.md) which all contributors are expected to adhere to. ## Building -To build Zellij, we're using cargo-make – you can install it by running `cargo install --force cargo-make`. +To build Zellij, we're using cargo-make – you can install it by running `cargo +install --force cargo-make`. To edit a manpage mandown crate (`cargo install +mandown`) is used and the work is done on a markdown file in docs/MANPAGE.md. -Zellij has a hard dependency on a package from `x11` most likely called `libX11`, or similarly on your system. +Zellij has a hard dependency on a package from `x11` most likely called +`libX11`, or similarly on your system. Here are some of the commands currently supported by the build system: @@ -37,19 +40,22 @@ cargo make clippy -W clippy::pedantic cargo make install /path/of/zellij/binary # Publish the zellij and zellij-tile crates cargo make publish +# Update manpage +cargo make manpage ``` -To run `install` or `publish`, you'll need `binaryen --version` > 97, for it's command `wasm-opt`. +To run `install` or `publish`, you'll need `binaryen --version` > 97, for it's +command `wasm-opt`. ## Looking for something to work on? -If you are new contributor to `Zellij` going through [beginners][good-first-issue] -should be a good start or you can join our public -[Discord server][discord-invite-link], we would be happy to help -finding something interesting to work on and guide through. +If you are new contributor to `Zellij` going through +[beginners][good-first-issue] should be a good start or you can join our public +[Discord server][discord-invite-link], we would be happy to help finding +something interesting to work on and guide through. -[discord-invite-link]: https://discord.gg/feHDHahHCz -[good-first-issue]: https://github.com/zellij-org/zellij/labels/good%20first%20issue +[discord-invite-link]: https://discord.gg/feHDHahHCz [good-first-issue]: +https://github.com/zellij-org/zellij/labels/good%20first%20issue ## Filing Issues @@ -58,9 +64,11 @@ Bugs and enhancement suggestions are tracked as GitHub issues. ### Lacking API for plugin in Zellij? If you have a plugin idea, but Zellij still doesn't have API required to make -the plugin consider opening [an issue][plugin-issue] and describing your requirements. +the plugin consider opening [an issue][plugin-issue] and describing your +requirements. -[plugin-issue]: https://github.com/zellij-org/zellij/issues/new?assignees=&labels=plugin%20system +[plugin-issue]: +https://github.com/zellij-org/zellij/issues/new?assignees=&labels=plugin%20system ### How Do I Submit A (Good) Bug Report? @@ -70,7 +78,8 @@ issue on that repository and provide the following information: - Use a **clear and descriptive title** for the issue to identify the problem. - Explain which **behavior you expected** to see instead and why. -- Describe the exact **steps to reproduce the problem** in as many details as necessary. +- Describe the exact **steps to reproduce the problem** in as many details as + necessary. - When providing code samples, please use [code blocks][code-blocks]. ### How Do I Submit A (Good) Enhancement Suggestion? @@ -78,23 +87,31 @@ issue on that repository and provide the following information: Instructions are similar to those for bug reports. Please provide the following information: -- Use a **clear and descriptive title** for the issue to identify the suggestion. -- Provide a **description of the suggested enhancement** in as many details as necessary. +- Use a **clear and descriptive title** for the issue to identify the + suggestion. +- Provide a **description of the suggested enhancement** in as many details as + necessary. - When providing code samples, please use [code blocks][code-blocks]. -[code-blocks]: https://help.github.com/articles/creating-and-highlighting-code-blocks/ +[code-blocks]: +https://help.github.com/articles/creating-and-highlighting-code-blocks/ ## Submitting Pull Requests -Instructions are similar to those for bug reports. Please provide the following information: +Instructions are similar to those for bug reports. Please provide the following +information: -- If this is not a trivial fix, consider **creating an issue to discuss first** and **later link to it from the PR**. +- If this is not a trivial fix, consider **creating an issue to discuss first** + and **later link to it from the PR**. - Use a **clear and descriptive title** for the pull request. - - Follow [Conventional Commit specification](https://www.conventionalcommits.org/en/v1.0.0/) -where sufficiently large or impactful change is made. + - Follow [Conventional Commit + specification](https://www.conventionalcommits.org/en/v1.0.0/) where + sufficiently large or impactful change is made. - Provide a **description of the changes** in as many details as necessary. -Before submitting your pull request, also make sure that the following conditions are met: +Before submitting your pull request, also make sure that the following +conditions are met: - Your new code **adheres to the code style** through running `cargo fmt`. -- Your new code **passes all existing and new tests** through running `cargo test`. +- Your new code **passes all existing and new tests** through running `cargo + test`. diff --git a/Cargo.toml b/Cargo.toml index c04206daf..705a09066 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -67,8 +67,7 @@ lto = true depends = "$auto" license-file = ["LICENSE.md", "4"] assets = [ - # TODO? - # ["assets/man/zellij.1", "usr/share/man/man1/zellij.1", "644"], + ["assets/man/zellij.1", "usr/share/man/man1/zellij.1", "644"], ["target/release/zellij", "usr/bin/zellij", "755"], ["GOVERNANCE.md", "usr/share/doc/zellij/GOVERNANCE.md", "644"], ["README.md", "usr/share/doc/zellij/README.md", "644"], diff --git a/Makefile.toml b/Makefile.toml index 2dcb80ad6..db68a76f4 100644 --- a/Makefile.toml +++ b/Makefile.toml @@ -64,7 +64,7 @@ args = ["clippy", "--", "@@split(CARGO_MAKE_TASK_ARGS,;)"] # Release building and installing Zellij [tasks.install] workspace = false -dependencies = ["build-plugins-release", "wasm-opt-plugins", "build-release"] +dependencies = ["build-plugins-release", "wasm-opt-plugins", "build-release", "manpage"] script_runner = "@duckscript" script = ''' if is_dir ${CARGO_MAKE_TASK_ARGS} @@ -93,10 +93,20 @@ for plugin in ${plugins} end ''' +[tasks.manpage] +description = "Use mandown crate to create or update man entry from docs/MANPAGES.md" +script = "mandown docs/MANPAGE.md ZELLIJ 1 > assets/man/zellij.1" +dependencies = ["install-mandown"] + +[tasks.install-mandown] +command = "cargo" +args = ["install", "mandown"] + + # CI Releasing Zellij [tasks.ci-build-release] workspace = false -dependencies = ["setup-cross-compilation", "build-plugins-release", "wasm-opt-plugins"] +dependencies = ["setup-cross-compilation", "build-plugins-release", "wasm-opt-plugins", "manpage"] command = "cross" args = ["build", "--verbose", "--release", "--target", "${CARGO_MAKE_TASK_ARGS}"] @@ -125,4 +135,6 @@ args = ["publish"] [tasks.publish-zellij] command = "cargo" -args = ["publish"]
\ No newline at end of file +args = ["publish"] + + diff --git a/docs/MANPAGE.md b/docs/MANPAGE.md new file mode 100644 index 000000000..6ef937c13 --- /dev/null +++ b/docs/MANPAGE.md @@ -0,0 +1,195 @@ +NAME +==== + +**zellij** - run zellij + +DESCRIPTION +=========== + +Zellij is a workspace aimed at developers, ops-oriented people and anyone who +loves the terminal. At its core, it is a terminal multiplexer (similar to tmux +and screen), but this is merely its infrastructure layer. + +Zellij includes a layout system, and a plugin system allowing one to create +plugins in any language that compiles to WebAssembly. + +OPTIONS +======= + +Run `zellij --help` to see available flags and subcommamds. + +CONFIGURATION +============= + +Zellij looks for configuration file in the following order: + +1. the file provided with _--config_ +2. under the path provided in *ZELLIJ_CONFIG* environment variable +3. the default location (see FILES section) + + +LAYOUTS +======= + +Layouts are yaml files which Zellij can load on startup when _--layout_ flag is +provided. + + +For example a file like this: +``` +--- +direction: Vertical +parts: + - direction: Horizontal + split_size: + Percent: 50 + parts: + - direction: Vertical + split_size: + Percent: 50 + - direction: Vertical + split_size: + Percent: 50 + - direction: Horizontal + split_size: + Percent: 50 +``` + +will tell Zellij to create this layout: +``` +┌─────┬─────┐ +│ │ │ +├─────┤ │ +│ │ │ +└─────┴─────┘ +``` + +CREATING LAYOUTS +---------------- + +A layout file is a nested tree structure. Each node describes either a pane +(leaf), or a space in which its parts (children) will be created. + +Each node has following fields: +* __direction: <Horizontal / Vertical\>__ - node's children will be created by a + split in given direction. +* **split_size:** - this indicates either a percentage of the node's parent's + space or a fixed size of columns/rows from its parent's space. + * __Percent: <1-100\>__ + * __Fixed: <lines_number/columns_number\>__ +* __plugin: /path/to/plugin.wasm__ - optional path to a compiled Zellij plugin. + If indicated loads a plugin into the created space. For more information see + PLUGINS section. + +KEYBINDINGS +=========== + +Zellij comes with a default set of keybindings which aims to fit as many users +as possible but that behaviour can be overidden or modified in user +configuration files. The information about bindings is available in the +_keybinds_ section of configuration. For example, to introduce a keybinding that +will create a new tab and go to tab 1 after pressing 'c' one can write: + +``` +keybinds: + normal: + - action: [ NewTab, GoToTab: 1,] + key: [ Char: 'c',] +``` + +where "normal" stands for a mode name (see MODES section), "action" part +specifies the actions to be executed by Zellij (see ACTIONS section) and "key" +is used to list keys or key combinations bound to given actions (see KEYS). + +ACTIONS +------- + +* __Quit__ - quits Zellij +* __SwitchToMode: <InputMode\>__ - switches to the specified input mode. See + MODES section for possible values. +* __Resize: <Direction\>__ - resizes focused pane in the specified direction + (one of: Left, Right, Up, Down). +* __FocusNextPane__ - switches focus to the next pane to the right or below if + on screen edge. +* __FocusPreviousPane__ - switches focus to the next pane to the left or above + if on screen edge. +* __SwitchFocus__ - left for legacy support. Switches focus to a pane with the + next ID. +* __MoveFocus: <Direction\>__ - moves focus in the specified direction (Left, + Right, Up, Down). +* __ScrollUp__ - scrolls up 1 line in the focused pane. +* __ScrollDown__ - scrolls down 1 line in the focused pane. +* __ToggleFocusFullscreen__ - toggles between fullscreen focus pane and normal + layout. +* __NewPane: <Direction\>__ - opens a new pane in the specified direction (Left, + Right, Up, Down) relative to focus. +* __CloseFocus__ - closes focused pane. +* __NewTab__ - creates a new tab. +* __GoToNextTab__ - goes to the next tab. +* __GoToPreviousTab__ - goes to previous tab. +* __CloseTab__ - closes current tab. +* __GoToTab: <Index\>__ - goes to the tab with the specified index number. + +KEYS +---- + +* __Char: <character\>__ - a single character with no modifier. +* __Alt: <character\>__ - a single character with `Alt` key as modifier. +* __Ctrl: <character\>__ - a single character with `Ctrl` key as modifier. +* __F: <1-12\>__ - one of `F` keys (usually at the top of the keyboard). +* __Backspace__ +* __Left / Right / Up / Down__ - arrow keys on the keyboard. +* __Home__ +* __End__ +* __PageUp / PageDown__ +* __BackTab__ - a backward Tab key. +* __Delete__ +* __Insert__ +* __Esc__ + + +MODES +----- + +* __normal__ - the default startup mode of Zellij. Provides the ability to + switch to different modes, as well as some quick navigation shortcuts. +* __locked__ - disables all keybindings except the one that would switch the + mode to normal (_ctrl-g_ by default). Useful when Zellij's keybindings + conflict with those of a chosen terminal app. +* __pane__ - includes instructions that manipulate the panes (adding new panes, + moving, closing). +* __tab__ - includes instructions that manipulate the tabs (adding new tabs, + moving, closing). +* __resize__ - allows resizing of the focused pane. +* __scroll__ - allows scrolling within the focused pane. +* __RenameTab__ - is a "hidden" mode that can be passed to _SwitchToMode_ + action. It will trigger renaming of a tab. + +PLUGINS +======= + +Zellij has a plugin system based on WebAssembly. Any language that can run on +WASI can be used to develop a plugin. To load a plugin include it in a layout +file. Zellij comes with default plugins included: _status-bar_, _strider_, +_tab-bar_. + +FILES +===== + +Default user configuration file location: +* Linux: _/home/alice/.config/zellij_ +* macOS: _/Users/Alice/Library/Application Support/com.Zellij-Contributors.zellij_ + +ENVIRONMENT +=========== +ZELLIJ_CONFIG + Path of Zellij config to load. + + +NOTES +===== + +The manpage is meant to provide concise offline reference. For more detailed +instructions please visit: + +https://zellij.dev/documentation |