STxT: The Book

A language for the web

◄ Previous Next ►

Chapter 3: STxT, Tutorial

If you had to read just one chapter of this book, this would be that chapter. Here we explain what STxT is, in a straightforward manner, without further ado. And we also give you enough notions so you can read any other chapter.

One example... now!

This is the first language I know where you can start with one example and everybody can get to understand it.

The example will be a cooking recipe. We will be tweaking it, so that it increasingly looks more like an STxT text, but you do not have to worry about this. I promise that it will be easy, not very traumatic, and you will like it :-D

Without further ado... Sweet fritters from Girona!

Sweet fritters from Girona

This is a recipe for making sweet fritters at Lent 
time. They are known also as Sweet Fritters from l'Empordà.
They are usually served as a dessert, and there is enough quantity
for up to 12 people. It is an easy to make recipe.

1 Kg flour
8 eggs
zest of 1-2 lemons
150 grams sugar
100 grams butter
1/4 liter milk
1 glass of grassolis (blend of muscatel, anise, cointreau)
75 grams yeast (from a bakery)
aniseed
a pinch of salt
a little bit of ground cinnamon

Place flour and the other ingredients in a bowl.
Melt the butter with some milk, as well as the
yeast. The milk for dissolving the yeast has to be only 
slightly lukewarm, because otherwise it would probably
lose its effect. Mix everything well, and let stand
covered for 3-5 hours (until the dough raises).
With a spoon or teaspoon, depending on the size you want, 
fry in plentiful oil until you turn golden. As you take
them out, sprinkle them with a little bit of the grassolis mixture, and 
cover them with sugar.

For now it is only text, it cannot yet be considered a valid STxT. But we will be tweaking it and little by little we will obtain a perfect STxT ;-)

First, we have to identify the parts and think of a hierarchical structure. A possible structure would be made of 5 parts. The full document is a recipe (1st part), and can be broken into 4: Title, Description, Ingredients, and Preparation.

******
Recipe
******

-----
Title
-----
Sweet fritters from Girona

-----------
Description
-----------
This is a recipe for making sweet fritters at Lent 
time. They are known also as Sweet Fritters from l'Empordà.
They are usually served as a dessert, and there is enough quantity
for up to 12 people. It is an easy to make recipe.

-----------
Ingredients
-----------
1 Kg flour
8 eggs
zest of 1-2 lemons
150 grams sugar
100 grams butter
1/4 liter milk
1 glass of grassolis (blend of muscatel, anise, cointreau)
75 grams yeast (from a bakery)
aniseed
a pinch of salt
a little bit of ground cinnamon

-----------
Preparation
-----------
Place flour and the other ingredients in a bowl.
Melt the butter with some milk, as well as the
yeast. The milk for dissolving the yeast has to be only 
slightly lukewarm, because otherwise it would probably
lose its effect. Mix everything well, and let stand
covered for 3-5 hours (until the dough raises).
With a spoon or teaspoon, depending on the size you want, 
fry in plentiful oil until you turn golden. As you take
them out, sprinkle them with a little bit of the grassolis mixture, and 
cover them with sugar.

This is a very natural structure, and is the basis for obtaining the final STxT document.

EVERYTHING in Namespaces (ns)

We are going to lose our fear right now of namespaces in STxT; as a tribute to all the xml traumatized users who cannot stand them ;-)

If we know something about xml and ns we will forget it momentarily.

Now pay attention.

An STxT document is made up of a set of nested nodes, and ALL the nodes must belong to a namespace (it does not have to be the same one always).

A namespace (ns) is a document (STxT!!) where it is specified which ones are its nodes, their shape, and what they may contain.

Contrary to other languages (such as xml) this document MUST EXIST and must be accessible through the web. It is normal that programs and parsers save it locally, but it is a requirement that the document exists and is accessible through the Internet. STxT has been made for the free access of information and it is basic that everyone be able to find the definitions.

