website: subcategories for variables

lmorg · Sep 15, 2024 · 45e4d8c · 45e4d8c
1 parent 043534e
commit 45e4d8c
Show file tree

Hide file tree

Showing 27 changed files with 70 additions and 28 deletions.
diff --git a/app/app.go b/app/app.go
@@ -16,9 +16,9 @@ const Name = "murex"
 const (
 	Major     = 6
 	Minor     = 3
-	Revision  = 4141
+	Revision  = 4145
 	Branch    = "develop"
-	BuildDate = "2024-09-15  15:44:46"
+	BuildDate = "2024-09-15  16:42:40"
 )
 
 // Copyright is the copyright owner string

diff --git a/docs/variables/argv.md b/docs/variables/argv.md
@@ -9,7 +9,7 @@ scope. eg `function`, `private`, `autocomplete` or shell script.
 
 Unlike `$PARAMS`, `$ARGV` includes the function name.
 
-This is a reserved variable so it cannot be changed.
+This is a [reserved variable](/docs/user-guide/reserved-vars.md) so it cannot be changed.
 
 ## Examples
 

diff --git a/docs/variables/columns.md b/docs/variables/columns.md
@@ -10,7 +10,7 @@ Some characters might be more than or less than 1 (one) cell in width, such
 as Chinese logograms and zero-width joiners. Whereas one ASCII character is
 the same width as one terminal cell.
 
-This is a reserved variable so it cannot be changed.
+This is a [reserved variable](/docs/user-guide/reserved-vars.md) so it cannot be changed.
 
 ## Other Reserved Variables
 

diff --git a/docs/variables/hostname.md b/docs/variables/hostname.md
@@ -7,7 +7,7 @@
 `HOSTNAME` returns the hostname of the machine (host / server / virtual machine
 / et al) that Murex is running from.
 
-This is a reserved variable so it cannot be changed.
+This is a [reserved variable](/docs/user-guide/reserved-vars.md) so it cannot be changed.
 
 ## Other Reserved Variables
 

diff --git a/docs/variables/murex_argv.md b/docs/variables/murex_argv.md
@@ -7,6 +7,8 @@
 `MUREX_ARGV` returns an array of the command name and parameters passed to
 the current running Murex shell
 
+This is a [reserved variable](/docs/user-guide/reserved-vars.md) so it cannot be changed.
+
 ## Examples
 
 ```

diff --git a/docs/variables/murex_exe.md b/docs/variables/murex_exe.md
@@ -8,7 +8,7 @@
 holds the full path to the running shell. The reason for defining a reserved
 variable is so that the shell path cannot be overridden.
 
-This is a reserved variable so it cannot be changed.
+This is a [reserved variable](/docs/user-guide/reserved-vars.md) so it cannot be changed.
 
 ## Other Reserved Variables
 

diff --git a/docs/variables/numeric.md b/docs/variables/numeric.md
@@ -6,7 +6,7 @@
 
 Variables named `0` and above are the equivalent index value of `@ARGV`.
 
-These are reserved variable so they cannot be changed.
+These are {{link "reserved variables" "reserved-vars"}} so they cannot be changed.
 
 ## Examples
 

diff --git a/docs/variables/params.md b/docs/variables/params.md
@@ -9,7 +9,7 @@ eg `function`, `private`, `autocomplete` or shell script.
 
 Unlike `$ARGV`, `$PARAMS` does not include the function name.
 
-This is a reserved variable so it cannot be changed.
+This is a [reserved variable](/docs/user-guide/reserved-vars.md) so it cannot be changed.
 
 ## Examples
 

diff --git a/docs/variables/self.md b/docs/variables/self.md
@@ -13,9 +13,9 @@ config are persistent within. In Murex, a variable declared inside an `if` or
 `foreach` block will be persistent outside of their blocks as long as you're
 still inside the same function.
 
-Please see scoping document (link below) for more information on scoping.
+Please read the {{link "scoping document" "scoping"}} for more information on scoping.
 
-This is a reserved variable so it cannot be changed.
+This is a [reserved variable](/docs/user-guide/reserved-vars.md) so it cannot be changed.
 
 ## Examples
 

diff --git a/docs/variables/shell.md b/docs/variables/shell.md
@@ -7,10 +7,11 @@
 `SHELL` is an environmental variable containing the full path to the current
 shell -- which in our case is Murex.
 
-This variable is set by Murex to conform to standards however, being an
-environmental variable, it can be overwritten via `export`. Thus you are
-recommended to use `MUREX_EXE`, which is a reserved variable, if you require
-precision.
+This variable is set by Murex to conform to POSIX standards. However, being an
+environmental variable, it can be overwritten via `export`.
+
+For Murex specific code, you are recommended to use `MUREX_EXE`, which is a
+reserved variable, and thus read only, if you require precision and safety.
 
 ## Other Reserved Variables
 

diff --git a/gen/docgen.yaml b/gen/docgen.yaml
@@ -225,6 +225,28 @@ Categories:
       CategoryTemplate: gen/variables-md-cat.tmpl
       DocumentTemplate: gen/variables-md-doc.tmpl
 
+    SubCategories:
+    - ID: vars.env
+      Title: Environmental Variables
+      VueIcon: arrows-turn-to-dots
+      Description: |-
+        Environmental variables are variables held at an operating system level and thus will get passed between running processes.
+    - ID: vars.scoped
+      Title: Scoped Variables
+      VueIcon: arrows-turn-to-dots
+      Description: |-
+        Scoped variables are defined within a specific function's scope. These might be reserved variables but they might also be used to provide structured returns from a particular scope.
+    - ID: vars.posix
+      Title: Defined by POSIX
+      VueIcon: arrows-turn-to-dots
+      Description: |-
+        These are variables defined by POSIX. In general they will be environmental variables, however in some cases Murex will follow the naming convention described in POSIX but return a reserved variable instead.
+    - ID: vars.reserved
+      Title: Reserved Variables
+      VueIcon: arrows-turn-to-dots
+      Description: |-
+        Reserved variables are read only values that are dynamically generated at the point of querying. They behave a little more like functions than variables, albeit the convenience of being called like a variable.
+
   # pipes:
 
   # apis:

diff --git a/gen/includes/this-is-a-reserved-var.inc.md b/gen/includes/this-is-a-reserved-var.inc.md
@@ -0,0 +1 @@
+This is a {{link "reserved variable" "reserved-vars"}} so it cannot be changed.
diff --git a/gen/variables/ARGV_doc.yaml b/gen/variables/ARGV_doc.yaml
@@ -2,6 +2,7 @@
   Title: >-
     `ARGV` (json)
   CategoryID: variables
+  SubCategoryIDs: [ vars.reserved, vars.scoped ]
   Summary: >-
     Array of the command name and parameters within a given
     scope
@@ -11,7 +12,7 @@
 
     Unlike `$PARAMS`, `$ARGV` includes the function name.
 
-    This is a reserved variable so it cannot be changed.
+    {{ include "gen/includes/this-is-a-reserved-var.inc.md" }}
   Examples: |-
     ```
     » function example { $ARGV }

