Inline examples into the manual (WIP / DO NOT MERGE)

[fingolfin]

This contains PR #8 and PR #12 and removes the example dir, by inlining the examples directly into the manual XML. The examples are then also automatically extracted for use in the test suite.

Those tests currently fail due to some diffs which are mostly harmless; i could easily fix them to work in, say, GAP 4.11; the tricky part is to make them work across several GAP versions (see e.g. the differences in output described in issue #5). I could take care of that, but before I invest such effort, I want to check if this is something @jdebeule would be interested in at all.

Thing is, I am still not quite sure if having the example also in .g files is explicitly wanted (then this PR here is in the wrong direction), or just for convenience for updating the examples to match the output of the latest versions of GAP & forms - because that can be done differently, as Thomas already described (I could add a script update_manual_examples.g to do it automatically, if desired)

[jdebeule]

So far I am happy with inlining the examples in the xml files of the documentation. However, there are some subtleties that we should discuss first. I'll try to explain this concisely here.

Based on past experiences, the examples in the documentation are not necessary ideal test-examples. Some examples in the manual require e.g. a substantial amount of computation time. For this reason, long time ago, we decided to keep the examples and the test files separate. At least, on the level of documentation. Now comes in the idea of the separate .g files (containing only the GAP commands). If an example is useful as a test as well, I'll simply generated (using my doggy './examples/generate_examples_files.g' and './tst/generate_tst_files.g' scripts) two versions of the output, one to be included in the xml, one to be included in the tst directory.

Especially for the fining package, where we have about 350 examples in .g files, I would like to keep this approach, i.e. to have the possibility to generate tst files independently from example files. I do understand now that the output of an example in the xml documentation files can be updated automatically, but still I would like to keep the possibility to generate example files (ready to be included in the xml files) from .g files as well. Based on experience, it is very easy to make mistakes manually copying/pasting the complete output from a GAP session.

So, to conclude, I think we are converging to a good solution, but I hope that the above explanation is claryfying a bit the workflow we used the past years to generate examples and tst files.