From 87e8b08fc893de4b620d2e1cede4c2317fddc15a Mon Sep 17 00:00:00 2001
From: dimgigov <gigov@gigov.org>
Date: Tue, 2 Jun 2026 11:36:59 +0300
Subject: [PATCH] docs: update README and LanguageRef with backtick strings +
 QBE backend

---
 README.md           | 25 ++++++++++++++++++-------
 docs/LanguageRef.md | 11 ++++++++++-
 2 files changed, 28 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 3884d9a..9d0d767 100644
--- a/README.md
+++ b/README.md
@@ -1,10 +1,8 @@
 # Bux Programming Language
 
-> **Status:** Self-hosting phase — `buxc2` (Bux compiler written in Bux) compiles `.bux` files to C. Bootstrap compiler (`buxc`, Nim) maintains backward compatibility.
+> **Status:** Self-hosting phase — `buxc2` compiles `.bux` → QBE SSA → native binary. Bootstrap (`buxc`, Nim) maintains backward compatibility via C transpiler.
 
-Bux is a fast, compiled, strongly-typed systems programming language. The long-term goal is a self-hosted compiler with a minimal runtime, native x86-64 backend, and modern tooling.
-
-Bux features a rich standard library (`Map`, `String`), modern error handling (`Result`, `Option`, and the `?` operator), and a portable C transpiler backend that runs on Linux, macOS, and Windows.
+Bux is a fast, compiled, strongly-typed systems programming language. Features a QBE backend for native code generation, raw multi-line strings, gradual ownership, async/await, generics, algebraic enums, and a package manager.
 
 ---
 
@@ -36,6 +34,18 @@ func Main() -> int {
 }
 ```
 
+### Raw Multi-line Strings
+```bux
+// Backtick strings: no escape processing, multi-line
+func Main() -> int {
+    PrintLine(`Hello \n World`);     // prints: Hello \n World (literal)
+    PrintLine(`Line 1
+Line 2
+Line 3`);                            // multi-line, newlines preserved
+    return 0;
+}
+```
+
 ### Error Handling with `?`
 ```bux
 enum Result {
@@ -138,7 +148,8 @@ func Main() -> int {
 | **Interfaces** | `interface` + `extend` for trait-like behavior |
 | **Error Handling** | `Result<T,E>`, `Option<T>`, and the `?` operator |
 | **Standard Library** | `Io`, `Array`, `String`, `Map` |
-| **Backend** | C transpiler (bootstrap) → self-hosting target |
+| **Backend** | QBE native codegen (self-hosting), C transpiler (bootstrap) |
+| **Strings** | Raw multi-line backtick strings (`...`), C-string interop |
 | **Gradual Ownership** | `@[Checked]` + `&T`/`&mut T` borrow checking |
 | **Async/Await** | `async func`, `spawn`, `.await` with stackful coroutines |
 | **Concurrency** | `Task`/`Channel` (pthread-based), `bux_async_yield`/`spawn` |
@@ -170,10 +181,10 @@ bux/
 ## Build & Test
 
 ```bash
-# Build bootstrap compiler (Nim)
+# Build bootstrap compiler (Nim → C)
 make build
 
-# Build self-hosted compiler (Bux → C → binary)
+# Build self-hosted compiler (Bux → QBE SSA → native)
 make selfhost
 
 # Run all tests
diff --git a/docs/LanguageRef.md b/docs/LanguageRef.md
index 962b89b..04ac579 100644
--- a/docs/LanguageRef.md
+++ b/docs/LanguageRef.md
@@ -48,12 +48,21 @@ async, await, spawn
 
 ### String Literals
 ```bux
-"Hello"           // String (UTF-8)
+"Hello"           // String (UTF-8) — escape sequences: \n \t \r \\ \"
 c8"Hello"         // *char8 (C string)
 c16"Hello"        // *char16
 c32"Hello"        // *char32
+`raw literal`     // Raw multi-line string — no escape processing
+`line 1
+line 2
+line 3`           // Newlines preserved as-is
 ```
 
+**Backtick raw strings** (`` `...` ``) treat all characters literally:
+- `\n` is two characters, not a newline
+- Actual newlines in source are preserved in the string
+- No way to escape the backtick character itself (use regular strings if needed)
+
 ### Number Literals
 ```bux
 42        // int