<!DOCTYPE html>
<html lang="en">
    <head>
<!--LOAD include/stdhead.html -->
        <title>blog: kethel/2 - m1kadev.nl</title>
    </head>

    <body>
<!--LOAD include/stdnav.html -->
        <main>
            <h1>Kethel/2: A high level overview of a low-level SSG</h1>
            <p>
                I've been meaning to rewrite my old elixir-based SSG for a newer, and easier to set up alternative.
                So, what language is the most portable, has universal support across linux distributions?
                <code>ISO/IEC 9899:1999</code>, or <em>The C Programming Language</em> - of course!
            </p>
           <h2>a small note of advice</h2>
            <p>
                Kethel isn't perfect by any means; it sometimes just writes garbled data to the output HTML document
                if a template or TSV ends with a newline, is probably vulnerable to several buffer overflow attacks,
                as no bounds checking is implemented at all, treats HTML as plain text, with only a
                "parser" which breaks if you change any nearly any formatting in the templates. And yet, it still works! <br />
                So, I'd like to explain some design decisions behind Kethel/2, for fun and to break-even on the time spent on
                this.
            </p>
            <h2><code>aggregate</code>, and my "solution" to index page generation</h2>
            <p>
                Aggregate was the 2nd program I wrote for my site, which fills the spot of a 'compiler', if we're following
                the compiler/linker metaphor. The RSS feed generation for my site before was really iffy
                (<a href="https://www.rfc-editor.org/info/rfc822/">RFC822</a> and <a href="https://www.rfc-editor.org/info/rfc2822/">RFC2822</a> are to blame).
                I <em>could</em> have switched to atom feeds instead of RSS in the original kethel, but I had better things to do with my time then
                refactor all my elixir code.
                <span>(This isn't an issue with elixir per se, but moreso that I didnt really wanna debug my elixir, wrote as my first and only elixir project)</span>
            </p>
            <p>
               The general idea with aggregate is that you provide a TSV file, with some free-form data, and aggregate could transform that into an index page,
               but also an Atom <code>&lt;entry&gt;</code>, with proper tag uri support. Coming back to the first sentence about the 'compiler' metaphor,
               aggregate does not generate the final html, but only 'preprocesses' the templates and generates a <code>mkpage</code>-compatible 'object page'.

               Since I've only used C in this project, I already had an obj folder for intermediate output, so it was easy to just generate all the indexes, and
               various feed entries, and use <code>mkpage</code> as a sort of <em>ersatz</em>-linker, to generate the final XML/HTML.
            </p>

            <h2>So, what is this <code>mkpage</code> all about then?</h2>
            <p>
                Mkpage is the original program that orchestrated all HTML generation, inspired by PHP's "it's just html!" approach, and
                <a href="https://zed.dev/">my code editor's</a> unwillingness to let me use unclosed tags in my template html files. I chose to use simple HTML comments
                with some meaning, which I then decode in C. Originally an experiment to only generate my homepage, it's been able to generate a lot of my pages
                relatively quickly.
            </p>
            <p>
                However, it quickly become clear that my linear-time no-seek approach to page generation wasnt really going to scale to, say,
                more than 2 pages in a directory. mkpage only supports 2 commands, <code>LOAD</code> and <code>STAMP</code>. <code>LOAD</code>
                takes a path, and puts the file's contents where the directive used to be.
                <code>STAMP</code> is used mostly for atom feed generation, but is generalised to work in most cases where you'd need a timestamp.
            </p>
            <p>
                Therefore, aggregate deals with most of the more complex parts of my website's build pipeline. A combination of some hardcoded behaviour (C
                lets you get away with way worse software architecture than elixir), and some generalised 'paradigms', has let me create this entire website with only 7 commands.
                Aggregate takes care of most of the more complicated commands, listed below.
            </p>
            <ul>
                <li><code>ANCHOR</code> - generates a reproducible id for any content-item, another issue i was dealing with in kethel2 </li>
                <li><code>PUT</code> - pastes a tsv table value, verbatim, does still have some issues with newlines thought</li>
                <li><code>LINK</code> - generates a permalink to a (section of a) page, for my microblog this uses </li>
                <li><code>ATOM</code> - generates all atom metadata for an entry</li>
                <li><code>DATE</code> - pretty prints the date</li>
            </ul>
            <h2>So that's it, honestly</h2>
            <p>
                Besides some dependency modelling in make, this is all that Kethel2 really needs. The only things I'd maybe want to change (or create, for funsies).

            </p>
            <figure>
                <blockquote><em>Merci d'avoir lu!</em></blockquote>
            </figure>
        </main>
	<hr>
<!--LOAD include/stdfooter.html -->
    </body>
</html>