Chapter 2: Tutorial
If you were to read only one chapter of this book, this would be the chapter. We explain what STxT is directly, without further ado. And we also give you enough knowledge to read any other chapter.
An Example... Right Now!
Documents Without Namespace
This is the first language I know of where you can start with an example and everyone can understand it.
The example will be a recipe. Let's go!
Recipe: Macaroni Recipe Description: :This is the description of the macaroni recipe. :Bla, bla, bla :Bla, bla, bla Servings: 3 Difficulty: easy Ingredients: Ingredient: (100g) Tomato Ingredient: (240g) Macaroni Steps: Step: (1) Make the sauce Step: (2) Boil the macaroni Step: (3) Mix the macaroni with the sauce and serve
Easy, right? Okay, I'm not a great chef :-D but it’s perfectly understandable.
Don’t use this recipe at home, wait for the next chapter ;-)
Well, you’ve just seen what a STxT document without a namespace looks like. These types of documents
are structured, but we don’t know the shape of the nodes. However, you can already see that they have structure, with a main node Recipe
, which has
a Description
node, Ingredients
, etc. These nodes in turn have others, and so on,
forming a hierarchical structure.
It’s worth mentioning the Description
node, which is a node that allows multilines.
Without a predefined structure, they are distinguished by being indented but with
lines that have no preceding label. This is very important for documents without a namespace.
Documents With Namespace
Now we’ll go further and define the same recipe with a namespace. First, we’ll show the recipe, and then we’ll show the namespace. You might think it should be done the other way around, but the reality is that most of the time, we’ll have an example and later define the general case.
Here’s the recipe:
Recipe (www.kocinando.com/receta.stxt): Macaroni Recipe Description: This is the description of the macaroni recipe. Bla, bla, bla Bla, bla, bla Servings: 3 Difficulty: easy Ingredients: Ingredient: (100g) Tomato Ingredient: (240g) Macaroni Steps: Step: (1) Make the sauce Step: (2) Boil the macaroni Step: (3) Mix the macaroni with the sauce and serve
What has changed? Well, now the recipe has an associated namespace,
which is www.kocinando.com/receta.stxt
, and the Description
node seems
more natural. That’s it :-) We’ve converted a document without a namespace
into one with a namespace, just by adding who it belongs to and removing the :
character from the multiline fields.
It couldn’t be simpler ;-)
Now let’s create the namespace. The namespace definition is found in a document without a namespace. In the previous version of STxT, it wasn’t like this, but it complicated the parsers and forced you to always have a namespace definition. Now this has changed, and everything has been greatly simplified.
Here’s the namespace we can create for the example:
Namespace: www.kocinando.com/receta.stxt Recipe: Description: (?) TEXT Servings: (?) NUMBER Difficulty: (?) ENUM : easy : medium : hard Ingredients: (1) Ingredient: (+) Steps: (1) Step: (+)
It’s very intuitive, the structure itself is a reflection of the hierarchical order, indicating the type of node if necessary.
The namespace should be accessible via the internet, at the same URL that indicates it.
Thus, this namespace should be available at https://www.kocinando.com/receta.stxt
.
Parsers should also have it available locally, and it’s better that way for performance.
We’ll talk more about namespaces later, but creating a document from them should be much simpler than in other languages.
Other Elements
Comments
It’s possible to insert comments in the documents to express unfinished parts, the author’s thoughts, etc. Comments won’t be used but allow enriching the document.
Recipe (www.kocinando.com/receta.stxt): Macaroni Recipe # This recipe was given to me by XX and I’ve made it many times # You’ll love it!! Description: This is the description of the macaroni recipe. Bla, bla, bla Bla, bla, bla Servings: 3 Difficulty: easy Ingredients: Ingredient: (100g) Tomato Ingredient: (240g) Macaroni Steps: Step: (1) Make the sauce Step: (2) Boil the macaroni Step: (3) Mix the macaroni with the sauce and serve
Different Namespaces in a Document
A namespace can refer to another one, to indicate that part of the document has its structure in another namespace. It’s better to see an example:
Namespace: www.kocinando.com/recetario.stxt RecipeBook: Recipe: (+) (www.kocinando.com/receta.stxt)
Here we see that Recipe
is from another namespace, and instead of providing the structure,
it refers to another namespace.
There is NO need to specify the internal namespace, only the main node.
So, an example of a recipe book would be:
RecipeBook (www.kocinando.com/recetario.stxt): Mom’s Recipes Recipe: Macaroni Recipe Description: This is the description of the macaroni recipe. Bla, bla, bla Bla, bla, bla Servings: 3 Difficulty: easy Ingredients: Ingredient: (100g) Tomato Ingredient: (240g) Macaroni Steps: Step: (1) Make the sauce Step: (2) Boil the macaroni Step: (3) Mix the macaroni with the sauce and serve Recipe: Pizza Recipe Ingredients: Ingredient: (1u) Pizza dough Ingredient: (100g) Tomato Ingredient: (50g) Cheese Steps: Step: (1) Add tomato and cheese to the pizza Step: (2) Bake for 15 minutes
End of the Tutorial
Please don’t continue. Reread this section at least one more time. Then continue.
Or better: read it again, take a break, and move on to the next section :-)