$ cats nobody@supertxt.net:articles/www-comparisons.s.txt

# World-Wide-Web Counterparts in the SuperTXT Stack

In this article we will cover certain aspects of the World-Wide-Web and how they work within the SuperTXT stack. The hope is to help to explain how the SuperTXT stack works through comparison. This also gives us an opportunity to explain some of the rationale.

## HTML Markup -> SuperTXT

HTML markup is notoriously difficult to read and compose in source form. Also, faithful parsing of it is left to only a single class of application, which is the web browser and it is a huge piece of software engineering, not small, and also very difficult to decompose.

Previous efforts to make the format more approachable include the invention of the WikiWiki markup languages. The unification effort of those led to Markdown, which has further splintered into different flavours. Markdown supports embedding any kind of HTML, and so you will always need a HTML capable web browser to browse a file. Finally, Markdown isn't entirely line oriented with breaking paragraphs, and mult-line heading styles.

More recently, Project Gemini developed a new markup that is line-oriented and broke the HTML dependency entirely. SuperTXT is deeply inspired by this format with some additional features and adjustments.

<h1>My document</h1>
<p>Some long phrase
that I want to grep
# My document

Some long phrase that I want to grep.

## URL/URI -> Command/pathname

Instead of URL/URI, links are made using either commands or pathnames. Commands have an advantage of being able to be run in a variety of places, such as the OS shell, or a graphical shell like brsh. They can occupy multiple lines, and are allowed to contain spaces, and can even have comments, which can make them much more readable/auditable by a user. The execution semantics of commands is clear in that the program is the one on the system path. Preformatted blocks with the '.sh' file extension behave as hyperlinks to new content. Since the commands are encapsulated in blocks they can be represented with spaces and extra lines as needed.

cats supertxt.net:articles/www-comparisons.s.txt # Run the cats command on the PATH to fetch this document

If a command is missing then it can be a search term to find how to install it.

srch <<EOF # Let's search to find out more about cats

Sometimes the entire command is unnecessarily verbose since it shares the same command as the one that fetched the current document. A link line reuses the command of the current document and provides the pathname to the new document.

→ www-comparisons.s.txt

## Media Types -> File Extensions

The World-Wide-Web uses hidden media types to inform the web browser (and other entities) the type of the requested or returned data via the "Accept" and "Content-Type" headers. SuperTXT uses the well established file extension system instead. If a user specifies a pathname with a particular file extension then this is the type that they expect to see, like ".txt" or ".jpg". Commands have the opportunity to perform type conversions to satisfy the request, or report an error. For hierarchical types where there are formats built on top of a container format there is a two-level compositional file extension convention established by Unix for tar and gzipped files with ".tar.gz" that can be reused as a convention for other combinations. SuperTXT is built on simple text ".txt" with additional features and so its file extension is ".s.txt" indicating that tools that work with simple text files can also work with SuperTXT files.

text/plain           -> .txt
text/supertxt        -> .s.txt
audio/wav            -> .wav
application/x-sh     -> .sh
image/png            -> .png
application/tar+gzip -> .tar.gz

somefile.png # This is a PNG image

## Web Browser -> Shell/Commands/SSH/Filesystem/OS

Instead of a single large web browser, SuperTXT decomposes it into specialized components. The OS itself is responsible for scheduling, resource allocation of the running processes. It is very good at these tasks and has entire suites of tools to work with them, such as activity monitors and deadlocked app detection. The OS also handles network connections. SSH is a standard secure networking system, with identity management features. Commands can use SSH, OS, and local filesystem to achieve their goals, such as managing their state, and network transparency.

The web browser can provide rich application experiences in a way that isn't possible with simple typesetting through SuperTXT and a graphics capable shell. In these instances then a command can provide its own graphical user interface that is well suited to its domain. Site-specific commands can provide a internet site oriented experience that is graphical, command-line driven, or both.

## Web Server -> SSH server/Commands

Anything more than trivial static websites will require a web server in order to access the content. The web server operates over TCP and therefore needs a well communicated port number, even while developing it on your laptop. Since SuperTXT is command oriented a server isn't usually necessary for local content creation since the command does the work of a server without a port number. If a server is required for network access then an SSH server can be started on a server to run the commands remotely. Luckily, OpenSSH and other SSH server implementations are commonly used with servers and have built-in user access control capabilties. SSH capable commands are often able to invoke themselves through the SSH connection as long as they are installed on the server too. There are specialized SSH server implementations, such as the SuperTXT consrv, for anonymous and public internet services.

## HTTP Headers -> SuperTXT Points

HTTP headers are famously hidden from the user's view and can store information on your computer through the use of cookies. They are often used for different kinds of user tracking and so this lacks transparency. Instead of hiding these details from the user, the SuperTXT stack promotes the use of points at the top of a document, either underneath the top-level heading if there is one or directly on top of the document. Since SuperTXT points can have a predicate (field name) it can be keyed like an HTTP header, with a value after the colon. The values can be assigned data types too, such as dates, or geographical coordinates.

# Top-level heading
* key1: value1
* key2: value2