Messages

Your method is simliar to what I suggested. The slight variation I suggested allows you to implement redo as well as undo.

I'm not sure what you mean  by "while the mouse is held down".  Presumably you are dragging tiles into place.  Personally I would make a function that handles the  mouse_up event which would write
an entry into an edit journal.  Then I would have Do and Undo functions that take a journal index as their argument.   So the mouse up handler would write the command to the end of the journal and then execute Do() on that journal entry.

Code: ags

struct journal {
     int Command;  // necessary if there is more than one editor command
     int TileX;
     int TileY;
     int NewTile;
     int OldTile;
}
journal EditJournal[MAX_EDITS_PER_SESSION];

If this graphic ever does become part of the website or anything, and anyone wants the background to be a different color, I can always give the png with Alpha or whatever.

I was thinking about this topic when reading this thread earlier today.  Should there be a resource pak available that contains some of the new cool website icons  in a couple different sizes and varieties?  These would be fore use on members websites to promote their games and/or AGS.  They could also be used as sprites in games themselves, tutorials, etc.         

[Criteria]

"I don't have a dog in this fight.."  as the saying goes but a couple of idea and observations come to mind that may be helpful so I thought I'd share my thoughts.

Criteria
I think there may be some confusion as to what is meant by "criteria".   Is it really necessary to know all the nitty gritty details of how the rating was given?   The problem with revealing this is that the final judgement of the panel is largely subjective so revelation of objective guidelines the panel has made for itself, IMHO, is not very helpful and likely to be counter-productive.   I fully appreciate that using objective criteria helps achieve a measure of consistency between panel members and between games but in the end it comes down to subjective opinion(s).  I think the reluctance the criteria, rightly so,  stems from the realization that the relationships between objective criteria and ratings are necessarily nebulus. 

Perhaps the need for transparency would be better served by a more general description of the process.   Something like the following for example, illustrates the tone and level of detail I am suggesting; the specifics would obviously be different.

The ratings panel is composed of xx members of the Ags community and experienced game developers.  Panel members play each game from beginning to end and note such factors as playability, enjoyability, dialogue, story, graphics, sound, music, etc... to form an opinion.  At the end of an evaluation period the panel members discuss their individual opinions and reach a consensus.    One of the panel members is charged with writing a review consistent with the consensus of the panel.

Review
My first suggestion for the review is that the the cup ratting be clickable and linked to the rating. 

My second suggestion is that the review be written for the benefit of the game author rather than the game players.   How so?  I was a member of Toastmasters, for a number of years, where members learn speaking and leadership skills.  The key ingredient to the success of their program is the way members' practice speeches are critiqued, which I will share with you. 

Someone is assigned to give an evaluation speech immediately after the main speech.   The evaluation is usually structured into three parts consisting of no more than three points each.   The evaluation speech begins by pointing out the best parts of the speech.   Next the evaluator points out what could  be improved.  There is no point in mentioning more than three things because

1) The speaker may become disillusioned/discouraged
2) It's difficult for people to remember more than three things at a time

The evaluation ends on a positive note by mentioning what things the evaluator would like to see more of in the future.   This essentially presents negatives in a positive light (i.e. "half full" rather than "half empty").  This is also an opportunity to encourage the speaker  to continue making speeches and improving.

I think all of this or something similar could be applied to the panel's reviews.   Game authors wouldn't be in the dark about why they got the rating they got.  They would have clear guidance and specific suggestions to improve on their next effort.    Game players would get the same or more benefit from this sort of review as before.

Author Communication
I think the author should be given advance notice of the rating and a copy of the review before publication as a matter of professional courtesy.   It may be a good idea to invite the author to respond if he is so inclined and the panel could take the author's response into account before publication.   It may even be desirable to include the author's response to the end of the review;  this would perhaps keep responses civil and mature.   Anyway a process something like this would cut short any debate or controversy about overly generous or overly harsh panel ratings.

