diff options
| author | Dave Davenport <DaveDavenport@users.noreply.github.com> | 2021-10-29 14:00:22 +0200 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2021-10-29 14:00:22 +0200 |
| commit | b1dff0c2114d44059cd95f53bf604eaec222d9f8 (patch) | |
| tree | 762d39ae79b18793af0d7a956f9425292c9f9304 | |
| parent | 8db289d065319e76242b78cdcc4836e5ccd038a0 (diff) | |
Update to documentation by RaZ0rr-Two (#1495)
* Update readme 1 (manpages)
* Update 2 (create config.md)
* README update final 1
* Rename to CONFIG
* README update final 2
* small update
* Aligning the top to center
* Corrected dead links
* gif (mp4) added
Co-authored-by: RaZ0rr-Two <84911063+RaZ0rr-Two@users.noreply.github.com>
| -rw-r--r-- | CONFIG.md | 200 | ||||
| -rw-r--r-- | README.md | 148 |
2 files changed, 321 insertions, 27 deletions
diff --git a/CONFIG.md b/CONFIG.md new file mode 100644 index 00000000..ba4876b5 --- /dev/null +++ b/CONFIG.md @@ -0,0 +1,200 @@ +> # :warning: This page does not describe all of **ROFI**'s configuration options, just the most common usecase. For the full configuration options, check the manpages. + +<br /> + + +## :exclamation: Upgrade from old configuration format to new :exclamation: + +In release after '2 Jan 2020' you can convert to the new configuration format by using the following command: + +```bash +rofi -upgrade-config +``` + +This will create `~/.config/rofi/config.rasi` (or the default location for your system) with the previously configured options. + +From 1.7.0 the old configuration format is no longer supported and the `-upgrade-config` option is no longer available. + +<br /> + +# Where does the configuration live + +Rofi's configurations, custom themes live in `${XDG_CONFIG_HOME}/rofi/`, on most systems this is `~/.config/rofi/`. + +The name of the main configuration file is `config.rasi`. (`~/.config/rofi/config.rasi`). + +# Create an empty configuration file + +Open `~/.config/rofi/config.rasi` in your favorite text editor and add the following block: + +```css +configuration { + +} +``` +You can now set the options in the `configuration` block. + +# Create a configuration file from current setup + +If you do not want to start from scratch, or want to migrate from older configuration format, you can get tell rofi to dumps it configuration: + +```bash +rofi -dump-config > ~/.config/rofi/config.rasi +``` + +This will have all the possible settings and their current value. +If a value is the default value, the entry will be commented. + +For example: +```css +configuration { +/* modi: "window,run,ssh,drun";*/ +/* font: "mono 12";*/ +/* location: 0;*/ +/* yoffset: 0;*/ +/* xoffset: 0;*/ +/* fixed-num-lines: true;*/ +... cut ... +/* ml-row-down: "ScrollDown";*/ +/* me-select-entry: "MousePrimary";*/ +/* me-accept-entry: "MouseDPrimary";*/ +/* me-accept-custom: "Control+MouseDPrimary";*/ +} +``` + +# Configuration file format + +## Encoding + +The encoding of the file is utf-8. Both Unix (`\n`) and windows (`\r\n`) newlines format are supported. But Unix is preferred. + +## Comments + +C and C++ file comments are supported. + +* Anything after `// ` and before a newline is considered a comment. +* Everything between `/*` and `*/` is a comment. + +Comments can be nested and the C comments can be inline. + +The following is valid: + +``` +// Magic comment. +property: /* comment */ value; +``` + +However, this is not: + +``` +prop/*comment*/erty: value; +``` + +## White space + +White space and newlines, like comments, are ignored by the parser. + +This: + +``` +property: name; +``` + +Is identical to: + +``` + property : +name + +; +``` + +## Data types + +**ROFI**'s configuration supports several data formats: + +### String + +A string is always surrounded by double quotes (`"`). Between the quotes there can be any printable character. + +For example: + +```css + + ml-row-down: "ScrollDown"; +``` + +### Number + +An integer may contain any full number. + +For example: + +``` +eh: 2; +``` + +### Boolean + +Boolean value is either `true` or `false`. This is case-sensitive. + +For example: + +```css +show-icons: true; +``` + +This is equal to the `-show-icons` option on the commandline, and `show-icons: false;` is equal to `-no-show-icons`. + +### Character + +Character value is always surrounded by single quotes (') and should contain a single character. +It supports escaping. + +```css +matching-negate-char: '-'; +``` + +### List + +This is not supported by the old configuration system, but can be used in the **rasi** format. + +A list starts with a '[' and ends with a ']'. The entries in the list are comma-separated. +The entry in the list single ASCII words. + +```css + combi-modi: [window,drun]; +``` +For older versions you have : + +```css + combi-modi: "window,drun"; +``` + +# Get a list of all possible options + +There are 2 ways to get a list of all options: + +1. Dump the configuration file explained above. (`rofi -dump-config`) +2. Look at output of `rofi -h`. + +To see what values an option support check the manpage, it describes most of them. + +NOTE: not all options might be in the manpage, as options can be added at run-time. (f.e. by plugins). + + +# Splitting configuration over multiple files + +It is possible to split configuration over multiple files using imports. For example in `~/.config/rofi/config.rasi` + +```css +configuration { +} +@import "myConfig" +@theme "MyTheme" + +``` + +Rofi will first parse the config block in `~/.config/rofi/config.rasi`, then parse `~/.config/rofi/myConfig.rasi` and then load the theme `myTheme`.\ +More information can be obtained from **Themes** section\ +Imports can be nested. @@ -1,11 +1,19 @@ -[](https://github.com/davatorium/rofi/issues) -[](https://github.com/davatorium/rofi/network) -[](https://github.com/davatorium/rofi/stargazers) -[](https://github.com/davatorium/rofi/releases) -[](https://github.com/davatorium/rofi/discussions) -[](https://repology.org/metapackage/rofi/versions) +<p align="center"> +<a href="https://github.com/davatorium/rofi/issues"><img src="https://img.shields.io/github/issues/davatorium/rofi.svg"></a> +<a href="https://img.shields.io/github/forks/davatorium/rofi.svg"><img src="https://img.shields.io/github/forks/davatorium/rofi.svg"></a> +<a href="https://github.com/davatorium/rofi/stargazers"><img src="https://img.shields.io/github/stars/davatorium/rofi.svg"></a> +<a href="https://github.com/davatorium/rofi/releases"><img src="https://img.shields.io/github/downloads/davatorium/rofi/total.svg"></a> +<a href="https://github.com/davatorium/rofi/discussions"><img src="https://img.shields.io/badge/forum-online-green.svg"></a> +<a href="https://repology.org/metapackage/rofi/versions"><img src="https://repology.org/badge/tiny-repos/rofi.svg"></a> +</p> + +<h1 align="center"> + Rofi +</h1> +<p align="center"><i>A window switcher, Application launcher and dmenu replacement</i>.</p> + +https://user-images.githubusercontent.com/84911063/139428874-fe182dd6-82c6-49b8-8da1-920ddda3d1ed.mp4 -# A window switcher, Application launcher and dmenu replacement **Rofi** started as a clone of simpleswitcher, written by [Sean Pringle](http://github.com/seanpringle/simpleswitcher) - a popup window switcher roughly based on [superswitcher](http://code.google.com/p/superswitcher/). @@ -16,6 +24,34 @@ ssh-launcher, and can act as a drop-in dmenu replacement, making it a very versa **Rofi**, like dmenu, will provide the user with a textual list of options where one or more can be selected. This can either be running an application, selecting a window, or options provided by an external script. + +## What is rofi not? + +Rofi is not: + +* A UI toolkit. +* A library to be used in other applications. +* An application that can support every possible use-case. It tries to be generic enough to be usable by everybody. + * Specific functionality can be added using scripts or plugins, many exists. +* Just a dmenu replacement. The dmenu functionality is a nice 'extra' to **rofi**, not its main purpose. + + +# Table of Contents + +- [Features](#features) +- [Modi](#modi) +- [Manpages]($manpage) +- [Installation](#installation) +- [Quickstart](#quickstart) + - [Usage](#usage) + - [Configuration](#configuration) + - [Themes]($themes) +- [Screenshots](#screenshots) +- [Wiki](#wiki) +- [Discussion places](#discussion-places) + +# Features + Its main features are: * Fully configurable keyboard navigation @@ -42,6 +78,8 @@ Its main features are: * Easily extensible using scripts and plugins * Advanced Theming +# Modi + **Rofi** has several built-in modi implementing common use cases and can be extended by scripts (either called from **Rofi** or calling **Rofi**) or plugins. @@ -58,39 +96,95 @@ Below is a list of the different modi: **Rofi** is known to work on Linux and BSD. - -# Screenshots - - - - - # Manpage -For more up to date information, please see the manpages: +For more up to date information, please see the manpages. The other sections and links might have outdated information as they have relatively less maintainance than the manpages. So, if you come across any issues please consult manpages, [discussion](https://github.com/davatorium/rofi/discussions) and [issue traker](https://github.com/davatorium/rofi/issues?q=) before filing new issue. * Manpages: * [rofi](doc/rofi.1.markdown) * [rofi-theme](doc/rofi-theme.5.markdown) * [rofi-script](doc/rofi-script.5.markdown) * [rofi-theme-selector](doc/rofi-theme-selector.1.markdown) - * Discussion places: - * [Reddit](https://reddit.com/r/qtools/) - * [GitHub Discussions](https://github.com/davatorium/rofi/discussions) - * IRC (#rofi on irc.libera.chat) - * [wiki](https://github.com/davatorium/rofi/wiki) (Currently unmaintained). # Installation Please see the [installation guide](https://github.com/davatorium/rofi/blob/next/INSTALL.md) for instructions on how to install **Rofi**. -# What is rofi not? +# Quickstart -Rofi is not: +## Usage -* A UI toolkit. -* A library to be used in other applications. -* An application that can support every possible use-case. It tries to be generic enough to be usable by everybody. - * Specific functionality can be added using scripts or plugins, many exists. -* Just a dmenu replacement. The dmenu functionality is a nice 'extra' to **rofi**, not its main purpose. +> **This section just gives a brief overview of the various options. To get the full set of options see the _manpages_ section above** + +#### Running rofi + +To launch **rofi** directly in a certain mode, specify a mode with `rofi -show <mode>`. +To show the `run` dialog: + + rofi -show run + +Or get the options from a script: + + ~/my_script.sh | rofi -dmenu + +Specify an ordered, comma-separated list of modes to enable. +Enabled modes can be changed at runtime. Default key is `Ctrl+Tab`. +If no modes are specified, all configured modes will be enabled. +To only show the `run` and `ssh` launcher: + + rofi -modi "run,ssh" -show run + + +The modi to combine in combi mode. +For syntax to `-combi-modi`, see `-modi`. +To get one merge view, of `window`,`run`, and `ssh`: + + rofi -show combi -combi-modi "window,run,ssh" -modi combi + +## Configuration + +Generate a default configuration file +``` +mkdir -p ~/.config/rofi +rofi -dump-config > ~/.config/rofi/config.rasi +``` + +This creates a file called `config.rasi` in the `~/.config/rofi/` folder. You can modify this file to set configuration settings and modify themes. `config.rasi` is the file rofi looks to by default. + +Please see the [configuration guide](https://github.com/davatorium/rofi/blob/next/CONFIG.md) for a summary of configuration options. More detailed options are provided in the manpages. + +## Themes + +Please see the [themes](https://github.com/davatorium/rofi/wiki/themes) section from the [wiki](https://github.com/davatorium/rofi/wiki) for brief reference. More detailed options are provided in the [themes manpages](https://github.com/davatorium/rofi/blob/next/doc/rofi-theme.5.markdown). + +# Screenshots + + + + + +# Wiki + +| ❗ **The Wiki is Community maintained and are not thoroughly tested** | +| --- | + +[Go to wiki](https://github.com/davatorium/rofi/wiki) . + +#### Contents + +* [User scripts](https://github.com/davatorium/rofi/wiki/User-scripts) +* [dmenu Specs](https://github.com/davatorium/rofi/wiki/dmenu_specs) +* [mode Specs](https://github.com/davatorium/rofi/wiki/mode-Specs) +* [F.A.Q.](https://github.com/davatorium/rofi/wiki/Frequently-Asked-Questions). +* [Script mode](https://github.com/davatorium/rofi/wiki/rfc-script-mode) +* [Debugging](https://github.com/davatorium/rofi/wiki/Debugging-Rofi) +* [Creating an issue](https://github.com/davatorium/rofi/blob/master/.github/CONTRIBUTING.md) +* [FORUM](https://reddit.com/r/qtools/) +* [Creating a Pull request](https://github.com/davatorium/rofi/wiki/Creating-a-pull-request) + +# Discussion places: + + * [Reddit](https://reddit.com/r/qtools/) + * [GitHub Discussions](https://github.com/davatorium/rofi/discussions) + * IRC (#rofi on irc.libera.chat) |