From 00d064e3498b96438def1d6ced069565a6423c12 Mon Sep 17 00:00:00 2001 From: NKGoc Date: Tue, 4 May 2021 20:50:27 +0200 Subject: [PATCH 01/10] add manpage to zellij --- Cargo.toml | 4 +- Makefile.toml | 16 ++- assets/man/zellij.1 | 339 ++++++++++++++++++++++++++++++++++++++++++++ docs/MANPAGE.md | 195 +++++++++++++++++++++++++ 4 files changed, 550 insertions(+), 4 deletions(-) create mode 100644 assets/man/zellij.1 create mode 100644 docs/MANPAGE.md diff --git a/Cargo.toml b/Cargo.toml index a1f260cc..24fb4d92 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -48,6 +48,7 @@ features = ["unstable"] [dev-dependencies] insta = "1.6.0" tempfile = "3.2.0" +mandown = "0.1.2" [build-dependencies] structopt = "0.3" @@ -69,8 +70,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 1d11f0d1..c68d7223 100644 --- a/Makefile.toml +++ b/Makefile.toml @@ -6,6 +6,7 @@ SKIP_TEST = false # Add clippy to the default flow [tasks.dev-test-flow] +description = "Defines the default developer build flow with tests." dependencies = [ "format-flow", "format-toml-conditioned-flow", @@ -64,7 +65,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", "manpages-install"] script_runner = "@duckscript" script = ''' if is_dir ${CARGO_MAKE_TASK_ARGS} @@ -125,4 +126,15 @@ args = ["publish"] [tasks.publish-zellij] command = "cargo" -args = ["publish"] \ No newline at end of file +args = ["publish"] + +[tasks.manpage] +description = "Use mandown crate to create or update man entry from docs/MANPAGES.md" +workspace = false +script = "mandown docs/MANPAGE.md ZELLIJ 1 > assets/man/zellij.1" + +[tasks.manpage-install] +description = "Install manpage from assets" +workspace = false +command = "sudo" +args = ["cp", "assets/man/zellij.1", "/usr/share/man/man1/"] diff --git a/assets/man/zellij.1 b/assets/man/zellij.1 new file mode 100644 index 00000000..f2e600c0 --- /dev/null +++ b/assets/man/zellij.1 @@ -0,0 +1,339 @@ +.TH "ZELLIJ" 1 + +.SH "NAME" +.PP +\fBzellij\fP \- run zellij + +.SH "DESCRIPTION" +.PP +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\. +.PP +Zellij includes a layout system, and a plugin system allowing one to create +plugins in any language that compiles to WebAssembly\. + +.SH "OPTIONS" +.PP +Run `\f[CR]zellij \-\-help\fP` to see available flags and subcommamds\. + +.SH "CONFIGURATION" +.PP +Zellij looks for configuration file in the following order: +.RS +.Bl +.IP 1. 4 +the file provided with \fI\-\-config\fP +.El +.Bl +.IP 2. 4 +under the path provided in \fIZELLIJ_CONFIG\fP environment variable +.El +.Bl +.IP 3. 4 +the default location (see FILES section) +.El +.RE + +.SH "LAYOUTS" +.PP +Layouts are yaml files which Zellij can load on startup when \fI\-\-layout\fP flag is +provided\. +.PP +For example a file like this: +.RS +.PP +.nf +\-\-\- +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 +.fi +.RE +.PP +will tell Zellij to create this layout: +.RS +.PP +.nf ++\-\-\-\-\-+\-\-\-\-\-+ +| | | ++\-\-\-\-\-+ | +| | | ++\-\-\-\-\-+\-\-\-\-\-+ +.fi +.RE + +.SS "CREATING LAYOUTS" +.PP +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\. +.PP +Each node has following fields: +.RS +.Bl +.IP \(bu 4 +\fBdirection: \fP \- node's children will be created by a +split in given direction\. +.El +.Bl +.IP \(bu 4 +\fBsplit_size:\fP \- this indicates either a percentage of the node's parent's +space or a fixed size of columns/rows from its parent's space\. +.RS +.Bl +.IP \(bu 4 +\fBPercent: <1\-100>\fP +.El +.Bl +.IP \(bu 4 +\fBFixed: \fP +.El +.RE +.El +.Bl +.IP \(bu 4 +\fBplugin: /path/to/plugin\.wasm\fP \- optional path to a compiled Zellij plugin\. +If indicated loads a plugin into the created space\. For more information see +PLUGINS section\. +.El +.RE + +.SH "KEYBINDINGS" +.PP +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 +\fIkeybinds\fP 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: +.RS +.PP +.nf +keybinds: + normal: + \- action: [ NewTab, GoToTab: 1,] + key: [ Char: 'c',] +.fi +.RE +.PP +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)\. + +.SS "ACTIONS" +.RS +.Bl +.IP \(bu 4 +\fBQuit\fP \- quits Zellij +.El +.Bl +.IP \(bu 4 +\fBSwitchToMode: \fP \- switches to the specified input mode\. See +MODES section for possible values\. +.El +.Bl +.IP \(bu 4 +\fBResize: \fP \- resizes focused pane in the specified direction +(one of: Left, Right, Up, Down)\. +.El +.Bl +.IP \(bu 4 +\fBFocusNextPane\fP \- switches focus to the next pane to the right or below if +on screen edge\. +.El +.Bl +.IP \(bu 4 +\fBFocusPreviousPane\fP \- switches focus to the next pane to the left or above +if on screen edge\. +.El +.Bl +.IP \(bu 4 +\fBSwitchFocus\fP \- left for legacy support\. Switches focus to a pane with the +next ID\. +.El +.Bl +.IP \(bu 4 +\fBMoveFocus: \fP \- moves focus in the specified direction (Left, +Right, Up, Down)\. +.El +.Bl +.IP \(bu 4 +\fBScrollUp\fP \- scrolls up 1 line in the focused pane\. +.El +.Bl +.IP \(bu 4 +\fBScrollDown\fP \- scrolls down 1 line in the focused pane\. +.El +.Bl +.IP \(bu 4 +\fBToggleFocusFullscreen\fP \- toggles between fullscreen focus pane and normal +layout\. +.El +.Bl +.IP \(bu 4 +\fBNewPane: \fP \- opens a new pane in the specified direction (Left, +Right, Up, Down) relative to focus\. +.El +.Bl +.IP \(bu 4 +\fBCloseFocus\fP \- closes focused pane\. +.El +.Bl +.IP \(bu 4 +\fBNewTab\fP \- creates a new tab\. +.El +.Bl +.IP \(bu 4 +\fBGoToNextTab\fP \- goes to the next tab\. +.El +.Bl +.IP \(bu 4 +\fBGoToPreviousTab\fP \- goes to previous tab\. +.El +.Bl +.IP \(bu 4 +\fBCloseTab\fP \- closes current tab\. +.El +.Bl +.IP \(bu 4 +\fBGoToTab: \fP \- goes to the tab with the specified index number\. +.El +.RE + +.SS "KEYS" +.RS +.Bl +.IP \(bu 4 +\fBChar: \fP \- a single character with no modifier\. +.El +.Bl +.IP \(bu 4 +\fBAlt: \fP \- a single character with `\f[CR]Alt\fP` key as modifier\. +.El +.Bl +.IP \(bu 4 +\fBCtrl: \fP \- a single character with `\f[CR]Ctrl\fP` key as modifier\. +.El +.Bl +.IP \(bu 4 +\fBF: <1\-12>\fP \- one of `\f[CR]F\fP` keys (usually at the top of the keyboard)\. +.El +.Bl +.IP \(bu 4 +\fBBackspace\fP +.El +.Bl +.IP \(bu 4 +\fBLeft / Right / Up / Down\fP \- arrow keys on the keyboard\. +.El +.Bl +.IP \(bu 4 +\fBHome\fP +.El +.Bl +.IP \(bu 4 +\fBEnd\fP +.El +.Bl +.IP \(bu 4 +\fBPageUp / PageDown\fP +.El +.Bl +.IP \(bu 4 +\fBBackTab\fP \- a backward Tab key\. +.El +.Bl +.IP \(bu 4 +\fBDelete\fP +.El +.Bl +.IP \(bu 4 +\fBInsert\fP +.El +.Bl +.IP \(bu 4 +\fBEsc\fP +.El +.RE + +.SS "MODES" +.RS +.Bl +.IP \(bu 4 +\fBnormal\fP \- the default startup mode of Zellij\. Provides the ability to +switch to different modes, as well as some quick navigation shortcuts\. +.El +.Bl +.IP \(bu 4 +\fBlocked\fP \- disables all keybindings except the one that would switch the +mode to normal (\fIctrl\-g\fP by default)\. Useful when Zellij's keybindings +conflict with those of a chosen terminal app\. +.El +.Bl +.IP \(bu 4 +\fBpane\fP \- includes instructions that manipulate the panes (adding new panes, +moving, closing)\. +.El +.Bl +.IP \(bu 4 +\fBtab\fP \- includes instructions that manipulate the tabs (adding new tabs, +moving, closing)\. +.El +.Bl +.IP \(bu 4 +\fBresize\fP \- allows resizing of the focused pane\. +.El +.Bl +.IP \(bu 4 +\fBscroll\fP \- allows scrolling within the focused pane\. +.El +.Bl +.IP \(bu 4 +\fBRenameTab\fP \- is a "hidden" mode that can be passed to \fISwitchToMode\fP +action\. It will trigger renaming of a tab\. +.El +.RE + +.SH "PLUGINS" +.PP +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: \fIstatus\-bar\fP, \fIstrider\fP, +\fItab\-bar\fP\. + +.SH "FILES" +.PP +Default user configuration file location: +.RS +.Bl +.IP \(bu 4 +Linux: \fI/home/alice/\.config/zellij\fP +.El +.Bl +.IP \(bu 4 +macOS: \fI/Users/Alice/Library/Application Support/com\.Zellij\-Contributors\.zellij\fP +.El +.RE + +.SH "ENVIRONMENT" +.PP +ZELLIJ_CONFIG +Path of Zellij config to load\. + +.SH "NOTES" +.PP +The manpage is meant to provide concise offline reference\. For more detailed +instructions please visit: +.PP +https://zellij\.dev/documentation diff --git a/docs/MANPAGE.md b/docs/MANPAGE.md new file mode 100644 index 00000000..6ef937c1 --- /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: __ - 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: __ +* __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: __ - switches to the specified input mode. See + MODES section for possible values. +* __Resize: __ - 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: __ - 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: __ - 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: __ - goes to the tab with the specified index number. + +KEYS +---- + +* __Char: __ - a single character with no modifier. +* __Alt: __ - a single character with `Alt` key as modifier. +* __Ctrl: __ - 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 From 4ebf0c8c44eca2612d5d10c318ad227b5f07fd0a Mon Sep 17 00:00:00 2001 From: NKGoc Date: Tue, 4 May 2021 20:53:23 +0200 Subject: [PATCH 02/10] remove description added when making sense out of cargo make --- Makefile.toml | 1 - 1 file changed, 1 deletion(-) diff --git a/Makefile.toml b/Makefile.toml index c68d7223..60ad31ca 100644 --- a/Makefile.toml +++ b/Makefile.toml @@ -6,7 +6,6 @@ SKIP_TEST = false # Add clippy to the default flow [tasks.dev-test-flow] -description = "Defines the default developer build flow with tests." dependencies = [ "format-flow", "format-toml-conditioned-flow", From ba99c379cc6d47415f883142c4053faf0197c880 Mon Sep 17 00:00:00 2001 From: NKGoc Date: Tue, 4 May 2021 21:06:48 +0200 Subject: [PATCH 03/10] typo fix --- Makefile.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile.toml b/Makefile.toml index 60ad31ca..86543f6d 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", "manpages-install"] +dependencies = ["build-plugins-release", "wasm-opt-plugins", "build-release", "manpage-install"] script_runner = "@duckscript" script = ''' if is_dir ${CARGO_MAKE_TASK_ARGS} From 3f300bf834fa7d5ae5b956ca08265b4da9110ebd Mon Sep 17 00:00:00 2001 From: NKGoc Date: Wed, 5 May 2021 11:48:47 +0200 Subject: [PATCH 04/10] simplifications --- Makefile.toml | 6 ------ 1 file changed, 6 deletions(-) diff --git a/Makefile.toml b/Makefile.toml index 86543f6d..b4821278 100644 --- a/Makefile.toml +++ b/Makefile.toml @@ -131,9 +131,3 @@ args = ["publish"] description = "Use mandown crate to create or update man entry from docs/MANPAGES.md" workspace = false script = "mandown docs/MANPAGE.md ZELLIJ 1 > assets/man/zellij.1" - -[tasks.manpage-install] -description = "Install manpage from assets" -workspace = false -command = "sudo" -args = ["cp", "assets/man/zellij.1", "/usr/share/man/man1/"] From 0ab7a51d04ae195dc894a196beba3d9813fbf0f6 Mon Sep 17 00:00:00 2001 From: NKGoc Date: Wed, 5 May 2021 12:05:05 +0200 Subject: [PATCH 05/10] simplifications --- CONTRIBUTING.md | 4 +++- Cargo.toml | 1 - Makefile.toml | 6 ------ 3 files changed, 3 insertions(+), 8 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 96659dce..5294e501 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -14,7 +14,7 @@ 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. @@ -37,6 +37,8 @@ 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`. diff --git a/Cargo.toml b/Cargo.toml index 24fb4d92..24249272 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -48,7 +48,6 @@ features = ["unstable"] [dev-dependencies] insta = "1.6.0" tempfile = "3.2.0" -mandown = "0.1.2" [build-dependencies] structopt = "0.3" diff --git a/Makefile.toml b/Makefile.toml index 86543f6d..b4821278 100644 --- a/Makefile.toml +++ b/Makefile.toml @@ -131,9 +131,3 @@ args = ["publish"] description = "Use mandown crate to create or update man entry from docs/MANPAGES.md" workspace = false script = "mandown docs/MANPAGE.md ZELLIJ 1 > assets/man/zellij.1" - -[tasks.manpage-install] -description = "Install manpage from assets" -workspace = false -command = "sudo" -args = ["cp", "assets/man/zellij.1", "/usr/share/man/man1/"] From 24b4ae831c3a322025b94b5dfc4a5d5387495fbf Mon Sep 17 00:00:00 2001 From: NKGoc Date: Wed, 5 May 2021 12:07:47 +0200 Subject: [PATCH 06/10] wrapped lines in CONTRIBUTING.md --- CONTRIBUTING.md | 67 ++++++++++++++++++++++++++++++------------------- 1 file changed, 41 insertions(+), 26 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5294e501..b8efe437 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 edit a manpage mandown crate (`cargo install mandown`) is used and the work is done on a markdown file in docs/MANPAGE.md. +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: @@ -41,17 +44,18 @@ cargo make publish 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 @@ -60,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? @@ -72,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? @@ -80,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`. From 6d826dcae0cc6003c2a8e318f3f8bb7d6b59cc7e Mon Sep 17 00:00:00 2001 From: NKGoc Date: Wed, 5 May 2021 12:58:20 +0200 Subject: [PATCH 07/10] Removing generated manpage --- .gitignore | 3 +- assets/man/zellij.1 | 339 -------------------------------------------- 2 files changed, 2 insertions(+), 340 deletions(-) delete mode 100644 assets/man/zellij.1 diff --git a/.gitignore b/.gitignore index f211f382..54137021 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/assets/man/zellij.1 b/assets/man/zellij.1 deleted file mode 100644 index f2e600c0..00000000 --- a/assets/man/zellij.1 +++ /dev/null @@ -1,339 +0,0 @@ -.TH "ZELLIJ" 1 - -.SH "NAME" -.PP -\fBzellij\fP \- run zellij - -.SH "DESCRIPTION" -.PP -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\. -.PP -Zellij includes a layout system, and a plugin system allowing one to create -plugins in any language that compiles to WebAssembly\. - -.SH "OPTIONS" -.PP -Run `\f[CR]zellij \-\-help\fP` to see available flags and subcommamds\. - -.SH "CONFIGURATION" -.PP -Zellij looks for configuration file in the following order: -.RS -.Bl -.IP 1. 4 -the file provided with \fI\-\-config\fP -.El -.Bl -.IP 2. 4 -under the path provided in \fIZELLIJ_CONFIG\fP environment variable -.El -.Bl -.IP 3. 4 -the default location (see FILES section) -.El -.RE - -.SH "LAYOUTS" -.PP -Layouts are yaml files which Zellij can load on startup when \fI\-\-layout\fP flag is -provided\. -.PP -For example a file like this: -.RS -.PP -.nf -\-\-\- -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 -.fi -.RE -.PP -will tell Zellij to create this layout: -.RS -.PP -.nf -+\-\-\-\-\-+\-\-\-\-\-+ -| | | -+\-\-\-\-\-+ | -| | | -+\-\-\-\-\-+\-\-\-\-\-+ -.fi -.RE - -.SS "CREATING LAYOUTS" -.PP -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\. -.PP -Each node has following fields: -.RS -.Bl -.IP \(bu 4 -\fBdirection: \fP \- node's children will be created by a -split in given direction\. -.El -.Bl -.IP \(bu 4 -\fBsplit_size:\fP \- this indicates either a percentage of the node's parent's -space or a fixed size of columns/rows from its parent's space\. -.RS -.Bl -.IP \(bu 4 -\fBPercent: <1\-100>\fP -.El -.Bl -.IP \(bu 4 -\fBFixed: \fP -.El -.RE -.El -.Bl -.IP \(bu 4 -\fBplugin: /path/to/plugin\.wasm\fP \- optional path to a compiled Zellij plugin\. -If indicated loads a plugin into the created space\. For more information see -PLUGINS section\. -.El -.RE - -.SH "KEYBINDINGS" -.PP -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 -\fIkeybinds\fP 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: -.RS -.PP -.nf -keybinds: - normal: - \- action: [ NewTab, GoToTab: 1,] - key: [ Char: 'c',] -.fi -.RE -.PP -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)\. - -.SS "ACTIONS" -.RS -.Bl -.IP \(bu 4 -\fBQuit\fP \- quits Zellij -.El -.Bl -.IP \(bu 4 -\fBSwitchToMode: \fP \- switches to the specified input mode\. See -MODES section for possible values\. -.El -.Bl -.IP \(bu 4 -\fBResize: \fP \- resizes focused pane in the specified direction -(one of: Left, Right, Up, Down)\. -.El -.Bl -.IP \(bu 4 -\fBFocusNextPane\fP \- switches focus to the next pane to the right or below if -on screen edge\. -.El -.Bl -.IP \(bu 4 -\fBFocusPreviousPane\fP \- switches focus to the next pane to the left or above -if on screen edge\. -.El -.Bl -.IP \(bu 4 -\fBSwitchFocus\fP \- left for legacy support\. Switches focus to a pane with the -next ID\. -.El -.Bl -.IP \(bu 4 -\fBMoveFocus: \fP \- moves focus in the specified direction (Left, -Right, Up, Down)\. -.El -.Bl -.IP \(bu 4 -\fBScrollUp\fP \- scrolls up 1 line in the focused pane\. -.El -.Bl -.IP \(bu 4 -\fBScrollDown\fP \- scrolls down 1 line in the focused pane\. -.El -.Bl -.IP \(bu 4 -\fBToggleFocusFullscreen\fP \- toggles between fullscreen focus pane and normal -layout\. -.El -.Bl -.IP \(bu 4 -\fBNewPane: \fP \- opens a new pane in the specified direction (Left, -Right, Up, Down) relative to focus\. -.El -.Bl -.IP \(bu 4 -\fBCloseFocus\fP \- closes focused pane\. -.El -.Bl -.IP \(bu 4 -\fBNewTab\fP \- creates a new tab\. -.El -.Bl -.IP \(bu 4 -\fBGoToNextTab\fP \- goes to the next tab\. -.El -.Bl -.IP \(bu 4 -\fBGoToPreviousTab\fP \- goes to previous tab\. -.El -.Bl -.IP \(bu 4 -\fBCloseTab\fP \- closes current tab\. -.El -.Bl -.IP \(bu 4 -\fBGoToTab: \fP \- goes to the tab with the specified index number\. -.El -.RE - -.SS "KEYS" -.RS -.Bl -.IP \(bu 4 -\fBChar: \fP \- a single character with no modifier\. -.El -.Bl -.IP \(bu 4 -\fBAlt: \fP \- a single character with `\f[CR]Alt\fP` key as modifier\. -.El -.Bl -.IP \(bu 4 -\fBCtrl: \fP \- a single character with `\f[CR]Ctrl\fP` key as modifier\. -.El -.Bl -.IP \(bu 4 -\fBF: <1\-12>\fP \- one of `\f[CR]F\fP` keys (usually at the top of the keyboard)\. -.El -.Bl -.IP \(bu 4 -\fBBackspace\fP -.El -.Bl -.IP \(bu 4 -\fBLeft / Right / Up / Down\fP \- arrow keys on the keyboard\. -.El -.Bl -.IP \(bu 4 -\fBHome\fP -.El -.Bl -.IP \(bu 4 -\fBEnd\fP -.El -.Bl -.IP \(bu 4 -\fBPageUp / PageDown\fP -.El -.Bl -.IP \(bu 4 -\fBBackTab\fP \- a backward Tab key\. -.El -.Bl -.IP \(bu 4 -\fBDelete\fP -.El -.Bl -.IP \(bu 4 -\fBInsert\fP -.El -.Bl -.IP \(bu 4 -\fBEsc\fP -.El -.RE - -.SS "MODES" -.RS -.Bl -.IP \(bu 4 -\fBnormal\fP \- the default startup mode of Zellij\. Provides the ability to -switch to different modes, as well as some quick navigation shortcuts\. -.El -.Bl -.IP \(bu 4 -\fBlocked\fP \- disables all keybindings except the one that would switch the -mode to normal (\fIctrl\-g\fP by default)\. Useful when Zellij's keybindings -conflict with those of a chosen terminal app\. -.El -.Bl -.IP \(bu 4 -\fBpane\fP \- includes instructions that manipulate the panes (adding new panes, -moving, closing)\. -.El -.Bl -.IP \(bu 4 -\fBtab\fP \- includes instructions that manipulate the tabs (adding new tabs, -moving, closing)\. -.El -.Bl -.IP \(bu 4 -\fBresize\fP \- allows resizing of the focused pane\. -.El -.Bl -.IP \(bu 4 -\fBscroll\fP \- allows scrolling within the focused pane\. -.El -.Bl -.IP \(bu 4 -\fBRenameTab\fP \- is a "hidden" mode that can be passed to \fISwitchToMode\fP -action\. It will trigger renaming of a tab\. -.El -.RE - -.SH "PLUGINS" -.PP -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: \fIstatus\-bar\fP, \fIstrider\fP, -\fItab\-bar\fP\. - -.SH "FILES" -.PP -Default user configuration file location: -.RS -.Bl -.IP \(bu 4 -Linux: \fI/home/alice/\.config/zellij\fP -.El -.Bl -.IP \(bu 4 -macOS: \fI/Users/Alice/Library/Application Support/com\.Zellij\-Contributors\.zellij\fP -.El -.RE - -.SH "ENVIRONMENT" -.PP -ZELLIJ_CONFIG -Path of Zellij config to load\. - -.SH "NOTES" -.PP -The manpage is meant to provide concise offline reference\. For more detailed -instructions please visit: -.PP -https://zellij\.dev/documentation From b70d73a5810e14fd41d0217ec4ca82c1c42802c0 Mon Sep 17 00:00:00 2001 From: NKGoc Date: Wed, 5 May 2021 13:16:58 +0200 Subject: [PATCH 08/10] new tasks to install mandown and generate manpage --- Makefile.toml | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/Makefile.toml b/Makefile.toml index b4821278..0ff37fd9 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", "manpage-install"] +dependencies = ["build-plugins-release", "wasm-opt-plugins", "build-release", "manpage"] script_runner = "@duckscript" script = ''' if is_dir ${CARGO_MAKE_TASK_ARGS} @@ -96,7 +96,7 @@ end # CI Releasing Zellij [tasks.ci-build-release] workspace = false -dependencies = ["setup-cross-compilation", "build-plugins-release", "wasm-opt-plugins"] +dependencies = ["setup-cross-compilation", "install-mandown", "build-plugins-release", "wasm-opt-plugins", "manpage"] command = "cross" args = ["build", "--verbose", "--release", "--target", "${CARGO_MAKE_TASK_ARGS}"] @@ -104,6 +104,10 @@ args = ["build", "--verbose", "--release", "--target", "${CARGO_MAKE_TASK_ARGS}" command = "cargo" args = ["install", "cross"] +[tasks.install-mandown] +command = "cargo" +args = ["install", "mandown"] + # Publishing Zellij [tasks.publish] clear = true From 0003f8268f3e3353d9302de833a1e07cfda829ef Mon Sep 17 00:00:00 2001 From: NKGoc Date: Wed, 5 May 2021 13:20:26 +0200 Subject: [PATCH 09/10] new tasks to install mandown and generate manpage --- Makefile.toml | 22 ++++++++++++++++------ 1 file changed, 16 insertions(+), 6 deletions(-) diff --git a/Makefile.toml b/Makefile.toml index b4821278..f82a44b5 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", "manpage-install"] +dependencies = ["build-plugins-release", "wasm-opt-plugins", "build-release", "manpage"] script_runner = "@duckscript" script = ''' if is_dir ${CARGO_MAKE_TASK_ARGS} @@ -93,10 +93,15 @@ for plugin in ${plugins} end ''' +[tasks.manpage] +description = "Use mandown crate to create or update man entry from docs/MANPAGES.md" +workspace = false +script = "mandown docs/MANPAGE.md ZELLIJ 1 > assets/man/zellij.1" + # CI Releasing Zellij [tasks.ci-build-release] workspace = false -dependencies = ["setup-cross-compilation", "build-plugins-release", "wasm-opt-plugins"] +dependencies = ["setup-cross-compilation", "install-mandown", "build-plugins-release", "wasm-opt-plugins", "ci-manpage"] command = "cross" args = ["build", "--verbose", "--release", "--target", "${CARGO_MAKE_TASK_ARGS}"] @@ -104,6 +109,14 @@ args = ["build", "--verbose", "--release", "--target", "${CARGO_MAKE_TASK_ARGS}" command = "cargo" args = ["install", "cross"] +[tasks.install-mandown] +command = "cargo" +args = ["install", "mandown"] + +[tasks.ci-manpage] +script = "mandown docs/MANPAGE.md ZELLIJ 1 > assets/man/zellij.1" +dependencies = ["install-mandown"] + # Publishing Zellij [tasks.publish] clear = true @@ -127,7 +140,4 @@ args = ["publish"] command = "cargo" args = ["publish"] -[tasks.manpage] -description = "Use mandown crate to create or update man entry from docs/MANPAGES.md" -workspace = false -script = "mandown docs/MANPAGE.md ZELLIJ 1 > assets/man/zellij.1" + From b504a5379e21780bef8e728f6a406bfec02c7491 Mon Sep 17 00:00:00 2001 From: NKGoc Date: Wed, 5 May 2021 14:16:53 +0200 Subject: [PATCH 10/10] auto install mandown if it's not there (tested with Manjaro repositories) --- Makefile.toml | 18 +++++++----------- 1 file changed, 7 insertions(+), 11 deletions(-) diff --git a/Makefile.toml b/Makefile.toml index cb1ec120..7f7cdef1 100644 --- a/Makefile.toml +++ b/Makefile.toml @@ -95,14 +95,18 @@ end [tasks.manpage] description = "Use mandown crate to create or update man entry from docs/MANPAGES.md" -workspace = false 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", "install-mandown", "build-plugins-release", "wasm-opt-plugins", "ci-manpage"] - +dependencies = ["setup-cross-compilation", "build-plugins-release", "wasm-opt-plugins", "manpage"] command = "cross" args = ["build", "--verbose", "--release", "--target", "${CARGO_MAKE_TASK_ARGS}"] @@ -110,14 +114,6 @@ args = ["build", "--verbose", "--release", "--target", "${CARGO_MAKE_TASK_ARGS}" command = "cargo" args = ["install", "cross"] -[tasks.install-mandown] -command = "cargo" -args = ["install", "mandown"] - -[tasks.ci-manpage] -script = "mandown docs/MANPAGE.md ZELLIJ 1 > assets/man/zellij.1" -dependencies = ["install-mandown"] - # Publishing Zellij [tasks.publish] clear = true