From 432862a253cf7723787ac4adda2a803770b27958 Mon Sep 17 00:00:00 2001
From: Araozu <fernando@araozu.dev>
Date: Sat, 23 Nov 2024 19:20:13 -0500
Subject: [PATCH] feat: v0.0.1 docs

---
 src/layouts/NewDocsLayout.astro     |  49 +++++++++----
 src/pages/en/v0.0.1/learn/index.mdx | 103 +++++++++++++++++++++++++++-
 2 files changed, 135 insertions(+), 17 deletions(-)

diff --git a/src/layouts/NewDocsLayout.astro b/src/layouts/NewDocsLayout.astro
index 99099cb..741c40a 100644
--- a/src/layouts/NewDocsLayout.astro
+++ b/src/layouts/NewDocsLayout.astro
@@ -52,7 +52,9 @@ const posts_2 = posts
 		// being `/spec/ast/tokens` would be `/ast/tokens`
 		path: post.url.substring(base_len),
 	}))
-	.sort((p1, p2) => (p1.frontmatter.order > p2.frontmatter.order ? 1 : -1));
+	.sort((p1, p2) =>
+		p1.frontmatter.order > p2.frontmatter.order ? 1 : -1,
+	);
 
 // build a hierarchy of the files
 const second_level: Record<string, Array<AstroFile>> = {
@@ -117,7 +119,7 @@ const rc = url_components[1] ?? "";
 ---
 
 <BaseLayout title={frontmatter.title}>
-	<Navbar />
+	<Navbar version={version} />
 
 	<div
 		class="lg:grid lg:grid-cols-[14rem_auto_12rem] lg:container mx-auto font-display"
@@ -127,13 +129,20 @@ const rc = url_components[1] ?? "";
 			class="pt-12 h-screen lg:sticky top-0 fixed z-10 bg-c-bg w-60 lg:w-auto border-r-2 lg:border-0
                 border-c-border-1 -translate-x-64 lg:translate-x-0 transition-transform"
 		>
-			<nav class="py-4 pr-2 overflow-x-scroll h-[calc(100vh-3rem)]">
-				<div class="mb-2 relative" x-data="{open: false}">
+			<nav
+				class="py-4 pr-2 overflow-x-scroll h-[calc(100vh-3rem)]"
+			>
+				<div
+					class="mb-2 relative"
+					x-data="{open: false}"
+				>
 					<button
 						class="bg-c-bg text-c-text border border-c-primary rounded px-3 w-full font-mono mt-2 flex items-center hover:dark:bg-zinc-800 transition-colors cursor-pointer text-left"
 						@click="open = !open"
 					>
-						<span class="inline-block w-full">
+						<span
+							class="inline-block w-full"
+						>
 							{version}
 						</span>
 						<svg
@@ -157,14 +166,18 @@ const rc = url_components[1] ?? "";
 							class="absolute top-0 w-full bg-c-bg border border-c-primary rounded"
 						>
 							{
-								versions.map((x) => (
-									<a
-										class="px-3 py-1 hover:dark:bg-zinc-800 transition-colors font-mono inline-block w-full text-left"
-										href={`${lc}${x}${rc}`}
-									>
-										{x}
-									</a>
-								))
+								versions.map(
+									(x) => (
+										<a
+											class="px-3 py-1 hover:dark:bg-zinc-800 transition-colors font-mono inline-block w-full text-left"
+											href={`${lc}${x}${rc}`}
+										>
+											{
+												x
+											}
+										</a>
+									),
+								)
 							}
 						</div>
 					</div>
@@ -172,7 +185,11 @@ const rc = url_components[1] ?? "";
 
 				<hr class="my-6" />
 
-				{entries.map((entry) => <Sidebar entry={entry} />)}
+				{
+					entries.map((entry) => (
+						<Sidebar entry={entry} />
+					))
+				}
 			</nav>
 		</div>
 
@@ -186,7 +203,9 @@ const rc = url_components[1] ?? "";
 			class="lg:pt-12 hidden lg:block pt-4 max-h-screen overflow-x-scroll sticky top-0"
 		>
 			<nav class="rounded-md lg:mt-10">
-				<h2 class="font-display font-medium pb-2 text-c-text-2">
+				<h2
+					class="font-display font-medium pb-2 text-c-text-2"
+				>
 					On this page
 				</h2>
 
diff --git a/src/pages/en/v0.0.1/learn/index.mdx b/src/pages/en/v0.0.1/learn/index.mdx
index f107348..8614a33 100644
--- a/src/pages/en/v0.0.1/learn/index.mdx
+++ b/src/pages/en/v0.0.1/learn/index.mdx
@@ -7,6 +7,105 @@ order: 1
 import InteractiveCode from "@/components/InteractiveCode.astro";
 import Code from "@/components/Code.astro";
 
-# THP :D
+# Welcome
+
+Welcome to the documentation of the THP programming languague.
+
+THP ~~is~~ will be a new programming language that compiles to PHP.
+
+![Accurate visual description of THP](/img/desc_thp.jpg)
+
+## Compiler rewrite
+
+THP was previously written on Rust, but now it's being rewritten in Zig.
+
+![Friendship ended with Rust, now Zig is my best friend.](/img/mudasir.jpg)
+
+Due to the rewrite everything has reversed. The Rust version was `v0.1.3`,
+the Zig rewrite is `v0.0.1`. Also, this is a good opportunity to version
+the docs.
+
+The `latest` branch contains future ideas and stuff, but the versioned branches
+(for example, `v0.0.1`) will document **only** actual, implemented
+things, and new branches will be published as the compiler evolves.
+
+## Why?
+
+PHP is an old language. It has been growing since 1995, adopting a
+lot of features from many places like C, Perl, Java, etc. This was
+done in a very inconsistent way, as detailed by Eevee in their article
+[PHP: a fractal of bad design.](https://eev.ee/blog/2012/04/09/php-a-fractal-of-bad-design/)
+
+Along the years PHP has been improving. PHP added classes, exceptions,
+interfaces, traits, type hints and checks, functional features,
+reflection, etc., etc. However, by building on top of the existing
+language without a clear design philosophy, and by keeping backwards
+compatibility, we ended up with a messy language. The article
+above goes into detail about this.
+
+In spite of this, PHP has remained widely used and loved, in a
+weird way (I'd say in the same way that people love JavaScript),
+and at the time of writing PHP 8.3 is available. However,
+PHP is to my eyes fundamentally flawed, and cannot be fixed
+without completely breaking what came before.
+
+This is where THP comes in. I wanted a modern language
+that could run in the same environment that PHP does.
+And I quickly realized that building on top of PHP
+in the same way that TypeScript did for JavaScript would be
+detrimental. It would be better to create a completely new
+language, treat PHP source code as a "low level" compilation
+target, and focus entirely on the new language.
+
+This new language would be mainly inspired by what **I** consider the best
+designed languages out there: Rust as a baseline, Zig for
+its null and error handling and Kotlin for its OOP features.
+In a way, PHP will be adapted to, say, Rust's syntax and semantics,
+instead of having Rust adapt to PHP.
+
+In pursue of this THP **will** ditch many things about PHP,
+in name of consistency. These are things that PHP devs are
+used to doing, but that I consider bad practices, hacks or
+workarounds. One example of this are variable variables on PHP:
+`$$variable`.
+
+Another critical point of THP is type safety. It is a goal
+to approach the same level of type safety that have compiled
+languages like Java/Go/Rust, and leave aside dynamic typing
+as much as possible. Types cannot be turned off, you cannot
+use `Any` to avoid typechecking, and so on.
+
+Finally, there are some additions to the language that I consider
+essential today: A good, unified LSP, type definitions,
+accesible documentation, an opinionated code formatter
+and plugins for major editors like VSCode and Neovim.
+
+## Goals
+
+- Implement a strongly typed language, without unknown types
+- Implement generics
+- Reduce implicit type conversion to a minimum.
+- Remove the inconsistencies in the language.
+- Organize the PHP stdlib.
+- Have a clear distinctions between Arrays, Tuples, Maps and Sets.
+- Implement Sum types
+- Have typings for popular libraries (like TS's `.d.ts`).
+- Have a simple instalation, with a single binary
+- Ship a **_blazingly fast_**, native binary, written in Zig.
+- Ship a language server, linter & formatter built in.
+- Configure a THP project with a single file.
+- Support in-place compilation of individual files.
+
+## Not goals
+
+These are **not** things that THP wants to solve or implement
+
+- Be what TypeScript is for JavaScript (PHP with types).
+- Strictly adhere to PHP syntax/conventions.
+- Strictly reuse PHP syntax
+
+THP **_intentionally_** uses a different syntax from PHP to signal
+that it is a different language, and has different semantics.
+
+
 
-Version 0.0.1