PolytreeDE/rofi
1
0
Fork 0
mirror of https://github.com/davatorium/rofi.git synced 2024-11-18 13:54:36 -05:00
Code Releases Activity

Manpage tweaks for rofi.1 (#1120)

Browse source 
* Man pages: Add version and dump-* options

* Man pages: Add -display and -markup to rofi.1

* Man pages: Use the metavariable in -async-pre-read

* Man pages: document the dmenu -w option

* Man pages/help: correct -only-match description

* Man pages/help: -normal-window does not only apply in dmenu mode

* Man page: modi are lowercase

Entering the modi as the man page had them would not work

* Man page: minor formatting/grammar tweaks

* modi and command names are `backticked`
* rofi is **bold**
* other man pages are **bold(1)**
* Pango is capitalised according to their own website.
* Option arguments are *like1*,*this2*

* Man pages: fix Pango markup link
This commit is contained in:
John Beard 2020-05-10 14:44:29 +01:00 committed by GitHub
parent 1a9e6450e3
commit 3df5a616cd
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 309 additions and 167 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
doc/help-output.txt
View file

@ -11,7 +11,7 @@ Command line only options:
-dump-xresources Dump the current configuration in Xresources format and exit.
-e [string] Show a dialog displaying the passed message and exit.
-markup Enable pango markup where possible.
-normal-window In dmenu mode, behave as a normal window. (experimental)
-normal-window Behave as a normal window. (experimental)
-show [mode] Show the mode 'mode' and exit. The mode has to be enabled.
-no-lazy-grab Disable lazy grab that, when fail to grab keyboard, does not block but retry later.
-no-plugins Disable loading of external plugins.
@ -29,8 +29,8 @@ DMENU command line options:
-l [integer] Number of rows to display
-window-title [string] Set the dmenu window title
-i Set filter to be case insensitive
-only-match Force selection or custom entry
-no-custom Don't accept custom entry
-only-match Force selection to be given entry, disallow no match
-no-custom Don't accept custom entry, allow no match
-select [string] Select the first row that matches
-password Do not show what the user inputs. Show '*' instead.
-markup-rows Allow and render pango markup as input data.

295
doc/rofi.1
View file

@ -1,3 +1,4 @@
.nh
.TH ROFI 1 rofi
.SH NAME
.PP
@ -16,8 +17,8 @@ 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.
between windows, start applications or log into a remote machine via \fB\fCssh\fR\&.
There are different \fImodi\fP for different types of actions.
.PP
\fBrofi\fP can also function as (drop\-in) replacement for \fBdmenu(1)\fP\&.
@ -25,7 +26,7 @@ actions.
.SS Running rofi
.PP
To launch \fBrofi\fP directly in a certain mode, specify a mode with \fB\fCrofi \-show <mode>\fR\&.
To show the run dialog:
To show the \fB\fCrun\fR dialog:
.PP
.RS
@ -45,8 +46,8 @@ 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.
\fBrofi\fP does not aim to be 100% compatible with \fB\fCdmenu\fR\&. There are simply too many different flavors of \fB\fCdmenu\fR\&.
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
@ -68,6 +69,8 @@ Markup support can be enabled, see CONFIGURATION options.
.SH CONFIGURATION
.PP
There are currently three methods of setting configuration options (evaluated in order below):
.RS
.IP \(bu 2
System configuration file (for example \fB\fC/etc/rofi.rasi\fR or old format \fB\fC/etc/rofi.conf\fR).
It first checks XDG\_CONFIG\_DIRS and then SYSCONFDIR (that is passed at compile time).
@ -81,16 +84,24 @@ Rasi theme file: The new \fItheme\fP format can be used to set configuration val
.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).
By default \fB\fCXDG\_USER\_CONFIG\_DIR\fR 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
.PP
\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
.PP
\fBNOTE\fP: If you want to use the new configuration format, the config file should be named \fB\fCconfig.rasi\fR\&.
.PP
\fBNOTE\fP: You can upgrade to the new configuration file format using \fB\fCrofi \-upgrade\-config\fR
.PP
@ -106,7 +117,7 @@ rofi.lines: 10
.RE
.PP
Command line options override settings from Xresources file. The same option set as argument — prefixed with a '\-':
Command\-line options override settings from the Xresources file. The same option set as argument — prefixed with a '\-':
.PP
.RS
@ -131,6 +142,8 @@ rofi \-dump\-xresources
.PP
The configuration system supports the following types:
.RS
.IP \(bu 2
string
.IP \(bu 2
@ -140,6 +153,8 @@ char
.IP \(bu 2
Boolean
.RE
.PP
Boolean options have a non\-default command\-line syntax. Example to enable option X:
@ -172,14 +187,33 @@ Below is a list of the most important options:
\fB\fC\-help\fR
.PP
The help option shows the full list of commandline options and the current set value.
The help option shows the full list of command\-line options and the current set values.
These include dynamic (run\-time generated) options.
.PP
\fB\fC\-version\fR
.PP
Show the \fBrofi\fP version and exit.
.PP
\fB\fC\-dump\-config\fR
.PP
Dump the current active configuration, in rasi format, to stdout and exit.
Information about the rasi format can be found in the \fBrofi\-theme(5)\fP manpage.
.PP
\fB\fC\-dump\-theme\fR
.PP
Dump the current active theme, in rasi format, to stdout and exit.
.PP
\fB\fC\-dump\-xresources\fR
.PP
Dump the current active configuration in Xresources format to the command\-line.
Dump the current active configuration, in Xresources format, to stdout.
This does not validate all passed values (for example, colors).
.PP
@ -187,6 +221,8 @@ This does not validate all passed values (for example, colors).
.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
@ -194,6 +230,14 @@ Specify the number of threads \fBrofi\fP should use:
.IP \(bu 2
2..N: Specify the maximum number of threads to use in the thread pool.
.RE
.PP
\fB\fC\-display\fR \fIdisplay\fP
.PP
The X server to contact. Default is \fB\fC$DISPLAY\fR\&.
.PP
\fB\fC\-dmenu\fR
@ -244,13 +288,13 @@ rofi \-show run
.RE
.PP
\fB\fC\-modi\fR \fImode1,mode1\fP
\fB\fC\-modi\fR \fImode1,mode2\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:
Enabled modes can be changed at runtime. Default key is \fB\fCCtrl+Tab\fR\&.
If no modes are specified, all configured modes will be enabled.
To only show the \fB\fCrun\fR and \fB\fCssh\fR launcher:
.PP
.RS
@ -262,7 +306,7 @@ rofi \-modi "run,ssh" \-show run
.RE
.PP
Custom modes can be added using the internal 'script' mode. Each mode has two parameters:
Custom modes can be added using the internal \fB\fCscript\fR mode. Each such mode has two parameters:
.PP
.RS
@ -274,7 +318,7 @@ Custom modes can be added using the internal 'script' mode. Each mode has two pa
.RE
.PP
Example: Have a mode 'Workspaces' using the \fB\fCi3\_switch\_workspaces.sh\fR script:
Example: Have a mode called 'Workspaces' using the \fB\fCi3\_switch\_workspaces.sh\fR script:
.PP
.RS
@ -286,7 +330,7 @@ rofi \-modi "window,run,ssh,Workspaces:i3\_switch\_workspaces.sh" \-show Workspa
.RE
.PP
Notes: The I3 Window manager does not like commas in the command when specifying an exec command.
Notes: The i3 window manager does not like commas in the command when specifying an exec command.
For that case '#' can be used as an separator.
.PP
@ -363,7 +407,7 @@ Specify the directory where \fBrofi\fP should look for plugins.
\fB\fC\-show\-icons\fR
.PP
Show application icons in drun and window modes.
Show application icons in \fB\fCdrun\fR and \fB\fCwindow\fR modes.
.PP
\fB\fC\-icon\-theme\fR
@ -373,6 +417,18 @@ Specify icon theme to be used.
If not specified default theme from DE is used, \fIAdwaita\fP and \fIgnome\fP themes act as
fallback themes.
.PP
\fB\fC\-markup\fR
.PP
Use Pango markup to format output wherever possible.
.PP
\fB\fC\-normal\-window\fR
.PP
Make \fBrofi\fP react like a normal application window. Useful for scripts like Clerk that are basically an application.
.SS Matching
.PP
\fB\fC\-matching\fR \fImethod\fP
@ -380,6 +436,8 @@ fallback themes.
.PP
Specify the matching algorithm used.
Current the following methods are supported.
.RS
.IP \(bu 2
\fBnormal\fP: match the int string
.IP \(bu 2
@ -389,6 +447,8 @@ Current the following methods are supported.
.IP \(bu 2
\fBfuzzy\fP: do a fuzzy match
.RE
.PP
Default: \fInormal\fP
@ -402,7 +462,7 @@ Note: glob matching might be slow for larger lists
Tokenize the input.
.PP
\fB\fC\-drun\-categories\fR \fIcategory\fP,\fIcategory\fP
\fB\fC\-drun\-categories\fR \fIcategory1\fP,\fIcategory2\fP
.PP
Only show desktop files that are present in the listed categories.
@ -411,8 +471,10 @@ Only show desktop files that are present in the listed categories.
\fB\fC\-drun\-match\-fields\fR \fIfield1\fP,\fIfield2\fP,...
.PP
When using drun, match only with the specified Desktop entry fields.
When using \fB\fCdrun\fR, match only with the specified Desktop entry fields.
The different fields are:
.RS
.IP \(bu 2
\fBname\fP: the application's name
.IP \(bu 2
@ -424,17 +486,17 @@ The different fields are:
.IP \(bu 2
\fBcomment\fP: the application comment
.IP \(bu 2
\fBall\fP: all of the aboveDefault: \fIname,generic,exec,categories,keywords\fP
.PP
\fBall\fP: all of the above
.PP
Default: \fIname,generic,exec,categories,keywords\fP
.RE
.PP
\fB\fC\-drun\-display\-format\fR
.PP
The format string for the drun dialog:
The format string for the \fB\fCdrun\fR dialog:
.RS
.IP \(bu 2
\fBname\fP: the application's name
.IP \(bu 2
@ -446,6 +508,8 @@ The format string for the drun dialog:
.IP \(bu 2
\fBcomment\fP: the application comment
.RE
.PP
Pango markup can be used to formatting the output.
@ -482,6 +546,8 @@ Default: false
.PP
When using window mode, match only with the specified fields.
The different fields are:
.RS
.IP \(bu 2
\fBtitle\fP: window's title
.IP \(bu 2
@ -493,11 +559,9 @@ The different fields are:
.IP \(bu 2
\fBdesktop\fP: window's current desktop
.IP \(bu 2
\fBall\fP: all of the aboveDefault: \fIall\fP
.PP
\fBall\fP: all of the above
.PP
Default: \fIall\fP
.RE
.PP
\fB\fC\-matching\-negate\-char\fR \fIchar\fP
@ -688,6 +752,8 @@ When one entry is left, automatically select it.
Select monitor to display \fBrofi\fP on.
It accepts as input: \fIprimary\fP (if primary output is set), the \fIxrandr\fP output name, or integer number (in order of
detection). Negative numbers are handled differently:
.RS
.IP \(bu 2
\fB\-1\fP: the currently focused monitor.
.IP \(bu 2
@ -698,11 +764,9 @@ behavior.)
.IP \(bu 2
\fB\-4\fP: the monitor with the focused window.
.IP \(bu 2
\fB\-5\fP: the monitor that shows the mouse pointer.Default: \fI\-5\fP
.PP
\fB\-5\fP: the monitor that shows the mouse pointer.
.PP
Default: \fI\-5\fP
.RE
.PP
See \fB\fCrofi \-h\fR output for the detected monitors, their position, and size.
@ -739,8 +803,14 @@ This option can be specified multiple times.
.PP
Override the default DPI setting.
.RS
.IP \(bu 2
If set to \fB\fC0\fR, it tries to auto\-detect based on X11 screen size (similar to i3 and GTK).
If set to \fB\fC1\fR, it tries to auto\-detect based on the size of the monitor that rofi is displayed on (similar to latest Qt 5).
.IP \(bu 2
If set to \fB\fC1\fR, it tries to auto\-detect based on the size of the monitor that \fBrofi\fP is displayed on (similar to latest Qt 5).
.RE
.PP
\fB\fC\-selected\-row\fR \fIselected row\fP
@ -769,16 +839,20 @@ rofi \-terminal xterm
.PP
Pattern: \fI{terminal}\fP
.PP
Default: \fIx\-terminal\-emulator\fP
.PP
\fB\fC\-ssh\-client\fR \fIclient\fP
.PP
Override the used ssh client.
Override the used \fB\fCssh\fR client.
.PP
Pattern: \fI{ssh\-client}\fP
.PP
Default: \fIssh\fP
.SS SSH settings
@ -791,6 +865,8 @@ The pattern \fI{host}\fP is replaced by the selected ssh entry.
.PP
Pattern: \fI{ssh\-client}\fP
.PP
Default: \fI{terminal} \-e {ssh\-client} {host}\fP
.PP
@ -854,6 +930,8 @@ Format what is being displayed for windows.
.PP
\fIfield\fP:
.RS
.IP \(bu 2
\fBw\fP: desktop name
.IP \(bu 2
@ -865,6 +943,8 @@ Format what is being displayed for windows.
.IP \(bu 2
\fBc\fP: class
.RE
.PP
\fIlen\fP: maximum field length (0 for auto\-size). If length and window \fIwidth\fP are negative, field length is \fIwidth \- len\fP\&.
if length is positive, the entry will be truncated or padded to fill that length.
@ -890,11 +970,11 @@ Show window thumbnail (if available) as icon in the window switcher.
.SS Combi settings
.PP
\fB\fC\-combi\-modi\fR \fImode1,mode2\fP
\fB\fC\-combi\-modi\fR \fImode1\fP,\fImode2\fP
.PP
The modi to combine in combi mode.
For syntax to see \fB\fC\-modi\fR\&.
For syntax to \fB\fC\-combi\-modi\fR, see \fB\fC\-modi\fR\&.
To get one merge view, of \fB\fCwindow\fR,\fB\fCrun\fR, and \fB\fCssh\fR:
.PP
@ -907,7 +987,7 @@ rofi \-show combi \-combi\-modi "window,run,ssh" \-modi combi
.RE
.PP
Notes: The I3 Window manager does not like commas in the command when specifying an exec command.
Notes: The i3 window manager does not like commas in the command when specifying an exec command.
For that case '#' can be used as a separator.
.SS History and Sorting
@ -931,17 +1011,21 @@ This setting can be changed at runtime (see \fB\fC\-kb\-toggle\-sort\fR).
.PP
There are 2 sorting method:
.RS
.IP \(bu 2
levenshtein (Default)
.IP \(bu 2
fzf sorting.
.RE
.SS Dmenu specific
.PP
\fB\fC\-sep\fR \fIseparator\fP
.PP
Separator for dmenu. Example: To show a list of 'a' to 'e' with '|' as a separator:
Separator for \fB\fCdmenu\fR\&. Example: To show a list of 'a' to 'e' with '|' as a separator:
.PP
.RS
@ -956,7 +1040,7 @@ echo "a|b|c|d|e" | rofi \-sep '|' \-dmenu
\fB\fC\-p\fR \fIprompt\fP
.PP
Specify the prompt to show in dmenu mode. For example, select 'monkey', a,b,c,d, or e.
Specify the prompt to show in \fB\fCdmenu\fR mode. For example, select 'monkey', a,b,c,d, or e.
.PP
.RS
@ -992,13 +1076,15 @@ Default: \fI15\fP
\fB\fC\-i\fR
.PP
Makes dmenu searches case\-insensitive
Makes \fB\fCdmenu\fR searches case\-insensitive
.PP
\fB\fC\-a\fR \fIX\fP
.PP
Active row, mark \fIX\fP as active. Where \fIX\fP is a comma\-separated list of python(1)\-style indices and ranges, e.g. indices start at 0, \-1 refers to the last row with \-2 preceding it, ranges are left\-open and right\-close, and so on. You can specify:
.RS
.IP \(bu 2
A single row: '5'
.IP \(bu 2
@ -1010,6 +1096,8 @@ A set of rows: '2,0,\-9'
.IP \(bu 2
Or any combination: '5,\-3:,7:11,2,0,\-9'
.RE
.PP
\fB\fC\-u\fR \fIX\fP
@ -1021,7 +1109,8 @@ Urgent row, mark \fIX\fP as urgent. See \fB\fC\-a\fR option for details.
.PP
Only return a selected item, do not allow custom entry.
This mode always returns an entry, or returns directly when no entries given.
This mode always returns an entry. It will not return if no matching entry is
selected.
.PP
\fB\fC\-no\-custom\fR
@ -1035,6 +1124,8 @@ This mode returns directly when no entries given.
.PP
Allows the output of dmenu to be customized (N is the total number of input entries):
.RS
.IP \(bu 2
\&'s' selected string
.IP \(bu 2
@ -1044,12 +1135,14 @@ Allows the output of dmenu to be customized (N is the total number of input entr
.IP \(bu 2
\&'q' quote string
.IP \(bu 2
\&'p' Selected string stripped from pango markup (Needs to be a valid string)
\&'p' Selected string stripped from Pango markup (Needs to be a valid string)
.IP \(bu 2
\&'f' filter string (user input)
.IP \(bu 2
\&'F' quoted filter string (user input)
.RE
.PP
Default: 's'
@ -1063,15 +1156,9 @@ Select first line that matches the given string
\fB\fC\-mesg\fR \fIstring\fP
.PP
Add a message line below the filter entry box. Supports pango markup.
Add a message line below the filter entry box. Supports Pango markup.
For more information on supported markup see here
\[la]https://developer.gnome.org/pango/stable/PangoMarkupFormat.html\[ra]
.PP
\fB\fC\-normal\-window\fR
.PP
Make \fBrofi\fP react like a normal application window. Useful for scripts like Clerk that are basically an application.
\[la]https://developer.gnome.org/pygtk/stable/pango-markup-language.html\[ra]
.PP
\fB\fC\-dump\fR
@ -1097,9 +1184,9 @@ Hide the input text. This should not be considered secure!
\fB\fC\-markup\-rows\fR
.PP
Tell \fBrofi\fP that DMenu input is pango markup encoded, and should be rendered.
Tell \fBrofi\fP that DMenu input is Pango markup encoded, and should be rendered.
See here
\[la]https://developer.gnome.org/pango/stable/PangoMarkupFormat.html\[ra] for details about pango markup.
\[la]https://developer.gnome.org/pygtk/stable/pango-markup-language.html\[ra] for details about Pango markup.
.PP
\fB\fC\-multi\-select\fR
@ -1111,7 +1198,7 @@ Allow multiple lines to be selected. Adds a small selection indicator to the lef
\fB\fC\-sync\fR
.PP
Force rofi mode to first read all data from stdin before showing the selection window. This is original dmenu behavior.
Force \fBrofi\fP mode to first read all data from stdin before showing the selection window. This is original dmenu behavior.
.PP
Note: the default asynchronous mode will also be automatically disabled if used with conflicting options,
@ -1121,7 +1208,8 @@ such as \fB\fC\-dump\fR, \fB\fC\-only\-match\fR or \fB\fC\-auto\-select\fR\&.
\fB\fC\-async\-pre\-read\fR \fInumber\fP
.PP
Reads the first 25 entries blocking, then switches to async mode. This makes it feel more 'snappy'.
Reads the first \fInumber\fP entries blocking, then switches to async mode.
This makes it feel more 'snappy'.
.PP
\fIdefault\fP: 25
@ -1132,6 +1220,12 @@ Reads the first 25 entries blocking, then switches to async mode. This makes it
.PP
Set name used for the window title. Will be shown as Rofi \- \fItitle\fP
.PP
\fB\fC\-w\fR \fIwindowid\fP
.PP
Position \fBrofi\fP over the window with the given X11 window ID.
.PP
\fB\fC\-keep\-right\fR
@ -1144,20 +1238,20 @@ Set ellipsize mode to start. So end of string is visible.
.PP
Pops up a message dialog (used internally for showing errors) with \fImessage\fP\&.
Message can be multi\-line.
Message can be multi\-\&line.
.SS Other
.PP
\fB\fC\-drun\-use\-desktop\-cache\fR
.PP
Build and use a cache with the content of desktop files. Usable for systems with slow harddrives.
Build and use a cache with the content of desktop files. Usable for systems with slow hard drives.
.PP
\fB\fC\-drun\-reload\-desktop\-cache\fR
.PP
If \fB\fCdrun\-use\-desktop\-cache\fR is enbled, rebuild a cache with the content of desktop files.
If \fB\fCdrun\-use\-desktop\-cache\fR is enabled, rebuild a cache with the content of desktop files.
.PP
\fB\fC\-pid\fR \fIpath\fP
@ -1238,6 +1332,8 @@ For more information on debugging, see the wiki
.SH PATTERN
.PP
To launch commands (for example, when using the ssh launcher), the user can enter the used command\-line. The following keys can be used that will be replaced at runtime:
.RS
.IP \(bu 2
\fB\fC{host}\fR: the host to connect to
.IP \(bu 2
@ -1249,6 +1345,8 @@ To launch commands (for example, when using the ssh launcher), the user can ente
.IP \(bu 2
\fB\fC{window}\fR: the window ID of the selected window (in \fB\fCwindow\-command\fR)
.RE
.SH DMENU REPLACEMENT
.PP
If \fB\fCargv[0]\fR (calling command) is dmenu, \fBrofi\fP will start in dmenu mode.
@ -1271,6 +1369,8 @@ manual.
.PP
The theme setup allows you to specify colors per state, similar to \fBi3\fP
Currently 3 states exist:
.RS
.IP \(bu 2
\fBnormal\fP: normal row
.IP \(bu 2
@ -1278,8 +1378,12 @@ Currently 3 states exist:
.IP \(bu 2
\fBactive\fP: highlighted row (active)
.RE
.PP
For each state, the following 5 colors must be set:
.RS
.IP \(bu 2
\fBbg\fP: background color row
.IP \(bu 2
@ -1291,10 +1395,12 @@ For each state, the following 5 colors must be set:
.IP \(bu 2
\fBhlbg\fP: background color selected row
.RE
.PP
The window background and border color should be specified separately. The key \fB\fCcolor\-window\fR contains
a tuple \fB\fCbackground,border,separator\fR\&.
An example for \fB\fCXresources\fR file:
An example \fB\fCXresources\fR file:
.PP
.RS
@ -1312,7 +1418,7 @@ rofi.color\-window: #fdf6e3, #002b36, #002b36
.RE
.PP
Same settings can also be specified on command\-line:
Same settings can also be specified on the command\-line:
.PP
.RS
@ -1376,6 +1482,8 @@ of the window will be visible through it.
.SH KEY BINDINGS
.PP
\fBrofi\fP has the following key bindings:
.RS
.IP \(bu 2
\fB\fCCtrl\-v, Insert\fR: Paste from clipboard
.IP \(bu 2
@ -1441,6 +1549,8 @@ of the window will be visible through it.
.IP \(bu 2
\fB\fCAlt\-Shift\-S\fR: Take a screenshot and store it in the Pictures directory.
.RE
.PP
To get a full list of key bindings on the commandline, see \fB\fCrofi \-h\fR\&.
The options starting with \fB\fC\-kb\fR are keybindings.
@ -1451,53 +1561,53 @@ To get a searchable list of key bindings, run \fB\fCrofi \-show keys\fR\&.
A key binding starting with \fB\fC!\fR will act when all keys have been released.
.SH Available Modi
.SS Window
.SS window
.PP
Show a list of all the windows and allow switching between them.
Pressing the \fB\fCdelete\-entry\fR binding (\fB\fCshift\-delete\fR) will close the window.
Pressing the \fB\fCaccept\-custom\fR binding (\fB\fCcontrol\-enter\fR or \fB\fCshift\-enter\fR) will run a command on the window.
(See option \fB\fCwindow\-command\fR );
.SS WindowCD
.SS windowcd
.PP
Shows a list of the windows on the current desktop and allows switching between them.
Pressing the \fB\fCdelete\-entry\fR binding (\fB\fCshift\-delete\fR) will kill the window.
Pressing the \fB\fCaccept\-custom\fR binding (\fB\fCcontrol\-enter\fR or \fB\fCshift\-enter\fR) will run a command on the window.
(See option \fB\fCwindow\-command\fR );
.SS Run
.SS run
.PP
Shows a list of executables in \fB$PATH\fP and can launch them (optional in a terminal).
Shows a list of executables in \fB\fC$PATH\fR and can launch them (optional in a terminal).
Pressing the \fB\fCdelete\-entry\fR binding (\fB\fCshift\-delete\fR) will remove this entry from the run history.
Pressing the \fB\fCaccept\-custom\fR binding (\fB\fCcontrol\-enter\fR or \fB\fCshift\-enter\fR) will run the command in a terminal.
.SS DRun
.SS drun
.PP
Same as the \fBrun\fP launches, but the list is created from the installed desktop files. It automatically launches them
in a terminal if specified in the Desktop File.
Pressing the \fB\fCdelete\-entry\fR binding (\fB\fCshift\-delete\fR) will remove this entry from the run history.
Pressing the \fB\fCaccept\-custom\fR binding (\fB\fCcontrol\-enter\fR or \fB\fCshift\-enter\fR) with custom input (no entry matching) will run the command in a terminal.
.SS SSH
.SS ssh
.PP
Shows a list of SSH targets based on your ssh config file, and allows to quickly \fB\fCssh\fR into them.
Shows a list of SSH targets based on your \fB\fCssh\fR config file, and allows to quickly \fB\fCssh\fR into them.
.SS Keys
.SS keys
.PP
Shows a searchable list of key bindings.
.SS Script
.SS script
.PP
Allows custom scripted Modi to be added.
.SH FAQ
.SS The text in the window switcher is not nicely lined out.
.SS The text in the window switcher is not nicely aligned.
.PP
Try using a mono\-space font.
.SS The window is completely black.
.PP
Check quotes used on the commandline: you might have used \fB\fC“\fR ("smart quotes") instead of \fB\fC"\fR ("machine quotes").
Check quotes used on the command\-line: you might have used \fB\fC“\fR ("smart quotes") instead of \fB\fC"\fR ("machine quotes").
.SS What does the icon in the top right show?
.PP
@ -1532,7 +1642,7 @@ rofi \-modi run \-show run
.RE
.PP
Show the run dialog, and allow switching to Desktop File run dialog (drun):
Show the run dialog, and allow switching to Desktop File run dialog (\fB\fCdrun\fR):
.PP
.RS
@ -1544,7 +1654,7 @@ rofi \-modi run,drun \-show run
.RE
.PP
Combine the run and Desktop File run dialog (drun):
Combine the run and Desktop File run dialog (\fB\fCdrun\fR):
.PP
.RS
@ -1556,7 +1666,7 @@ rofi \-modi combi \-show combi \-combi\-modi run,drun
.RE
.PP
Combine the run and Desktop File run dialog (drun), and allow switching to window switcher:
Combine the run and Desktop File run dialog (\fB\fCdrun\fR), and allow switching to window switcher:
.PP
.RS
@ -1635,7 +1745,7 @@ See also the i3 manual
\[la]http://i3wm.org/docs/userguide.html\[ra]:
.PP
Some tools (such as import or xdotool) might be unable to run upon a KeyPress event, because the keyboard/pointer is
Some tools (such as \fB\fCimport\fR or \fB\fCxdotool\fR) might be unable to run upon a KeyPress event, because the keyboard/pointer is
still grabbed. For these situations, the \fB\fC\-\-release\fR flag can be used, as it will execute the command after the keys have
been released.
@ -1687,7 +1797,7 @@ Please see this
.SH ISSUE TRACKER
.PP
\fBrofi\fP issue tracker can be found here
The \fBrofi\fP issue tracker can be found here
\[la]https://github.com/DaveDavenport/rofi/issues\[ra]
.PP
@ -1697,24 +1807,25 @@ first.
.SH SEE ALSO
.PP
rofi\-sensible\-terminal(1), dmenu(1), rofi\-theme(5), rofi\-script(5), rofi\-theme\-selector(1)
\fBrofi\-sensible\-terminal(1)\fP, \fBdmenu(1)\fP, \fBrofi\-theme(5)\fP, \fBrofi\-script(5)\fP, \fBrofi\-theme\-selector(1)\fP
.SH AUTHOR
.PP
Qball Cow
\[la]qball@gmpclient.org\[ra]
.RS
.IP \(bu 2
Qball Cow qball@gmpclient.org
\[la]mailto:qball@gmpclient.org\[ra]
.IP \(bu 2
Rasmus Steinke rasi@xssn.at
\[la]mailto:rasi@xssn.at\[ra]
.IP \(bu 2
Quentin Glidic sardemff7+rofi@sardemff7.net
\[la]mailto:sardemff7+rofi@sardemff7.net\[ra]
.RE
.PP
Rasmus Steinke
\[la]rasi@xssn.at\[ra]
Original code based on work by: Sean Pringle sean.pringle@gmail.com
\[la]mailto:sean.pringle@gmail.com\[ra]
.PP
Quentin Glidic
\[la]sardemff7+rofi@sardemff7.net\[ra]
.PP
Original code based on work by: Sean Pringle
\[la]sean.pringle@gmail.com\[ra]
.PP
For a full list of authors, check the AUTHORS file.
For a full list of authors, check the \fB\fCAUTHORS\fR file.

171
doc/rofi.1.markdown
View file

@ -19,15 +19,15 @@ filter, tokenized search and more.
## USAGE
**rofi**'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 *modi* for different types of
actions.
between windows, start applications or log into a remote machine via `ssh`.
There are different *modi* for different types of actions.
**rofi** can also function as (drop-in) replacement for **dmenu(1)**.
### Running rofi
To launch **rofi** directly in a certain mode, specify a mode with `rofi -show <mode>`.
To show the run dialog:
To show the `run` dialog:
rofi -show run
@ -37,7 +37,7 @@ To show the run dialog:
The website for `dmenu` can be found [here](http://tools.suckless.org/dmenu/).
**rofi** does not aim to be 100% compatible with dmenu. There are simply too many different flavors of dmenu.
**rofi** 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, **rofi** offers some extended features (like multi-select, highlighting, message bar, extra key bindings).
@ -61,21 +61,24 @@ There are currently three methods of setting configuration options (evaluated in
* Rasi theme file: The new *theme* format can be used to set configuration values.
* Configuration File: This uses the same format as the Xresources file.
By default it looks in `XDG_USER_CONFIG_DIR`/rofi/config, but can be overridden on commandline.
By default XDG_USER_CONFIG_DIR defaults to `$HOME/.config`. (See `rofi -h` for current location).
By default `XDG_USER_CONFIG_DIR` defaults to `$HOME/.config`. (See `rofi -h` for current location).
This is the recommended way of configuring **rofi**.
* Command-line options: Arguments passed to **rofi**.
**TIP**: To get a template config file run: `rofi -dump-xresources > rofi-example.config`.
**NOTE**: In version 1.4.0 we support configuration in a new format, a config for this can be generated by: `rofi
-dump-config > config.rasi`
**NOTE**: In version 1.4.0 we support configuration in a new format, a config for this can be generated by:
`rofi -dump-config > config.rasi`
**NOTE**: If you want to use the new configuration format, the config file should be named `config.rasi`.
**NOTE**: You can upgrade to the new configuration file format using `rofi -upgrade-config`
The Xresources file expects options starting with `rofi.` followed by its name. An example to set the number of lines:
rofi.lines: 10
Command line options override settings from Xresources file. The same option set as argument — prefixed with a '-':
Command-line options override settings from the Xresources file. The same option set as argument — prefixed with a '-':
rofi -lines 10
@ -104,12 +107,25 @@ Below is a list of the most important options:
`-help`
The help option shows the full list of commandline options and the current set value.
The help option shows the full list of command-line options and the current set values.
These include dynamic (run-time generated) options.
`-version`
Show the **rofi** version and exit.
`-dump-config`
Dump the current active configuration, in rasi format, to stdout and exit.
Information about the rasi format can be found in the **rofi-theme(5)** manpage.
`-dump-theme`
Dump the current active theme, in rasi format, to stdout and exit.
`-dump-xresources`
Dump the current active configuration in Xresources format to the command-line.
Dump the current active configuration, in Xresources format, to stdout.
This does not validate all passed values (for example, colors).
`-threads` *num*
@ -120,6 +136,10 @@ Specify the number of threads **rofi** should use:
* 1: Disable threading
* 2..N: Specify the maximum number of threads to use in the thread pool.
`-display` *display*
The X server to contact. Default is `$DISPLAY`.
`-dmenu`
Run **rofi** in dmenu mode. This allows for interactive scripts.
@ -142,24 +162,24 @@ To show the run-dialog:
rofi -show run
`-modi` *mode1,mode1*
`-modi` *mode1,mode2*
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:
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
Custom modes can be added using the internal 'script' mode. Each mode has two parameters:
Custom modes can be added using the internal `script` mode. Each such mode has two parameters:
<name>:<script>
Example: Have a mode 'Workspaces' using the `i3_switch_workspaces.sh` script:
Example: Have a mode called 'Workspaces' using the `i3_switch_workspaces.sh` script:
rofi -modi "window,run,ssh,Workspaces:i3_switch_workspaces.sh" -show Workspaces
Notes: The I3 Window manager does not like commas in the command when specifying an exec command.
Notes: The i3 window manager does not like commas in the command when specifying an exec command.
For that case '#' can be used as an separator.
`-case-sensitive`
@ -208,7 +228,7 @@ Specify the directory where **rofi** should look for plugins.
`-show-icons`
Show application icons in drun and window modes.
Show application icons in `drun` and `window` modes.
`-icon-theme`
@ -216,6 +236,14 @@ Specify icon theme to be used.
If not specified default theme from DE is used, *Adwaita* and *gnome* themes act as
fallback themes.
`-markup`
Use Pango markup to format output wherever possible.
`-normal-window`
Make **rofi** react like a normal application window. Useful for scripts like Clerk that are basically an application.
### Matching
`-matching` *method*
@ -236,13 +264,13 @@ Note: glob matching might be slow for larger lists
Tokenize the input.
`-drun-categories` *category*,*category*
`-drun-categories` *category1*,*category2*
Only show desktop files that are present in the listed categories.
`-drun-match-fields` *field1*,*field2*,...
When using drun, match only with the specified Desktop entry fields.
When using `drun`, match only with the specified Desktop entry fields.
The different fields are:
* **name**: the application's name
@ -256,7 +284,7 @@ The different fields are:
`-drun-display-format`
The format string for the drun dialog:
The format string for the `drun` dialog:
* **name**: the application's name
* **generic**: the application's generic name
@ -419,8 +447,9 @@ This option can be specified multiple times.
`-dpi` *number*
Override the default DPI setting.
If set to `0`, it tries to auto-detect based on X11 screen size (similar to i3 and GTK).
If set to `1`, it tries to auto-detect based on the size of the monitor that rofi is displayed on (similar to latest Qt 5).
* If set to `0`, it tries to auto-detect based on X11 screen size (similar to i3 and GTK).
* If set to `1`, it tries to auto-detect based on the size of the monitor that **rofi** is displayed on (similar to latest Qt 5).
`-selected-row` *selected row*
@ -437,13 +466,15 @@ Specify which terminal to start.
rofi -terminal xterm
Pattern: *{terminal}*
Default: *x-terminal-emulator*
`-ssh-client` *client*
Override the used ssh client.
Override the used `ssh` client.
Pattern: *{ssh-client}*
Default: *ssh*
### SSH settings
@ -454,6 +485,7 @@ Set the command to execute when starting a ssh session.
The pattern *{host}* is replaced by the selected ssh entry.
Pattern: *{ssh-client}*
Default: *{terminal} -e {ssh-client} {host}*
`-parse-hosts`
@ -528,15 +560,15 @@ Show window thumbnail (if available) as icon in the window switcher.
### Combi settings
`-combi-modi` *mode1,mode2*
`-combi-modi` *mode1*,*mode2*
The modi to combine in combi mode.
For syntax to see `-modi`.
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
Notes: The I3 Window manager does not like commas in the command when specifying an exec command.
Notes: The i3 window manager does not like commas in the command when specifying an exec command.
For that case '#' can be used as a separator.
### History and Sorting
@ -564,13 +596,13 @@ There are 2 sorting method:
`-sep` *separator*
Separator for dmenu. Example: To show a list of 'a' to 'e' with '|' as a separator:
Separator for `dmenu`. Example: To show a list of 'a' to 'e' with '|' as a separator:
echo "a|b|c|d|e" | rofi -sep '|' -dmenu
`-p` *prompt*
Specify the prompt to show in dmenu mode. For example, select 'monkey', a,b,c,d, or e.
Specify the prompt to show in `dmenu` mode. For example, select 'monkey', a,b,c,d, or e.
echo "a|b|c|d|e" | rofi -sep '|' -dmenu -p "monkey:"
@ -586,7 +618,7 @@ Default: *15*
`-i`
Makes dmenu searches case-insensitive
Makes `dmenu` searches case-insensitive
`-a` *X*
@ -605,7 +637,8 @@ Urgent row, mark *X* as urgent. See `-a` option for details.
`-only-match`
Only return a selected item, do not allow custom entry.
This mode always returns an entry, or returns directly when no entries given.
This mode always returns an entry. It will not return if no matching entry is
selected.
`-no-custom`
@ -620,7 +653,7 @@ Allows the output of dmenu to be customized (N is the total number of input entr
* 'i' index (0 - (N-1))
* 'd' index (1 - N)
* 'q' quote string
* 'p' Selected string stripped from pango markup (Needs to be a valid string)
* 'p' Selected string stripped from Pango markup (Needs to be a valid string)
* 'f' filter string (user input)
* 'F' quoted filter string (user input)
@ -632,12 +665,8 @@ Select first line that matches the given string
`-mesg` *string*
Add a message line below the filter entry box. Supports pango markup.
For more information on supported markup see [here](https://developer.gnome.org/pango/stable/PangoMarkupFormat.html)
`-normal-window`
Make **rofi** react like a normal application window. Useful for scripts like Clerk that are basically an application.
Add a message line below the filter entry box. Supports Pango markup.
For more information on supported markup see [here](https://developer.gnome.org/pygtk/stable/pango-markup-language.html)
`-dump`
@ -655,8 +684,8 @@ Hide the input text. This should not be considered secure!
`-markup-rows`
Tell **rofi** that DMenu input is pango markup encoded, and should be rendered.
See [here](https://developer.gnome.org/pango/stable/PangoMarkupFormat.html) for details about pango markup.
Tell **rofi** that DMenu input is Pango markup encoded, and should be rendered.
See [here](https://developer.gnome.org/pygtk/stable/pango-markup-language.html) for details about Pango markup.
`-multi-select`
@ -665,14 +694,15 @@ Allow multiple lines to be selected. Adds a small selection indicator to the lef
`-sync`
Force rofi mode to first read all data from stdin before showing the selection window. This is original dmenu behavior.
Force **rofi** mode to first read all data from stdin before showing the selection window. This is original dmenu behavior.
Note: the default asynchronous mode will also be automatically disabled if used with conflicting options,
such as `-dump`, `-only-match` or `-auto-select`.
`-async-pre-read` *number*
Reads the first 25 entries blocking, then switches to async mode. This makes it feel more 'snappy'.
Reads the first *number* entries blocking, then switches to async mode.
This makes it feel more 'snappy'.
*default*: 25
@ -680,6 +710,10 @@ Reads the first 25 entries blocking, then switches to async mode. This makes it
Set name used for the window title. Will be shown as Rofi - *title*
`-w` *windowid*
Position **rofi** over the window with the given X11 window ID.
`-keep-right`
Set ellipsize mode to start. So end of string is visible.
@ -696,11 +730,11 @@ Message can be multi-line.
`-drun-use-desktop-cache`
Build and use a cache with the content of desktop files. Usable for systems with slow harddrives.
Build and use a cache with the content of desktop files. Usable for systems with slow hard drives.
`-drun-reload-desktop-cache`
If `drun-use-desktop-cache` is enbled, rebuild a cache with the content of desktop files.
If `drun-use-desktop-cache` is enabled, rebuild a cache with the content of desktop files.
`-pid` *path*
@ -789,7 +823,7 @@ For each state, the following 5 colors must be set:
The window background and border color should be specified separately. The key `color-window` contains
a tuple `background,border,separator`.
An example for `Xresources` file:
An example `Xresources` file:
! State: 'bg', 'fg', 'bgalt', 'hlbg', 'hlfg'
rofi.color-normal: #fdf6e3, #002b36, #eee8d5, #586e75, #eee8d5
@ -799,7 +833,7 @@ An example for `Xresources` file:
! 'background', 'border', 'separator'
rofi.color-window: #fdf6e3, #002b36, #002b36
Same settings can also be specified on command-line:
Same settings can also be specified on the command-line:
rofi -color-normal "#fdf6e3,#002b36,#eee8d5,#586e75,#eee8d5"
@ -873,54 +907,54 @@ A key binding starting with `!` will act when all keys have been released.
## Available Modi
### Window
### window
Show a list of all the windows and allow switching between them.
Pressing the `delete-entry` binding (`shift-delete`) will close the window.
Pressing the `accept-custom` binding (`control-enter` or `shift-enter`) will run a command on the window.
(See option `window-command` );
### WindowCD
### windowcd
Shows a list of the windows on the current desktop and allows switching between them.
Pressing the `delete-entry` binding (`shift-delete`) will kill the window.
Pressing the `accept-custom` binding (`control-enter` or `shift-enter`) will run a command on the window.
(See option `window-command` );
### Run
### run
Shows a list of executables in **$PATH** and can launch them (optional in a terminal).
Shows a list of executables in `$PATH` and can launch them (optional in a terminal).
Pressing the `delete-entry` binding (`shift-delete`) will remove this entry from the run history.
Pressing the `accept-custom` binding (`control-enter` or `shift-enter`) will run the command in a terminal.
### DRun
### drun
Same as the **run** launches, but the list is created from the installed desktop files. It automatically launches them
in a terminal if specified in the Desktop File.
Pressing the `delete-entry` binding (`shift-delete`) will remove this entry from the run history.
Pressing the `accept-custom` binding (`control-enter` or `shift-enter`) with custom input (no entry matching) will run the command in a terminal.
### SSH
### ssh
Shows a list of SSH targets based on your ssh config file, and allows to quickly `ssh` into them.
Shows a list of SSH targets based on your `ssh` config file, and allows to quickly `ssh` into them.
### Keys
### keys
Shows a searchable list of key bindings.
### Script
### script
Allows custom scripted Modi to be added.
## FAQ
### The text in the window switcher is not nicely lined out.
### The text in the window switcher is not nicely aligned.
Try using a mono-space font.
### The window is completely black.
Check quotes used on the commandline: you might have used `“` ("smart quotes") instead of `"` ("machine quotes").
Check quotes used on the command-line: you might have used `“` ("smart quotes") instead of `"` ("machine quotes").
### What does the icon in the top right show?
@ -939,15 +973,15 @@ Show the run dialog:
rofi -modi run -show run
Show the run dialog, and allow switching to Desktop File run dialog (drun):
Show the run dialog, and allow switching to Desktop File run dialog (`drun`):
rofi -modi run,drun -show run
Combine the run and Desktop File run dialog (drun):
Combine the run and Desktop File run dialog (`drun`):
rofi -modi combi -show combi -combi-modi run,drun
Combine the run and Desktop File run dialog (drun), and allow switching to window switcher:
Combine the run and Desktop File run dialog (`drun`), and allow switching to window switcher:
rofi -modi combi,window -show combi -combi-modi run,drun
@ -976,7 +1010,7 @@ Use `qalc` to get a simple calculator in **rofi**:
In [i3](http://i3wm.org/) you want to bind **rofi** to be launched on key release. Otherwise, it cannot grab the keyboard.
See also the i3 [manual](http://i3wm.org/docs/userguide.html):
Some tools (such as import or xdotool) might be unable to run upon a KeyPress event, because the keyboard/pointer is
Some tools (such as `import` or `xdotool`) might be unable to run upon a KeyPress event, because the keyboard/pointer is
still grabbed. For these situations, the `--release` flag can be used, as it will execute the command after the keys have
been released.
@ -1018,24 +1052,21 @@ Please see [this](https://github.com/DaveDavenport/rofi/wiki/Debugging Rofi) wik
## ISSUE TRACKER
**rofi** issue tracker can be found [here](https://github.com/DaveDavenport/rofi/issues)
The **rofi** issue tracker can be found [here](https://github.com/DaveDavenport/rofi/issues)
When creating an issue, please read [this](https://github.com/DaveDavenport/rofi/blob/master/.github/CONTRIBUTING.md)
first.
## SEE ALSO
rofi-sensible-terminal(1), dmenu(1), rofi-theme(5), rofi-script(5), rofi-theme-selector(1)
**rofi-sensible-terminal(1)**, **dmenu(1)**, **rofi-theme(5)**, **rofi-script(5)**, **rofi-theme-selector(1)**
## AUTHOR
Qball Cow <qball@gmpclient.org>
Rasmus Steinke <rasi@xssn.at>
Quentin Glidic <sardemff7+rofi@sardemff7.net>
* Qball Cow <qball@gmpclient.org>
* Rasmus Steinke <rasi@xssn.at>
* Quentin Glidic <sardemff7+rofi@sardemff7.net>
Original code based on work by: Sean Pringle <sean.pringle@gmail.com>
For a full list of authors, check the AUTHORS file.
For a full list of authors, check the `AUTHORS` file.