probably fixed

Author: mf366-dev

.gitattributes

@@ -10,7 +10,7 @@
 # default for csharp files.
 # Note: This is only used by command line
 ###############################################################################
-#*.cs     diff=csharp
+*.cs     diff=csharp
 
 ###############################################################################
 # Set the merge driver for project and solution files
@@ -77,7 +77,9 @@
 # This should fix it.
 *.cs linguist-language=C#
 
+# Documentation
 *.md linguist-documentation
-*.st linguist-vendored
+*.html linguist-documentation
 
-site/** linguist-vendored
+# Throwback to when github thought this repo contained 74% smalltalk
+*.st linguist-vendored

.github/workflows/deploy_docs.yml

@@ -24,4 +24,8 @@ jobs:
           restore-keys: |
             mkdocs-material-
       - run: pip install -r requirements-docs.txt
-      - run: mkdocs gh-deploy --force
+      # This is commented out because I don't think
+      # we have to force push but just in case...
+      #- run: mkdocs gh-deploy --force
+      - run: mkdocs gh-deploy
+      # ^ comment this if we end up force pushing

docs/api/csharp/index.md

@@ -8,35 +8,40 @@ RSML can be installed in 2 ways: **package reference** (via NuGet) or **project
 Installing RSML via its NuGet package is the recommended way to install RSML, as it guarantees stability.
 
 === ".NET CLI"
-    Simply run the following line in the terminal.
-
     ```bash
-    dotnet add package RSML --version 1.0.5
+    dotnet add package OceanApocalypseStudios.RSML --version 2.0.0
     ```
 
 === "Project File"
-    To install RSML via your project file, simply ass the following line to an `#!xml <ItemGroup>`.
-
-    ```xml
-    <PackageReference Include="RSML" Version="1.0.5" />
+    ```xml title="ItemGroup"
+    <PackageReference Include="OceanApocalypseStudios.RSML" Version="2.0.0" />
     ```
 
 === "Visual Studio (PMC)"
-    If you use Visual Studio, you can instead run the following line in the builtin **Package Manager Console**.
+    ```powershell title="VS Package Manager Console"
+    NuGet\Install-Package OceanApocalypseStudios.RSML -Version 2.0.0
+    ```
+
+=== "Central Package Management (CPM)"
+    ```xml title="Directory.Packages.props"
+    <PackageVersion Include="OceanApocalypseStudios.RSML" Version="2.0.0" />
+    ```
 
-    ```powershell
-    NuGet\Install-Package RSML -Version 1.0.5
+    ```xml title="Project File"
+    <PackageReference Include="OceanApocalypseStudios.RSML" />
     ```
 
 ### Project Reference _(Not recommended)_
 If, for whatever reason, you need the latest nightly updates, you may also add the RSML project to your solution.
 
-Please keep in mind that not all nightly updates are guaranteed to be bug-free or stable. Nightly updates are also not documented, only stable versions are.
+!!! warning
+    Please keep in mind that not all nightly updates are guaranteed to be bug-free or stable. Nightly updates are also not documented, only stable versions are.
 
 ```bash
-cd YourSolution/YourProject/
-# Assuming you've got the RSML project at YourSolution/RSML/
-dotnet add reference ../RSML/RSML.csproj
+# Adapt this to your solution structure
+cd src/MyAwesomeProject/
+dotnet add reference ../../include/RSML/
 ```
 
-1. If your solution is included in a `git` repository already, consider using [Git Submodules](https://git-scm.com/docs/git-submodule) instead.
+???+ tip "Git Submodules"
+    If your solution is included in a `git` repository already, consider using [Git Submodules](https://git-scm.com/docs/git-submodule) instead.

docs/api/index.md

@@ -4,7 +4,7 @@
 <!-- or any later version published by the Free Software Foundation; -->
 <!-- with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. -->
 
-# RSML as an API
+# RSML's API
 !!! tip
     It's recommended to know the actual [language](../language/index.md) itself before learning how to use RSML programmatically.
 

docs/cli/index.md

@@ -1,5 +1,5 @@
-# RSML directly in your Terminal
-Red Sea's CLI (`RSML.CLI`) was made with the intention of serving as a quick, easy-to-use and simple way to evaluate RSML files using the [`official-25`](../language/standards/official-25.md) and [`roadlike`](../language/standards/roadlike.md) [language standards](../language/standards/index.md).
+# RSML's CLI
+Red Sea Markup Language's CLI (`RSML.CLI`) was made with the intention of serving as a quick, easy-to-use and simple way to evaluate RSML files using the [`official-25`](../language/standards/official-25.md) and [`roadlike`](../language/standards/roadlike.md) [language standards](../language/standards/index.md).
 
 It is used by [RSML for Python](../api/python/index.md) to simulate using the actual RSML DLL, even though that's not what actually happens. At least, not directly via Python.
 

docs/language/implementations.md

@@ -3,3 +3,6 @@ Anyone can implement their own RSML parser and evaluator, but one should do thei
 
 Furthermore, it's highly recommended to inform the implementation's users about the level of compliance with the RSML specification, including any known limitations or deviations.
 
+## Compliance
+For an implementation to be 100% compliant with RSML's specification, it must define: all special actions defined in the specification and no more than those; comments exactly as specified; logic paths with the same syntax, structure and overloads; arguments with the same meaning and functionality; same semantics.
+

docs/language/index.md

@@ -5,7 +5,7 @@
 <!-- with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. -->
 
 
-# RSML as a Language
+# RSML, the Language
 
 ## Abstract
 **Red Sea Markup Language** (RSML) is a simple declarative markup language created for the purpose of following logic paths based on the host's operating system and CPU architecture.
@@ -345,7 +345,9 @@ These are built into the language and cannot be changed whatsoever _(unless you
 
 RSML is evaluated from **start to finish** _([see Advanced Representation of the Process Flow](#advanced-representation))_, meaning that the **very first** logic path **with a return operator in it** that matches will be used and the evaluation ends there. All the logic beyond that point is ignored completely, including comments and special actions.
 
-### Simplified Representation <!-- md:version 2.0.0-prerelease8 -->
+### Simplified Representation
+Valid as of <!-- md:version 2.0.0-prerelease8 -->.
+
 ``` mermaid
 ---
 title: Simplified Representation of the Evaluation Process Flow
@@ -360,7 +362,9 @@ flowchart LR
   E -->B;
 ```
 
-### Advanced Representation <!-- md:version 2.0.0-prerelease8 -->
+### Advanced Representation
+Valid as of <!-- md:version 2.0.0-prerelease8 -->.
+
 ``` mermaid
 ---
 title: Advanced Representation of the Evaluation Process Flow
@@ -415,7 +419,7 @@ The recommended file extension for RSML files is `.rsea`, but other extensions m
 ## Syntax Reference
 This is a quick reference sheet on RSML's syntax.
 
-???+ example "Quick syntax reference"
+!!! example "Quick syntax reference"
     ```rsea
     # This is a comment
 
@@ -445,7 +449,7 @@ This is a quick reference sheet on RSML's syntax.
 ## What might be coming soon?
 Well, you haven't heard this from me, but there are plans to add more features to RSML in future versions, such as:
 
-- **Logical INBETWEEN operator** in logic paths, to allow for more complex matching conditions.
+- **Logical `INBETWEEN` operator** in logic paths, to allow for more complex matching conditions.
 - **Line-NOT and Argument-NOT operators** to negate matches.
 - **Support for more operating systems and CPU architectures** as they become relevant.
 - **Enhanced error handling and reporting** for better debugging.

material/overrides/hooks/shortcodes.py

@@ -61,6 +61,8 @@ def replace(match: re.Match):
         # Otherwise, raise an error
         raise RuntimeError(f"Unknown shortcode: {type}")
 
+    print(f"DEBUG: path sep is {os.sep}")
+
     # Find and replace all external asset URLs in current page
     return re.sub(
         r"<!-- md:(\w+)(.*?) -->",
@@ -93,21 +95,35 @@ def get_linkable_setting(type: str) -> str:
 
 
 def _resolve_path(path: str, page: Page, files: Files):
-    path, anchor, *_ = f"{path}#".split("#")
-    
-    print(f"DEBUG: {path} ({anchor})")
-    
-    path = _resolve(files.get_file_from_path(path), page)
-    return "#".join([path, anchor]) if anchor else path
+    path_part, sep, anchor = path.partition("#")
+    anchor = anchor if sep else None
+
+    print(f"DEBUG: {path_part} ({anchor})")
+
+    resolved = _resolve(files.get_file_from_path(path_part), page)
+
+    print(f"DEBUG [new]: {resolved}")
+
+    return f"{resolved}#{anchor}" if anchor is not None else resolved
 
 
 def _resolve(file: File, page: Page):
-    path = os.path.relpath(file.src_uri, page.file.src_uri)
+    print(f"DEBUG file.src_uri ==> {file.src_uri}")
+    print(f"DEBUG page.file.src_uri ==> {page.file.src_uri}")
+
+    src = os.path.abspath(file.src_uri)
+    page_src = os.path.abspath(page.file.src_uri)
+    rel = os.path.relpath(src, start=os.path.dirname(page_src))
+
+    print(f"DEBUG: {file.src_uri} & {page.file.src_uri} || {src} & {page_src}")
+    print(f"DEBUG: path sep is {os.pathsep}")
+    print(f"DEBUG: relpath ==> {rel}")
+    print(f"DEBUG: ext ==> {os.path.extsep}")
 
-    print(f'DEBUG: {file.src_uri} & {page.file.src_uri}')
-    print(f'DEBUG: path sep is {os.pathsep}; {os.sep}')
+    norm = os.path.normpath(rel)
+    print(f"DEBUG: norm ==> {norm}")
 
-    return os.sep.join(path.split(os.sep)[1:])
+    return os.path.extsep.join(norm.split(os.path.extsep)[:-1]) if os.path.extsep in norm else norm
 
 
 class Badges:

mkdocs.yml

@@ -229,13 +229,13 @@ markdown_extensions:
 nav:
   - Home: index.md
   - Why use RSML?:
-    - Why RSML?: why/index.md
+    - _: why/index.md
     - Alternatives to RSML: why/alternatives.md
   - Language:
-    - RSML as a Language: language/index.md
+    - _: language/index.md
     - RSML Implementations: language/implementations.md
   - API:
-    - RSML as an API: api/index.md
+    - _: api/index.md
     - Guides:
       - About our Guides: api/guides/index.md
       - Easy:
@@ -268,7 +268,7 @@ nav:
       #- Getting Started: api/cpp/index.md
       #- Reference: api/cpp/reference.md
   - CLI:
-    - RSML as a CLI: cli/index.md
+    - _: cli/index.md
     - Commands: cli/commands.md
     - Real-world usage: cli/examples.md
   - Contributing: contributing.md