diff --git a/Cargo.toml b/Cargo.toml index a1f260cc9..24fb4d924 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 1d11f0d1a..c68d7223a 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 000000000..f2e600c00 --- /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 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: __ - 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