Anonymity
I don't really want to know who the panel members are.  I don't think any benefit comes of it.  The panel ought to create a virtual forum member named MrBlueCup, MisterBlue, BC or some such name so that they can communicate with the community.   If someone has a gripe or a sincere question they could pm  MisterBlue.

[String Extender Function - String.StrToken()]

Do what clarvalon says.  The String Extender function, String.StrToken() shown below allows one to easily read CSV values.  Here is an example of how to use it.  You would of course want to put this example in a while loop that reads each line from the csv file and then executes the tokenizer code.

You could also use StrToken() to copy the CSV file to a binary file and then read the binary file on game startup.   You could then distribute only the binary version of the file with your game.

Code: ags

	struct guy {
		String Name;
		int HP; 
		int Level;
		int Etc;
	}
	guy Guy[100];
	int id;
	String line, buf;

	// Id, name, HP, Level, Etc
	line = "1, Bob, 100, 20, 50";
	id = Line.StrToken(',', true);
	Guy[id].Name = Line.StrToken(',');
	buf = Line.StrToken(',');
	Guy[id].HP = buf.AsInt();
	buf = Line.StrToken(',');
	Guy[id].Level = buf.AsInt();
	buf = Line.StrToken(',');
	Guy[id].Etc = buf.AsInt();

String Extender Function - String.StrToken()

Code: ags

*** Script Header ***
import String StrToken(this String*, char c, bool reset=0) 

*** Global Script ***
//================================================================== 
	String 	TokenString;
	int 		TokenIx=0;
//
	String StrToken(this String*, char c, bool reset) {
//
// Emulates operation of standard C language strtok() function. When
// this function is first called, for a given string value, it 
// returns the first occurance of the specified separator character.  
// Subsequent calls return the next occurance of the specified token 
// character.
//
// The parameter C specifies the token seperator character to use 
// for this call.  A different character may be specified eaxch time 
// this function is called.
//
// The optional reset parameter fporces the tokenization process to 
// start over from the begining of the lione.
//
//    Example:
//
//    String Line;
//    Line = "Goodbye, cruel world. Farewell!");
//    Display(Line.StrToken(' ',true);
//    Display(Line.StrToken(',');
//    Display(Line.StrToken('!');
//    Display(Line.StrToken(',',true);
//
//    Displays the following ...
//    Goodbye,
//    cruel world
//    Farewell
//    Goodbye
//-------------------------------------------------------------------
	int 		i, j, t;
	String 	token;

	// Initialize tokenizer 
	if ((TokenString==null)||(TokenString!=this)||(reset)) {
		if (this!=null) TokenString = this;
		else TokenString = "";
		TokenIx = 0;
	}
	// Check for end of string
	if (TokenIx<this.Length) {
		
		// Skip leading whitespace
		token = "";
		i = TokenIx;
		while ((i<this.Length)&&(this.Chars[i]<=' ')) i++;
		j = i;	// Save token beginning
	
		// Get token end
		while ((i<this.Length)&&(this.Chars[i]!=c)) i++;
	
		// Save token index for next time
		TokenIx = i+1;

		// Extract token from string
		token = this.Substring(j, i-j); 
	}
	else {
		// Token index, TokenIx, is greater than the length so ...
		// since there are no more tokens return an empty string
		token = "";
	}
	return token;
}

As you correctly surmise it's not possible to have objects or characters on/in a GUI.   

1.  Use buttons instead of objects.  You can play with the Button.NormalGraphic and
Button.Visible properties to get the effect your desire.

2.  Ypu can incorporate the dialog into your phone GUI.  Have a look at "Dialog options, custom rendering" in the manual.

A salary of $150,000 for a network engineer with 2 years experience is not a credible statistic.  The figure  of $24k to $72k is more realistic.    It sounds like they are selling an $850 Cisco class.   My wife took the cisco router class at the community college.  It was an automated self study course that ran on a PC.   The information is presented and then you are asked perform related task via a simulator that is part of the course.   Periodically the class was given an examination which was monitored by the teacher.  After completing the course the students could then take the certification test.

