diff --git a/doc/rofi.1 b/doc/rofi.1 index b4a12032..21ea57ab 100644 --- a/doc/rofi.1 +++ b/doc/rofi.1 @@ -1,1664 +1,1692 @@ -.\" generated with Ronn/v0.7.3 -.\" http://github.com/rtomayko/ronn/tree/0.7.3 -. -.TH "ROFI" "1" "January 2020" "" "" -. -.SH "NAME" -\fBrofi\fR \- A window switcher, application launcher, ssh dialog and dmenu replacement -. -.SH "SYNOPSIS" -\fBrofi\fR [ \-show \fImode\fR ]|[ \-dmenu ]|[ \-e \fImsg\fR ] [ CONFIGURATION ] -. -.SH "DESCRIPTION" -\fBrofi\fR is an X11 pop\-up window switcher, run dialog, dmenu replacement, and more\. It focuses on being fast to use and have minimal distraction\. It supports keyboard and mouse navigation, type to filter, tokenized search and more\. -. -.SH "USAGE" -\fBrofi\fR\'s main functionality is to assist in your workflow, allowing you to quickly switch between windows, start applications or log into a remote machine via ssh\. There are different \fImodi\fR for different types of actions\. -. -.P -\fBrofi\fR can also function as (drop\-in) replacement for \fBdmenu(1)\fR\. -. -.SS "Running rofi" -To launch \fBrofi\fR directly in a certain mode, specify a mode with \fBrofi \-show \fR\. To show the run dialog: -. -.IP "" 4 -. -.nf +.TH ROFI 1 rofi +.SH NAME +.PP +\fBrofi\fP \- A window switcher, application launcher, ssh dialog and dmenu replacement +.SH SYNOPSIS +.PP +\fBrofi\fP [ \-show \fImode\fP ]|[ \-dmenu ]|[ \-e \fImsg\fP ] [ CONFIGURATION ] + +.SH DESCRIPTION +.PP +\fBrofi\fP is an X11 pop\-up window switcher, run dialog, dmenu replacement, and more. It focuses on +being fast to use and have minimal distraction. It supports keyboard and mouse navigation, type to +filter, tokenized search and more. + +.SH USAGE +.PP +\fBrofi\fP\&'s main functionality is to assist in your workflow, allowing you to quickly switch +between windows, start applications or log into a remote machine via ssh. There are different \fImodi\fP for different types of +actions. + +.PP +\fBrofi\fP can also function as (drop\-in) replacement for \fBdmenu(1)\fP\&. + +.SS Running rofi +.PP +To launch \fBrofi\fP directly in a certain mode, specify a mode with \fB\fCrofi \-show \fR\&. +To show the run dialog: + +.PP +.RS + +.nf rofi \-show run -. -.fi -. -.IP "" 0 -. -.SS "Emulating dmenu" -\fBrofi\fR can emulate \fBdmenu(1)\fR (a dynamic menu for X) when launched with the \fB\-dmenu\fR flag\. -. -.P -The website for \fBdmenu\fR can be found here \fIhttp://tools\.suckless\.org/dmenu/\fR\. -. -.P -\fBrofi\fR does not aim to be 100% compatible with dmenu\. There are simply too many different flavors of dmenu\. The idea is that the basic usage command\-line flags are obeyed, theme\-related flags are not\. Besides, \fBrofi\fR offers some extended features (like multi\-select, highlighting, message bar, extra key bindings)\. -. -.SS "Display Error message" -\fBrofi\fR error dialog can also be called from the command line\. -. -.IP "" 4 -. -.nf +.fi +.RE + +.SS Emulating dmenu +.PP +\fBrofi\fP can emulate \fBdmenu(1)\fP (a dynamic menu for X) when launched with the \fB\fC\-dmenu\fR flag. + +.PP +The website for \fB\fCdmenu\fR can be found here +\[la]http://tools.suckless.org/dmenu/\[ra]\&. + +.PP +\fBrofi\fP does not aim to be 100% compatible with dmenu. There are simply too many different flavors of dmenu. +The idea is that the basic usage command\-line flags are obeyed, theme\-related flags are not. +Besides, \fBrofi\fP offers some extended features (like multi\-select, highlighting, message bar, extra key bindings). + +.SS Display Error message +.PP +\fBrofi\fP error dialog can also be called from the command line. + +.PP +.RS + +.nf rofi \-e "my message" -. + .fi -. -.IP "" 0 -. -.P -Markup support can be enabled, see CONFIGURATION options\. -. -.SH "CONFIGURATION" +.RE + +.PP +Markup support can be enabled, see CONFIGURATION options. + +.SH CONFIGURATION +.PP There are currently three methods of setting configuration options (evaluated in order below): -. -.IP "\(bu" 4 -System configuration file (for example \fB/etc/rofi\.rasi\fR or old format \fB/etc/rofi\.conf\fR)\. -. -.IP "\(bu" 4 -Xresources: A method of storing key values in the Xserver\. See here \fIhttps://en\.wikipedia\.org/wiki/X_resources\fR for more information\. -. -.IP "\(bu" 4 -Rasi theme file: The new \fItheme\fR format can be used to set configuration values\. -. -.IP "\(bu" 4 -Configuration File: This uses the same format as the Xresources file\. By default it looks in \fBXDG_USER_CONFIG_DIR\fR/rofi/config, but can be overridden on commandline\. By default XDG_USER_CONFIG_DIR defaults to \fB$HOME/\.config\fR\. (See \fBrofi \-h\fR for current location)\. This is the recommended way of configuring \fBrofi\fR\. -. -.IP "\(bu" 4 -Command\-line options: Arguments passed to \fBrofi\fR\. -. -.IP "" 0 -. -.P -\fBTIP\fR: To get a template config file run: \fBrofi \-dump\-xresources > rofi\-example\.config\fR\. \fBNOTE\fR: In version 1\.4\.0 we support configuration in a new format, a config for this can be generated by: \fBrofi \-dump\-config > config\.rasi\fR \fBNOTE\fR: If you want to use the new configuration format, the config file should be named \fBconfig\.rasi\fR\. \fBNOTE\fR: You can upgrade to the new configuration file format using \fBrofi \-upgrade\-config\fR -. -.P -The Xresources file expects options starting with \fBrofi\.\fR followed by its name\. An example to set the number of lines: -. -.IP "" 4 -. -.nf -rofi\.lines: 10 -. +.RS +.IP \(bu 2 +System configuration file (for example \fB\fC/etc/rofi.rasi\fR or old format \fB\fC/etc/rofi.conf\fR). +.IP \(bu 2 +Xresources: A method of storing key values in the Xserver. See +here +\[la]https://en.wikipedia.org/wiki/X_resources\[ra] for more information. +.IP \(bu 2 +Rasi theme file: The new \fItheme\fP format can be used to set configuration values. +.IP \(bu 2 +Configuration File: This uses the same format as the Xresources file. +By default it looks in \fB\fCXDG\_USER\_CONFIG\_DIR\fR/rofi/config, but can be overridden on commandline. +By default XDG\_USER\_CONFIG\_DIR defaults to \fB\fC$HOME/.config\fR\&. (See \fB\fCrofi \-h\fR for current location). +This is the recommended way of configuring \fBrofi\fP\&. +.IP \(bu 2 +Command\-line options: Arguments passed to \fBrofi\fP\&. + +.RE + +.PP +\fBTIP\fP: To get a template config file run: \fB\fCrofi \-dump\-xresources > rofi\-example.config\fR\&. +\fBNOTE\fP: In version 1.4.0 we support configuration in a new format, a config for this can be generated by: \fB\fCrofi +\-dump\-config > config.rasi\fR +\fBNOTE\fP: If you want to use the new configuration format, the config file should be named \fB\fCconfig.rasi\fR\&. +\fBNOTE\fP: You can upgrade to the new configuration file format using \fB\fCrofi \-upgrade\-config\fR + +.PP +The Xresources file expects options starting with \fB\fCrofi.\fR followed by its name. An example to set the number of lines: + +.PP +.RS + +.nf +rofi.lines: 10 + .fi -. -.IP "" 0 -. -.P -Command line options override settings from Xresources file\. The same option set as argument — prefixed with a \'\-\': -. -.IP "" 4 -. -.nf +.RE +.PP +Command line options override settings from Xresources file. The same option set as argument — prefixed with a '\-': + +.PP +.RS + +.nf rofi \-lines 10 -. + .fi -. -.IP "" 0 -. -.P +.RE + +.PP To get a list of available options formatted as Xresources entries, run: -. -.IP "" 4 -. -.nf +.PP +.RS + +.nf rofi \-dump\-xresources -. + .fi -. -.IP "" 0 -. -.P +.RE + +.PP The configuration system supports the following types: -. -.IP "\(bu" 4 + +.RS +.IP \(bu 2 string -. -.IP "\(bu" 4 +.IP \(bu 2 integer (signed and unsigned) -. -.IP "\(bu" 4 +.IP \(bu 2 char -. -.IP "\(bu" 4 +.IP \(bu 2 Boolean -. -.IP "" 0 -. -.P -Boolean options have a non\-default command\-line syntax\. Example to enable option X: -. -.IP "" 4 -. -.nf +.RE + +.PP +Boolean options have a non\-default command\-line syntax. Example to enable option X: + +.PP +.RS + +.nf \-X -. + .fi -. -.IP "" 0 -. -.P +.RE + +.PP To disable option X: -. -.IP "" 4 -. -.nf +.PP +.RS + +.nf \-no\-X -. + .fi -. -.IP "" 0 -. -.P +.RE + +.PP Below is a list of the most important options: -. -.SS "General" -\fB\-help\fR -. -.P -The help option shows the full list of commandline options and the current set value\. These include dynamic (run\-time generated) options\. -. -.P -\fB\-dump\-xresources\fR -. -.P -Dump the current active configuration in Xresources format to the command\-line\. This does not validate all passed values (for example, colors)\. -. -.P -\fB\-threads\fR \fInum\fR -. -.P -Specify the number of threads \fBrofi\fR should use: -. -.IP "\(bu" 4 -0: Autodetect the number of supported hardware threads\. -. -.IP "\(bu" 4 + +.SS General +.PP +\fB\fC\-help\fR + +.PP +The help option shows the full list of commandline options and the current set value. +These include dynamic (run\-time generated) options. + +.PP +\fB\fC\-dump\-xresources\fR + +.PP +Dump the current active configuration in Xresources format to the command\-line. +This does not validate all passed values (for example, colors). + +.PP +\fB\fC\-threads\fR \fInum\fP + +.PP +Specify the number of threads \fBrofi\fP should use: + +.RS +.IP \(bu 2 +0: Autodetect the number of supported hardware threads. +.IP \(bu 2 1: Disable threading -. -.IP "\(bu" 4 -2\.\.N: Specify the maximum number of threads to use in the thread pool\. -. -.IP "" 0 -. -.P -\fB\-dmenu\fR -. -.P -Run \fBrofi\fR in dmenu mode\. This allows for interactive scripts\. In \fBdmenu\fR mode, \fBrofi\fR reads from STDIN, and output to STDOUT\. A simple example, displaying three pre\-defined options: -. -.IP "" 4 -. -.nf +.IP \(bu 2 +2..N: Specify the maximum number of threads to use in the thread pool. + +.RE + +.PP +\fB\fC\-dmenu\fR + +.PP +Run \fBrofi\fP in dmenu mode. This allows for interactive scripts. +In \fB\fCdmenu\fR mode, \fBrofi\fP reads from STDIN, and output to STDOUT. +A simple example, displaying three pre\-defined options: + +.PP +.RS + +.nf +echo \-e "Option #1\\nOption #2\\nOption #3" | rofi \-dmenu -echo \-e "Option #1\enOption #2\enOption #3" | rofi \-dmenu -. .fi -. -.IP "" 0 -. -.P +.RE + +.PP Or get the options from a script: -. -.IP "" 4 -. -.nf -~/my_script\.sh | rofi \-dmenu -. +.PP +.RS + +.nf +\~/my\_script.sh | rofi \-dmenu + .fi -. -.IP "" 0 -. -.P -\fB\-show\fR \fImode\fR -. -.P -Open \fBrofi\fR in a certain mode\. Available modes are \fBwindow\fR, \fBrun\fR, \fBdrun\fR, \fBssh\fR, \fBcombi\fR\. The special argument \fBkeys\fR can be used to open a searchable list of supported key bindings (see \fIKEY BINDINGS\fR) -. -.P +.RE + +.PP +\fB\fC\-show\fR \fImode\fP + +.PP +Open \fBrofi\fP in a certain mode. Available modes are \fB\fCwindow\fR, \fB\fCrun\fR, \fB\fCdrun\fR, \fB\fCssh\fR, \fB\fCcombi\fR\&. +The special argument \fB\fCkeys\fR can be used to open a searchable list of supported key bindings +(see \fIKEY BINDINGS\fP) + +.PP To show the run\-dialog: -. -.IP "" 4 -. -.nf +.PP +.RS + +.nf rofi \-show run -. -.fi -. -.IP "" 0 -. -.P -\fB\-modi\fR \fImode1,mode1\fR -. -.P -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 modes will be enabled\. To only show the run and ssh launcher: -. -.IP "" 4 -. -.nf +.fi +.RE + +.PP +\fB\fC\-modi\fR \fImode1,mode1\fP + +.PP +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 modes will be enabled. +To only show the run and ssh launcher: + +.PP +.RS + +.nf rofi \-modi "run,ssh" \-show run -. -.fi -. -.IP "" 0 -. -.P -Custom modes can be added using the internal \'script\' mode\. Each mode has two parameters: -. -.IP "" 4 -. -.nf +.fi +.RE + +.PP +Custom modes can be added using the internal 'script' mode. Each mode has two parameters: + +.PP +.RS + +.nf :