This guide will help you to get started using SuperTXT. If you don't know what this is about you can check out the [:@introduction] first. Afterwards you will be able to browse, read, and write in the medium. Some fundamental computer knowledge is assumed here.
SuperTXT is a lightweight markup language that works well on its own, but is designed to fit well in a greater family of technologies. This means that you can start with only a very small part of it, perhaps just parts of the markup language. Depending on the situation the other pieces might become useful in the future.
You are currently reading this guide. There are a variety of ways that you could be doing this. For simplicity, let's assume for a moment that you've actually got a copy of this file and other related ones on your local computer and are reading this using a simple text editor. There are many other ways you might have gotten here, including a SuperTXT capable viewer like brsh, possibly over SSH. SuperTXT can be written and read virtually anywhere that permits plain text, even some social media sites like Twitter and Mastodon.
By now you've already seen examples of paragraphs, which are just single lines that contain one or more sentences. The most basic SuperTXT document is just a collection of paragraphs. No other special syntax is required. But, because the paragraphs form a single line, instead of being manually broken into separate lines your viewer can wrap the paragraphs automatically to match the width of your screen, or window. Also, if you want to search for a specific phrase there's no need to consider that it could have a newline character in the middle. Editing large lines is also relatively straight forward with the advent of graphical editors where you can place the cursor visually. Even the terminal-based editor vim can be configured to handle a mouse click from a graphical terminal.
Try writing a paragraph into your favorite tool.
This is my first SuperTXT document!
If you have the ability to set the file name give it the extension ".s.txt" so that most tools will see it as a text file. It is one!
Headings are signposts that can be used for both readers (and tools) to navigate quickly to a particular section. Visually, headings stand out because of the '#' at the beginning of the line. Adding a heading with more '#' than the previous makes a sub-heading. Only one top-level heading is permitted in a document. It represents the overarching topic and entity described by the document. This principal heading should not have an anchor since it is already anchored by the document itself.
It's customary to have a top-level heading for any serious document giving it a purpose. Let's add one now.
# Learning SuperTXT This is my first SuperTXT document!
Some ideas are best presented in point form:
We can make our document a bit more striking with some points in it.
# Learning SuperTXT This is my first SuperTXT document! I want to learn the following: * How to author documents with the markup * What kind of structures are available * Add some sizzle to my documents ♨️
Giving credit where credit is due is a great way to share recognition and give people the means to dive more deeply into the source material. Sometimes it's just to give a part of the current document more prominence with a bit of repetition and something visually striking.
This is a simple quote of text within the same document. You can also give a simple attribution at the end so that someone can find the book.
> To be, or not to be > > -- Shakespeare's Hamlet, Act 3, Scene 1
Preformatted blocks are there to encapsulate one or more lines that should be handled specially. When these are shown in their source form they are guaranteed to be displayed in the way that you've formatted it with fixed width fonts so that it lines up correctly.
These words do not overlap
with these words
These blocks also have the ability to break free of the SuperTXT system with code of other file types or documents. Code examples are often placed in these kinds of blocks, or even shell commands that the user can run. The file extension on the first line tells the user and tools what file extension is being used there.
echo "Hello World" # Run this in a shell to put Hello World to standard output
SuperTXT itself doesn't have support for tables. It doesn't need to because preformatted blocks unlock this ability through a tabular file format like Comma-Separated Values (CSV), or Labeled Tab-Separated Values (LTSV). Tools might decide to show this as a table with the column headings, sorting, and other features. Meanwhile, the source format is readable (mostly).
date:2022-05-22 temperature:17.5 date:2022-05-23 temperature:19.5 date:2022-05-24 temperature:19.2 date:2022-05-25 temperature:18.6
For the most part what you've seen above can work great reading/writing in very wide variety of text editors and viewers. Now we get to the part where the tools can be a big difference. Unfortunately, not many tools understand SuperTXT yet. We really hope that will change someday. The browsing of SuperTXT content is doable without purpose-fit tools, but they really can make a difference. At this point we recommend that you install two tools that should make your life better while browsing yours and others SuperTXT documents: brsh and cats.
A simple and easy way to install them is using the [:@homebrew] system with a tap hosted on this site. Assuming you have homebrew installed already, you can tap and install the tools like this:
brew tap supertxt/tap ssh://nobody@supertxt.net/git/st-brew # Adds the tap brew install supertxt/tap/brsh supertxt/tap/cats # Installs cats and brsh
Alternatively, if you have a recent version of Go programming language installed you can install them like this:
go install supertxt.net/git/cats/cmd/cats@latest go install supertxt.net/git/st-int/cmd/brsh@latest
Assuming that installation went ok, you can run brsh into a GUI interface of a Unix shell, and run cats much like you would the built-in Unix cat tool.
cats path/to/my-first.s.txt
The big difference is that both brsh and cats work together to give you a richer browsing experience. With the introduction of hyperlinking you can (and some people do) manually traverse links, but this will be much easier. Also, you can use this environment to browse the SuperTXT site through SSH.
cats nobody@supertxt.net:whats-sshla.s.txt
Links can be a disaster for a paragraph in terms of readability in its source form. That's why we recommend separating them out into a different line like this link to the SuperTXT specification below. Alt-click on the link line to adjust your command-line to get to the destination document.
The freedom is there to move this link line wherever you want it to be. If you have a link heavy document you might put them all at the end. But, if they're all at the end, then it's difficult to know what bit of text refers to which link. This is why link lines can provide anchor text that's much easier to weave into a paragraph. Here's a link to the [:@supertxt specification] link line and it doesn't matter where it is in the document. There are some unusual characters, but the paragraph mostly flows as it should.
You can also anchor other elements like [:@headings], and preformatted blocks with [:@commands] in them. Navigating the link with brsh and the Alt-click gesture generally highlights that place in the document. If the preformatted block has the ".sh" file extension then the brsh will also auto-fill that command into the command-line so that you can inspect it and run it with the Enter key.
srch -C nobody@supertxt.net: <<EOF browser EOF
In this guide you took a brief tour of the SuperTXT elements, such as paragraphs, [:@headings], [:@quotes], [:@preformatted], and [:@links]. Along the way some new concepts were introduced, such as anchors. There was a brief detour into some recommended tools. With an assortment of examples you can see that the format is simple, but versatile, and still just plain text!
HAVE SOME FEEDBACK ON THIS DOCUMENT?
You can provide a conventional comment on this document.
ssh nobody@supertxt.net ccmnt start.s.txt <<EOF suggestion: Here's my actionable suggestion. EOF