Here is Cisco information about their certifications.
http://www.cisco.com/web/learning/le3/le2/le0/le9/learning_certification_type_home.html

In addition to community college there are various places that provide training and certification testing.  I have the opinion they are hyping the placement aspect to sell the training course.   The price of the training sounds a little steep to me.

You can  check out network engineering jo0b/salaries at http://dice.com, http://craigslist.com and other employment websites.   

Those functions in the tutorial are connected to the buttons through and are commonly referred to as "event handlers".   The lightning bolt button mentioned by bicilotti provides a means for you to define events to which you would like to connect connect a function.  When these events occur in game the functions to which they are connected are executed.  So you will have to use the lioghtning bolt to create an event for each button the same as you have done on the first one which you say is now working.

Tip: Global Script Organisation
There are no special locations within the global script or any other script.   However, the AGS compiler is of a single pass design.  Because of this variables and functions must be closer to the top of the script than (i.e. defined before) any function that may use them.   So deciding the order of things  within the global script (or any script)  is then dictated by what uses what.   

This can get very confusing rather quickly as the script grows.  So it is important to keep your scripts organized.  Functions can be grouped into categories so that functions in one category do not call each other.  In this way each category or group of functions can be ordered in a way that makes it easy to find and maintain them. 

Since your button event handlers are meant to be called by the engine and not by other functions they can be grouped together and located near the bottom of the script.  This way the button event handlers are able to call other functions you may have defined in the global script.

"I refuse to join any club forum that would have me as a member."  - Groucho Marx

I'm currently working on a module that extracts documentation from the source files and produces a document such as this. 

http://demo.agspace.ws/project/modules/Modox/Modox.html

The format of the document is determined by a template file.  So it ought to be possible make a template file that would produce  a document in  wiki format.   Of course documentation doesn't exist without effort; the module only extracts content that the module author has taken time to create.  The advantage is that the content resides in the same file and location in the file where the code it describes resides, making it easy for the author to create and maintain.

An alternate solution would be to have an official module repository where accepted modules would meet  minimum criteria such as documentation of required ags version and other required modules.   This could include an online HTML document similar to the above example and a means of adding supplementary information from users, sort of like the games page.    Perhaps the commentary could have a couple of categories such as Reviews, Tips and Tricks, Bug Reports, etc

Note: for those who are not module designers, the module Programming Guidelines describe a scheme for using  macros to test for correct AGS Version and module dependencies.   It is assumed that modules  built with a specific ags version will function correctly on later versions but not earlier ones.

I think having an organised module library is a good idea regradles of the form it may take.   

What you are asking is very possible.  The MiniGame module for example allows information to be passed to and fromm the caller.  This information could be used during start up to make the mini game immediately exit or to perform some other task when started directly from the command line and to exhibit a completely different behavior when started from the main game.

Here are links to the mini-game module ...
http://demo.agspace.ws/project/archive/MiniGame-T0100.zip

and the DemoQuest GIP thread
http://www.adventuregamestudio.co.uk/yabb/index.php?topic=34048.0

Merry Christmas
Rick

Since my  last update I've uncovered and corrected a number of bugs that surfaced when imperfect content model was specified.  Anyway that's why I am delayed getting out the next version.   However, the good news is that I've implemented some features that allow the "See Also" and notes sections to be generated without hand coding.

The first thing to note is that in the template file commands and variable substitutions have been separated and now each have a different form.  This, I believe, is a bit clearer and easier to explain and it also makes the underlying implementation less complicated.

Code: ags

// Variable have the same form as before.  For example the string  #{SomeVariable} is 
// replaced with the value of SomeVariable.
//
// Commands start with a # symbol, kid of like macros in an include file.  They can have 
// a number of arguments and span multiple lines using the curly braces  to delimit their extent.
// The for-each command for example has the following form

