Merge pull request #455 from Adhalianna/main

Add a manpage to Zellij

.gitignore

@@ -3,3 +3,4 @@
 .vscode
 .vim
 .DS_Store 
+/assets/man/zellij.1

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
+**First**: if you're unsure or afraid of anything, just ask on our [Discord
-[Discord server][discord-invite-link] or submit the issue or pull request anyway.
+server][discord-invite-link] or submit the issue or pull request anyway. You
-You won't be yelled at for giving it your best effort. The worst that can happen
+won't be yelled at for giving it your best effort. The worst that can happen is
-is that you'll be politely asked to change something. We appreciate any sort
+that you'll be politely asked to change something. We appreciate any sort of
-of contributions, and don't want a wall of rules to get in the way of that.
+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]
+If you are new contributor to `Zellij` going through
-should be a good start or you can join our public
+[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
+[Discord server][discord-invite-link], we would be happy to help finding
-finding something interesting to work on and guide through.
+something interesting to work on and guide through.
 
-[discord-invite-link]: https://discord.gg/feHDHahHCz
+[discord-invite-link]: https://discord.gg/feHDHahHCz [good-first-issue]:
-[good-first-issue]: https://github.com/zellij-org/zellij/labels/good%20first%20issue
+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.
+- Use a **clear and descriptive title** for the issue to identify the
-- Provide a **description of the suggested enhancement** in as many details as necessary.
+  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/)
+    - Follow [Conventional Commit
-where sufficiently large or impactful change is made.
+      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`.

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"],

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}"]
 
@@ -126,3 +136,5 @@ args = ["publish"]
 [tasks.publish-zellij]
 command = "cargo"
 args = ["publish"]
+
+

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