diff --git a/gen/variables/COLUMNS_doc.yaml b/gen/variables/COLUMNS_doc.yaml
@@ -2,6 +2,7 @@
   Title: >-
     `COLUMNS` (int)
   CategoryID: variables
+  SubCategoryIDs: [ vars.reserved, vars.posix ]
   Summary: >-
     Character width of terminal
   Description: |-
@@ -11,7 +12,7 @@
     as Chinese logograms and zero-width joiners. Whereas one ASCII character is
     the same width as one terminal cell.
 
-    This is a reserved variable so it cannot be changed.
+    {{ include "gen/includes/this-is-a-reserved-var.inc.md" }}
   Synonyms:
   - columns
   - COLUMNS

diff --git a/gen/variables/EVENT_RETURN_doc.yaml b/gen/variables/EVENT_RETURN_doc.yaml
@@ -2,6 +2,7 @@
   Title: >-
     `EVENT_RETURN` (json)
   CategoryID: variables
+  SubCategoryIDs: [ vars.scoped ]
   Summary: >-
     Return values for events
   Description: |-

diff --git a/gen/variables/HOSTNAME_doc.yaml b/gen/variables/HOSTNAME_doc.yaml
@@ -2,13 +2,14 @@
   Title: >-
     `HOSTNAME` (str)
   CategoryID: variables
+  SubCategoryIDs: [ vars.reserved ]
   Summary: >-
     Hostname of the current machine
   Description: |-
     `HOSTNAME` returns the hostname of the machine (host / server / virtual machine
     / et al) that Murex is running from.
 
-    This is a reserved variable so it cannot be changed.
+    {{ include "gen/includes/this-is-a-reserved-var.inc.md" }}
   Synonyms:
   - hostname
   - HOSTNAME

diff --git a/gen/variables/MUREX_ARGV_doc.yaml b/gen/variables/MUREX_ARGV_doc.yaml
@@ -2,11 +2,14 @@
   Title: >-
     `MUREX_ARGV` (json)
   CategoryID: variables
+  SubCategoryIDs: [ vars.reserved ]
   Summary: >-
     Array of the command name and parameters passed to the current shell
   Description: |-
     `MUREX_ARGV` returns an array of the command name and parameters passed to
     the current running Murex shell
