oxaliq.net/README

  
                     --------------
                    | λ oxaliq.net |\ 
                    \--------------\ \
                     \______________\|

it's my personal home page.
it's for putting stuff on the web.

it's written in racket and serves (mostly) static html pages. there's some little
javascript in there - https://htmx.org/

why's there some javascript? because javascript is still kinda important to me??
mostly cause i think this htmx project is neat and allows me to do some cool things
without sending several megabytes. and the pages still work without allowing scripts.

so 
 ________________
|----------------|
| HOW IT'S BUILT |
|----------------|
 ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
it's a racket web server that uses xml library to generate some valid html.
i write my little posts in xml-like s-expressions. (not for everyone! but i like the
expressivity!) someday, i might turn it into a proper dsl with support for htmx's 
~funky~ syntax and a little more distance from it's host language, but not this day.

i make generous use of `racket/web-server` with a dispatcher for `hx/` prefixed content
(snippets of html), and plain `/` (for rendering full pages.) handlers build the
content from the little sexpr .scm files (they're not valid racket on they're own,
they get read and evaluated as data.) it's all real small and everything, but i figured
why not save the generated html in a `static/` directory so it doesn't need to be built
on each request? so that's what happens.  

that's the server! it's compiled and hosted on bunk.computer. it's all very cute.

 _________________
|-----------------|
| WHAT'S ON THERE |
|-----------------|
 ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
so, yea, it's all running over there and it's serving up some html (with a little dash
of javascript.) so what's on it?

right now, the plan's for

      ~UNSETTLED THOUGHTS~
      it's like a blog. just thinking out loud. or talking about projects that aren't
      ready to get their "tires kicked" yet

        ~SETTLED THOUGHTS~
        it's like a portfolio. links to stuff. deployed stuff. pictures of stuff. a
        home for everything that's done enough to need a home. or projects with
        "minimally kickable tires"

                ~THOUGHTS ABOUT THOUGHTS?~
                there's some "root" resources. yr typical about page, y'know with some
                biographical information, or whatever. "errata" like: 
  ~a page about the site itself. 
  ~maybe a link page with some links to things i like or do as a person with other people
   in the world
  ~a tag index and indices for tags

the structure of things is such that: there's no templating per se. if the request
has the path prefix "/hx/" you just get little snippets of html. the htmx is there to
stitch that stuff together. make sure yr browser insesrts the response where it 
belongs in the page and i wipe my hands of the the thing. otherwise you get a page
stitched together from all the bits and bobs.

so don't be surprised if yr response is just an ~unsettled thought~ without any header
or footer or any of that fanciness.

 _____________
|-------------|
| HOW TO POST |
|-------------|
 ¯¯¯¯¯¯¯¯¯¯¯¯¯
let's talk about the posting. so you write up a little bit of s-expressified xml-like 
plain text works of astounding eloquence; how do you get the server to generate some 
stuff for you? i wrote a little utility for that. it's called "publish" and it uses a
#lang package a friend made for making cli tools called 
[cli](https://docs.racket-lang.org/cli/index.html)

the tool is called "publish" and it needs some flags to build a thing right.
```
$ publish -i in-progress/ex.txt \ # -i is for the input (i keep em in in-progress/")
          -r unsettled \ # -r is for the resource "type" (see "WHAT'S ON THERE?")
          -t ecology,art,computer \ # -t is for comma separated tags
          -l "An Example Text" \ # -l is for head_l_ine (it means title)
          -d "a short description-like a sentence long ideally"
  # there's also an "-x" flag to do a "test run" before publishing. it'll generate
  # stuff in publish-test/ including a "staging database" (it's csv files)
```
there's a couple things this'll do. 
- first it'll take yr post and do some processing, add a footer with metadata and tags.
-  it'll also update the "database" of csv files for the resource type and for all of 
   the associated tags. 
- this generates new index files for the resource type, and the tags.
- if the post introduces a new tag, a new tag index gets made.
- the atom feed gets updated with the uri and the relevant info about the post.
  (it's on the to-do list to embed the post in the feed, cause i like to read my rss
   in cli, but i'm also a hypocrite that wants people to visit my page!)
- finally it moves the input file to an archive folder. 
  (in the future i'll make an update tool for posting updates to existing stuff!)

so that's simple enough.

 ______________________
|----------------------|
| HOW TO MODIFY A POST |
|----------------------|
 ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
so, some things aren't done til yr dead. some of those things might be posts. `publish`
is always going to move yr text into archive/ and you'll be able to move that file back
to in-progress/ when yr ready to start working on it again.

then you can use the "modify" tool. here's how it works
```
$ modify -i in-progress/ex.txt \ # -i is for the input
         -r unsettled \ # -r is for the resource type
         -l "An Example Text" \ # -l is for the head_l_ine (title)
```
you can't currently change the description or the tags on existing posts.
what this does:
- update the csv files for the resource type
- rebuilds the source with footer and metadata and tags
- update the atom feed, but this time with a "updated" tag in the entry

if at any point the script encounters a problem, any changes will be rolled back

 _________
| LICENSE |
 ¯¯¯¯¯¯¯¯¯
the source code is available under GNU AGPLv3 : /LICENSE
the content (in source directory) is available under 
CC-BY-SA-4.0 : static/license/license.txt