#for-each {
     // Basic content model 
     item-type {
          <tag>#{VariableName}</tag> 
     }

     // Model that iterates over each of the item's lines
     item-type-Begin {
          <tag>
     }
     item-type-Lines {
          <tag>#{Line}</tag> 
     }
     item-type-End {
          </tag>
     }

     // Model that iterates over each of the item's lines
     item-type-Begin {
          <tag>
     }
     item-type-Lines {
          <tag>#{Line}</tag> 
     }
     item-type-End {
          </tag>
     }
}

The two features that make "See Also" possible are Word Iterators and Custom Item Types.  
A custom item type can be created by beginning a paragraph with a set of square brackets enclosing the name of the custom item type.

Code: ags

This is normal paragraph text blah, blah, bla bla bla blaaaah.
This is more of the same.   This item will be of type eModox_Paragraph 
having a text value of "Paragraph" which can be accessed in the template file 
using the variable #{Type}.

[See Also] This is also paragraph text but it has an item type of eModox_Custom 
and it has a text value of  "SeeAlso" (note spaces are removed) which is also accessed in the template file via #{Type}.

Now that we have an item type specific to the "See Also" sections we can construct a content model to render the text and html tags in the proper form.   But to do this we need to have a variable for each word so "Words" iterator was added to accommodate this need and the resyulting content model looks like the following.

Code: ags

// Commands start with a # symbol, kid of like macros in an include file.  They can have 
// a number of arguments and span multiple lines using the curly braces  to delimit their extent.
// The for-each command for example has the following form

#for-each {
     // Model that iterates over each word in the item
     // implements "See Also" feature
     SeeAlso-Begin {
          <p class="#{Type}">#{Name}:  
     }
     SeeAlso-Words {
          <a href="##{Word}" class="#{Type}">#{Word}</a>,
     }
     SeeAlso-End {
          </p>
     }
}

The "Note:" and other similar section formatting can be achieved using either custom item types or the pre-format class feature mentioned in the previous post.  I used the pre-format class feature to implement the example box in my demo document.

The other thing that has changed is that each software entity has it's own item type an so it's render format is under complete control of the template file.  This means that header level and other formatting can be applied depending upon what type of thing it is.;  For example, the navigation scheme in monkey's document (i.e CountDown module) can be easily implemented by making the appropriate template file.

Before I release this version I plan to add a couple more features which should not be very difficult to implement and will hopefully eliminate most of the remaining needs you have (i.e monkey) to hand edit the output file.   This will also give me a little more testing time as well.

Those two features are FullNames for functions, properties and methods and HTML Passthrough.
Previously I had formed the names of methods and properties by pre-pending the object name and a dot as monkey has done in his document.  Somewhere along the line I saw other documentation that didn't do that and I talked myself out of it.   Now after having seen what monkey has done and having thought through the "See Also" feature it is clear that using the current short names  (i.e. names without the object name) to create links will be problematic.   What's needed is a second name variable #{FullName} for each item and that is accessible from the template file.

The second thing to do is to be sure that raw HTML/XML tags appearing in the source document are passed through to the output.  I believe that this is mostly the case at the moment except if the tag is found at the beginning of a line.  So this just needs to be reviewed and minor adjustments made to accommodate this.

Anyway monkey if you can think of anything else that needs to be in here or any other kinds of things requiring hand editing please let me know.  

[edit]
Monkey, I was just thinking about the horizontal alignment issue you mention.   I don't think it's that terribly difficult to preserve the horizontal spacing but I am concerned about that having undesirable affects on the rendering of plain text and possibly other formats.   After I get the next version out I plan to start on adding the things needed to render to plain text.  Things like commands to set page size and margins, function to do line wrap and fill, page breaks and numbering etc.  I'd like the opportunity to consider what to do about horizontal spacing  at that time since I'll have a better idea of what is needed for plain text.

