the magic behind automa basic

../ r

2022-06-29

To celebrate the beginning of a new triapul project, automa basic, I took the opportunity to write a brand new content managing system for it. While it is still in its infancy, though operational (this website being a proof of that), not a single line of any automa basic .html files was touched by human hand.

But this is not so much a statement of my impeccable execution of obsolete ideas, as it is a proof of concept. Just like with twat, the triapul automaton that provides an interface to posting and editing website content, or teige (teige does famously make use of ImageMagick, but can work without it), the image gallery manager, all these were written in ksh in base OpenBSD installations.

Note that twat has become so bloated and importable, that it will take some time for it to see public release. Nevertheless, I will write about it eventually. I know, rm is itching to rewrite it in go, but would it work in base OpenBSD then? ;) (rm says 'yes :D, go can compile portable binarie for all BSDs')

This means that andre, the program that handles the web content of automa basic will work out of the box with no dependencies on any systems that comes with ksh.

Surely there are plenty of tools to manage one's website and I in no way aim to compete with those, but I am proud of the fact that a single script file (and a config file to manage the paths to one's webserver root directory) can provide a user with a friendly method of managing their internet presence.

Some basic commands of andre that are already implemented are the following:

$ andre -w # writes a new post, all posts are also listed on user's index, if he so chooses.
$ andre -wf file # create a new post from a prewritten file
$ andre -ei # edits (and updates) user's index
$ andre -eI ID # edits a post by ID
$ andre -rI ID # removes a post by ID
$ andre -l # lists all posts by dates, titles, and IDs

In a perfect world, one would not need anything but these few commands to manage their site. In the future I aim to provide automated RSS integration and adapt teige's image upload - but for now, there are bugs to fix and features to fine-tune. twat also has a feature where it monitors a specific directory and then posts whatever valid file it found. This allows for an easy way of posting via, say, email. I want to adapt that as well.

andre is also being written with multi-user environment in mind and can manage multiple users' sites, each in their own directory, with individual permissions.

But here's the kicker!

Writing a simple manager is one thing, fundamentally you're generating html files with supplied headers, so that editing one file, will update all. It's a simple method of pasting together a universal header, an html formated body of each post and variables that go in various places throughout the document (ie: HTML_TITLE, HTML_DESCRIPTION). You keep the individual posts offline for when a user edits them and rebuilds the online version. But how to get around the fact that this method would still require the posts to be written in html?

I wrote my own spin on markdown for that, all part of the single ksh script. To keep things short, take a look below at the format of a file I wrote this very post in. I call it writing html in plain text.

Again, this is not meant to replace or compete with other languages or tools that do these tasks. But a method like mine offers a simple way of maintaining an automated website via nothing but ksh and plain text files.

A little preview

andre looks for lines beginning with DATE, TITLE, LANG, DESC and TAGS and turns them into variables that are used for generating the html file. TITLE also get's posted as <h1>

Currently the supported COMMANDS are the following: H2, H3, H4,... IMG, URL, NOTE, PRE, LIST.

Lines that begin with these are telling andre to format them accordingly, with some mitigation of errors. For example the URL or IMG commands accept urls both external and internal (www.website.com/image.png /img/image.png), if a user forgets or chooses not to supply the protocol for external images, andre attempts to fill it in. If an image or url does not exist, he will not post it.

this is a picture of Puffy

this is a link to my profile on bsd.network

The syntax is simple. For commands for which it makes sense the first space or tab following the COMMAND tells andre to expect a url, the next space or tab, in the case of URL and IMG, text between <a> </a> and img alt= respectively.

In the case of NOTE, which is currently just a <p> with a class that turns it into italics, the syntax would be:

NOTE text that follows will be in italics.

In the case of LIST, the command on a single line tells andre to expect <li> until it hits an empty line and closes the list. LIST also accepts URL.

This isn't.

There is also PRE which on an empty line tells andre to format next lines as part of the <pre> until it encounters another PRE and closes the tag.

Any text not beginning with the aforementioned COMMANDS andre treats as <p> and any subsequent line is considered a part of that <p>. This is there to allow for manual line breaks when writing long paragraphs.

An empty line closes the </p>

The future of simplicity

If you like this project, stay tuned for any updates!

As with most of my programs - written with love on and for OpenBSD (and ksh <3).

An example file:

This is what the file that I wrote this page in looks like (the '#' are not part of it):

