From 3d6e9a9ba17ec808f615f48ac0f7f272c1ae7ff3 Mon Sep 17 00:00:00 2001 From: elkowar <5300871+elkowar@users.noreply.github.com> Date: Tue, 17 Aug 2021 11:14:16 +0200 Subject: [PATCH] Reformat markdown --- docs/src/configuration.md | 68 ++++++++++++++++++++++++++------- docs/src/expression_language.md | 7 +++- docs/src/working_with_gtk.md | 4 +- 3 files changed, 61 insertions(+), 18 deletions(-) diff --git a/docs/src/configuration.md b/docs/src/configuration.md index 6ae579f..e46c4d4 100644 --- a/docs/src/configuration.md +++ b/docs/src/configuration.md @@ -2,11 +2,22 @@ (For a list of all built in widgets (i.e. `box`, `text`, `slider`) see [Widget Documentation](widgets.md)) -Eww is configured using its own language called `yuck`. using yuck, you declare the structure and content of your widgets, the geometry, position and behavior of any windows, as well as any state and data that will be used in your widgets. Yuck is based around S-expressions, which you may know from lisp-like languages. If you're using vim, you can make use of [yuck.vim](https://github.com/elkowar/yuck.vim) for editor support. It is also recommended to use [parinfer](https://shaunlebron.github.io/parinfer/), which makes working with s-expressions delightfully easy! +Eww is configured using its own language called `yuck`. +using yuck, you declare the structure and content of your widgets, the geometry, position and behavior of any windows, +as well as any state and data that will be used in your widgets. +Yuck is based around S-expressions, which you may know from lisp-like languages. +If you're using vim, you can make use of [yuck.vim](https://github.com/elkowar/yuck.vim) for editor support. +It is also recommended to use [parinfer](https://shaunlebron.github.io/parinfer/), +which makes working with s-expressions delightfully easy! -Additionally, any styles are defined in scss (which is mostly just slightly improved CSS syntax). While eww supports a significant portion of the CSS you know from the web, not everything is supported, as eww relies on GTKs own CSS engine. Notably, some animation features are unsupported, as well as most layout-related CSS properties such as flexbox, `float`, absolute position or `width`/`height`. +Additionally, any styles are defined in scss (which is mostly just slightly improved CSS syntax). +While eww supports a significant portion of the CSS you know from the web, +not everything is supported, as eww relies on GTKs own CSS engine. +Notably, some animation features are unsupported, +as well as most layout-related CSS properties such as flexbox, `float`, absolute position or `width`/`height`. -To get started, you'll need to create two files: `eww.yuck` and `eww.scss`. These files must be placed under `$XDG_CONFIG_HOME/eww` (this is most likely `~/.config/eww`). +To get started, you'll need to create two files: `eww.yuck` and `eww.scss`. +These files must be placed under `$XDG_CONFIG_HOME/eww` (this is most likely `~/.config/eww`). Now that those files are created, you can start writing your first widget! @@ -89,7 +100,13 @@ We are creating a widget named `greeter`. This widget takes two attributes, call Now, we declare the body of our widget. We make use of a `box`, which we set a couple attributes of. -We need this `box`, as a widget definition can only ever contain a single widget - otherwise, eww would not know if it should align them vertically or horizontally, how it should space them, and so on. Thus, we wrap multiple children in a `box.`. This box then contains a reference to the provided attribute `text`, as well as a button. In that buttons `onclick` attribute, we make refer to the provided `name` using string-interpolation syntax: `"${name}"`. This allows us to easily refer to any variables within strings. In fact, there is a lot more you can do withing `${...}` - more on that in the chapter about the [expression language](expression_language.md). +We need this `box`, as a widget definition can only ever contain a single widget - otherwise, +eww would not know if it should align them vertically or horizontally, how it should space them, and so on. +Thus, we wrap multiple children in a `box.`. +This box then contains a reference to the provided attribute `text`, as well as a button. +In that buttons `onclick` attribute, we make refer to the provided `name` using string-interpolation syntax: `"${name}"`. +This allows us to easily refer to any variables within strings. +In fact, there is a lot more you can do withing `${...}` - more on that in the chapter about the [expression language](expression_language.md). To then use our widget, we call it just like we would use any other built-in widget, and provide the required attributes. @@ -113,9 +130,12 @@ There are four different types of variables: basic, polling, listening, and a se (defvar foo "initial value") ``` -This is the simplest type of variable. Basic variables don't ever change automatically. Instead, you explicitly update them by calling eww like so: `eww update foo="new value"`. +This is the simplest type of variable. +Basic variables don't ever change automatically. +Instead, you explicitly update them by calling eww like so: `eww update foo="new value"`. -This is useful if you have values that change very rarely, or may change as a result of some external script you wrote. They may also be useful to have buttons within eww change what is shown within your widget, by setting attributes like `onclick` to run `eww update`. +This is useful if you have values that change very rarely, or may change as a result of some external script you wrote. +They may also be useful to have buttons within eww change what is shown within your widget, by setting attributes like `onclick` to run `eww update`. **Polling variables (`defpoll`)** @@ -127,9 +147,12 @@ This is useful if you have values that change very rarely, or may change as a re A polling variable is a variable which runs a provided shell-script repeatedly, in a given interval. -This may be the most commonly used type of variable. They are useful to access any quickly retrieved value repeatedly, and thus are the perfect choice for showing your time, date, as well as other bits of information such as your volume. +This may be the most commonly used type of variable. +They are useful to access any quickly retrieved value repeatedly, +and thus are the perfect choice for showing your time, date, as well as other bits of information such as your volume. -Optionally, you can specify a timeout, after which the provided script will be aborted. This helps to avoid accidentally launching thousands of never-ending processes on your system. +Optionally, you can specify a timeout, after which the provided script will be aborted. +This helps to avoid accidentally launching thousands of never-ending processes on your system. **Listening variables (`deflisten`)** @@ -138,17 +161,30 @@ Optionally, you can specify a timeout, after which the provided script will be a `tail -F /tmp/some_file`) ``` -Listening variables might be the most confusing of the bunch. A listening variable runs a script once, and reads its output continously. Whenever the script outputs a new line, the value will be updated to that new line. In the example given above, the value of `foo` will start out as `"whatever"`, and will change whenever a new line is appended to `/tmp/some_file`. +Listening variables might be the most confusing of the bunch. +A listening variable runs a script once, and reads its output continously. +Whenever the script outputs a new line, the value will be updated to that new line. +In the example given above, the value of `foo` will start out as `"whatever"`, and will change whenever a new line is appended to `/tmp/some_file`. -These are particularly useful if you have a script that can monitor some value on its own. For example, the command `xprop -spy -root _NET_CURRENT_DESKTOP` writes the currently focused desktop whenever it changes. This can be used to implement a workspace widget for a bar, for example. Another example usecase is monitoring the currently playing song with playerctl: `playerctl --follow metadata --format {{title}}`. +These are particularly useful if you have a script that can monitor some value on its own. +For example, the command `xprop -spy -root _NET_CURRENT_DESKTOP` writes the currently focused desktop whenever it changes. +This can be used to implement a workspace widget for a bar, for example. +Another example usecase is monitoring the currently playing song with playerctl: `playerctl --follow metadata --format {{title}}`. **Built-in "magic" variables** -In addition to definition your own variables, eww provides some values for you to use out of the box. These include values such as your CPU and RAM usage. These mostly contain their data as JSON, which you can then use using the [json access syntax](expression_language.md). All available magic variables are listed [here](magic-vars.md). +In addition to definition your own variables, eww provides some values for you to use out of the box. +These include values such as your CPU and RAM usage. +These mostly contain their data as JSON, which you can then use using the [json access syntax](expression_language.md). +All available magic variables are listed [here](magic-vars.md). ## Dynamically generated widgets with `literal` -In some cases, you want to not only change the text, value or color of a widget dynamically, but instead want to generate an entire widget structure dynamically. This is necessary if you want to display lists of things (for example notifications) where the amount is not necessarily known, or if you want to change the widget structure in some other more complex way. +In some cases, you want to not only change the text, +value or color of a widget dynamically, but instead want to generate an entire widget structure dynamically. +This is necessary if you want to display lists of things (for example notifications) +where the amount is not necessarily known, +or if you want to change the widget structure in some other more complex way. For this, you can make use of one of ewws most powerful features: the `literal` widget. @@ -158,7 +194,8 @@ For this, you can make use of one of ewws most powerful features: the `literal` (literal :content variable_containing_yuck) ``` -Here, you specify the content of your literal by providing it a string (most likely stored in a variable) which contains a single yuck widget tree. Eww then reads the provided value and renders the resulting widget. Whenever it changes, the widget will be rerendered. +Here, you specify the content of your literal by providing it a string (most likely stored in a variable) which contains a single yuck widget tree. +Eww then reads the provided value and renders the resulting widget. Whenever it changes, the widget will be rerendered. Note that this is not all that efficient. Make sure to only use `literal` when necessary! @@ -178,5 +215,8 @@ A single yuck-file may import the contents of any other yuck file. For this, mak ### Using a separate eww configuration directory -If you want to separate different widgets even further, you can create a new eww config folder anywhere else. Then, you can tell eww to use that configuration directory by passing _every_ command the `--config /path/to/your/config/dir` flag. Make sure to actually include this in all your `eww` calls, including `eww kill`, `eww logs`, etc. This launches a separate instance of the eww daemon, that has separate logs and state from your main eww configuration. +If you want to separate different widgets even further, you can create a new eww config folder anywhere else. +Then, you can tell eww to use that configuration directory by passing _every_ command the `--config /path/to/your/config/dir` flag. +Make sure to actually include this in all your `eww` calls, including `eww kill`, `eww logs`, etc. +This launches a separate instance of the eww daemon, that has separate logs and state from your main eww configuration. diff --git a/docs/src/expression_language.md b/docs/src/expression_language.md index d1f2219..b8010fe 100644 --- a/docs/src/expression_language.md +++ b/docs/src/expression_language.md @@ -1,8 +1,11 @@ # Simple expression language -Yuck includes a small expression language that can be used to run several operations on your data. This can be used to show different values depending on certain conditions, do mathematic operations, and even to access values withing JSON-structures. +Yuck includes a small expression language that can be used to run several operations on your data. +This can be used to show different values depending on certain conditions, +do mathematic operations, and even to access values withing JSON-structures. -These expressions can be placed anywhere within your configuration in between `{ ... }`, as well as withing strings, inside string-interpolation blocks (`"foo ${ ... } bar"`). +These expressions can be placed anywhere within your configuration in between `{ ... }`, +as well as withing strings, inside string-interpolation blocks (`"foo ${ ... } bar"`). ## Example diff --git a/docs/src/working_with_gtk.md b/docs/src/working_with_gtk.md index 039d1bb..39dbdad 100644 --- a/docs/src/working_with_gtk.md +++ b/docs/src/working_with_gtk.md @@ -17,13 +17,13 @@ SCSS is _very_ close to CSS so if you know CSS you'll have no problem learning S The debugger can be used for **a lot** of things. Especially if something doesn't work or isn't styled right. to enable it launch your eww daemon with ```bash -GTK_DEBUG=interactive ./eww daemon +GTK_DEBUG=interactive eww daemon ``` or in fish ```bash -env GTK_DEBUG=interactive ./eww daemon +env GTK_DEBUG=interactive eww daemon ``` If a style or something similar doesn't work you can click on the icon in the top left icon to select the thing that isn't being styled or isn't being styled correctly.