However, in the meantime I just had a bit of a brain storm I'dl ike to share and get your input.  I was thinking "What if the horizontal spacing of the output could be specified in the template file separate from the horizontal spacing of the template file itself?   This would address my concern,  I think it would also meet your needs as well, and would probably be a piece of cake to implement.  Confused yet?  Here's an example of what I am talking about:

Code: ags

#for-each {
     // Make level-1 sectionz one all the way to the left margin
     Section.1 {
          <h1>#{Name}</h1>
     }
     // Make level-2 sections indented 5 spaces 
     Section.2 {
          .....<h2>#{Name}</h2>
     }
     // Make paragraph tags indented 10 spaces 
     // Make paragraph text indented 15 spaces 
     paragraph {
          ..........<p>
          ...............#{Lines}
          ..........</p>
     }
     // In the above examples the leading dot characters 
     // will be replaced in the output file by space characters.
}

This would allow the template file to be indented in whatever way is needed to make sense of the template file, independently from the indentation desired in the output file.   Anyway it's just something that came to me a few minutes ago and I haven't had time do digest it yet.  Please feel free to opine...

[Note:]

I had a look at your new module's documentation and it looks really nice.    I appreciate the effort you are making as it makes me feel like my effort is worthwhile.   I have completed the scripting of the next version and I am currently updating and testing the template and CSS files.  So I should have the new version out later tonight or early tomorrow, depnding on how sleepy I get.

I've addressed the following issues you pointed out :

- writeprotected properties, 
These are now included in the document

- property comments
Comments following property declarations are now included in the document

- version parsing
It is now more sophisticated and flexible. It supplies formatting for 3..N character interger version numbers and version numbers containing a decimal point.  If another format is used it just passes it through unchanged. 

I'll let you know when I have the new version uploaded.  In the meantime here are some things I noticed in your document and some things to think about...

Note:
I'm not sure if you are aware of this feature but if you made your "Note:" sections as preformatted text the resulting html tag would be given a class of "Note" allowing you to style it as you please.

Code: ags

<pre class="Note">
Your note text .....
</pre>

Table Of Contents and Other Content Formatting
You will be happy to know that you will be able to accomplish what you have done  by just changing the template.   You will have full control over the header level of functions, methods, properties, etc from within the template file.

See Also:
I noticed and like you "see also" feature.  I'll think on how to do this without manually editing the HTML.

Horizontal Spacing/Format
I'm still thinking on this and have decided to defer action until I begin rendering to plain text.  I think some related issues will arise and so I would like to address this issue at that time.   A concern I have is that on the one hand it may be desirable to use indentation to make the template file easier to read and maintain but it may not be desirable to have that same indentation show up in the output file.   This will be a bit more clear when you see what the new template file looks like.

That's all for now.  Need to get back to work and get the next version out...

Thanks for the feedback. 

You're very much welcome and I'm glad to hear that the HTML tags are now exclusively contained in the template file. Does this mean that the template formatting can be preserved too? ...

No and yes!      I am using the same function to read lines out of both the template and source files.  The parser needs to ignore leading white space so the line reading routine does this first thing.   This is also true for some aspects of interpreting the template file.  I'll see what I can do about preserving the horizontal formatting of the template file.

CHM Help ...

...  I think it has to explicitly be passed through the CHM compiler to generate a valid CHM file.

There is a set of, I believe three files, that is passed through the CHM compiler which is freely available from M$.  The idea would be to first render the source files and then pass the result through the CHM compiler to get get the final chm.

writeprotected int WriteProtectedData; // this can be publicly read, but can only be set privately

Thanks.  Leaving this out was an oversight on my part.  I'll get it fixed for the next version.

If I remove the line "  // blargh:" then the description does not show up at all.

I am certain I had this working correctly at one point in time.  I must have generated a bug along the way somewhere.   I'll get it fixed for the next version.

