From 8f8c69dc1676ed8fed7dd94d72b67e9e60370d9a Mon Sep 17 00:00:00 2001 From: Scoopta Date: Mon, 13 Jan 2020 18:59:52 -0800 Subject: [PATCH] Added man pages --- man/wofi.1 | 110 +++++++++++++++++++++++++++++++++++++ man/wofi.5 | 155 +++++++++++++++++++++++++++++++++++++++++++++++++++++ man/wofi.7 | 97 +++++++++++++++++++++++++++++++++ 3 files changed, 362 insertions(+) create mode 100644 man/wofi.1 create mode 100644 man/wofi.5 create mode 100644 man/wofi.7 diff --git a/man/wofi.1 b/man/wofi.1 new file mode 100644 index 0000000..a3b93ed --- /dev/null +++ b/man/wofi.1 @@ -0,0 +1,110 @@ +.TH wofi 1 +.SH NAME +wofi \- A rofi inspired launcher for wlroots compositors + +.SH SYNOPSIS +.B wofi +[options] + +.SH DESCRIPTION +.B wofi +is a rofi inspired menu program for wlroots compositors such as sway. It is intended to be highly customizable and flexible with the help of CSS styling and a dmenu mode that allows for endless scriptability. Wofi can be run cacheless in dmenu mode automatically by invoking it as dmenu with symlink. + +Wofi was designed specifically for wlroots and makes use of the wlr\-layer\-shell protocol. If your compositor does not support this protocol or if you are in a non\-wayland environment then wofi must be run with \fB\-\-normal\-window\fR or it will crash. If you wish to run wofi this way you can also place \fBnormal_window=true\fR in your config file to avoid specifying the option on the command line. + +.SH OPTIONS +.TP +.B \-h, \-\-help +Prints the help message and then exits. +.TP +.B \-f, \-\-fork +Forks the menu so the terminal running it can be closed. +.TP +.B \-c, \-\-conf=\fIPATH\fR +Specifies the config file to use. +.TP +.B \-s, \-\-style=\fIPATH\fR +Specifies the CSS file to use as the stylesheet. +.TP +.B \-C, \-\-color=\fIPATH\fR +Specifies the colors file to use. +.TP +.B \-d, \-\-dmenu +Runs wofi in dmenu mode. +.TP +.B \-S, \-\-show=\fIMODE\fR +Specifies the mode to run in. A list of modes can be found in \fBwofi\fR(7). +.TP +.B \-W, \-\-width=\fIWIDTH\fR +Specifies the menu width in pixels, default is 1000. +.TP +.B \-H, \-\-height=\fIHEIGHT\fR +Specifies the menu height in pixels, default is 400. +.TP +.B \-p, \-\-prompt=\fIPROMPT\fR +Sets the prompt to be display in the search box, default is the name of the mode. +.TP +.B \-x, \-\-xoffset=\fIOFFSET\fR +Sets the x offset from the location in pixels, default is 0. +.TP +.B \-y, \-\-yoffset=\fIOFFSET\fR +Sets the y offset from the location in pixels, default is 0. +.TP +.B \-n, \-\-normal\-window +Runs wofi in a normal window instead of using wlr\-layer\-shell. +.TP +.B \-I, \-\-allow\-images +Allows image escape sequences to be processed and rendered. +.TP +.B \-m, \-\-allow\-markup +Allows pango markup to be processed and rendered. +.TP +.B \-k, \-\-cache\-file=\fIPATH\fR +Specifies the cache file to load/store cache, default is $XDG_CACHE_HOME/wofi- where is the name of the mode, if $XDG_CACHE_HOME is not specified ~/.cache is used. +.TP +.B \-t, \-\-term=\fITERM\fR +Specifies the term to use when running a program in a terminal. This overrides the default terminal run order which is kitty, termite, gnome-terminal, weston-terminal in that order. +.TP +.B \-P, \-\-password \fR[character] +Runs wofi in password mode with an optional password character to use. If no character is specified * is used by default. +.TP +.B \-e, \-\-exec\-search +Activiating a seach with enter will execute the search not the first result. +.TP +.B \-b, \-\-hide\-scroll +Hides the scroll bars. +.TP +.B \-M, \-\-matching=\fIMODE\fR +Specifies the matching mode, it can be either contains or fuzzy, default is contains. +.TP +.B \-i, \-\-insensitive +Enables case insensitive search. +.TP +.B \-q, \-\-parse\-search +Parses out image escapes and pango preventing them from being used for searching. +.TP +.B \-v, \-\-version +Prints the version and then exits. +.TP +.B \-l, \-\-location=\fILOCATION\fR +Specifies the location. See \fBwofi\fR(7) for more information, default is center. +.TP +.B \-a, \-\-no\-actions +Disables multiple actions for modes that support it. + +.SH CONFIGURATION +Wofi has 3 main files used for configuration. All files are completely optional. +.IP 1. 4 +The config file which defaults to $XDG_CONFIG_HOME/wofi/config. +.IP 2. 4 +The CSS file which defaults to $XDG_CONFIG_HOME/wofi/style.css. +.IP 3. 4 +The colors file which defaults to the pywal cache $XDG_CACHE_HOME/wal/colors. + +.P +All 3 of these paths can be manually specified using the respective command line flag. In the case of the last 2 they can additionally be specified in the config file. + +In the event $XDG_CONFIG_HOME is not specified it defaults to ~/.config likewise if $XDG_CACHE_HOME is not specified it defaults to ~/.cache. + +Information about the formats for these files can be found in +.B wofi\fR(5). diff --git a/man/wofi.5 b/man/wofi.5 new file mode 100644 index 0000000..07505cd --- /dev/null +++ b/man/wofi.5 @@ -0,0 +1,155 @@ +.TH wofi 5 +.SH NAME +wofi \- configuration file and styling + +.SH DESCRIPTION +Wofi's configuration format is very simple, consisting of key value pairs in snake case. The majority of the config options are the command line options, there are however a small handful of options only accessible via wofi's config. + +Mode specific options for the built-in modes are documented in \fBwofi\fR(7). They are placed in the config file in the format \fBmode-example_opt=val\fR. For example dmenu has an option called \fBparse_action\fR which would be placed in the config as \fBdmenu-parse_action=true\fR. + +.SH CONFIG OPTIONS +Most of the options here are the command flags as found in \fBwofi\fR(1) in snake case, however some are unique to the config. + +.TP +.B style=\fIPATH\fR +Specifies the CSS file to use as the stylesheet. +.TP +.B stylesheet=\fIPATH\fR +Specifies the CSS file to use as the stylesheet. This option is NOT the same as \fBstyle\fR. Absolute paths are absolute however relative paths are relative to the wofi config folder location $XDG_CONFIG_HOME/wofi and NOT the current working directory as they are with \fBstyle\fR. They are also NOT relative to the path as specified by \fB\-\-conf\fR. This option comes from rootbar and is probably more confusing than it's worth. You should probably use \fBstyle\fR unless you're sure this is what you want. +.TP +.B color=\fIPATH\fR +Specifies the colors file to use. +.TP +.B colors=\fIPATH\fR +Specifies the colors file to use. This option is NOT the same as \fBcolor\fR. Absolute paths are absolute however relative paths are relative to the wofi config folder location $XDG_CONFIG_HOME/wofi and NOT the current working directory as they are with \fBcolor\fR. They are also NOT relative to the path as specified by \fB\-\-conf\fR. This option comes from rootbar and is probably more confusing than it's worth. You should probably use \fBcolor\fR unless you're sure this is what you want. +.TP +.B show=\fIMODE\fR +Specifies the mode to run in. A list of modes can be found in \fBwofi\fR(7). +.TP +.B mode=\fIMODE\fR +Identical to \fBshow\fR. +.TP +.B width=\fIWIDTH\fR +Specifies the menu width in pixels, default is 1000. +.TP +.B height=\fIHEIGHT\fR +Specifies the menu height in pixels, default is 400. +.TP +.B prompt=\fIPROMPT\fR +Sets the prompt to be display in the search box, default is the name of the mode. +.TP +.B xoffset=\fIOFFSET\fR +Sets the x offset from the location in pixels, default is 0. +.TP +.B x=\fIOFFSET\fR +Identical to \fBxoffset\fR. +.TP +.B yoffset=\fIOFFSET\fR +Sets the y offset from the location in pixels, default is 0. +.TP +.B y=\fIOFFSET\fR +Identical to \fByoffset\fR. +.TP +.B normal_window=\fIBOOL\fR +If true runs wofi in a normal window instead of using wlr\-layer\-shell, default is false. +.TP +.B allow_images=\fIBOOL\fR +If true allows image escape sequences to be processed and rendered, default is false. +.TP +.B allow_markup=\fIBOOL\fR +If true allows pango markup to be processed and rendered, default is false. +.TP +.B cache_file=\fIPATH\fR +Specifies the cache file to load/store cache, default is $XDG_CACHE_HOME/wofi- where is the name of the mode, if $XDG_CACHE_HOME is not specified ~/.cache is used. +.TP +.B term=\fITERM\fR +Specifies the term to use when running a program in a terminal. This overrides the default terminal run order which is kitty, termite, gnome-terminal, weston-terminal in that order. +.TP +.B password=\fICHARACTER\fR +Runs wofi in password mode using the specified character, default is false. +.TP +.B exec_search=\fIBOOL\fR +If true activiating a seach with enter will execute the search not the first result, default is false. +.TP +.B hide_scroll=\fIBOOL\fR +If true hides the scroll bars, default is false. +.TP +.B matching=\fIMODE\fR +Specifies the matching mode, it can be either contains or fuzzy, default is contains. +.TP +.B insensitive=\fIBOOL\fR +If true enables case insensitive search, default is false. +.TP +.B parse_search=\fIBOOL\fR +If true parses out image escapes and pango preventing them from being used for searching, default is false. +.TP +.B location=\fILOCATION\fR +Specifies the location. See \fBwofi\fR(7) for more information, default is center. +.TP +.B no_actions=\fIBOOL\fR +If true disables multiple actions for modes that support it, default is false. +.TP +.B orientation=\fIORIENTATION\fR +Specifies the orientation, it can be either horizontal or vertical, default is vertical. +.TP +.B halign=\fIALIGN\fR +Specifies the horizontal align for the entire scrolled area, it can be any of fill, start, end, or center, default is fill. +.TP +.B content_halign=\fIALIGN\fR +Specifies the horizontal align for the individual entries, it can be any of fill, start, end, or center, default is fill. +.TP +.B valign=\fIALIGN\fR +Specifies the vertical align for the entire scrolled area, it can be any of fill, start, end, or center, the default is orientation dependent. If vertical then it defaults to start, if horizontal it defaults to center. +.TP +.B filter_rate=\fIRATE\fR +Specifies the rate at which search results are updated in milliseconds, default is 100. +.TP +.B image_size=\fISIZE\fR +Specifies the size of images in pixels when images are enabled, default is 32. + +.SH CSS SELECTORS +Any GTK widget can be selected by using the name of its CSS node, these however might change with updates and are not guarenteed to stay constant. Wofi also provides certain widgets with names and classes which can be referenced from CSS to give access to the most important widgets easily. \fBwofi\fR(7) contains the current widget layout used by wofi so if you want to get into CSS directly using GTK widget names look there for info. + +.TP +.B #window +.br +The name of the window itself. +.TP +.B #outer\-box +.br +The name of the box that contains everything. +.TP +.B #input +.br +The name of the search bar. +.TP +.B #scroll +.br +The name of the scrolled window containing all of the entries. +.TP +.B #inner\-box +.br +The name of the box containing all of the entries. +.TP +.B #img +.br +The name of all images in entries displayed in image mode. +.TP +.B #text +.br +The name of all the text in entries. +.TP +.B #unselected +.br +The name of all entries currently unselected. +.TP +.B #selected +.br +The name of all entries currently selected. +.TP +.B .entry +.br +The class attached to all entries. + +.SH COLORS +The colors file should be formatted as new line separated hex values. These values should be in the standard HTML format and begin with a hash. diff --git a/man/wofi.7 b/man/wofi.7 new file mode 100644 index 0000000..55a7666 --- /dev/null +++ b/man/wofi.7 @@ -0,0 +1,97 @@ +.TH wofi 7 +.SH NAME +wofi \- Built in modes and other features + +.SH DESCRIPTION +Wofi contains several built in modes as well as support for a combi like feature as well as a lot of other features which are documented here. + +.SH MODES +Currently wofi has 3 built in modes +.IP 1. 4 +run \- searches $PATH for executables and allows them to be run by selecting them. +.IP 2. 4 +drun \- searches $XDG_DATA_HOME/applications and $XDG_DATA_DIRS/applications for desktop files and allows them to be run by selecting them. +.IP 3. 4 +dmenu \- reads from stdin and displays options which when selected will be output to stdout. + +.P +In the event $XDG_DATA_HOME is not specified it defaults to ~/.local/share. If $XDG_DATA_DIRS is not specified it defaults to /usr/local/share:/usr/share. + +Combi is not a mode however it does exist as a feature. You can use it by doing --show mode1,mode2,mode3,etc. You can mix and match any number of modes however each mode can only be loaded once so doing something like --show run,drun,run is not supported although I'm not sure why you'd do that in the first place. + +.SH DMENU CONFIG OPTIONS +.TP +.B parse_action=\fIBOOL\fR +If true the result returned by dmenu will be stripped of image escape sequences and pango markup, default is false. + +.SH RUN CONFIG OPTIONS +.TP +.B always_parse_args=\fIBOOL\fR +If true spaces will not be treated as part of the executable name but rather as an argument separator equivalent to holding control while pressing enter, default is false. +.TP +.B show_all=\fIBOOL\fR +If true shows all the entries in path, this will show entries that have the same executable name, for example /bin/bash and /usr/bin/bash will be shown separately as bash instead of having one bash entry for the first one encountered, default is true. + +.SH LOCATIONS +There are 9 possible locations which can be specified either by name or by number, the number scheme is the same as in rofi and the corresponding number is listed next to the names below, the default is center. +.IP 1. 4 +center 0 +.IP 2. 4 +top_left 1 +.IP 3. 4 +top 2 +.IP 4. 4 +top_right 3 +.IP 5. 4 +right 4 +.IP 6. 4 +bottom_right 5 +.IP 7. 4 +bottom 6 +.IP 8. 4 +bottom_left 7 +.IP 9. 4 +left 8 + +.P +The x and y offsets are applied based on layer\-shell anchors which means an x offset can only be applied if wofi is anchored on the x axis, i.e. you can only use an x offset with the top_left, top_right, right, bottom_right, bottom_left, and left locations. center, top, and bottom can't have x offsets as they're not anchored on the x axis. Likewise y offsets can only be applied to top_left, top, top_right, bottom_right, bottom, and bottom_left locations. center, left, and right can't have y offsets because they're not anchored to the y axis. Since center can't have offsets on either as it's not anchored to any axis any x or y offset applied while using center will override the location to top_left for backwards compatiblity reasons seeing as not doing so would simply ignore the offsets anyway. + +.SH WIDGET LAYOUT +This section is for advanced CSS which needs more control than the built in wofi CSS names/classes allow for. This widget layout is subject to change at any time and without warning so your CSS might very well break if you rely on this. Widgets which have their corresponding names next to them if they have them. + +.B window \- #window +.RS 4 +.B box \- #outer\-box +.RS 4 +.B entry \- #input + +.B scrolledwindow \- #scroll +.RS 4 +.B viewport +.RS 4 +.B box +.RS 4 +.B flowbox \- #inner\-box +.RS 4 +.B flowboxchild +.RS 4 +.B .entry \- #unselected or #selected +.br +This is a WofiPropertyBox which has no CSS node however the .entry class is attached, the name is dependent on whether or not the entry is selected. + +.RS 4 +.B image +.br +This is only present if an image is present in the entry and might occur multiple times if multiple images are present. + +.B label +.br +This is only present if text is present in the entry and might occur multiple times if there are multiple text objects in a single entry. +.RE +.RE +.RE +.RE +.B scrollbar +.RE +.RE +.RE