Let’s see how the example namespace would be (the real STxT document is not like this, we will see this later, but the information that it will contain will be this same one):

Namespace: www.cooking.demo/recipe.stxt

If it were not made up it would be accessible through the web 
using the url: http://www.cooking.demo/recipe.stxt

We define 5 nodes:

* Recipe
* Title
* Description
* Ingredients
* Preparation

Recipe will be in turn of the node type, and will contain nodes 
of the type 'Title', 'Description', 'Ingredients' 
and 'Preparation' (all of the same namespace). 
Title, Description, Ingredients, and preparation will be 
in turn text type nodes.

It could be represented schematically:

* Recipe: Node type, and contains:
** Title: Text type
** Description: Text type
** Ingredients: Text type
** Preparation: Text type
    
This document will also have other restrictions, as that there can only
be one title, or that the description is optional, but this also will
be seen further ahead.

And now we will rewrite the recipe with the previous nodes and namespaces. We must keep in mind that we only need to specify the namespace of the first node, the other namespaces are deduced automatically from its definition.

Incredible!
Finally a bit of coherence and user friendliness in the ns! :-)

Recipe(www.cooking.demo/recipe.stxt):

Title: Sweet fritters from Girona

Description: 
    This is a recipe for making sweet fritters at Lent 
    time. They are known also as Sweet Fritters from l'Empordà.
    They are usually served as a dessert, and there is enough quantity
    for up to 12 people. It is an easy to make recipe.

Ingredients:
    1 Kg flour
    8 eggs
    zest of 1-2 lemons
    150 grams sugar
    100 grams butter
    1/4 liter milk
    1 glass of grassolis (blend of muscatel, anise, cointreau)
    75 grams yeast (from a bakery)
    aniseed
    a pinch of salt
    a little bit of ground cinnamon

Preparation:
    Place flour and the other ingredients in a bowl.
    Melt the butter with some milk, as well as the
    yeast. The milk for dissolving the yeast has to be only 
    slightly lukewarm, because otherwise it would probably
    lose its effect. Mix everything well, and let stand
    covered for 3-5 hours (until the dough raises).
    With a spoon or teaspoon, depending on the size you want, 
    fry in plentiful oil until you turn golden. As you take
    them out, sprinkle them with a little bit of the grassolis mixture,
    and cover them with sugar.

And that's it! Our first STxT document! :-) Take a good look at it. You don't need anything else.

Read this section as many times as you wish, it is essential. It is everything. If you understand this, that’s it. You will know STxT.

Please do not go on. Read this section at least once again.
After that, go on.
Or better: rest, read it again, and move on to the next section :-)

Nodes and indentation

We said before that an STxT document is a set of nested nodes. But we have not said what the nesting rules are, or how it is done. But everything is very intuitive and visual:

It is made according to the node indentation.

Better with an example, it is easier to see it than to explain it:

Node 1(x):
    Node 2:
        Node 3: Node text 3
        Node 4: Node text 4
    Node 5:
        Node 6: Node text 6
        Node 7: Node text 7

In this example we have a main node Node 1, which in turn contains 2 nodes: Node 2 and Node 5. At the same time Node 2 contains Node 3 and Node 4, and Node 5 contains Node 6 and Node 7.

This structure is very visual (actually the explanation has been more complicated), and easily inferable from each node’s indentation. Just by changing the indentation, we change this structure.

For example, the following document is the same, but with a different indentation:

Node 1(...):
    Node 2:
        Node 3: Node text 3
        Node 4: Node text 4
        Node 5:
            Node 6: Node text 6
    Node 7: Node text 7

The entire structure has now changed:

We see that the hierarchical structure has completely changed.

In our recipe for example, the structure was:

Recipe(...):
    Title:
    Description:
    Ingredients:
    Preparation:

We had a node Recipe containing all the other nodes.

We see that indentation is the key, and indentation is obtained by tab characters. It is also possible to obtain it through spaces, although the tabs have always been a standard in texts, so it is the recommended form in STxT (besides saving space).

