From 5eaa5572ef3944747d88c1d5506c934409383f39 Mon Sep 17 00:00:00 2001 From: Dave Davenport Date: Mon, 7 Jun 2021 23:13:21 +0200 Subject: [PATCH] [Manpage] Update rofi.1 --- doc/rofi-script.5 | 12 ++ doc/rofi-sensible-terminal.1 | 4 + doc/rofi-theme-selector.1 | 4 + doc/rofi-theme.5 | 225 +++++++++++++++++++++++++++++++---- doc/rofi.1 | 213 ++++++++++++++++++++++++--------- doc/rofi.1.markdown | 87 +++++++++----- 6 files changed, 436 insertions(+), 109 deletions(-) diff --git a/doc/rofi-script.5 b/doc/rofi-script.5 index 96aef1e2..bc6b98bc 100644 --- a/doc/rofi-script.5 +++ b/doc/rofi-script.5 @@ -64,6 +64,8 @@ Rofi sets the following environment variable when executing the script: .SS \fB\fCROFI\_RETV\fR .PP An integer number with the current state: + +.RS .IP \(bu 2 \fB0\fP: Initial call of script. .IP \(bu 2 @@ -73,6 +75,8 @@ An integer number with the current state: .IP \(bu 2 \fB10\-28\fP: Custom keybinding 1\-19 ( need to be explicitely enabled by script ). +.RE + .SS \fB\fCROFI\_INFO\fR .PP Environment get set when selected entry get set with the property value of the 'info' row option, if set. @@ -96,6 +100,8 @@ For example to set the prompt: .PP The following extra options exists: + +.RS .IP \(bu 2 \fBprompt\fP: Update the prompt text. .IP \(bu 2 @@ -113,6 +119,8 @@ The following extra options exists: .IP \(bu 2 \fBuse\-hot\-keys\fP: If set to true, it enabled the Custom keybindings for script. Warning this breaks the normal rofi flow. +.RE + .SH Parsing row options .PP Extra options for individual rows can be set. @@ -132,6 +140,8 @@ For example: .PP The following options are supported: + +.RS .IP \(bu 2 \fBicon\fP: Set the icon for that row. .IP \(bu 2 @@ -141,6 +151,8 @@ The following options are supported: .IP \(bu 2 \fBinfo\fP: Info that, on selection, gets placed in the \fB\fCROFI\_INFO\fR environment variable. This entry does not get searched. +.RE + .PP multiple entries can be passed using the \fB\fC\\x1f\fR separator. diff --git a/doc/rofi-sensible-terminal.1 b/doc/rofi-sensible-terminal.1 index 6d10df97..30d4a15d 100644 --- a/doc/rofi-sensible-terminal.1 +++ b/doc/rofi-sensible-terminal.1 @@ -16,6 +16,8 @@ shipping this script in a way which is appropriate for the distribution. .PP It tries to start one of the following (in that order): + +.RS .IP \(bu 2 \fB\fC$TERMINAL\fR (this is a non\-standard variable) .IP \(bu 2 @@ -53,6 +55,8 @@ alacritty .IP \(bu 2 kitty +.RE + .SH SEE ALSO .PP rofi(1) diff --git a/doc/rofi-theme-selector.1 b/doc/rofi-theme-selector.1 index 99525093..de076ff4 100644 --- a/doc/rofi-theme-selector.1 +++ b/doc/rofi-theme-selector.1 @@ -18,6 +18,8 @@ It lets you preview each theme with the Enter key and apply the theme to your .SH Theme directories .PP \fBrofi\-theme\-selector\fP searches the following directories for themes: + +.RS .IP \(bu 2 ${PREFIX}/share/rofi/themes .IP \(bu 2 @@ -25,6 +27,8 @@ $XDG\_CONFIG\_HOME/rofi/themes .IP \(bu 2 $XDG\_DATA\_HOME/share/rofi/themes +.RE + .PP ${PREFIX} reflects the install location of rofi. In most cases this will be "/usr".
$XDG\_CONFIG\_HOME is normally unset. Default path is "$HOME/.config".
diff --git a/doc/rofi-theme.5 b/doc/rofi-theme.5 index 13a48dc3..b486a647 100644 --- a/doc/rofi-theme.5 +++ b/doc/rofi-theme.5 @@ -19,11 +19,15 @@ preferred. .SH Comments .PP C and C++ file comments are supported. + +.RS .IP \(bu 2 Anything after \fB\fC//\fR and before a newline is considered a comment. .IP \(bu 2 Everything between \fB\fC/*\fR and \fB\fC*/\fR is a comment. +.RE + .PP Comments can be nested and the C comments can be inline. @@ -242,6 +246,8 @@ When used, values with the wrong type that cannot be converted are ignored. .PP The current theme format supports different types: + +.RS .IP \(bu 2 a string .IP \(bu 2 @@ -277,12 +283,18 @@ an environment variable .IP \(bu 2 Inherit +.RE + .PP Some of these types are a combination of other types. -.SH String.IP \(bu 2 +.SH String +.RS +.IP \(bu 2 Format: \fB\fC"[:print:]+"\fR +.RE + .PP A string is always surrounded by double quotes (\fB\fC"\fR). Between the quotes there can be any printable character. @@ -301,9 +313,13 @@ font: "Awasome 12"; .PP The string must be valid UTF\-8. -.SH Integer.IP \(bu 2 +.SH Integer +.RS +.IP \(bu 2 Format: \fB\fC[\-+]?[:digit:]+\fR +.RE + .PP An integer may contain any number. @@ -319,9 +335,13 @@ lines: 12; .fi .RE -.SH Real.IP \(bu 2 +.SH Real +.RS +.IP \(bu 2 Format: \fB\fC[\-+]?[:digit:]+(\\.[:digit:]+)?\fR +.RE + .PP A real is an integer with an optional fraction. @@ -340,9 +360,13 @@ real: 3.4; .PP The following is not valid: \fB\fC\&.3\fR, \fB\fC3.\fR or scientific notation: \fB\fC3.4e\-3\fR\&. -.SH Boolean.IP \(bu 2 +.SH Boolean +.RS +.IP \(bu 2 Format: \fB\fC(true|false)\fR +.RE + .PP Boolean value is either \fB\fCtrue\fR or \fB\fCfalse\fR\&. This is case\-\&sensitive. @@ -361,6 +385,8 @@ dynamic: false; .SH Color .PP \fBrofi\fP supports the color formats as specified in the CSS standard (1,2,3 and some of CSS 4) + +.RS .IP \(bu 2 Format: \fB\fC#{HEX}{3}\fR (rgb) .IP \(bu 2 @@ -382,11 +408,15 @@ Format: \fB\fCcmyk( {PERCENTAGE}, {PERCENTAGE}, {PERCENTAGE}, {PERCENTAGE} [, {P .IP \(bu 2 Format: \fB\fC{named\-color} [ / {PERCENTAGE} ]\fR +.RE + .PP The white\-space format proposed in CSS4 is also supported. .PP The different values are: + +.RS .IP \(bu 2 \fB\fC{HEX}\fR is a hexadecimal number ('0\-9a\-f' case insensitive). .IP \(bu 2 @@ -415,6 +445,8 @@ PapayaWhip, PeachPuff, Peru, Pink, Plum, PowderBlue, Purple, RebeccaPurple, Red, Salmon, SandyBrown, SeaGreen, SeaShell, Sienna, Silver, SkyBlue, SlateBlue, SlateGray, SlateGrey, Snow, SpringGreen, SteelBlue, Tan, Teal, Thistle, Tomato, Turquoise, Violet, Wheat, White, WhiteSmoke, Yellow, YellowGreen,transparent +.RE + .PP For example: @@ -442,12 +474,18 @@ text\-color: Black; .fi .RE -.SH Text style.IP \(bu 2 +.SH Text style +.RS +.IP \(bu 2 Format: \fB\fC(bold|italic|underline|strikethrough|none)\fR +.RE + .PP Text style indicates how the highlighted text is emphasized. \fB\fCNone\fR indicates that no emphasis should be applied. + +.RS .IP \(bu 2 \fB\fCbold\fR: make the text thicker then the surrounding text. .IP \(bu 2 @@ -457,16 +495,24 @@ should be applied. .IP \(bu 2 \fB\fCstrikethrough\fR: put a line through the highlighted text. -.SH Line style.IP \(bu 2 +.RE + +.SH Line style +.RS +.IP \(bu 2 Format: \fB\fC(dash|solid)\fR +.RE + .PP Indicates how a line should be drawn. It currently supports: * \fB\fCdash\fR: a dashed line, where the gap is the same width as the dash * \fB\fCsolid\fR: a solid line -.SH Distance.IP \(bu 2 +.SH Distance +.RS +.IP \(bu 2 Format: \fB\fC{Integer}px\fR .IP \(bu 2 Format: \fB\fC{Real}em\fR @@ -477,8 +523,12 @@ Format: \fB\fC{Real}%\fR .IP \(bu 2 Format: \fB\fC{Integer}mm\fR +.RE + .PP A distance can be specified in 3 different units: + +.RS .IP \(bu 2 \fB\fCpx\fR: Screen pixels. .IP \(bu 2 @@ -490,6 +540,8 @@ A distance can be specified in 3 different units: .IP \(bu 2 \fB\fC%\fR: Percentage of the \fBmonitor\fP size. +.RE + .PP Distances used in the horizontal direction use the monitor width. Distances in the vertical direction use the monitor height. @@ -523,6 +575,8 @@ width: calc( 100% \- 37px ); .PP It supports the following operations: + +.RS .IP \(bu 2 \fB\fC+\fR : Add .IP \(bu 2 @@ -538,10 +592,14 @@ It supports the following operations: .IP \(bu 2 \fB\fCmax\fR : Maximum of l or rvalue; +.RE + .PP It uses the C precedence ordering. -.SH Padding.IP \(bu 2 +.SH Padding +.RS +.IP \(bu 2 Format: \fB\fC{Integer}\fR .IP \(bu 2 Format: \fB\fC{Distance}\fR @@ -552,11 +610,15 @@ Format: \fB\fC{Distance} {Distance} {Distance}\fR .IP \(bu 2 Format: \fB\fC{Distance} {Distance} {Distance} {Distance}\fR +.RE + .PP If no unit is specified, pixels are assumed. .PP The different number of fields in the formats are parsed like: + +.RS .IP \(bu 2 1 field: \fB\fCall\fR .IP \(bu 2 @@ -566,7 +628,11 @@ The different number of fields in the formats are parsed like: .IP \(bu 2 4 fields: \fB\fCtop\fR, \fB\fCright\fR, \fB\fCbottom\fR, \fB\fCleft\fR -.SH Border.IP \(bu 2 +.RE + +.SH Border +.RS +.IP \(bu 2 Format: \fB\fC{Integer}\fR .IP \(bu 2 Format: \fB\fC{Distance}\fR @@ -585,6 +651,8 @@ Format: \fB\fC{Distance} {Line style} {Distance} {Line style} {Distance} {Line s .IP \(bu 2 Format: \fB\fC{Distance} {Line style} {Distance} {Line style} {Distance} {Line style} {Distance} {Line style}\fR +.RE + .PP Borders are identical to padding, except that each distance field has a line style property. @@ -599,9 +667,12 @@ When no unit is specified, pixels are assumed. .SH Position .PP Indicate a place on the window/monitor. -.IP \(bu 2 -Format: \fB\fC(center|east|north|west|south|north east|north west|south west|south east)\fR +.RS +.IP \(bu 2 + +.PP +Format: \fB\fC(center|east|north|west|south|north east|north west|south west|south east)\fR .PP .RS @@ -609,13 +680,15 @@ Format: \fB\fC(center|east|north|west|south|north east|north west|south west|sou north west | north | north east \-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\- - west | center | east + west | center | east \-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\- south west | south | south east .fi .RE +.RE + .SH Visibility .PP It is possible to hide widgets: @@ -625,9 +698,13 @@ inputbar { enabled: false; } -.SH Reference.IP \(bu 2 +.SH Reference +.RS +.IP \(bu 2 Format: \fB\fC@{PROPERTY NAME}\fR +.RE + .PP A reference can point to another reference. Currently, the maximum number of redirects is 20. A property always refers to another property. It cannot be used for a subpart of the property. @@ -660,28 +737,44 @@ window { .fi .RE -.SH Orientation.IP \(bu 2 +.SH Orientation +.RS +.IP \(bu 2 Format: \fB\fC(horizontal|vertical)\fR +.RE + .PP Specify the orientation of the widget. -.SH Cursor.IP \(bu 2 +.SH Cursor +.RS +.IP \(bu 2 Format: \fB\fC(default|pointer|text)\fR +.RE + .PP Specify the type of mouse cursor that is set when the mouse pointer is over the widget. -.SH List of keywords.IP \(bu 2 +.SH List of keywords +.RS +.IP \(bu 2 Format: \fB\fC[ keyword, keyword ]\fR +.RE + .PP A list starts with a '[' and ends with a ']'. The entries in the list are comma\-separated. The \fB\fCkeyword\fR in the list refers to an widget name. -.SH Environment variable.IP \(bu 2 +.SH Environment variable +.RS +.IP \(bu 2 Format: \fB\fC${:alnum:}\fR +.RE + .PP This will parse the environment variable as the property value. (that then can be any of the above types). The environment variable should be an alphanumeric string without white\-space. @@ -697,9 +790,13 @@ The environment variable should be an alphanumeric string without white\-space. .fi .RE -.SH Inherit.IP \(bu 2 +.SH Inherit +.RS +.IP \(bu 2 Format: \fB\fCinherit\fR +.RE + .PP Inherits the property from its parent widget. @@ -756,14 +853,20 @@ element selected { .SH Name .PP The current widgets available in \fBrofi\fP: + +.RS .IP \(bu 2 \fB\fCwindow\fR + +.RS .IP \(bu 2 \fB\fCoverlay\fR: the overlay widget. .IP \(bu 2 \fB\fCmainbox\fR: The mainbox box. .IP \(bu 2 \fB\fCinputbar\fR: The input bar box. + +.RS .IP \(bu 2 \fB\fCbox\fR: the horizontal @box packing the widgets .IP \(bu 2 @@ -776,27 +879,49 @@ The current widgets available in \fBrofi\fP: \fB\fCnum\-rows\fR: Shows the total number of rows. .IP \(bu 2 \fB\fCnum\-filtered\-rows\fR: Shows the total number of rows after filtering. + +.RE .IP \(bu 2 \fB\fClistview\fR: The listview. + +.RS .IP \(bu 2 \fB\fCscrollbar\fR: the listview scrollbar .IP \(bu 2 \fB\fCelement\fR: a box in the listview holding the entries + +.RS .IP \(bu 2 \fB\fCelement\-icon\fR: the widget in the listview's entry showing the (optional) icon .IP \(bu 2 \fB\fCelement\-index\fR: the widget in the listview's entry keybindable index (1,2,3..0) .IP \(bu 2 \fB\fCelement\-text\fR: the widget in the listview's entry showing the text. + +.RE + +.RE .IP \(bu 2 \fB\fCmode\-switcher\fR: the main horizontal @box packing the buttons. + +.RS .IP \(bu 2 \fB\fCbutton\fR: the buttons @textbox for each mode + +.RE .IP \(bu 2 \fB\fCmessage\fR: The container holding the textbox. + +.RS .IP \(bu 2 \fB\fCtextbox\fR: the message textbox +.RE + +.RE + +.RE + .PP Note that these path names match the default theme. Themes that provide a custom layout will have different elements, and structure. @@ -868,7 +993,9 @@ This allows the colors used for drawing the handle to be set independently. .PP The following properties are currently supported: -.SS all widgets:.IP \(bu 2 +.SS all widgets: +.RS +.IP \(bu 2 \fBenabled\fP: enable/disable the widget .IP \(bu 2 \fBpadding\fP: padding @@ -892,7 +1019,11 @@ Color of the border \fBcursor\fP: cursor Type of mouse cursor that is set when the mouse pointer is hovered over the widget. -.SS window:.IP \(bu 2 +.RE + +.SS window: +.RS +.IP \(bu 2 .PP \fBfont\fP: string @@ -936,7 +1067,11 @@ The width of the window \fBy\-offset\fP: distance The offset of the window to the anchor point, allowing you to push the window left/right/up/down -.SS scrollbar:.IP \(bu 2 +.RE + +.SS scrollbar: +.RS +.IP \(bu 2 \fBbackground\-color\fP: color .IP \(bu 2 \fBhandle\-width\fP: distance @@ -945,14 +1080,22 @@ The offset of the window to the anchor point, allowing you to push the window le .IP \(bu 2 \fBborder\-color\fP: color -.SS box:.IP \(bu 2 +.RE + +.SS box: +.RS +.IP \(bu 2 \fBorientation\fP: orientation Set the direction the elements are packed. .IP \(bu 2 \fBspacing\fP: distance Distance between the packed elements. -.SS textbox:.IP \(bu 2 +.RE + +.SS textbox: +.RS +.IP \(bu 2 \fBbackground\-color\fP: color .IP \(bu 2 \fBborder\-color\fP: the color used for the border around the widget. @@ -982,7 +1125,11 @@ color is optional, multiple highlight styles can be added like: bold underline i .IP \(bu 2 \fBmarkup\fP: Force markup on, beware that only valid pango markup strings are shown. -.SS listview:.IP \(bu 2 +.RE + +.SS listview: +.RS +.IP \(bu 2 \fBcolumns\fP: integer Number of columns to show (at least 1) .IP \(bu 2 @@ -1016,6 +1163,8 @@ Reverse the ordering (top down to bottom up). \fBfixed\-columns\fP: boolean Do not reduce the number of columns shown when number of visible elements is not enough to fill them all. +.RE + .PP Each element is a \fB\fCbox\fR called \fB\fCelement\fR\&. Each \fB\fCelement\fR can contain an \fB\fCelement\-icon\fR and \fB\fCelement\-text\fR\&. @@ -1142,6 +1291,8 @@ The layout of \fBrofi\fP can be tweaked by packing the 'fixed' widgets in a cust .PP The following widgets are fixed, as they provide core \fBrofi\fP functionality: + +.RS .IP \(bu 2 prompt .IP \(bu 2 @@ -1161,9 +1312,13 @@ num\-rows .IP \(bu 2 num\-filtered\-rows +.RE + .PP The following keywords are defined and can be used to automatically pack a subset of the widgets. These are used in the default theme as depicted in the figure above. + +.RS .IP \(bu 2 mainbox Packs: \fB\fCinputbar, message, listview, mode\-switcher\fR @@ -1171,11 +1326,15 @@ Packs: \fB\fCinputbar, message, listview, mode\-switcher\fR inputbar Packs: \fB\fCprompt,entry,case\-indicator\fR +.RE + .PP Any widget name starting with \fB\fCtextbox\fR is a textbox widget, others are box widgets and can pack other widgets. .PP There are several special widgets that can be used by prefixing the name of the widget: + +.RS .IP \(bu 2 \fB\fCtextbox\fR: This is a textbox widget. The displayed string can be set with \fB\fCstr\fR\&. @@ -1191,6 +1350,8 @@ The \fB\fCaction\fR can be set to: \fB\fCok|alternate\fR: accept entry and launch alternate action (for run launch in terminal). \fB\fCcustom|alternate\fR: accept custom input and launch alternate action. +.RE + .PP To specify children, set the \fB\fCchildren\fR property (this always happens on the \fB\fCbox\fR child, see example below): @@ -1281,6 +1442,8 @@ Just like CSS, \fBrofi\fP uses the box model for each widget. .PP Explanation of the different parts: + +.RS .IP \(bu 2 Content \- The content of the widget. .IP \(bu 2 @@ -1293,6 +1456,8 @@ The border use the border\-color of the widget. Margin \- Clears an area outside the border. The margin is transparent. +.RE + .PP The box model allows us to add a border around elements, and to define space between elements. @@ -1417,6 +1582,8 @@ Parts of the theme can be conditionally loaded, like the CSS \fB\fC@media\fR opt .PP It supports the following keys as constraint: + +.RS .IP \(bu 2 \fB\fCmin\-width\fR: load when width is bigger or equal then value. .IP \(bu 2 @@ -1432,6 +1599,8 @@ It supports the following keys as constraint: .IP \(bu 2 \fB\fCmonitor\-id\fR: The monitor id, see rofi \-help for id's. +.RE + .PP @media takes an integer number or a fraction, for integer number \fB\fCpx\fR can be added. @@ -1450,11 +1619,15 @@ It supports the following keys as constraint: .PP The rasi file format offers two methods of including other files. This can be used to modify existing themes, or have multiple variations on a theme. + +.RS .IP \(bu 2 import: Import and parse a second file. .IP \(bu 2 theme: Discard theme, and load file as a fresh theme. +.RE + .PP Syntax: @@ -1473,6 +1646,8 @@ The specified file can either by \fIname\fP, \fIfilename\fP,\fIfull path\fP\&. .PP If a filename is provided, it will try to resolve it in the following order: + +.RS .IP \(bu 2 \fB\fC${XDG\_CONFIG\_HOME}/rofi/themes/\fR .IP \(bu 2 @@ -1482,6 +1657,8 @@ If a filename is provided, it will try to resolve it in the following order: .IP \(bu 2 \fB\fC${INSTALL PREFIX}/share/rofi/themes/\fR +.RE + .PP A name is resolved as a filename by appending the \fB\fC\&.rasi\fR extension. diff --git a/doc/rofi.1 b/doc/rofi.1 index a7c217d1..af7c1acb 100644 --- a/doc/rofi.1 +++ b/doc/rofi.1 @@ -68,6 +68,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). It first checks XDG\_CONFIG\_DIRS and then SYSCONFDIR (that is passed at compile time). @@ -77,6 +79,8 @@ Rasi theme file: The new \fItheme\fP format can be used to set configuration val .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\-config > config.rasi\fR @@ -97,6 +101,8 @@ This will contain (commented) all current configuration options. .PP The configuration system supports the following types: + +.RS .IP \(bu 2 string .IP \(bu 2 @@ -104,10 +110,12 @@ integer (signed and unsigned) .IP \(bu 2 char .IP \(bu 2 -Boolean +boolean .IP \(bu 2 lists +.RE + .PP For the syntax of these options see the \fBrofi\-theme(5)\fP manpage. @@ -177,6 +185,8 @@ Try to parse the file and 0 when succesful. .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 @@ -184,6 +194,8 @@ 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 @@ -387,6 +399,8 @@ Make rofi steal focus on launch and restore close to window that held it when la .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 @@ -398,6 +412,8 @@ Current the following methods are supported. .IP \(bu 2 \fBprefix\fP: match prefix +.RE + .PP Default: \fInormal\fP @@ -422,6 +438,8 @@ Only show desktop files that are present in the listed categories. .PP 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 @@ -439,11 +457,15 @@ The different fields are: .PP Default: \fIname,generic,exec,categories,keywords\fP +.RE + .PP \fB\fC\-drun\-display\-format\fR .PP The format string for the \fB\fCdrun\fR dialog: + +.RS .IP \(bu 2 \fBname\fP: the application's name .IP \(bu 2 @@ -455,6 +477,8 @@ The format string for the \fB\fCdrun\fR dialog: .IP \(bu 2 \fBcomment\fP: the application comment +.RE + .PP Pango markup can be used to formatting the output. @@ -491,6 +515,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 @@ -508,6 +534,8 @@ The different fields are: .PP Default: \fIall\fP +.RE + .PP \fB\fC\-matching\-negate\-char\fR \fIchar\fP @@ -707,6 +735,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 @@ -723,6 +753,8 @@ behavior.) .PP Default: \fI\-5\fP +.RE + .PP See \fB\fCrofi \-h\fR output for the detected monitors, their position, and size. @@ -758,11 +790,15 @@ 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). .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 @@ -881,6 +917,8 @@ Format what is being displayed for windows. .PP \fIfield\fP: + +.RS .IP \(bu 2 \fBw\fP: desktop name .IP \(bu 2 @@ -892,6 +930,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. @@ -958,11 +998,15 @@ 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 + .PP \fB\fC\-max\-history\-size\fR \fInumber\fP @@ -1032,6 +1076,8 @@ Makes \fB\fCdmenu\fR searches case\-insensitive .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 @@ -1043,6 +1089,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 @@ -1069,6 +1117,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 @@ -1084,6 +1134,8 @@ Allows the output of dmenu to be customized (N is the total number of input entr .IP \(bu 2 \&'F' quoted filter string (user input) +.RE + .PP Default: 's' @@ -1188,12 +1240,6 @@ Message can be multi\-line. .PP Directory the file browser starts in. -.PP -.RS - -.fi -.RE - .SS Other .PP \fB\fC\-drun\-use\-desktop\-cache\fR @@ -1242,50 +1288,11 @@ Click the mouse outside of the \fBrofi\fP window to exit. .PP Default: \fIenabled\fP -.SS Debug -.PP -\fB\fC\-no\-config\fR - -.PP -Disable parsing of configuration. This runs rofi in \fIstock\fP mode. - -.PP -\fB\fC\-no\-plugins\fR - -.PP -Disables the loading of plugins. - -.PP -To get a trace with (lots of) debug information, set the following environment variable when executing \fBrofi\fP: - -.PP -.RS - -.nf -G\_MESSAGES\_DEBUG=all - -.fi -.RE - -.PP -The trace can be filtered by only outputting the relevant domains, for example: - -.PP -.RS - -.nf -G\_MESSAGES\_DEBUG=Dialogs.DRun - -.fi -.RE - -.PP -For more information on debugging, see the wiki -\[la]https://github.com/DaveDavenport/rofi/wiki/Debugging%20Rofi\[ra] - .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 @@ -1297,6 +1304,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. @@ -1313,11 +1322,13 @@ ln \-s /usr/bin/rofi /usr/bin/dmenu .SH THEMING .PP -Please see rofi\-theme(5) manpage for more information on themeing. +Please see \fBrofi\-theme(5)\fP manpage for more information on themeing. .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 @@ -1385,6 +1396,8 @@ Please see rofi\-theme(5) manpage for more information on themeing. .IP \(bu 2 \fB\fCCtrl\-l\fR: File complete for run dialog. +.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. @@ -1402,6 +1415,9 @@ Pressing the \fB\fCdelete\-entry\fR binding (\fB\fCshift\-delete\fR) will close 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 ); +.PP +If there is no match, it will try to launch the input. + .SS windowcd .PP Shows a list of the windows on the current desktop and allows switching between them. @@ -1418,6 +1434,10 @@ Shows a list of executables in \fB\fC$PATH\fR and can launch them (optional in a 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. +.PP +When pressing the \fB\fCmode\-complete\fR binding (\fB\fCControl\-l\fR), you can use the File Browser mode to launch the application +with a file as the first argument. + .SS drun .PP Same as the \fBrun\fP launches, but the list is created from the installed desktop files. It automatically launches them @@ -1425,6 +1445,14 @@ 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) will run the command in a terminal. +.PP +The DRUN mode tries to follows the XDG Desktop Entry +Specification +\[la]https://freedesktop.org/wiki/Specifications/desktop-entry-spec/\[ra] and should be compatible with +applications using this standard. Some application create invalid desktop files, \fBrofi\fP will discard these entries. +See de debugging section how to get more information from the DRUN mode, this will print why desktop files are +discarded. + .SS ssh .PP Shows a list of SSH targets based on your \fB\fCssh\fR config file, and allows to quickly \fB\fCssh\fR into them. @@ -1435,7 +1463,7 @@ Shows a searchable list of key bindings. .SS script .PP -Allows custom scripted Modi to be added. +Allows custom scripted Modi to be added, see the \fBrofi\-script(5)\fP manpage for more information. .SS combi .PP @@ -1636,14 +1664,85 @@ SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. .SH SUPPORT .PP -\fBrofi\fP support can be obtained here -\[la]irc://irc.libera.chat:6697/#rofi\[ra] (#rofi on irc.libera.chat), or via the -forum +\fBrofi\fP support can be obtained: + * GitHub Discussions +\[la]https://github.com/davatorium/rofi/discussions\[ra] + * Forum (reddit) \[la]https://reddit.com/r/qtools//\[ra] + * IRC +\[la]irc://irc.libera.chat:6697/#rofi\[ra] (#rofi on irc.libera.chat), .SH DEBUGGING .PP -Please see this +To debug it is smart to first try disabling your custom configuration: +\fB\fC\-no\-config\fR + +.PP +Disable parsing of configuration. This runs rofi in \fIstock\fP mode. + +.PP +If you run custom C plugins, you can disable them using: + +.PP +\fB\fC\-no\-plugins\fR + +.PP +Disables the loading of plugins. + +.PP +To further debug the plugin, you can get a trace with (lots of) debug information. This debug output can be enabled for +multiple parts in rofi using the glib debug framework. Debug domains can be enabled by setting the G\_MESSAGES\_DEBUG +environment variable. At creation of this page the following debug domains exists: + +.RS +.IP \(bu 2 +all: Show debug information from all domains. +.IP \(bu 2 +X11Helper: The X11 Helper functions. +.IP \(bu 2 +View: The main rofi\_view functions. +.IP \(bu 2 +Widgets.Box: The Box widget. +.IP \(bu 2 +Dialogs.DMenu: The dmenu mode. +.IP \(bu 2 +Dialogs.Run: The run mode. +.IP \(bu 2 +Dialogs.DRun: The desktop file run mode. +.IP \(bu 2 +Dialogs.Window: The window mode. +.IP \(bu 2 +Dialogs.Script: The script mode. +.IP \(bu 2 +Dialogs.Combi: The script mode. +.IP \(bu 2 +Dialogs.Ssh: The ssh mode. +.IP \(bu 2 +Rofi: The main application. +.IP \(bu 2 +Timings: Get timing output. +.IP \(bu 2 +Theme: Theme engine debug output. (warning lots of output). +.IP \(bu 2 +Widgets.Icon: The Icon widget. +.IP \(bu 2 +Widgets.Line: The line widget. +.IP \(bu 2 +Widgets.Box: The box widget. +.IP \(bu 2 +Widgets.Container: The container widget. +.IP \(bu 2 +Widgets.Window: The window widget. +.IP \(bu 2 +Helpers.IconFetcher: Information about icon lookup. + +.RE + +.PP +The output of this can provide useful information when writing an issue. + +.PP +More information (possibly outdated) see this \[la]https://github.com/DaveDavenport/rofi/wiki/Debugging Rofi\[ra] wiki entry. .SH ISSUE TRACKER @@ -1660,7 +1759,9 @@ first. .PP \fBrofi\-sensible\-terminal(1)\fP, \fBdmenu(1)\fP, \fBrofi\-theme(5)\fP, \fBrofi\-script(5)\fP, \fBrofi\-theme\-selector(1)\fP -.SH AUTHOR.IP \(bu 2 +.SH AUTHOR +.RS +.IP \(bu 2 Qball Cow \[la]qball@gmpclient.org\[ra] .IP \(bu 2 @@ -1670,6 +1771,8 @@ Rasmus Steinke Quentin Glidic \[la]sardemff7+rofi@sardemff7.net\[ra] +.RE + .PP Original code based on work by: Sean Pringle \[la]sean.pringle@gmail.com\[ra] diff --git a/doc/rofi.1.markdown b/doc/rofi.1.markdown index b365678e..c8414639 100644 --- a/doc/rofi.1.markdown +++ b/doc/rofi.1.markdown @@ -72,7 +72,7 @@ The configuration system supports the following types: * string * integer (signed and unsigned) * char - * Boolean + * boolean * lists For the syntax of these options see the **rofi-theme(5)** manpage. @@ -761,30 +761,6 @@ Click the mouse outside of the **rofi** window to exit. Default: *enabled* -### Debug - -`-no-config` - -Disable parsing of configuration. This runs rofi in *stock* mode. - -`-no-plugins` - -Disables the loading of plugins. - -To get a trace with (lots of) debug information, set the following environment variable when executing **rofi**: - -``` -G_MESSAGES_DEBUG=all -``` - -The trace can be filtered by only outputting the relevant domains, for example: - -``` -G_MESSAGES_DEBUG=Dialogs.DRun -``` - -For more information on debugging, see the [wiki](https://github.com/DaveDavenport/rofi/wiki/Debugging%20Rofi) - ## PATTERN 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: @@ -804,7 +780,7 @@ This way it can be used as a drop-in replacement for dmenu. Just copy or symlink ## THEMING -Please see rofi-theme(5) manpage for more information on themeing. +Please see **rofi-theme(5)** manpage for more information on themeing. ## KEY BINDINGS @@ -860,6 +836,8 @@ 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` ); +If there is no match, it will try to launch the input. + ### windowcd Shows a list of the windows on the current desktop and allows switching between them. @@ -875,6 +853,9 @@ Shows a list of executables in `$PATH` and can launch them (optional in a termin 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. +When pressing the `mode-complete` binding (`Control-l`), you can use the File Browser mode to launch the application +with a file as the first argument. + ### drun Same as the **run** launches, but the list is created from the installed desktop files. It automatically launches them @@ -882,6 +863,12 @@ 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`) will run the command in a terminal. +The DRUN mode tries to follows the [XDG Desktop Entry +Specification](https://freedesktop.org/wiki/Specifications/desktop-entry-spec/) and should be compatible with +applications using this standard. Some application create invalid desktop files, **rofi** will discard these entries. +See de debugging section how to get more information from the DRUN mode, this will print why desktop files are +discarded. + ### ssh Shows a list of SSH targets based on your `ssh` config file, and allows to quickly `ssh` into them. @@ -892,7 +879,7 @@ Shows a searchable list of key bindings. ### script -Allows custom scripted Modi to be added. +Allows custom scripted Modi to be added, see the **rofi-script(5)** manpage for more information. ### combi @@ -1003,12 +990,52 @@ been released. ## SUPPORT -**rofi** support can be obtained [here](irc://irc.libera.chat:6697/#rofi) (#rofi on irc.libera.chat), or via the -[forum](https://reddit.com/r/qtools//) +**rofi** support can be obtained: + * [GitHub Discussions](https://github.com/davatorium/rofi/discussions) + * [Forum (reddit)](https://reddit.com/r/qtools//) + * [IRC](irc://irc.libera.chat:6697/#rofi) (#rofi on irc.libera.chat), ## DEBUGGING -Please see [this](https://github.com/DaveDavenport/rofi/wiki/Debugging Rofi) wiki entry. +To debug it is smart to first try disabling your custom configuration: +`-no-config` + +Disable parsing of configuration. This runs rofi in *stock* mode. + +If you run custom C plugins, you can disable them using: + +`-no-plugins` + +Disables the loading of plugins. + +To further debug the plugin, you can get a trace with (lots of) debug information. This debug output can be enabled for +multiple parts in rofi using the glib debug framework. Debug domains can be enabled by setting the G_MESSAGES_DEBUG +environment variable. At creation of this page the following debug domains exists: + + * all: Show debug information from all domains. + * X11Helper: The X11 Helper functions. + * View: The main rofi_view functions. + * Widgets.Box: The Box widget. + * Dialogs.DMenu: The dmenu mode. + * Dialogs.Run: The run mode. + * Dialogs.DRun: The desktop file run mode. + * Dialogs.Window: The window mode. + * Dialogs.Script: The script mode. + * Dialogs.Combi: The script mode. + * Dialogs.Ssh: The ssh mode. + * Rofi: The main application. + * Timings: Get timing output. + * Theme: Theme engine debug output. (warning lots of output). + * Widgets.Icon: The Icon widget. + * Widgets.Line: The line widget. + * Widgets.Box: The box widget. + * Widgets.Container: The container widget. + * Widgets.Window: The window widget. + * Helpers.IconFetcher: Information about icon lookup. + +The output of this can provide useful information when writing an issue. + +More information (possibly outdated) see [this](https://github.com/DaveDavenport/rofi/wiki/Debugging Rofi) wiki entry. ## ISSUE TRACKER