#DATE 22-06-29
#TITLE the magic behind automa basic
#LANG en-US
#DESC andre - the plain text html language
#TAGS andre, html
#
#To celebrate the beginning of a new triapul project, automa basic, I took the
#opportunity to write a brand new content managing system for it. While it is still
#in its infancy, though operational (this website being a proof of that), not a
#single line of any automa basic .html files was touched by human hand.
#
#But this is not so much a statement of my impeccable execution of obsolete ideas,
#as it is a proof of concept. Just like with twat, the triapul automaton that
#provides an interface to posting and editing website content, or teige (teige
#does famously make use of ImageMagick, but can work without it), the image gallery
#manager, all these were written in ksh in base OpenBSD installations.
#
#NOTE Note that twat has become so bloated and importable, that it will take some time for it to see public release. Nevertheless, I will write about it eventually. I know, rm is itching to rewrite it in go, but would it work in base OpenBSD then? ;)
#
#This means that andre, the program that handles the web content of automa basic
#will work out of the box with no dependencies on any systems that comes with ksh.
#
#Surely there are plenty of tools to manage one's website and I in no way aim
#to compete with those, but I am proud of the fact that a single script file
#(and a config file to manage the paths to one's webserver root directory) can
#provide a user with a friendly method of managing their internet presence.
#
#Some basic commands of andre that are already implemented are the following:
#
#PRE
#$ andre -w # writes a new post, all posts are also listed on user's index, if he so chooses.
#$ andre -wf file # create a new post from a prewritten file
#$ andre -ei # edits (and updates) user's index
#$ andre -eI ID # edits a post by ID
#$ andre -rI ID # removes a post by ID
#$ andre -l # lists all posts by dates, titles, and IDs
#PRE
#
#In a perfect world, one would not need anything but these few commands to manage their
#site. In the future I aim to provide automated RSS integration and adapt teige's
#image upload - but for now, there are bugs to fix and features to fine-tune. twat also
#has a feature where it monitors a specific directory and then posts whatever valid
#file it found. This allows for an easy way of posting via, say, email. I want to
#adapt that as well.
#
#andre is also being written with multi-user environment in mind and can manage
#multiple users' sites, each in their own directory, with individual permissions.
#
#H2 But here's the kicker!
#
#Writing a simple manager is one thing, fundamentally you're generating html files with
#supplied headers, so that editing one file, will update all. It's a simple method of
#pasting together a universal header, an html formated body of each post and variables
#that go in various places throughout the document (ie: HTML_TITLE, HTML_DESCRIPTION).
#You keep the individual posts offline for when a user edits them and rebuilds the
#online version. But how to get around the fact that this method would still require
#the posts to be written in html?
#
#I wrote my own spin on markdown for that, all part of the single ksh script. To keep
#things short, take a look below at the format of a file I wrote this very post in. I
#call it writing html in plain text.
#
#Again, this is not meant to replace or compete with other languages or tools that do these
#tasks. But a method like mine offers a simple way of maintaining an
#automated website via nothing but ksh and plain text files.
#
#
#H3 A little preview
#
#andre looks for lines beginning with DATE, TITLE, LANG, DESC and TAGS and turns them
#into variables that are used for generating the html file. TITLE also get's posted
#as <h1>
#
#Currently the supported COMMANDS are the following: H2, H3, H4,... IMG, URL, NOTE,
#PRE, LIST.
#
#Lines that begin with these are telling andre to format them accordingly, with some
#mitigation of errors. For example the URL or IMG commands accept urls both external
#and internal (www.website.com/image.png /img/image.png), if a user forgets or chooses
#not to supply the protocol for external images, andre attempts to fill it in. If
#an or url does not exist, he will not post it.
#
#IMG /img/puffy.gif this is a picture of Puffy
#URL bsd.network/@prahou this is a link to my profile on bsd.network
#
#The syntax is simple. For commands for which it makes sense the first space or tab
#following the COMMAND tells andre to expect a url, the next space or tab, in the
#case of URL and IMG, text between <a> </a> and img alt= respectively.
#
#In the case of NOTE, which is currently just a <p> with a class that turns it
#into italics, the syntax would be:
#
#PRE
#NOTE text that follows will be in italics.
#PRE
#
#In the case of LIST, the command on a single line tells andre to expect <li>
#until it hits an empty line and closes the list. LIST also accepts URL.
#
#LIST
#this is a part of a list
#so is this
#and so is this
#URL openbsd.org openbsd.org
#
#This isn't.
#
#There is also PRE which on an empty line tells andre to format next lines as part
#of the <pre> until it encounters another PRE and closes the tag.
#
#Any text not beginning with the aforementioned COMMANDS andre treats as <p>
#and any subsequent line is considered a part of that <p>. This is there
#to allow for manual line breaks when writing long paragraphs.
#
#An empty line closes the </p>
#
#H2 The future of simplicity
#
#If you like this project, stay tuned for any updates!
#
#As with most of my programs - written with love on and for OpenBSD (and ksh <3).
#
#H3 An example file:
#
#This is what the file that I wrote this page in looks like (the '#' are not part of it):

This file is not recursive.

andre is named after André Breton, a French surrealist.

triapul.cz