Chapter(www.semantictext.info/book.stxt): Metadata: Title: Chapter 3: STxT, Tutorial Description: Tutorial which explains the basic operation of STxT Author: Joan Costa Mombiela Last_modif: 2013-03-01 Nav: Prev: 02 Next: 04 title: Chapter 3: @STxT@, Tutorial text: 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. h1: One example... now! text: 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!// code: 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. text: 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. code: ****** 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. text: This is a very natural structure, and is the basis for obtaining the final @STxT@ document. h1: EVERYTHING in Namespaces (ns) text: 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 ;-) alert: If we know something about xml and ns we will forget it momentarily. alert: Now pay attention. text: 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): code: 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. text: 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.// assert: Incredible! \\ Finally a bit of coherence and user friendliness in the ns! :-) code: 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. text: 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@. alert: 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 :-) h1: Nodes and indentation text: 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: assert: It is made according to the node indentation. text: Better with an example, it is easier to see it than to explain it: code: 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 text: 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: code: 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 text: The entire structure has now changed: * Node 1: Contains Node 2 and 7 * Node 2: Contains Node 3, 4, and 5 * Node 5: Contains Node 6 We see that the hierarchical structure has completely changed. In our recipe for example, the structure was: code: Recipe(...): Title: Description: Ingredients: Preparation: text: 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). assert: Rule: An @STxT@ document can only have one main node text: 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: code: Recipe(...): Title: Description: Ingredients: Preparation: text: 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 code: 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 text: is equivalent to code: 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 h1: Node and Text 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. assert: Alignment is the only thing that matters text: 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: code: 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". text: 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!// code: Node (...): Text Node: We are going to put an xml example; of how things were done before STxT: This is an example This is an escape example: < h1: Comments text: 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. assert: In @STxT@, all lines that begin with the character # are comments text: 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. code: # ----------------------------------------------------- # 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. # ----------------------------------------------------- text: 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. h1: Finally, grammar text: 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 ;-) code: 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 text: The information contained is what we had previously seen: * There are 4 text nodes: Title, Description, Ingredients, Preparation * There is one node container of others: Recipe. This one in turn must contain the others in the following way: **There must be **one** Title node **There may** be one Description **There must be **one** Ingredients node **There must be **one** Preparation node 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. h1: Overview text: * An @STxT@ document is a set of hierarchical nodes. * The structure of any node is defined in its corresponding namespace. * The node hierarchy can be seen visually, and is achieved through indentation (using tabs). * An @STxT@ document can only have one main node, which lets us align its children without having to indent them * The namespaces of all nodes do not need to be specified, only the one for the main node. The rest will be inferred automatically. * A document can have nodes from different namespaces. * A document must comply with its corresponding grammar.