This is a specification document for SuperTXT and related conventions. You will find a section for each of the major concepts along with the possible variants, and informative examples.
SuperTXT is a line-oriented format built on top of plain text. The type of any line can be identified by reading at most the first 3 text characters.
Each line has a type. There is a description of each type below.
Paragraphs are lines in a SuperTXT document (.s.txt) that don't match any of the other types and aren't empty. It is the fallback.
A paragraph is a single line that can contain any collection of Unicode characters. There are certain special characters that can wrap sequences of characters within a paragraph. In each case, there's a special starting character that must be matched by an end character, which is sometimes the same, sometimes different.
Start End Description * * Highlighted sequence of characters (e.g. italic in deep reading form) ** ** Extra highlighted sequence of characters (e.g. bold in deep reading form) [ ] Characters in between represent an inline link (escaped using backslack '\[' and '\]')
Paragraphs are free to be rendered using variable-width fonts, if possible.
Headings are lines that begin with one or more '#' characters followed by a single space. The number of these characters indicates the level of the heading, not to exceed a level of three. There can be at most one level one headings, and it must be on the first line of the document.
# (anchor) key: heading text
There are two optional constructs available for headings. One is an anchor, which provides a name that can be used for linking directly to the section starting at the heading. Anchors are not permitted on level one headings since links to the top of the document should be made via the document's address.
There is an optional key, which is used to indicate the relationship to the entity described in the heading with the parent heading. Again, this is not permitted on level one headings as the relationship is ambiguous. The key is permitted to be an inline link using the same delimiters (\[ and \]) as in paragraphs.
The level 1 heading is not required for a SuperTXT document. It can be omitted from a document that doesn't have a clear title. It's possible to have documents that contain only level 2 and higher headings.
Points are defined as lines that begin with a single '*' character and one space. They can be placed anywhere in a SuperTXT document.
* point OR * key: value
The first variant of a point is used for simple text points within the contents of the document. There is no semantic meaning to them other than to the reader of the prose.
The second variant contains a key and value and must be located together after a heading to have a semantic meaning. The points are in relation to the entity declared by the preceding heading. Their values are prefixed by the key, which indicates their relationship to this entity. Note that if the points are at the beginning of the document and the level 1 heading isn't present they are provided semantics for the entire document in the same way as if the heading is present.
Keys can be inline links to further documentation about the relationship. In this case the key should be surrounded by square braces as in this example.
# Toronto * type: city * [:@population]: 2794356 => (population) city-semantics.s.txt:@pop
If the key is not a link, such as the "type" key above, it then assumes the universal meaning. One source of universal meanings can be found at the [:@schema.org] community.
Values can also be inline links, using the square braces to indicate this. Otherwise, values are considered to be scalar values. You can provide the data type of the scalar value by name or link using "^^^" as the separator. Here are some examples.
u
* created: 2018-10-22T15:33:00Z^^^DateTime * visitors: 45^^^Number * mass: 21kg^^^QuantitativeValue * reading time: 1.5H^^^Duration * foo: AB2345^^^[:@license plate] => (license plate) transpo-defs.org:licensing.s.txt:@lic-plate
Link lines provide a directly navigable [:@pathname2] with some extra features. Sometimes paths can be long, or lack sufficient context on their own in the document. The link lines can help to make the links flow better.
=> (anchor) path/to/some/place.ext
This link declares a location of another document. It also binds it to an named anchor that can be used within the current document. A link doesn't require an anchor, but it can help to integrate it with surrounding prose.
Here some paragraph text. Check out this [:@other document] => (other document) path/to/some/other/place/with/a/long/path/other-document.s.txt
The link path can be to a document, or an precise anchor point within the document, such as a line number, or entity. In this example, the first link points to line 25 of "document1.txt" and the second link points to the heading with anchor "foo" in "document2.s.txt", which declares an entity
=> document1.txt:25 => document2.s.txt:@foo
Preformatted blocks can span multiple lines while preserving the formatting of the text. They are started by a line that starts with three back-ticks followed by an optional anchor, and anchor for the content.
Preformatted
Text
The file extension provides context for the type of the content based on the file extension that would normally be used for it. If no file extension is specified then it is implied to be ".txt" plain text content.
An anchor provides intra-document navigation to the preformatted block. If the file extension can be run as a command by the user agent (i.e. browser or shell) then navigation can set up a command to be inspected and run by the user.
Preformatted blocks for SuperTXT (.s.txt file extension) can indent all lines for better readability and also to escape any inner preformatted blocks.
A quote line highlights a section of characters or markup that can be attributed to a particular source, or admonition.
> Quoted text -- simple attribution
This is a very simple quote and attribution separated with the "--" separator.
> Quoted text line 1 > Quoted text line 2 > -- simple attribution
Multiple lines, including the attribution can be glued together into a single long quote.
> Quoted text => (anchor) path/to/attributed/document.txt
Putting a quote directly above a link attributes the quote to the linked document.
> Quoted text > * key: value => (anchor) path/to/document.s.txt
Quote lines that start with a point attribute specific semantic values to the linked path. Note that these semantic values may be externally ascribed to the link, so they may or may not be present in the attributed document with the same value. The meaning of this discrepancy is left open to the reader and/or tooling. For example, the point could be a fetch date, or content hash to help discover if it was updated since the quote was made to help explain any possible discrepancies. In other cases the quote could be attempting to externally provide corrections or overlay information to the content of the linked document.
> important: > Don't forget to set your alarm!
If the first quote line ends with a colon ":" then this quote represents an admonition. The leading text indicates the type of admonition (e.g. note, tip, warning, error, important, danger). The remaining quote represents the content of the admonition. Note that in this case neither simple, nor link attribution should be specified for the quote.
An include represents a line where external content should be included there in a "deep reading" rendering of the content. In browsing form these behave nearly identically to link lines, including the preceding quote lines that can used to make a heading for the included content and/or repeat information from that document.
<= (logo) images/logo.png
The anchor is optional and can be used to link to the included content from elsewhere in the document. Note that it doesn't automatically navigate to the destination document like a link line.
Ultimately, links involve generating new command-lines for fetching new content. The most fundamental form of a link is spelling out a command-line with a preformatted block and the ".sh" file extension. It's enough information to have a browser navigate there.
``` .sh command --option=value arg/file.s.txt ```
This is verbose, too verbose to be allowed inside a line (paragraph, point, heading) as it would disrupt the flow of reading. But, a preformatted block can be referenced through to the anchor.
Where shall we go [:@next] ``` (next) .sh command --option=value arg/file2.s.txt ```
Trouble is that the preformatted blocks can become repetitive in a document where all the commands and options are virtually the same. The only difference is often the path. Plus, the preformatted blocks cost three lines for every link instead of one with the path. A single link line is much smaller.
Where shall we go [:@next] => (next) nobody@server1^1234:dir1/file.s.txt:@next
This link line uses the current command and the "--srefl=redirection" reflection to query the command itself for the complete command to navigate from the current location to that place.
Links from within a line are permitted to be full paths, as what can be specified in a link line.
Where shall we go [nobody@server1^1234:dir1/file.s.txt:@next]
The inline links are permitted to include details such as the user (nobody), server address (server1), port number (1234), directory (dir1), file (file.s.txt), and heading anchor (next). Most of these details can be omitted, so long as the complete destination command can be assembled via the reflection with at least one piece of information. If only a local portion is present then this is bypassed in favour of navigating to a local anchor, which provides a mechanism for moving the complexity of the link outside the paragraph, heading, point, etc. and into separate link lines. Sometimes paths are simple and clear so that they can remain inline.
Semantics are introduced through the adding keys to points, headings, or quotes, which establishes a relationship (predicate) between a subject and object. The result is the creation of a semantic triple of this form, which is surprisingly versatile.
<subject> <predicate> <object>
Subjects are entities that are usually introduced via a heading, often with an anchor. The level 1 heading has an implicit address of the current document without the file extension. Level 2 and 3 headings without an anchor are consi.e. "blank" entities, addressable only as a subject of triples in the current document.
## (entity1) Entity1
This entity called ":@entity1" within the current document can have a description like this.
## (entity1) Entity1 * color: black
The resulting triple is this in subject, predicate, object form.
[:@entity1] color black
In this case the object is a simple string "black". The object of a triple can be another entity. The object entity can be entirely contained within the parent entity in the same document using a sub-entity (i.e. sub-heading) and a key that relates it through a predicate to the parent. Additional triples can be used to further describe the child.
## (entity1) Entity1 ### (entity2) pred1: Entity2 * pred2: somestringobject
This document produces two triples.
[:@entity1] pred1 [:@entity2] [:@entity2] pred2 somestringobject
The object can also be an external link to another document.
# Cheese Grater - Product Review * type: review * reviews: [somesite.net:products/cheese_grater_133]
The triples could look something like this.
[reviews.com:reviews/155] type review [reviews.com:reviews/155] reviews [somesite.net:products/cheese_grater_133]
The subject is generally anchored to an entity described in the current document. However, quotations can make statements about external subjects using a link line attribution and points with keys inside the quotation.
> * status: closed => foo/bar/status
This creates the following triple generated from this document.
[foo/bar/status] status closed
Predicates can also be a link instead of simple string for further description, or event its own semantics.
# Document1 * [:@version]: 0.0.1 ## (version) Version Information Version information is three positive integers separated by periods representing the major, minor and service aspects of the version.
The triple representation is here:
[thisdocument] [:@version] 0.0.1
Sometimes the object of a triple is a string with a specific data type, such as a number, or date, that must be marked. There can be special parsing required for these kinds of data types. This is done with a special '^^^' as described previously in the [:@points] section.
HAVE SOME FEEDBACK ON THIS DOCUMENT?
You can provide a conventional comment on this document.
ssh nobody@supertxt.net ccmnt specs/supertxt.s.txt <<EOF suggestion: Here's my actionable suggestion. EOF