Re: versions
...I don't recall the guidelines saying that the version number should be padded out to exactly 4 digits. In fact, it shows three digits. ...

The parsing of the version number can certainly be made more flexible.  For the next version I plan to allow the version number to be of variable length (min of 3 chars) with the last two chars being the minor version.   What other variations should I attempt to accommodate?   

What should I presumably be putting then between these so that there will be a distinction between the struct's members, the instance, and the global function instead of them all just being on the same header level with nothing separating them?

You could just add a comment line with a level-1 section title as shown in the example below.  You could also, of course, add additional paragraph text and other content as part of the section.

Code: ags

struct StructName {
  int IntProperty; // documentation lines and such removed for simplicity sake :P, this is all just pseudo code anyway
  String StringProperty;
  // etc.
};

// 0 StructName Instances
import StructName StructMember;
import function FunctionName();

[h1]StructName[/h1]
[h2]Struct properties...[/h2]
[h2]...[/h2]
[h2]...[/h2]
[h1]StructName Instances[/h1]
[h2]Global instance of struct[/h2]
[h2]Global function[/h2]

[Html Tags]

Monkey, thanks for the great feedback.  I am putting the finishing touches on a re-factored renderer. I have to do some code clean-up and update the html template file so that the same document will be produced as before.  The new renderer doesn't know or care what is being rendered.  All HTML tags are now contained in the template file.  

Html TagsIn it's new incarnation text files are supported the same as html.  It should also be possible to create template files that will produce

All tags and other markup are now specified in the template file and are no longer part of the Modox script.

Plain Text Output
Plain text files can now be rendered, however,  support for page break, margins,  and
line fill, line justify, wrap, etc needs to be added

Multiple Output FilesThe output file is now specified inside the template file.  The file name may be constructed using variable substitution so it's possible to use things like module name and version to construct the file name.  It's also now possible to produce multiple output files from one template.

CHM Help
It ought to be possible to render the required file set to create CHM help files.  If anyone has experience with this I could use some help or advice in this area.

I am also planning a review of the parser so your feedback comes at an opportune time.  Let me respond briefly to each point you raise.

I've just noticed that when the functions are being extracted the documentation includes the "import" keyword.

Perhaps so.  I just picked up whatever was on the line and only excluded the punctuation characters  ";" and "{" at the end of the line(s).  I can exclude the import statements if thats the consensus of how it ought to be.  I don't really have a preference one way or the other, just what is best way for the most people.

-writeprotected members are ignored entirely. The module currently does not detect these properties at all, though since they are public they should be documented.

I was wondering about that and you know I didn't have any examples and wasn't certain public properties could be write protected.  What is the proper form anyway/

Code: ags

     protected int SomeVariable;

-Member descriptions are omitted. I was able to work around this by adding on a line by itself something such as "// blarg:" at the start of each property description.  

The parser is expecting the description to follow the declaration.   The  declaration  statements
serve as both definition of a software entity and a section title for the document.  The following ought to be picked up by the parser, if not then there is a bug.  Also note that in the case of object methods, global functions and global variables content will also be picked up from the script file and will also be included.

Code: ags

     int SomeVariable;
     // This variable is used for this that and the other thing.
     //  The description of the variable follows the declaration so
     // so these lines are the description of SomeVariable. 

-Pointer members...are strange. I found that if you declare your pointers such as Type* Name (with the asterisk attached to the type) that the member is ignored entirely, yet if you declare it as Type *Name or even Type * Name then the asterisk is considered part of the property name!

Ahhh ok!  I understand what's going on here.  I keep a list of all the built-in AGS types and add to that list each of the user defined types as they are defined.  So when the parser sees something like "int",  "Monkeys_Object", etc it knows that this line needs further analysis.  This should be fixed in the next version.

-Version macros required odd formatting. It seems that in order to get the version macros to detect properly they must be padded to 4 spaces. This is far from desirable for me. As a matter of fact, I would like to be able to provide the VERSION macro as a float.

