rtfm/intro Manual Introduction - a first version.

The same text is presented in two formats: for an external text editor (.txt)
or with lines limited to 80 characters.

The links are prepared but not functionnal.

docs/rtfm/intro 80 char

@@ -0,0 +1,143 @@
+Welcome to Gem-graph !
+
+Gem-graph lets you move and transform drawn objects using an automaton. It's an
+ideal tool for describing the evolution of a situation through drawing. Would
+you like to see your drawings evolve automatically to represent a phenomenon?
+Gem-graph lets you transform your drawings as you wish. You can draw whatever
+you want. It's your drawing and you decide how it evolves! You can use gem-graph
+to make a game. You can use it to make a model of a phenomenon that interests you.
+You can represent what you want simply or in more realistic detail.
+Simple parts and more detailed parts can coexist in the same design. You can
+watch what you have created evolve without interfering or guiding it towards what
+you want to achieve. You can mix several drawings and animations. You can observe
+them in detail, modify them, go back, start again, measure, compare and keep the
+results that interest you so that you can play them again.
+
+However, a certain amount of effort will be required to achieve this. A complicated
+model will require more work than a simpler one, but it is possible to start with
+something simple and develop it step by step. In any case, you must draw what you
+want to see and say how you want it to be transformed. Gem-graph cannot do that
+for you. Gem-graph can only help you to draw up and develop your idea. However,
+it can give you powerful tools to do so. The strength of gem-graph - short for
+'geometric graph' - lies in the fact that it deals only with very simple drawing
+elements, all of which are similar, and that the rules it uses to manipulate these
+elements are equally simple and similar. As a result, these rules can be combined
+and processed automatically, no matter how many there are. The tools provided by
+gem-graph give you access to the power of the automaton it uses to draw and animate
+your drawings, and this manual is here to help you to learn how to master them.
+
+One way of doing this is to reproduce a very simple example, such as when a word
+processing program asks you to write "Hello world". For gem-graph, the equivalent
+of "Hello world" will be to move a small line on your screen. Once you have done
+this simple example, you will know enough to quickly build and animate much more
+complex drawings that suit your desires. If you like learning this way, this
+example is explained (here). If you prefer to learn by reading what the commands
+you see on the screen are doing, they have been detailed (here). The table of
+contents goes from the simplest to the most complicated. How to set up a simple
+model, observe it and measure what it does, then transform it by changing what
+you see and how it reacts.
+
+------------
+
+Our "Hello world" is the simplest program that gem-graph can execute. It consists
+of a single short arrow, which moves in a straight line in a single direction.
+To do this, we first had to draw this little arrow and then make it move. The
+result is certainly not very exciting, but this example is enough to show how a
+drawing is made and how it is animated. One state and one rule are enough. The
+rule only says: if an arrow is drawn here, I erase it and redraw it on the next
+square. For the moment, you don't need to know in detail how the rule works
+(it's described here). All that gem-graph needs to know is written in the
+"Hello world" file (here). If you open this file, you'll find a description of
+the arrow (here) and its movement (there).
+
+------------
+
+To improve this model, it is possible to give the arrow the ability to move in
+two directions: forwards or backwards. To do this, we need to add a second rule.
+This second rule says: if an arrow is drawn here, I erase it and redraw it on the
+previous square. A random draw (described here) is also necessary to determine
+whether the first or second rule applies. With these two rules and the random
+draw, the arrow now sometimes goes forwards, sometimes backwards. We can call
+this second model a "random walk".
+
+------------
+
+The second model (the random walk) had one state (the arrow) and two rules
+(forward/backward). Now here's a model with two states and two rules:
+the pendulum. This time, the arrow can be drawn either tilted forwards or tilted
+backwards (these are the two possible states) and the two rules switch the drawn
+arrow from one state to the other or vice versa. In the file, the states are (here)
+and the rules (here). The pendulum does not change place, but alternates between
+left and right. Like the previous ones, you can slow down the programme so that
+you can observe the movements.
+
+------------
+
+Once you know how to write a state and a rule, you can write thousands of them:
+they will always be combinations of the same elementary form. However, it is also
+possible to combine programs: for example, you can combine the reports and rules
+from the two previous models to create a new model that shows both phenomena
+simultaneously. Once again, in the file, the states are (here) and the rules
+(here).
+
+------------
+
+The next example shows how the same rule can be applied to a multitude of states.
+The rule is the same as that used in the first model: an arrow can only be moved
+one square forward, but this time you have to check that the square forward is
+free. If it isn't, the arrow won't move. Once the rule has been modified in this
+way, it can be applied to a multitude of arrows distributed randomly in space
+(see details here).
+When you set the model in motion, you will see all these small lines moving from
+left to right. A single rule is responsible for all these movements.
+For a small fee, we can apply the two rules of the 'random walk' model to all the
+arrows distributed in this space, and they will then all behave in the same way,
+sometimes moving forwards, sometimes backwards.
+
+------------
+
+
+In the next example, we first build a model similar to the previous one: a
+multitude of arrows are randomly distributed in space, but this time they are
+vertical and the movements are up and down instead of right and left. Then, we
+add this model to the previous state and set the final model in motion. We see
+then little lines moving from left to right or reverse if they are horizontal,
+and up and down or reverse if they are vertical. Their number is constant. They
+don't change shape or direction. There seems to be no accident when they cross.
+Nothing else happens.
+
+------------
+
+The last example in this series, because it shows a multitude of diverse and
+simultaneous movements, perhaps gives the impression of a more complex system.
+It would be easy to make it even more complex, but it's much more interesting
+to show how gem-graph can be used to analyse and control that complexity (here). At
+this point, it's time to compare gem-graph to other classes of automata that do
+quite similar things, and to look at what it can actually do and what its
+limitations are.
+
+------------
+
+The main difference between gem-graph models and agent-based models is that
+gem-graph deals with situations, not agents. In a situation where several agents
+are interacting and each agent could apply a different rule, gem-graph considers
+and processes the situation. Not the agents. Whatever the state - the new
+situation - that results from his action, his decision-making process will have
+been simple and straightforward. It will therefore be easy to modify and control.
+And the diversity of possible new situations will be far greater than that
+offered by agent-based models.
+
+------------
+
+The comparison between gem-graphs and cellular automata first comes up against
+a question of vocabulary. What is commonly called a 'rule' in one and the other
+is not the same thing. Gem-graphs and cellular automata have the same power:
+anything that can be done by one can be done by the other, but their writing is
+not the same (details of this comparison here).
+
+------------
+
+How can gem-graph be used to analyse and control the complexity of what it 
+represents and sets in motion? This chapter introduces the gem-graph mechanism.
+
+

docs/rtfm/intro.txt

@@ -0,0 +1,51 @@
+Welcome to Gem-graph !
+
+Gem-graph lets you move and transform drawn objects using an automaton. It's an ideal tool for describing the evolution of a situation through drawing. Would you like to see your drawings evolve automatically to represent a phenomenon? Gem-graph lets you transform your drawings as you wish. You can draw whatever you want. It's your drawing and you decide how it evolves! You can use gem-graph to make a game. You can use it to make a model of a phenomenon that interests you. You can represent what you want simply or in more realistic detail. Simple parts and more detailed parts can coexist in the same design. You can watch what you have created evolve without interfering or guiding it towards what you want to achieve. You can mix several drawings and animations. You can observe them in detail, modify them, go back, start again, measure, compare and keep the results that interest you so that you can play them again.
+
+However, a certain amount of effort will be required to achieve this. A complicated model will require more work than a simpler one, but it is possible to start with something simple and develop it step by step. In any case, you must draw what you want to see and say how you want it to be transformed. Gem-graph cannot do that for you. Gem-graph can only help you to draw up and develop your idea. However, it can give you powerful tools to do so. The strength of gem-graph - short for 'geometric graph' - lies in the fact that it deals only with very simple drawing elements, all of which are similar, and that the rules it uses to manipulate these elements are equally simple and similar. As a result, these rules can be combined and processed automatically, no matter how many there are. The tools provided by gem-graph give you access to the power of the automaton it uses to draw and animate your drawings, and this manual is here to help you to learn how to master them.
+
+One way of doing this is to reproduce a very simple example, such as when a word processing program asks you to write "Hello world". For gem-graph, the equivalent of "Hello world" will be to move a small line on your screen. Once you have done this simple example, you will know enough to quickly build and animate much more complex drawings that suit your desires. If you like learning this way, this example is explained (here). If you prefer to learn by reading what the commands you see on the screen are doing, they have been detailed (here). The table of contents goes from the simplest to the most complicated. How to set up a simple model, observe it and measure what it does, then transform it by changing what you see and how it reacts. 
+
+------------
+
+Our "Hello world" is the simplest program that gem-graph can execute. It consists of a single short arrow, which moves in a straight line in a single direction. To do this, we first had to draw this little arrow and then make it move. The result is certainly not very exciting, but this example is enough to show how a drawing is made and how it is animated. One state and one rule are enough. The rule only says: if an arrow is drawn here, I erase it and redraw it on the next square. For the moment, you don't need to know in detail how the rule works (it's described here). All that gem-graph needs to know is written in the "Hello world" file (here). If you open this file, you'll find a description of the arrow (here) and its movement (there).
+
+------------
+
+To improve this model, it is possible to give the arrow the ability to move in two directions: forwards or backwards. To do this, we need to add a second rule. This second rule says: if an arrow is drawn here, I erase it and redraw it on the previous square. A random draw (described here) is also necessary to determine whether the first or second rule applies. With these two rules and the random draw, the arrow now sometimes goes forwards, sometimes backwards. We can call this second model a "random walk".
+
+------------
+
+The second model (the random walk) had one state (the arrow) and two rules (forward/backward). Now here's a model with two states and two rules: the pendulum. This time, the arrow can be drawn either tilted forwards or tilted backwards (these are the two possible states) and the two rules switch the drawn arrow from one state to the other or vice versa. In the file, the states are (here) and the rules (here). The pendulum does not change place, but alternates between left and right. Like the previous ones, you can slow down the programme so that you can observe the movements.
+
+------------
+
+Once you know how to write a state and a rule, you can write thousands of them: they will always be combinations of the same elementary form. However, it is also possible to combine programs: for example, you can combine the reports and rules from the two previous models to create a new model that shows both phenomena simultaneously. Once again, in the file, the states are (here) and the rules (here).
+
+------------
+
+The next example shows how the same rule can be applied to a multitude of states. The rule is the same as that used in the first model: an arrow can only be moved one square forward, but this time you have to check that the square forward is free. If it isn't, the arrow won't move. Once the rule has been modified in this way, it can be applied to a multitude of arrows distributed randomly in space (see details here).
+When you set the model in motion, you will see all these small lines moving from left to right. A single rule is responsible for all these movements.
+For a small fee, we can apply the two rules of the 'random walk' model to all the arrows distributed in this space, and they will then all behave in the same way, sometimes moving forwards, sometimes backwards.
+
+------------
+
+
+In the next example, we first, we build a model similar to the previous one: a multitude of arrows are randomly distributed in space, but this time they are vertical and the movements are up and down instead of right and left. Then, we add this model to the previous state and set the final model in motion. We see then little lines moving from left to right or reverse if they are horizontal, and up and down or reverse if they are vertical. Their number is constant. They don't change shape or direction. There seems to be no accident when they cross. Nothing else happens.
+
+------------
+
+The last example in this series, because it shows a multitude of diverse and simultaneous movements, perhaps gives the impression of a more complex system. It would be easy to make it even more complex, but it's much more interesting to show how gem-graph can be used to analyse and control that complexity. At this point, it's time to compare gem-graph to other classes of automata that do quite similar things, and to look at what it can actually do and what its limitations are.
+
+------------
+
+The main difference between gem-graph models and agent-based models is that gem-graph deals with situations, not agents. In a situation where several agents are interacting and each agent could apply a different rule, gem-graph considers and processes the situation. Not the agents. Whatever the state - the new situation - that results from his action, his decision-making process will have been simple and straightforward. It will therefore be easy to modify and control. And the diversity of possible new situations will be far greater than that offered by agent-based models. 
+
+------------
+
+The comparison between gem-graphs and cellular automata first comes up against a question of vocabulary. What is commonly called a 'rule' in one and the other is not the same thing. Gem-graphs and cellular automata have the same power: anything that can be done by one can be done by the other, but their writing is not the same (details of this comparison here).
+
+------------
+
+How can gem-graph be used to analyse and control the complexity of what it represents and sets in motion? This chapter introduces the gem-graph mechanism.
+