+
+    {{ include "gen/includes/this-is-a-reserved-var.inc.md" }}
   Examples: |-
     ```
     » murex -trypipe -c '$MUREX_ARGV'

diff --git a/gen/variables/MUREX_EXE_doc.yaml b/gen/variables/MUREX_EXE_doc.yaml
@@ -2,14 +2,15 @@
   Title: >-
     `MUREX_EXE` (path)
   CategoryID: variables
+  SubCategoryIDs: [ vars.reserved ]
   Summary: >-
     Absolute path to running shell
   Description: |-
     `MUREX_EXE` is very similar to the `$SHELL` environmental variable in that it
     holds the full path to the running shell. The reason for defining a reserved
     variable is so that the shell path cannot be overridden.
 
-    This is a reserved variable so it cannot be changed.
+    {{ include "gen/includes/this-is-a-reserved-var.inc.md" }}
   Synonyms:
   - murex_exe
   - MUREX_EXE

diff --git a/gen/variables/PARAMS_doc.yaml b/gen/variables/PARAMS_doc.yaml
@@ -2,6 +2,7 @@
   Title: >-
     `PARAMS` (json)
   CategoryID: variables
+  SubCategoryIDs: [ vars.reserved, vars.scoped ]
   Summary: >-
     Array of the parameters within a given scope
   Description: |-
@@ -10,7 +11,7 @@
 
     Unlike `$ARGV`, `$PARAMS` does not include the function name.
 
-    This is a reserved variable so it cannot be changed.
+    {{ include "gen/includes/this-is-a-reserved-var.inc.md" }}
   Examples: |-
     ```
     » function example { $PARAMS }

diff --git a/gen/variables/PWDHIST_doc.yaml b/gen/variables/PWDHIST_doc.yaml
@@ -2,6 +2,7 @@
   Title: >-
     `PWDHIST` (json)
   CategoryID: variables
+  SubCategoryIDs: [ vars.env ]
   Summary: >-
     History of each change to the sessions working directory
   Description: |-

diff --git a/gen/variables/PWD_doc.yaml b/gen/variables/PWD_doc.yaml
@@ -2,6 +2,7 @@
   Title: >-
     `PWD` (path)
   CategoryID: variables
+  SubCategoryIDs: [ vars.posix, vars.env ]
   Summary: >-
     Current working directory
   Description: |-

diff --git a/gen/variables/SELF_doc.yaml b/gen/variables/SELF_doc.yaml
@@ -2,6 +2,7 @@
   Title: >-
     `SELF` (json)
   CategoryID: variables
+  SubCategoryIDs: [ vars.reserved, vars.scoped ]
   Summary: >-
     Meta information about the running scope.
   Description: |-
@@ -14,9 +15,9 @@
     `foreach` block will be persistent outside of their blocks as long as you're
     still inside the same function.
 
-    Please see scoping document (link below) for more information on scoping.
+    Please read the {{link "scoping document" "scoping"}} for more information on scoping.
 
-    This is a reserved variable so it cannot be changed.
+    {{ include "gen/includes/this-is-a-reserved-var.inc.md" }}
   Examples: |-
     ```
     » function example { $SELF }

diff --git a/gen/variables/SHELL_doc.yaml b/gen/variables/SHELL_doc.yaml
@@ -2,16 +2,18 @@
   Title: >-
     `SHELL` (str)
   CategoryID: variables
+  SubCategoryIDs: [ vars.posix, vars.env ]
   Summary: >-
     Path of current shell
   Description: |-
     `SHELL` is an environmental variable containing the full path to the current
     shell -- which in our case is Murex.
 
-    This variable is set by Murex to conform to standards however, being an
-    environmental variable, it can be overwritten via `export`. Thus you are
-    recommended to use `MUREX_EXE`, which is a reserved variable, if you require
-    precision.
+    This variable is set by Murex to conform to POSIX standards. However, being an
+    environmental variable, it can be overwritten via `export`.
+    
+    For Murex specific code, you are recommended to use `MUREX_EXE`, which is a
+    reserved variable, and thus read only, if you require precision and safety.
   Examples:
   Synonyms:
   - shell

diff --git a/gen/variables/meta-values_doc.yaml b/gen/variables/meta-values_doc.yaml
@@ -2,6 +2,7 @@
   Title: >-
     `$.`, Meta Values (json)
   CategoryID: variables
+  SubCategoryIDs: [ vars.scoped ]
   Summary: >-
     State information for iteration blocks
   Description: |-

diff --git a/gen/variables/numeric_doc.yaml b/gen/variables/numeric_doc.yaml
@@ -2,12 +2,13 @@
   Title: >-
     Numeric (str)
   CategoryID: variables
+  SubCategoryIDs: [ vars.reserved ]
   Summary: >-
     Variables who's name is a positive integer, eg `0`, `1`, `2`, `3` and above
   Description: |-
     Variables named `0` and above are the equivalent index value of `@ARGV`.
 
-    These are reserved variable so they cannot be changed.
+    These are {{link "reserved variables" "reserved-vars"}} so they cannot be changed.
   Examples: |-
     ```
     » function example { out $0 $2 }

diff --git a/gen/vuepress/sidebar.ts b/gen/vuepress/sidebar.ts
@@ -55,7 +55,7 @@ export default sidebar({
       collapsible: true,
     },
     {
-      text: "Spacial Variables",
+      text: "Special Variables",
       icon: "dollar",
       prefix: "variables/",
       children: "structure",

diff --git a/version.svg b/version.svg