From 57786e08f403d855a6ffa4ed34995cba155da23a Mon Sep 17 00:00:00 2001 From: Stardust-kyun <56178655+Stardust-kyun@users.noreply.github.com> Date: Sat, 28 Jan 2023 09:27:21 -0500 Subject: [PATCH] Readability edits for docs (#197) --- docs/home.md | 8 ++++---- docs/layouts/layout.md | 2 +- docs/module/flash.md | 4 ++-- docs/module/scratch.md | 8 ++++---- docs/module/swal.md | 2 +- docs/module/tabbed.md | 4 ++-- docs/module/twall.md | 2 +- docs/module/wall.md | 8 ++++---- docs/signals/pctl.md | 6 +++--- docs/widgets/app_launcher.md | 2 +- docs/widgets/tabbed_misc.md | 6 +++--- docs/widgets/tag_preview.md | 2 +- docs/widgets/task_preview.md | 4 ++-- docs/widgets/window_switcher.md | 2 +- 14 files changed, 30 insertions(+), 30 deletions(-) diff --git a/docs/home.md b/docs/home.md index 8c0ad44..2b07620 100644 --- a/docs/home.md +++ b/docs/home.md @@ -4,14 +4,14 @@ [AwesomeWM](https://awesomewm.org/) is literally what it stands for, an awesome window manager. -Its unique selling point has always been the widget system, which allows for fancy buttons, sliders, bars, dashboards and anything you can imagine. But that feature can be a curse. Most modules focus on the widget side of things which leave the actual window managing part of AwesomeWM underdeveloped compared to, for example, [xmonad](https://xmonad.org/) even though it's probably just as powerful in that area. +Its unique selling point has always been the widget system, which allows for fancy buttons, sliders, bars, dashboards, and anything you can imagine. But that feature can be a curse. Most modules focus on the widget side of things, which leaves the actual window managing part of AwesomeWM underdeveloped compared to, for example, [xmonad](https://xmonad.org/), even though it's probably just as powerful in that area. -This project focuses on that problem - adding new layouts and modules that make use of the widget system, but primarily focus on the new window managing features. +This project aims to fix that problem, adding new layouts and modules that make use of the widget system but primarily focusing on window managing features. ## Installation -- clone this repo into your `~/.config/awesome` folder +- Clone this repo into your `~/.config/awesome` folder - `git clone https://github.com/BlingCorp/bling.git ~/.config/awesome/bling` -- require the module in your `rc.lua`, and make sure it's under the beautiful module initialization +- Require the `bling` module in your `rc.lua`, making sure it's under the `beautiful` module initialization ```lua -- other imports diff --git a/docs/layouts/layout.md b/docs/layouts/layout.md index cbeb20c..e77b71c 100644 --- a/docs/layouts/layout.md +++ b/docs/layouts/layout.md @@ -2,7 +2,7 @@ Choose layouts from the list below and add them to to your `awful.layouts` list in your `rc.lua`. -Every one of them supports multiple master clients and master width factor making them easy to use. +Each layout supports multiple master clients and master width factors, making them easy to use. The mstab layout uses the tab theme from the tabbed module. diff --git a/docs/module/flash.md b/docs/module/flash.md index a12b78d..00a3521 100644 --- a/docs/module/flash.md +++ b/docs/module/flash.md @@ -1,6 +1,6 @@ ## 🔦 Flash Focus -Flash focus does an opacity animation effect on a client when it is focused. +Flash focus creates an opacity flash animation when a client is focused. ### Usage @@ -9,7 +9,7 @@ There are two ways in which you can use this module. You can enable it by callin ```lua bling.module.flash_focus.enable() ``` -This connects to the focus signal of a client, which means that the flash focus will activate however you focus the client. +This connects to the focus signal of a client, which means that the flash focus will activate with whatever method you use to focus the client. The other way is to call the function itself like this: `bling.module.flash_focus.flashfocus(someclient)`. This allows you to activate on certain keybinds like so: ```lua diff --git a/docs/module/scratch.md b/docs/module/scratch.md index 9b0b28b..64dc96d 100644 --- a/docs/module/scratch.md +++ b/docs/module/scratch.md @@ -69,7 +69,7 @@ term_scratch:connect_signal("turn_on", function(c) naughty.notify({title = "Turn The following signals are currently available. `turn_on`, `turn_off` and `inital_apply` pass the client on which they operated as an argument: -- `turn_on` fires when the scratchpad is turned on on a tag that it wasn't present on before -- `turn_off` fires when the scratchpad is turned off on a tag -- `spawn` fires when the scratchpad is launched with the given command -- `inital_apply` fires after `spawn`, when a corresponding client has been found and the properties have been applied +- `turn_on` fires when the scratchpad is turned on on a tag that it wasn't present on before. +- `turn_off` fires when the scratchpad is turned off on a tag. +- `spawn` fires when the scratchpad is launched with the given command. +- `inital_apply` fires after `spawn`, when a corresponding client has been found and the properties have been applied. diff --git a/docs/module/swal.md b/docs/module/swal.md index 0b3fed6..18a6b71 100644 --- a/docs/module/swal.md +++ b/docs/module/swal.md @@ -4,7 +4,7 @@ Can your window manager swallow? It probably can... ### Usage -To activate and deactivate window swallowing here are the following functions. If you want to activate it, just call the `start` function once in your `rc.lua`. +To activate and deactivate window swallowing use the following functions. If you only want to activate it, call the `start` function once in your `rc.lua`. ```lua bling.module.window_swallowing.start() -- activates window swallowing bling.module.window_swallowing.stop() -- deactivates window swallowing diff --git a/docs/module/tabbed.md b/docs/module/tabbed.md index 14b678a..7c9f5db 100644 --- a/docs/module/tabbed.md +++ b/docs/module/tabbed.md @@ -1,6 +1,6 @@ ## 📑 Tabbed -Tabbed implements a tab container. There are also different themes for the tabs. +Tabbed implements a tab container. There are several different themes for the tabs as well. ### Usage @@ -8,7 +8,7 @@ You should bind these functions to keys in order to use the tabbed module effect ```lua bling.module.tabbed.pick() -- picks a client with your cursor to add to the tabbing group bling.module.tabbed.pop() -- removes the focused client from the tabbing group -bling.module.tabbed.iter() -- iterates through the currently focused tabbing group +bling.module.tabbed.iter() -- iterates through the currently focused tabbing group bling.module.tabbed.pick_with_dmenu() -- picks a client with a dmenu application (defaults to rofi, other options can be set with a string parameter like "dmenu") bling.module.tabbed.pick_by_direction(dir) -- picks a client based on direction ("up", "down", "left" or "right") ``` diff --git a/docs/module/twall.md b/docs/module/twall.md index e0049e7..cacdb16 100644 --- a/docs/module/twall.md +++ b/docs/module/twall.md @@ -2,7 +2,7 @@ ### Usage -The function to set an automatically created tiled wallpaper can be called the following way (you don't need to set every option in the table): +The function to set a tiled wallpaper can be called by the following (not every option is necessary): ```lua awful.screen.connect_for_each_screen(function(s) -- that way the wallpaper is applied to every screen bling.module.tiled_wallpaper("x", s, { -- call the actual function ("x" is the string that will be tiled) diff --git a/docs/module/wall.md b/docs/module/wall.md index a3a26c8..23e0ba2 100644 --- a/docs/module/wall.md +++ b/docs/module/wall.md @@ -83,8 +83,8 @@ A wallpaper is one of the following elements: * a list containing any of the elements above To set up for multiple screens, two possible methods are: -* Call the `setup` function for each screen, passing the appropriate configuration and `screen` arg -* Call the `setup` function once, passing a table of screens as the `screen` arg. This applies the same configuration to all screens in the table +* Call the `setup` function for each screen, passing the appropriate configuration and `screen` arg. +* Call the `setup` function once, passing a table of screens as the `screen` arg. This applies the same configuration to all screens in the table. _Note_: Multiple screen setup only works for the `simple` and `random` setters ```lua @@ -105,8 +105,8 @@ bling.module.wallpaper.setup { ``` The provided setters `simple` and `random` will use 2 internal functions that you can use to write your own setter: -* `bling.module.wallpaper.prepare_list`: return a list of wallpapers directly usable by `apply` (for now, it just explores folders) -* `bling.module.wallpaper.apply`: a wrapper for gears.wallpaper functions, using the args table of setup +* `bling.module.wallpaper.prepare_list`: return a list of wallpapers directly usable by `apply` (for now, it just explores folders). +* `bling.module.wallpaper.apply`: a wrapper for gears.wallpaper functions, using the args table of setup. Here are the defaults: diff --git a/docs/signals/pctl.md b/docs/signals/pctl.md index 89a0709..c75547f 100644 --- a/docs/signals/pctl.md +++ b/docs/signals/pctl.md @@ -9,7 +9,7 @@ This is a signal module in which you can connect to certain bling signals to gra - Song length - If there are no players on -This module relies on `playerctl` and `curl`. If you have this module disabled, you won't need those programs. With this module, you can create a widget like below without worrying about the backend. +This module relies on `playerctl` and `curl`. If you have this module disabled, you won't need those programs. With this module, you can create a widget like the one below without worrying about the backend. ![](https://user-images.githubusercontent.com/33443763/107377569-fa807900-6a9f-11eb-93c1-174c58eb7bf1.png) @@ -157,7 +157,7 @@ end) Thats all! You don't even have to worry about updating the widgets, the signals will handle that for you. -Here's another example in which you get a notification with the album art, title, and artist whenever the song changes. +Here's another example in which you get a notification with the album art, title, and artist whenever the song changes: ```lua local naughty = require("naughty") @@ -184,7 +184,7 @@ button:buttons(gears.table.join( ### Theme Variables and Configuration -By default, this module will output signals from the most recently active player. If you wish to customize the behavior furthur, the following configuration options are available depending on the selected backend. Here is a summary of the two backends and which configuration options they support. +By default, this module will output signals from the most recently active player. If you wish to customize the behavior furthur, the following configuration options are available depending on the selected backend. Here is a summary of the two backends and which configuration options they support: | Option | playerctl_cli | playerctl_lib | | ------------------- | ------------------ | ------------------ | diff --git a/docs/widgets/app_launcher.md b/docs/widgets/app_launcher.md index be11343..a680f6a 100644 --- a/docs/widgets/app_launcher.md +++ b/docs/widgets/app_launcher.md @@ -14,7 +14,7 @@ To enable: local app_launcher = bling.widget.app_launcher() ``` -To run the app launcher, call `:toggle()` on the launcher. +To run the app launcher, call `:toggle()` on the launcher: ```lua app_launcher:toggle() diff --git a/docs/widgets/tabbed_misc.md b/docs/widgets/tabbed_misc.md index 3c41b19..c2e537e 100644 --- a/docs/widgets/tabbed_misc.md +++ b/docs/widgets/tabbed_misc.md @@ -28,7 +28,7 @@ bling.widget.tabbed_misc.titlebar_indicator(client, { }) ``` -a widget_template option is also available: +A `widget_template` option is also available: ```lua bling.widget.tabbed_misc.titlebar_indicator(client, { widget_template = { @@ -50,7 +50,7 @@ bling.widget.tabbed_misc.titlebar_indicator(client, { ### Example Implementation -You normally embed the widget in your titlebar... +The widget is typically embedded in a titlebar: ```lua awful.titlebar(c).widget = { { -- Left @@ -75,7 +75,7 @@ awful.titlebar(c).widget = { ``` ## Tasklist -The module exports a function that can be added to your tasklist as a `update_callback` +This module exports a function that can be added to your tasklist as an `update_callback`. ### Usage ```lua diff --git a/docs/widgets/tag_preview.md b/docs/widgets/tag_preview.md index bdf033d..ce96a60 100644 --- a/docs/widgets/tag_preview.md +++ b/docs/widgets/tag_preview.md @@ -49,7 +49,7 @@ By default, the widget is not visible. You must implement when it will update an ### Example Implementation -We can trigger the widget to show the specific tag when hovering over it in the taglist. The code shown below is the example taglist from the [AwesomeWM docs](https://awesomewm.org/doc/api/classes/awful.widget.taglist.html). Basically, we are going to update the widget and toggle it through the taglist's `create_callback`. (The bling addons are commented) +We can trigger the widget to show the specific tag when hovering over it in the taglist. The code shown below is the example taglist from the [AwesomeWM docs](https://awesomewm.org/doc/api/classes/awful.widget.taglist.html). We are going to update the widget and toggle it through the taglist's `create_callback` (bling addons are commented). ```lua s.mytaglist = awful.widget.taglist { screen = s, diff --git a/docs/widgets/task_preview.md b/docs/widgets/task_preview.md index d92ab1c..bb861b8 100644 --- a/docs/widgets/task_preview.md +++ b/docs/widgets/task_preview.md @@ -1,6 +1,6 @@ ## 🔍 Task Preview -This is a popup widget that will show a preview of the specified client. It is supposed to mimic the small popup that Windows has when hovering over the application icon. +This is a popup widget that will show a preview of the specified client. It intends to mimic the small popup when hovering over an application icon on Windows. ![](https://user-images.githubusercontent.com/33443763/124705653-d7b98b80-deaa-11eb-8091-42bbe62365be.png) @@ -82,7 +82,7 @@ By default, the widget is not visible. You must implement when it will update an ### Example Implementation -We can trigger the widget to show the specific client when hovering over it in the tasklist. The code shown below is the example icon only tasklist from the [AwesomeWM docs](https://awesomewm.org/doc/api/classes/awful.widget.tasklist.html). Basically, we are going to toggle the widget through the tasklist's `create_callback`. (The bling addons are commented) +We can trigger the widget to show the specific client when hovering over it in the tasklist. The code shown below is the example icon only tasklist from the [AwesomeWM docs](https://awesomewm.org/doc/api/classes/awful.widget.tasklist.html). We are going to toggle the widget through the tasklist's `create_callback` (bling addons are commented). ```lua s.mytasklist = awful.widget.tasklist { screen = s, diff --git a/docs/widgets/window_switcher.md b/docs/widgets/window_switcher.md index 8f48257..d827ad4 100644 --- a/docs/widgets/window_switcher.md +++ b/docs/widgets/window_switcher.md @@ -30,7 +30,7 @@ bling.widget.window_switcher.enable { } ``` -To run the window swicher you have to emit this signal from within your configuration (usually using a keybind). +To run the window swicher, emit this signal (usually with a keybind): ```lua awesome.emit_signal("bling::window_switcher::turn_on")