From 7b3bdddb82afc61c9c8d375d78799ccc463a48d0 Mon Sep 17 00:00:00 2001 From: Thomas Voss Date: Sat, 28 Oct 2023 15:01:23 +0200 Subject: Remove backup file --- src/srp/gsp/index.gsp.bak | 310 ---------------------------------------------- 1 file changed, 310 deletions(-) delete mode 100644 src/srp/gsp/index.gsp.bak diff --git a/src/srp/gsp/index.gsp.bak b/src/srp/gsp/index.gsp.bak deleted file mode 100644 index 1ff3686..0000000 --- a/src/srp/gsp/index.gsp.bak +++ /dev/null @@ -1,310 +0,0 @@ -html lang="en" { - head { m4_include(head.gsp) } - body { - header { - div { - h1 {-Never Settle For Trash} - m4_include(nav.gsp) - } - - figure .quote { - blockquote { - p {= - 🚨🚨 BREAKING: TYPESCRIPT SNATCHES DEFEAT FROM THE JAWS OF VICTORY - 🚨🚨 - } - } - figcaption {-Lane Wagner} - } - } - - main { - h2 {-Table of Contents} - - ul { - li {a href="#simple" {-Simplicity and Abstraction}} - li {a href="#sucks" {-Most Software Sucks}} - li {a href="#solution" {-My Solution}} - li {a href="#syntax" {-Syntax Highlighting}} - li {a href="#takeaway" {-The Takeaway}} - } - - h2 #simple {-Simplicity and Abstraction} - p {- - I like my software simple and devoid of useless abstraction. I often - find myself in positions where I’m searching for scissors to cut a sheet - of paper, and am instead greeted with a chainsaw. The urge to - over-complicate and -abstract your software can be strong; I often see - people who preach simple software writing programs to solve basic - problems that have 30 different command-line flags, and require a 50 - page m4_abbr(PDF) explaining its operation. - } - - p {- - Why do I mention all of this? Well as anyone who’s ever tried their - hand at web-development knows, websites are written in m4_abbr(HTML). I - wish I could say that’s a good thing, but as anyone who’s ever looked at - m4_abbr(HTML) before would know, that language is — to put it lightly — - really not great. It’s extremely verbose, and awkward to write- and - edit (angle brackets are not the easiest-to-reach keys on the keyboard). - } - - p {- - So what’s the solution? The most obvious to me is to create a nicer to - read- and write language which I can easily transpile down to - m4_abbr(HTML). Ideally the m4_abbr(CLI) is very simple and works on the - standard input and -output like all good UNIX utilities. I should be - able to transpile my site by simply running ‘@code{-cmd in.xyz - out.html}’, where my input reflects the structure of my output will - nicer, less-poluting syntax such as in ‘@code{-div .cls { … \}}’. - } - - p {- - The kind of tool I am describing here is what I imagine the ideal - solution to be. A @em{-simple} tool with a @em{-simple} function. It - takes an input language and produces an output language. There is also - minimal abstraction. The input language should reflect the structure of - m4_abbr(HTML), because that’s exactly what we’re trying to output. It - makes little sense to create a fundamentally different language when - m4_abbr(HTML) not only does a good job at defining a websites structure, - but sticking close to the language we are targetting just makes - everyones life easier in every way. - } - - h2 #sucks {-Most Software Sucks} - - p {- - So with my ideal solution being a simple language with a simple - m4_abbr(CLI) that sticks close to the structure of m4_abbr(HTML), let’s - take a look at what other people have come up with: - } - - figure { - pre { m4_fmt_code(markdown.md.gsp) } - } - - p {- Oh no.} - - p {- - Now most readers probably had the initial reaction of “@em{-What’s wrong - with Markdown?}”. To answer your question: everything. The issue I - have with these highly-prevalent Markdown-based replacements for - m4_abbr(HTML) is that they ignore the fundamental fact that - m4_abbr(HTML) and Markdown are @em{-not} compatible languages with each - other. m4_abbr(HTML) is designed around making websites (with the added - autism of m4_abbr(XML)). It gives us things like sematic tags for - describing input forms, navigation bars, figures, and more. With the - addition of classes and IDs, we can even style two paragraphs on the - same page in different ways. This is fundamentally not possible in - Markdown. If we ignore the fact that Markdown is just poorly designed, - it offers us basically none of what we need to make an even - slightly-complex static page as it’s not meant for website-design but - simply to be a readable plain-text format you can use for documentation - or your email or something. - } - - p {- - How do you make your navigation bar in Markdown? Or style two - paragraphs differently? You can’t. Some try to get around this by - adding extensions to the Markdown language, but they never manage to - cover all bases. Another problem I @em{-always} come across when trying - to use Markdown-to-m4_abbr(HTML) tools is code blocks. I always make - sure to use tabs for indentation in my code blocks instead of spaces, so - that I can vary the tab-width based on the screen size of the reader. - You obviously can’t do this with spaces since the fundamental (and - retarded) purpose of space-indentation is to force everyone to view code - with the same indentation, which sucks for users on mobile when you have - nice large indents. To this day I have yet to find a - Markdown-to-m4_abbr(HTML) converter that will let me have tab indents - without error-prone post-processing of the generated m4_abbr(HTML). - } - - p {- - Ok well… there are other ways of generating m4_abbr(HTML); one rather - popular option is Pug: - } - - figure { - pre .pug { m4_fmt_code(pug.pug.gsp) } - } - - p {- - While Pug certainly hits the ‘maintain the same structure’ point right - on the head, it fails in one very crucial area — it’s a JavaScript - library @em{-only}, and so requires a whole m4_abbr(JS) setup simply to - transpile your site to m4_abbr(HTML). What a bummer. There is also a - second issue which is that it uses an indentation-sensitive syntax. - Normally I am actually a fan of languages like this — such as Python — - but in the case of a markup language like Pug, this is terrible as it - makes macros and templating with tools such as @code{-m4} exceptionally - difficult. Pug @em{-does} offer templating faculties via JavaScript, - but I really try to minimize the amount of JavaScript I need to write - whenever possible. - } - - h2 #solution {-My Solution} - - p {- - So with no existing tools fitting my entry criteria, I did the only - reasonable next thing and made my own tool. It tries to stick to the - format of m4_abbr(HTML) as closely as possible while offering an - @em{-extremely} easy-to-use transpiler. It also has no added bullshit - like filters, templates, etc. If you want macros, use a macro-processor - like @code{-m4}. I called it m4_abbr(GSP) because everyone knows that - German Shorthaired Pointers are better than pugs. Here is a quick - syntax example: - } - - figure { - pre .gsp { m4_fmt_code(example.gsp.gsp) } - } - - p {- - Here you can see almost all of m4_abbr(GSP). The document follows the - same structure as m4_abbr(HTML), but thanks to the use of braces instead - of opening- and closing tags, the syntax is far less verbose and easier - to read. The language also provides shorthands for classses and IDs - through m4_abbr(CSS)-selector syntax. - } - - p {- - Templating and macros are also very easy via macro processors thanks to - the use of braces instead of whitespace-based scoping. You may have - noticed that I like to make use of abbreviations on this website that - expand when hovered over. I do this via the m4_abbr(HTML) - @code{-} tag, providing the appropriate class. For example, many - times on this very page I’ve made use of @code{-\@abbr .html {-HTML\}}. - Obviously repeating that everywhere in my document can be quite - annoying, so I’ve gotten around this by making use of the following - @code{-m4} macro: - } - - figure { - pre { m4_fmt_code(abbr.m4.gsp) } - } - - p {- - I can then insert abbreviations by simply writing something along the - lines of ‘@code{-⁨m4_abbr(HTML)⁩}’ in my document. - } - - aside { - p {- - The first thing I did after finishing the transpiler was to rewrite - this entire site in m4_abbr(GSP). There is something that just feels - so great about writing a tool that you actually use in your day-to-day - life. - } - } - - p {- - The transpiler itself is also incredibly easy to use, something - JavaScript developers would never be able to comprehend. In order to - transpile a m4_abbr(GSP) document into an m4_abbr(HTML) document, I - simply run ‘@code{-gsp index.gsp >index.html}’. Yep, that’s it. - } - - h2 #syntax {-Syntax Highlighting} - - p {- - One problem that I came across writing m4_abbr(GSP) was the lack of - syntax highlighting. It can seem not so important, but syntax - highlighting is crucial for helping you quickly identify different - syntax elements. The awesome solution I found for this ended being - Tree-Sitter. Tree-Sitter is a parser-generator that various text - editors such as Vim and Emacs can integrate with to offer efficient- and - high quality syntax highlighting, amongst other features such as - syntax-aware code folding and movement. - } - - p {- - After a bit of research and reading the documentation, I found that - creating your own parsers is actually really easy. You effectively just - define a JavaScript object that describes the language grammar, and a C - parser is generated from that. If you’re interested, you can find the - m4_abbr(GSP) parser @a href="https://git.sr.ht/~mango/tree-sitter-gsp" - {-here}. To give you a bit of an idea of just how simple a Tree-Sitter - parser is, here’s a simplified example of how you describe the - definition of a node, and a node name @x-ref{-1}: - } - - figure { - pre .js { m4_fmt_code(grammar.js.gsp) } - } - - aside { - p data-ref="1" {- - The definition for what constitutes a node name is simplified in the - example. In actuality node names can contain all sorts of unicode - characters too (because m4_abbr(XML) said so), but I would like the - regex to actually fit on the screen. - } - } - - p {- - As you can see, the grammar syntax is extremely simple. You simply - define your core syntax elements via regular expressions, and then - compose them together via helper functions such as @code{-optional} and - @code{-repeat} to define the full structure of your language. - } - - p {- - This isn’t enough though. We now have a parser for our language that - can create a syntax tree that our editor can take advantage of, but our - editor still doesn’t know what each node actually @em{-is} so that it - can be syntax highlighted properly. Tree Sitter solves this through a - query file written in scheme where we can describe how to syntax - highlight our m4_abbr(AST). This is what the configuration for - m4_abbr(GSP) looks like: - } - - figure { - figcaption { - code {-queries/highlights.scm} - } - pre { m4_fmt_code(highlights.scm.gsp) } - } - - p {- - As you can see, this is all really simple stuff, which is what I love so - much about Tree Sitter — it’s just so easy! With these basic annotions - your editor knows that attribute values should be highlighted like - strings, braces like tag delimiters, etc. In a similar vein, writing a - query to describe code-folding is really easy: - } - - figure { - figcaption { - code {-queries/folds.scm} - } - pre { m4_fmt_code(folds.scm.gsp) } - } - - h2 #takeaway {-The Takeaway} - - p {- - So what’s the takeaway? I think it’s that when you have a problem, - often times the best solution is not to fundamentally redesign something - from the ground up, or to completely change the way a system works, but - to instead identify the specific thing that annoys you and find a fix - for it. I thought that the syntax of m4_abbr(HTML) was annoying and - bad, so I found a solution for the syntax, while keeping the core - structure the same. In the same line of thinking, try not to - over-abstract — I’m looking at you, Java developers. Abstraction often - leads to exponentially increased complications the moment we want to do - anything different or out of the ordinary, so unless you can find a - really nice abstraction that doesn’t really make anyones life harder, - try to avoid them when you can. - } - - p {- - If you’re interested in m4_abbr(GSP), you can find the git repository - over at @a href="https://git.sr.ht/~mango/gsp" {-Sourcehut}. - } - } - - hr{} - - footer { m4_footer } - } -} -- cgit v1.2.3