Rule: An STxT document can only have one main node

This rule has to be met always, thus allowing for a simplification in the structuring of the documents. Therefore, it is not necessary that the 2nd level nodes be aligned.

In our example above, we could have the following structure, with the same meaning:

Recipe(...):
Title:
Description:
Ingredients:
Preparation:

Thanks to the structure, the first node found is the main node, and all others are considered its children. In the same way we would have the following text

Node 1(...):
    Node 2:
        Node 3: Node text 3
        Node 4: Node text 4
    Node 5:
        Node 6: Node text 6
        Node 7: Node text 7

is equivalent to

Node 1(...):

Node 2:
    Node 3: Node text 3
    Node 4: Node text 4
Node 5:
    Node 6: Node text 6
    Node 7: Node text 7

Node and Text

The most common node types in STxT documents are NODE and TEXT. The node type is a container for other nodes, while the text type allows the inclusion of a text, without restrictions.

Alignment is the only thing that matters

This is the basic rule for all nodes. Previously we have seen how the alignment changes the node hierarchy. In text nodes, the alignment lets us include any type of content WITHOUT NEEDING TO USE ESCAPE CHARACTERS. The only restriction is that it must be aligned to one level more than the text node.

One example, please:

Node (...):
    Text Node: This is where the contents of the text node begin. 
        All lines must be with an alignment above 
        the "Text Node:". We see that escape characters are not necessary.
        From the alignment we know what is part of "Text Node".

More fun now... how about if we introduce xml into the text? We will see that there is no problem. We can insert text content without having to escape any character. At Last!

Node (...):
    Text Node: We are going to put an xml example; 
        of how things were done before STxT:
        <node>
            <node1>This is an example</node1>
            <node2>This is an escape example: &lt;</node2>
        </node>

Comments

All computer techs know what the comments in any language are. In case we have any beginners, I will explain that comments are text that are only there in order to comment or add any observations, but have no effect on the document itself.

In STxT, all lines that begin with the character # are comments

Let’s go back to our example. We’ll imagine that we want to add information to our recipe, but this information is only incidental, or even just to increase the document’s readability. Thus, we would add this information as a comment.

# -----------------------------------------------------
# Author = Joan Costa Mombiela
# Creation date = 04-05-2013
# This recipe is originally from the Empordà. It was given to us
# by some very dear relatives.
# In gratitude, we have published it as the 1st
# recipe on this book.
# -----------------------------------------------------

Comments do not need to have any kind of format, it is free text that the author of the document can include. In addition, it does not have to be located anywhere specifically in the document. Any line that starts with # will be treated as a comment, and will not be taken into account in programs or communications.

Finally, grammar

And here is grammar. Or, the definition of namespace nodes. We will see it in more depth in the next chapter, but it is fairly self-explanatory; like all STxT documents ;-)

Namespace Definition(www.semantictext.info/namespace.stxt):

Node Definition:
    Type:NODE
    Name:Recipe
    Child:
        Node:Title
        Num:1
    Child:
        Node:Description
        Num:?
    Child:
        Node:Ingredients
        Num:1
    Child:
        Node:Preparation
        Num:1
        
Node Definition:
    Type:TEXT
    Name:Title
    
Node Definition:
    Type:TEXT
    Name:Description
    
Node Definition:
    Type:TEXT
    Name:Ingredients
    
Node Definition:
    Type:TEXT
    Name:Preparation

The information contained is what we had previously seen:

Just as a piece of information, there are 11 node types, although the node and text are the most common ones:

NODE, TEXT, URL, NATURAL, INTEGER, RATIONAL, NUMBER, BINARY, HEXADECIMAL, BASE64, BOOLEAN

Regarding Num we have the following possibilities: number,?, +, * All of them are very intuitive for those who are used to working with regular expressions.

Overview

◄ Previous Next ►
This website uses cookies to ensure you get the best experience on our website. [cookies.html|Learn more] Got it! More info