I got this straight out of the module guidelines.  Perhaps I am a bit out of date or this is a bit too strict.   post some examples and I'll see what I can do about getting them be recognised.

-No distinction between global and struct functions? I thought this was already implemented, yet when I run my module through yours the output does not reflect this. The struct name is reflected, its members listed, and then a global instance of that struct, as well as a global function are listed, but with nothing indicating they are not part of the struct. Actually as a matter of fact I would like to be able to avoid referencing the struct name altogether and only mention the instance because that is the user access interface.

Is it the case that the global instance import statements follow the struct definition?   If so what you are saying is that since the methods inside the struct and the global functions both have the same header level there doesn't appear to be a distinction between them when they are rendered into a document?  Have I understood this correctly?  

Internally the parser knows that the struct definition has ended and it categorises the imported global instance as a global function.   I'm not sure what ought to be done here.   Functions, variables, and constants are setup as header level 2 entities.  This presumes they are proceeded by a header level 1 document section.  In the case of methods and properties the struct definition serves this purpose.   There are currently a couple of options and a few more with the new renderer.

Simple Solution
The simplest thing to do is either create a header level 1 section just before the global instance import statement or move it so that it follows an appropriate level 1 section.

Alternative Solution
The new renderer allows specific types of content to be rendered (or not rendered) as the case may be.  So for example, in HTML form, the struct and it's properties and methods could be rendered with html id attribute id="MyStructName"  and then the styling could be adjusted to make anything with that id be invisible.  The template could also be designed to change the grouping of different kinds of items or not render them at all

Maybe we can talk about this more when I get the next version out, since it may already have the required solution implemented.  

Most words in the title of a book or movie are capitalised except words like a, the.  What is the proper way to make this determination?  I'm embarrassed to admit that I have been guessing at it all these years without knowing for sure.

Perhaps if someone compiles a more or less complete list of exceptions I will make a string extender function, String.Titlize(),  that converts a string to a properly capitalised title.

This is really keen looking. It's awesome that you came up with the idea/way to do this and the HTML/CSS looks very professional and nice. I'd definitely like to give it a shot myself as well.

monkey, thanks for your kind words.  TerranRich got  me started with CSS and I am grateful for his help.

Oh and regarding the idea of exporting plain-text docs instead of HTML...could that be done using simply a plain-text non-HTML template? Or does the parsing of the template expect valid HTML?

That's pretty much what I am aiming for.  The rendering process doesn't really care what's in the template file except for the #{...} things.  You can think of the things inside the braces as a command or function with optoinal arguments.  The  command, arguments, and the braces are replaced by whatever text the command produces.  It could be a short string or multiple lines of text. 

   #{command arg1 arg2 ... agr9}

In it's simplest form the #{} just contains a variable name, in which case it is simple replaced by the value of the variable.

I am currently working on an upgraded version of the renderer  where #{HtmlContent} and #{HtmlToc} will be deprecated in favor of a more general purpose ability to define a content model in the template file.   It will have a form similar to this:

Code: ags

#{ForEach

   Section {
      <h#{Level}>#{Name}</h#{Level}>
      <p class="definition">#{Definituion}</p>
   }

   Paragraph {
     <p>
     #{Lines}
    </p>
   }

   :
}

The ForEach command makes it iterate over each item that has been extracted from beginning of document to end.  For each item the render will search for a content model that matches the item type which it uses to render the output.  If it doesn't find a content model for that type of item then it moves on toi the next one.  So for example if you wanted to make an index you would just provide a content model for sections. 

Anyway doing it this way I will be able to render to a wider variety of different formats just by providing a different template file.   Anyway I'm about half way into the version of the renderer.  I am currently putting things all back together after having broken the whole thing.   Not to worry I have an archive of the previous version.

I'll be back when I have a new version..

My thoughts on this are a bit different than those of most folks... Anyway, here is my 10 cents worth...

