[CsMain] CS 2.1 Tutorial Testing and Documentation Eval

[markettwp]

Using CS 2.1 under Kubuntu 14.04, I have found some mistakes in the doc
text and code and propose a fix to make the tutorial actually work as
expected.

When attempting to run Tutorial 2, I find a set of doc instructions less
than clear:

From: CS/docs/html/manual/Simple-Loading-Material.html

The following text from this doc page is a problem:

...
4.2.2.1 Loading a Material in Memory

...

Then, we edit ‘simple.cpp’ and add the following in
Simple::Application() and Simple::CreateSprites() (before ‘return true’):

bool Simple::Application()
{
...
CreateSprites();
...
return true;
}
...
void Simple::CreateSprites()
{
// Load a texture for our sprite.
iTextureWrapper* txt = loader->LoadTexture ("spark",
"/lib/std/spark.png");
if (txt == 0)
ReportError("Error loading texture!");
}
...

The first sentence, above, explaining where to place this code is NOT
correct. The file name should be 'simple1.cpp' and the sentence should
read something like this:

"Then, we edit ‘simple1.cpp’ and add the following method call in
Simple::Application() (before ‘return true’) and also add the new
method: Simple::CreateSprites()."

============ MY FIX FOR THIS PROBLEM ================

The sprite will NOT display wen using the above code, even after adding
all of the code specified in the following pages of the tutorial. The
exact place to insert the call to CreateSprites() in Simple::Application
is NOT clear, it needs some change in the doc text itself. I don't know
exactly where the original author intended this method call to be placed...

I was able to place code in simple1.cpp, in the method
Simple::OnKeyboard (), which will cause the sprite to be displayed upon
entering the keystroke 's':

...
bool Simple::OnKeyboard (iEvent& ev)
{
// We got a keyboard event.
csKeyEventType eventtype = csKeyEventHelper::GetEventType (&ev);
if (eventtype == csKeyEventTypeDown)
{

...

// display a sprite
if (code == 's')
{
CreateSprites();
}
}

return false;
}
...

I think this approach to displaying the sprite actually makes more sense
in terms of learning how to use CS.

=================================================

Next, moving on to the following tutorial page:

CS/docs/html/manual/Simple-Creating-Mesh.html

The page title and first sentence reads as follows:

4.2.2.3 Creating a Mesh from a Factory

To create a mesh just add the following code in Simple::CreateSprites()
(before ‘return true’ and after the code we just added to load the mesh
factory):

void Simple::CreateSprites ()
{
...
}

The problem is that the method, Simple::CreateSprites(), is declared as
type VOID and does NOT return anything, so this sentence should read
something like this:

"To create a mesh just add the following code in Simple::CreateSprites()
(after the code we just added to load the mesh factory):"

[markettwp]

I stand corrected about the file naming used in the tutorial documentation.

The files 'simple.h' and 'simple.cpp' should properly be created by the
user and built from scratch according to the steps in the docs.

This is what is done in the first page of the 'simple' tutorial and I
missed it.

Please ignore the file name changes which I attempted to force in my
previous posts to this list.

Other changes which I noted in my posts, are still valid.