From 1155027ccdda7ecaa8f191b480f261828162d2f9 Mon Sep 17 00:00:00 2001
From: Vaxry <vaxry@vaxry.net>
Date: Fri, 18 Oct 2024 15:41:19 +0100
Subject: [PATCH] hyprlang: improve docs

---
 pages/Configuring/Keywords.md    | 26 ---------
 pages/Configuring/_index.md      | 35 +-----------
 pages/Hypr Ecosystem/hyprlang.md | 95 ++++++++++++++++++++++++++++++++
 3 files changed, 97 insertions(+), 59 deletions(-)

diff --git a/pages/Configuring/Keywords.md b/pages/Configuring/Keywords.md
index db73b4d..d997bd7 100644
--- a/pages/Configuring/Keywords.md
+++ b/pages/Configuring/Keywords.md
@@ -37,32 +37,6 @@ You can execute a shell script on:
 
 `exec-shutdown = command` will execute only on shutdown
 
-## Defining variables
-
-You can define your own custom variables using a dollar sign (`$`):
-
-```ini
-$VAR = value
-```
-
-For example:
-
-```ini
-$MyFavoriteGame = Among Us
-```
-
-Then you can reference them in the rest of the config. For example:
-
-```ini
-col.active_border = $MyColor
-```
-
-You are allowed to combine variables in-place with other strings, like this:
-
-```ini
-col.active_border = ff$MyRedValue1111
-```
-
 ## Sourcing (multi-file)
 
 Use the `source` keyword to source another file.
diff --git a/pages/Configuring/_index.md b/pages/Configuring/_index.md
index ca34c69..e0bd275 100644
--- a/pages/Configuring/_index.md
+++ b/pages/Configuring/_index.md
@@ -34,40 +34,9 @@ the toggleable / numerical options.
 
 {{< /callout >}}
 
-## Line style
+## Language style and syntax
 
-Every config line is a command followed by a value.
-
-```ini
-COMMAND = VALUE
-```
-
-The command can be a variable, or a special keyword (described further in this
-page)
-
-The trailing spaces at the beginning and end of words are not necessary, and are
-there only for legibility.
-
-### Comments
-
-Comments are started with the `#` character.
-
-If you want to escape it (put an actual `#` and not start a comment) you can use
-`##`. It will be turned into a single `#` that _will_ be a part of your line.
-
-### Escaping errors
-
-If you use plugins, you may want to ignore errors from missing options/keywords
-so that you don't get an error bar before they are loaded. To do so, do this:
-
-```ini
-# hyprlang noerror true
-
-bind = MOD, KEY, something, amogus
-someoption = blah
-
-# hyprlang noerror false
-```
+See the [hyprlang page](../Hypr-Ecosystem/hyprlang).
 
 ## Basic configuring
 
diff --git a/pages/Hypr Ecosystem/hyprlang.md b/pages/Hypr Ecosystem/hyprlang.md
index fdb02e5..c74b8e8 100644
--- a/pages/Hypr Ecosystem/hyprlang.md	
+++ b/pages/Hypr Ecosystem/hyprlang.md	
@@ -5,5 +5,100 @@ title: hyprlang
 
 hyprlang is a library that implements parsing for the hypr configuration language.
 
+## Syntax
+
+### Line style
+
+Every config line is a command followed by a value.
+
+```ini
+COMMAND = VALUE
+```
+
+The command can be a variable, or a special keyword (described further in this
+page)
+
+The trailing spaces at the beginning and end of words are not necessary, and are
+there only for legibility.
+
+### Categories
+
+Categories can be regular, and "special".
+
+Both are specified the same:
+```ini
+category {
+    variable = value
+}
+```
+
+Special categories can have other properties, like for example containing a key:
+```ini
+special {
+    key = A
+    variable = value
+}
+special {
+    key = B
+    variable = value
+}
+```
+
+This is like defining two "groups", one with the key of A, another with B. Hyprland for
+example uses those for per-device configs.
+
+### Defining variables
+
+Variables can be defined like so:
+```ini
+$VAR = myData
+```
+
+Later on, you can use them like so:
+```ini
+$SUFFIX = -san
+$NAME = Jeremy
+greeting = Hello, $NAME$SUFFIX.
+```
+
+You do not need spaces to separate values, or spaces around values.
+
+### Comments
+
+Comments are started with the `#` character.
+
+If you want to escape it (put an actual `#` and not start a comment) you can use
+`##`. It will be turned into a single `#` that _will_ be a part of your line.
+
+### Escaping errors
+
+If you use plugins, you may want to ignore errors from missing options/keywords
+so that you don't get an error bar before they are loaded. To do so, do this:
+
+```ini
+# hyprlang noerror true
+
+bind = MOD, KEY, something, amogus
+someoption = blah
+
+# hyprlang noerror false
+```
+
+### Inline options
+
+If you want to specify an option inline, without opening and closing a category, the separator is `:`:
+```ini
+category:variable = value
+```
+
+If the category is special and requires a key, you can do:
+```ini
+category[keyvalue]:variable = value
+```
+
+This is the syntax used by `hyprctl keyword`, for example.
+
+## Developer documentation
+
 See the documentation at [hyprland.org/hyprlang](https://hyprland.org/hyprlang/).