1.  Scaled up characters look worse than scaled down characters (i.e using walkable area scaling).

2. Start with the smallest room your game would typically have.  Usually this would be something like a 12ft x 12ft bedroom.   

3.  Pick a plane  that is about 10-20% into the depth of the background image.   

4.  Measure the pixel distance from floor to ceiling at that point.   For example in a 320x240 image
the pixel distance at our reference plane may be 192 pixels.

5.  Now estimate the actual distance in feet from floor to ceiling  that is being depicted.  For example bedrooms in most houses  these days have 8ft ceilings.  So if this is the case then we could calculate a pixel scaling by calculating 192px/8ft which comes out to a scaling of 24px/ft  or 2px/in.

6.  Using this scaling you can now determine how large to make your character sprites.  A six ft tall character would be 144px tall and a5ft tall character would be 120px tall.

7.  In larger rooms you can then scale the characters down using walkable area scaling.  Sprites of course loose detail when they are scaled down but it doesn't much matter if AGS scales them down or if they are just drawn smaller - smaller size means less detail. 

8.. You can of course choose any reference plane you desire.  For example if many or most of the rooms in your game are of similar size then it may be better to choose the most common sized room rather than the smallest room to determine pixel scaling of characters.

9.  You could also use the same pixel scaling to make object sprites.  Allow them to be scaled along with the character and they will be sized appropriately.
create your characters

it's possible calculate the pixel scaling

  start out by deciding on a scaling factor for the characters.   

Hi abstauber,

If your going to give it a try here is the demo project.  It's hosted in my little sandbox app called BluBox.  BluBox and the Gui support module Widget are also under heavy development at the moment so be aware there are a number of things hanging in an incomplete state.   However, you are welcome to use BluBox in it's current state if you find it useful.  Anyway here is the link:

http://demo.agspace.ws/project/archive/WidgetModule-S0001-000.zip

I would be interested to see what your current doc style looks like.  If you have a convenient example send me a link to it and I'll take a look.

This module provides functions that extract comments and code elements from an Ags Script Module's source files and renders an APIi document in one of several formats such as HTML or plain text. The module's script and header files are prepared following a few simple conventions that are easy to remember and apply. The result is natural, attractive, and professional looking source code that can automatically be converted to an API document.

The module is in a pre-alpha state at the moment.  It's basic functions are complete but lacks some critical features such as a user interface, file handling/selection abilities, and currently only renders to an HTML document.  

Here are the module's source files:
    http://demo.agspace.ws/project/modules/Modox/Modox.asc
    http://demo.agspace.ws/project/modules/Modox/Modox.ash

Here are the template files that were used to generate the document:
    http://demo.agspace.ws/project/modules/Modox/ModoxHtml-V0000.html
    http://demo.agspace.ws/project/modules/Modox/ModoxHtml-V0000.css

Here is the html document the module generated from it's own source files:
    http://demo.agspace.ws/project/modules/Modox/Modox.html

Please let me know if anyone has any interest in using this or feedback about the appearance of the output  document.  I am particularly interested to know if the HTML is sufficiently flexible to allow for future and more sophisticated CSS styling to be applied.

The html document renders perfectly in Firefox 3.5.  I am fairly new to CSS and from what I have read there are or have been a number of non-compliant browsers and versions of browsers. So not being an expert I can't guarantee how my CSS styling will look in other browsers. but I am willing to suggestions and feedback.  

Again this is a work in progress and it is not nearly finished.  I am posting at this early stage so that any input people wish to make can receive due consideration. Cheers
Rick

[edit]
Here is a demo project for anyone who would like to try it out.  Click the Read button to read a module doc into memory.  Click the render button to generate the document.   The name of the module can be change by editing the button handler near the end of the Room-3 script file.  Currently the module.asc and module.ash files need to be in the main game directory for this to work.

http://demo.agspace.ws/project/archive/WidgetModule-S0001-000.zip