Cleanup. (Mostly of the comments.)

svn-id: r13579

5 files changed, 247 insertions, 338 deletions

diff --git a/sword2/console.h b/sword2/console.h
index f25645dd49..d445b977f5 100644
--- a/sword2/console.h
+++ b/sword2/console.h
@@ -44,7 +44,7 @@ private:
 
 	int32 _showVar[MAX_SHOWVARS];
 
-	uint8 _debugTextBlocks[MAX_DEBUG_TEXT_BLOCKS];
+	uint8 _debugTextBlocks[MAX_DEBUG_TEXTS];
 
 	void clearDebugTextBlocks(void);
 	void makeDebugTextBlock(char *text, int16 x, int16 y);
diff --git a/sword2/debug.cpp b/sword2/debug.cpp
index 85a463932a..8d9bb1d8b2 100644
--- a/sword2/debug.cpp
+++ b/sword2/debug.cpp
@@ -31,7 +31,7 @@ namespace Sword2 {
 void Debugger::clearDebugTextBlocks(void) {
 	uint8 blockNo = 0;
 
-	while (blockNo < MAX_DEBUG_TEXT_BLOCKS && _debugTextBlocks[blockNo] > 0) {
+	while (blockNo < MAX_DEBUG_TEXTS && _debugTextBlocks[blockNo] > 0) {
 		// kill the system text block
 		_vm->_fontRenderer->killTextBloc(_debugTextBlocks[blockNo]);
 
@@ -45,10 +45,10 @@ void Debugger::clearDebugTextBlocks(void) {
 void Debugger::makeDebugTextBlock(char *text, int16 x, int16 y) {
 	uint8 blockNo = 0;
 
-	while (blockNo < MAX_DEBUG_TEXT_BLOCKS && _debugTextBlocks[blockNo] > 0)
+	while (blockNo < MAX_DEBUG_TEXTS && _debugTextBlocks[blockNo] > 0)
 		blockNo++;
 
-	assert(blockNo < MAX_DEBUG_TEXT_BLOCKS);
+	assert(blockNo < MAX_DEBUG_TEXTS);
 
 	_debugTextBlocks[blockNo] = _vm->_fontRenderer->buildNewBloc((uint8 *) text, x, y, 640 - x, 0, RDSPR_DISPLAYALIGN, CONSOLE_FONT_ID, NO_JUSTIFICATION);
 }
diff --git a/sword2/debug.h b/sword2/debug.h
index e29a002ff0..644450f75c 100644
--- a/sword2/debug.h
+++ b/sword2/debug.h
@@ -21,7 +21,7 @@
 #define D_DEBUG
 
 // FIXME: I don't know how large this constant used to be
-#define MAX_DEBUG_TEXT_BLOCKS 50
+#define MAX_DEBUG_TEXTS 50
 
 #define MAX_SHOWVARS 15
 
diff --git a/sword2/maketext.cpp b/sword2/maketext.cpp
index bc528bba28..7d90f9ba3e 100644
--- a/sword2/maketext.cpp
+++ b/sword2/maketext.cpp
@@ -35,141 +35,138 @@
 //		  for new system by JEL on 9oct96 and updated again (for font
 //		  as a resource) on 5dec96.
 
+#include "common/stdafx.h"
+#include "sword2/sword2.h"
+#include "sword2/defs.h"
+#include "sword2/logic.h"
+#include "sword2/maketext.h"
+#include "sword2/resman.h"
+#include "sword2/driver/d_draw.h"
+
+namespace Sword2 {
+
 #define MAX_LINES	30	// max character lines in output sprite
 
 #define BORDER_COL	200	// source colour for character border (only
 				// needed for remapping colours)
 #define LETTER_COL	193	// source colour for bulk of character ( " )
-#define NO_COL		0	// sprite background - 0 for transparency!
 #define SPACE		' '
 #define FIRST_CHAR	SPACE	// first character in character set
 #define LAST_CHAR	255	// last character in character set
 #define DUD		64	// the first "chequered flag" (dud) symbol in
 				// our character set is in the '@' position
-#include "common/stdafx.h"
-#include "sword2/sword2.h"
-#include "sword2/defs.h"
-#include "sword2/logic.h"
-#include "sword2/maketext.h"
-#include "sword2/resman.h"
-#include "sword2/driver/d_draw.h"
 
-namespace Sword2 {
-
-// info for each line of words in the output text sprite
+/**
+ * This function creates a new text sprite in a movable memory block. It must
+ * be locked before use, i.e. lock, draw sprite, unlock/free. The sprite data
+ * contains a FrameHeader, but not a standard file header.
+ *
+ * @param  sentence  pointer to a null-terminated string
+ * @param  maxWidth  the maximum allowed text sprite width in pixels
+ * @param  pen       the text colour, or zero to use the source colours
+ * @param  fontRes   the font resource id
+ * @param  border    the border colour; black by default
+ * @return a handle to a floating memory block containing the text sprite
+ * @note   The sentence must contain no leading, trailing or extra spaces.
+ *         Out-of-range characters in the string are replaced by a special
+ *         error-signal character (chequered flag)
+ */
 
 Memory *FontRenderer::makeTextSprite(uint8 *sentence, uint16 maxWidth, uint8 pen, uint32 fontRes, uint8 border) {
-	Memory *line;		// handle for the memory block which will
-				// contain the array of lineInfo structures
-	Memory *textSprite;	// handle for the block to contain the text
-				// sprite itself
-	uint16 noOfLines;	// no of lines of text required to fit within
-				// a sprite of width 'maxWidth' pixels
-
-	debug(5, "makeTextSprite(\"%s\", maxWidth=%u)", sentence, maxWidth);
+	debug(3, "makeTextSprite(\"%s\", maxWidth=%u)", sentence, maxWidth);
 
 	_borderPen = border;
 
-	// NB. ensure sentence contains no leading/tailing/extra spaces - if
-	// necessary, copy to another array first, missing the extra spaces.
-
-	// set the global layout variables
+	// Line- and character spacing are hard-wired, rather than being part
+	// of the resource.
 
 	if (fontRes == _vm->_speechFontId) {
-		_lineSpacing = -6;  // overlap lines by 6 pixels
-		_charSpacing = -3;  // overlap characters by 3 pixels
+		_lineSpacing = -6;
+		_charSpacing = -3;
 	} else if (fontRes == CONSOLE_FONT_ID) {
-		_lineSpacing = 0;   // no space or overlap between lines
-		_charSpacing = 1;   // 1 pixel spacing between each character
+		_lineSpacing = 0;
+		_charSpacing = 1;
 	} else {
 		_lineSpacing = 0;
 		_charSpacing = 0;
 	}
 
-	// allocate memory for array of lineInfo structures
+	// Allocate memory for array of lineInfo structures
 
-	line = _vm->_memory->allocMemory(MAX_LINES * sizeof(LineInfo), MEM_locked, (uint32) UID_temp);
+	Memory *line = _vm->_memory->allocMemory(MAX_LINES * sizeof(LineInfo), MEM_locked, UID_temp);
 
-	// get details of sentence breakdown into array of LineInfo structures
-	// and get the no of lines involved
+	// Get details of sentence breakdown into array of LineInfo structures
+	// and get the number of lines involved
 
-	noOfLines = analyseSentence(sentence, maxWidth, fontRes, (LineInfo *) line->ad);
+	uint16 noOfLines = analyseSentence(sentence, maxWidth, fontRes, (LineInfo *) line->ad);
 
-	// construct the sprite based on the info gathered - returns floating
+	// Construct the sprite based on the info gathered - returns floating
 	// mem block
 
-	textSprite = buildTextSprite(sentence, fontRes, pen, (LineInfo *) line->ad, noOfLines);
+	Memory *textSprite = buildTextSprite(sentence, fontRes, pen, (LineInfo *) line->ad, noOfLines);
 
-	// free up the lineInfo array now
 	_vm->_memory->freeMemory(line);
-
 	return textSprite;
 }
 
 uint16 FontRenderer::analyseSentence(uint8 *sentence, uint16 maxWidth, uint32 fontRes, LineInfo *line) {
-	uint16 pos = 0, wordWidth, wordLength, spaceNeeded;
-	uint16 lineNo = 0;
-	uint8 ch;
-	bool firstWord = true;
-
 	// joinWidth = how much extra space is needed to append a word to a
 	// line. NB. SPACE requires TWICE the '_charSpacing' to join a word
 	// to line
 
 	uint16 joinWidth = charWidth(SPACE, fontRes) + 2 * _charSpacing;
-	
-	// while not reached the NULL terminator
+
+	uint16 lineNo = 0;
+	uint16 pos = 0;
+	bool firstWord = true;
+
+	uint8 ch;
 
 	do {
-		// new word
-		wordWidth = 0;
-		wordLength = 0;
+		uint16 wordWidth = 0;
+		uint16 wordLength = 0;
 
-		// get first char of word (at position 'pos')
-		ch = sentence[pos++];
+		// Calculate the width of the word.
 
-		// while not SPACE or NULL terminator
+		ch = sentence[pos++];
 
-		while ((ch != SPACE) && ch) {
+		while (ch && ch != SPACE) {
 			wordWidth += charWidth(ch, fontRes) + _charSpacing;
 			wordLength++;
 			ch = sentence[pos++];
 		}
 
-		// no _charSpacing after final letter of word!
+		// Don't include any character spacing at the end of the word.
 		wordWidth -= _charSpacing;
 
 		// 'ch' is now the SPACE or NULL following the word
 		// 'pos' indexes to the position following 'ch'
 
 		if (firstWord) {
-			// first word on first line, so no separating SPACE
-			// needed
+			// This is the first word on the line, so no separating
+			// space is needed.
 
 			line[0].width = wordWidth;
 			line[0].length = wordLength;
 			firstWord = false;
 		} else {
-			// see how much extra space this word will need to
+			// See how much extra space this word will need to
 			// fit on current line (with a separating space
 			// character - also overlapped)
 
-			spaceNeeded = joinWidth + wordWidth;
+			uint16 spaceNeeded = joinWidth + wordWidth;
 
 			if (line[lineNo].width + spaceNeeded <= maxWidth) {
-				// fits this line
+				// The word fits on this line.
 				line[lineNo].width += spaceNeeded;
-				// NB. space+word characters
-				line[lineNo].length += 1 + wordLength;
+				line[lineNo].length += (1 + wordLength);
 			} else {
-				// put word (without separating SPACE) at
-				// start of next line
+				// The word spills over to the next line, i.e.
+				// no separating space.
 
-				// for next LineInfo structure in the array
 				lineNo++;
 
-				// exception if lineNo >= MAX_LINES
-				// debug_only( lineNo < MAX_LINES );
+				assert(lineNo < MAX_LINES);
 
 				line[lineNo].width = wordWidth;
 				line[lineNo].length = wordLength;
@@ -177,268 +174,235 @@ uint16 FontRenderer::analyseSentence(uint8 *sentence, uint16 maxWidth, uint32 fo
 		}
 	} while (ch);
 
-	// return no of lines
 	return lineNo + 1;
 }
 
-// Returns a handle to a floating memory block containing a text sprite, given
-// a pointer to a null-terminated string, pointer to required character set,
-// required text pen colour (or zero to use source colours), pointer to the
-// array of linInfo structures created by 'analyseSentence()', and the number
-// of lines (ie. no. of elements in the 'line' array).
-
-// PC Version of BuildTextSprite
+/**
+ * This function creates a new text sprite in a movable memory block. It must
+ * be locked before use, i.e. lock, draw sprite, unlock/free. The sprite data
+ * contains a FrameHeader, but not a standard file header.
+ *
+ * @param  sentence  pointer to a null-terminated string
+ * @param  fontRes   the font resource id
+ * @param  pen       the text colour, or zero to use the source colours
+ * @param  line      array of LineInfo structures, created by analyseSentence()
+ * @param  noOfLines the number of lines, i.e. the number of elements in 'line'
+ * @return a handle to a floating memory block containing the text sprite
+ * @note   The sentence must contain no leading, trailing or extra spaces.
+ *         Out-of-range characters in the string are replaced by a special
+ *         error-signal character (chequered flag)
+ */
 
 Memory *FontRenderer::buildTextSprite(uint8 *sentence, uint32 fontRes, uint8 pen, LineInfo *line, uint16 noOfLines) {
-	uint8 *linePtr, *spritePtr;
-	uint16 lineNo, pos = 0, posInLine, spriteWidth = 0, spriteHeight;
-	uint16 sizeOfSprite;
-	uint16 char_height = charHeight(fontRes);
-	FrameHeader *frameHeadPtr, *charPtr;
-	Memory *textSprite;
-	uint8 *charSet;
+	uint16 i;
+
+	// Find the width of the widest line in the output text
 
-	// spriteWidth = width of widest line of output text
+	uint16 spriteWidth = 0;
 
-	for (lineNo = 0; lineNo < noOfLines; lineNo++)
-		if (line[lineNo].width > spriteWidth)
-			spriteWidth = line[lineNo].width;
+	for (i = 0; i < noOfLines; i++)
+		if (line[i].width > spriteWidth)
+			spriteWidth = line[i].width;
 
-	// spriteHeight = tot height of char lines + tot height of separating
-	// lines
+	// Find the total height of the text sprite: the total height of the
+	// text lines, plus the total height of the spacing between them.
 
-	spriteHeight = char_height * noOfLines + _lineSpacing * (noOfLines - 1);
+	uint16 char_height = charHeight(fontRes);
+	uint16 spriteHeight = char_height * noOfLines + _lineSpacing * (noOfLines - 1);
 
-	// total size (no of pixels)
-	sizeOfSprite = spriteWidth * spriteHeight;
+	// Allocate memory for the text sprite
 
-	// allocate memory for sprite, and lock it ready for use
-	// NB. 'textSprite' is the given pointer to the handle to be used
-	textSprite = _vm->_memory->allocMemory(sizeof(FrameHeader) + sizeOfSprite, MEM_locked, (uint32) UID_text_sprite);
+	uint32 sizeOfSprite = spriteWidth * spriteHeight;
+	Memory *textSprite = _vm->_memory->allocMemory(sizeof(FrameHeader) + sizeOfSprite, MEM_locked, UID_text_sprite);
 
-	// the handle (*textSprite) now points to UNMOVABLE memory block
-	// set up the frame header
+	// At this stage, textSprite points to an unmovable memory block. Set
+	// up the frame header.
 
-	// point to the start of our memory block
-	frameHeadPtr = (FrameHeader *) textSprite->ad;
+	FrameHeader *frameHeadPtr = (FrameHeader *) textSprite->ad;
 
 	frameHeadPtr->compSize = 0;
 	frameHeadPtr->width = spriteWidth;
 	frameHeadPtr->height = spriteHeight;
-	
-	debug(5, "spriteWidth=%u", spriteWidth);
-	debug(5, "spriteHeight=%u", spriteHeight);
 
-	// ok, now point to the start (of the first line) of the sprite data
-	// itelf
+	debug(4, "Text sprite size: %ux%u", spriteWidth, spriteHeight);
 
-	linePtr = textSprite->ad + sizeof(FrameHeader);
+	// Clear the entire sprite to make it transparent.
 
-	// start with transparent sprite (no colour)
-	memset(linePtr, NO_COL, sizeOfSprite);
+	uint8 *linePtr = textSprite->ad + sizeof(FrameHeader);
+	memset(linePtr, 0, sizeOfSprite);
 
-	// open font file
-	charSet = _vm->_resman->openResource(fontRes);
+	uint8 *charSet = _vm->_resman->openResource(fontRes);
 
-	// fill sprite with characters, one line at a time
+	// Build the sprite, one line at a time
 
-	for (lineNo = 0; lineNo < noOfLines; lineNo++) {
-		// position the start of the line so that it is centred
-		// across the sprite
+	uint16 pos = 0;
 
-		spritePtr = linePtr + (spriteWidth - line[lineNo].width) / 2;
+	for (i = 0; i < noOfLines; i++) {
+		// Center each line
+		uint8 *spritePtr = linePtr + (spriteWidth - line[i].width) / 2;
 
 		// copy the sprite for each character in this line to the
 		// text sprite and inc the sprite ptr by the character's
 		// width minus the 'overlap'
 
-		for (posInLine = 0; posInLine < line[lineNo].length; posInLine++) {
-			charPtr = findChar(sentence[pos++], charSet);
-
-#ifdef _SWORD2_DEBUG			
-			if (charPtr->height != char_height)
-				error("FONT ERROR: '%c' is not same height as the space", sentence[pos - 1]);
-#endif
+		for (uint j = 0; j < line[i].length; j++) {
+			FrameHeader *charPtr = findChar(sentence[pos++], charSet);
 
+			assert(charPtr->height == char_height);
 			copyChar(charPtr, spritePtr, spriteWidth, pen);
 			spritePtr += charPtr->width + _charSpacing;
 		}
 
-		// skip space at end of last word in this line
+		// Skip space at end of last word in this line
 		pos++;
 
-		// move to start of next character line in text sprite
 		linePtr += (char_height + _lineSpacing) * spriteWidth;
 	}
 
-	// close font file
 	_vm->_resman->closeResource(fontRes);
 
-	// unlock the sprite memory block, so it's movable
+	// Unlock the sprite memory block, so it's movable
 	_vm->_memory->floatMemory(textSprite);
-
 	return textSprite;
 }
 
-// Returns the width of a character sprite, given the character's ASCII code
-// and a pointer to the start of the character set.
+/**
+ * @param  ch      the ASCII code of the character
+ * @param  fontRes the font resource id
+ * @return the width of the character
+ */
 
 uint16 FontRenderer::charWidth(uint8 ch, uint32 fontRes) {
-	FrameHeader *charFrame;
-	uint8 *charSet;
-	uint16 width;
-
-	// open font file
-	charSet = _vm->_resman->openResource(fontRes);
+	uint8 *charSet = _vm->_resman->openResource(fontRes);
 
-	// move to approp. sprite (header)
-	charFrame = findChar(ch, charSet);
-	width = charFrame->width;
+	FrameHeader *charFrame = findChar(ch, charSet);
+	uint16 width = charFrame->width;
 
-	// close font file
 	_vm->_resman->closeResource(fontRes);
-
-	// return its width
 	return width;
 }
 
+/**
+ * @param  fontRes the font resource id
+ * @return the height of a character sprite
+ * @note   All characters in a font are assumed to have the same height, so
+ *         there is no need to specify which one to look at.
+ */
+
 // Returns the height of a character sprite, given the character's ASCII code
 // and a pointer to the start of the character set.
 
 uint16 FontRenderer::charHeight(uint32 fontRes) {
-	FrameHeader *charFrame;
-	uint8 *charSet;
-	uint16 height;
+	uint8 *charSet = _vm->_resman->openResource(fontRes);
 
-	// open font file
-	charSet = _vm->_resman->openResource(fontRes);
+	FrameHeader *charFrame = findChar(FIRST_CHAR, charSet);
+	uint16 height = charFrame->height;
 
-	// assume all chars the same height, i.e. FIRST_CHAR is as good as any
-	charFrame = findChar(FIRST_CHAR, charSet);
-	height = charFrame->height;
-
-	// close font file
 	_vm->_resman->closeResource(fontRes);
-
-	// return its height
 	return height;
 }
 
-// Returns a pointer to the header of a character sprite, given the character's
-// ASCII code and a pointer to the start of the character set.
+/**
+ * @param  ch      the ASCII code of the character to find
+ * @param  charSet pointer to the start of the character set
+ * @return pointer to the requested character or, if it's out of range, the
+ *         'dud' character (chequered flag)
+ */
 
 FrameHeader* FontRenderer::findChar(uint8 ch, uint8 *charSet) {
-	// if 'ch' out of range, print the 'dud' character (chequered flag)
 	if (ch < FIRST_CHAR)
 		ch = DUD;
-
 	return _vm->fetchFrameHeader(charSet, ch - FIRST_CHAR);
 }
 
-// Copies a character sprite from 'charPtr' to the sprite buffer at 'spritePtr'
-// of width 'spriteWidth'. If pen is zero, it copies the data across directly,
-// otherwise it maps pixels of BORDER_COL to '_borderPen', and LETTER_COL to
-// 'pen'.
+/**
+ * Copies a character sprite to the sprite buffer.
+ * @param charPtr     pointer to the character sprite
+ * @param spritePtr   pointer to the sprite buffer
+ * @param spriteWidth the width of the character
+ * @param pen         If zero, copy the data directly. Otherwise remap the
+ *                    sprite's colours from BORDER_COL to _borderPen and from
+ *                    LETTER_COL to pen.
+ */
 
 void FontRenderer::copyChar(FrameHeader *charPtr, uint8 *spritePtr, uint16 spriteWidth, uint8 pen) {
-	uint8 *rowPtr, *source, *dest;
-	uint16 rows, cols;
+	uint8 *source = (uint8 *) charPtr + sizeof(FrameHeader);
+	uint8 *rowPtr = spritePtr;
 
-	// now pts to sprite data for char 'ch'
-	source = (uint8 *) charPtr + sizeof(FrameHeader);
+	for (uint i = 0; i < charPtr->height; i++) {
+		uint8 *dest = rowPtr;
 
-	// pts to start of first row of char within text sprite
-	rowPtr = spritePtr;
-
-	for (rows = 0; rows < charPtr->height; rows++) {
-		// start at beginning of row
-		dest = rowPtr;
-
-		// if required output pen is non-zero
 		if (pen) {
-			for (cols = 0; cols < charPtr->width; cols++) {
-				// inc source ptr along sprite data
+			// Use the specified colours
+			for (uint j = 0; j < charPtr->width; j++) {
 				switch (*source++) {
 				case LETTER_COL:
 					*dest = pen;
 					break;
 				case BORDER_COL:
-					// don't do a border pixel if there's
+					// Don't do a border pixel if there's
 					// already a bit of another character
 					// underneath (for overlapping!)
-
 					if (!*dest)
 						*dest = _borderPen;
 					break;
-
-					// do nothing if source pixel is zero,
+				default:
+					// Do nothing if source pixel is zero,
 					// ie. transparent
+					break;
 				}
-
-				// inc dest ptr to next pixel along row
 				dest++;
 			}
 		} else {
-			// pen is zero, so just copy character sprites
-			// directly into text sprite without remapping colours
+			// Pen is zero, so just copy character sprites
+			// directly into text sprite without remapping colours.
+			// Apparently overlapping is never considered here?
 			memcpy(dest, source, charPtr->width);
 			source += charPtr->width;
 		}			
-
-		// next row down (add width of text sprite)
 		rowPtr += spriteWidth;
 	}
 }
 
-// distance to keep speech text from edges of screen
+// Distance to keep speech text from edges of screen
 #define TEXT_MARGIN 12
 
-// creates a text bloc in the list and returns the bloc number the list of
-// blocs are read and blitted at render time choose alignment type
-// RDSPR_DISPLAYALIGN or 0
+/**
+ * Creates a text bloc in the list and returns the bloc number. The list of
+ * blocs is read and blitted at render time. Choose alignment type
+ * RDSPR_DISPLAYALIGN or 0
+ */
 
 uint32 FontRenderer::buildNewBloc(uint8 *ascii, int16 x, int16 y, uint16 width, uint8 pen, uint32 type, uint32 fontRes, uint8 justification) {
-	uint32	j = 0;
- 	FrameHeader *frame_head;
-	int16 text_left_margin;
-	int16 text_right_margin;
-	int16 text_top_margin;
-	int16 text_bottom_margin;
-
-	// find a free slot
-	while (j < MAX_text_blocs && _blocList[j].text_mem)
-		j++;
+	uint32 i = 0;
 
-	assert(j < MAX_text_blocs);
+	while (i < MAX_text_blocs && _blocList[i].text_mem)
+		i++;
 
-	// make the sprite!
-	_blocList[j].text_mem = makeTextSprite(ascii, width, pen, fontRes);
+	assert(i < MAX_text_blocs);
 
-	// speech to be centred above point (x,y), but kept on-screen
-	// where (x,y) is a point somewhere just above the talker's head
+	// Create and position the sprite
 
-  	// debug text just to be printed normally from point (x,y)
-
-	// JUSTIFICATION & POSITIONING
+	_blocList[i].text_mem = makeTextSprite(ascii, width, pen, fontRes);
 
 	// 'NO_JUSTIFICATION' means print sprite with top-left at (x,y)
 	// without margin checking - used for debug text
 
 	if (justification != NO_JUSTIFICATION) {
-		frame_head = (FrameHeader *) _blocList[j].text_mem->ad;
+		FrameHeader *frame_head = (FrameHeader *) _blocList[i].text_mem->ad;
 
 		switch (justification) {
-		// this one is always used for SPEECH TEXT; possibly
-		// also for pointer text
 		case POSITION_AT_CENTRE_OF_BASE:
-			x -= (frame_head->width) / 2;
+			// This one is always used for SPEECH TEXT; possibly
+			// also for pointer text
+			x -= (frame_head->width / 2);
 			y -= frame_head->height;
 			break;
 		case POSITION_AT_CENTRE_OF_TOP:
-			x -= (frame_head->width) / 2;
+			x -= (frame_head->width / 2);
 			break;
 		case POSITION_AT_LEFT_OF_TOP:
-			// the given coords are already correct for this!
+			// The given coords are already correct for this!
 			break;
 		case POSITION_AT_RIGHT_OF_TOP:
 			x -= frame_head->width;
@@ -451,7 +415,7 @@ uint32 FontRenderer::buildNewBloc(uint8 *ascii, int16 x, int16 y, uint16 width,
 			y -= frame_head->height;
 			break;
 		case POSITION_AT_LEFT_OF_CENTRE:
-			y -= (frame_head->height) / 2;
+			y -= (frame_head->height / 2);
 			break;
 		case POSITION_AT_RIGHT_OF_CENTRE:
 			x -= frame_head->width;
@@ -459,22 +423,22 @@ uint32 FontRenderer::buildNewBloc(uint8 *ascii, int16 x, int16 y, uint16 width,
 			break;
 		}
 
-		// ensure text sprite is a few pixels inside the visible screen
+		// Ensure text sprite is a few pixels inside the visible screen
 		// remember - it's RDSPR_DISPLAYALIGN
 
-		text_left_margin = TEXT_MARGIN;
-		text_right_margin = 640 - TEXT_MARGIN - frame_head->width;
-		text_top_margin = TEXT_MARGIN;
-		text_bottom_margin = 400 - TEXT_MARGIN - frame_head->height;
+		uint16 text_left_margin = TEXT_MARGIN;
+		uint16 text_right_margin = 640 - TEXT_MARGIN - frame_head->width;
+		uint16 text_top_margin = TEXT_MARGIN;
+		uint16 text_bottom_margin = 400 - TEXT_MARGIN - frame_head->height;
 
-		// move if too far left or too far right
+		// Move if too far left or too far right
 
 		if (x < text_left_margin)
 			x = text_left_margin;
 		else if (x > text_right_margin)
 			x = text_right_margin;
 			
-		// move if too high or too low
+		// Move if too high or too low
 
 		if (y < text_top_margin)
 			y = text_top_margin;
@@ -482,109 +446,81 @@ uint32 FontRenderer::buildNewBloc(uint8 *ascii, int16 x, int16 y, uint16 width,
 			y = text_bottom_margin;
 	}
 
-	_blocList[j].x = x;
-	_blocList[j].y = y;
+	// The sprite is always uncompressed
+	_blocList[i].type = type | RDSPR_NOCOMPRESSION;
 
-	// always uncompressed
-  	_blocList[j].type = type | RDSPR_NOCOMPRESSION;
+	_blocList[i].x = x;
+	_blocList[i].y = y;
 
-	return j + 1;
+	return i + 1;
 }
 
-void FontRenderer::printTextBlocs(void) {
-	//called by build_display
-
-	FrameHeader *frame;
-	SpriteInfo spriteInfo;
-	uint32 rv;
-	uint32 j;
+/**
+ * Called by buildDisplay()
+ */
 
-	for (j = 0; j < MAX_text_blocs; j++) {
-		if (_blocList[j].text_mem) {
-			frame = (FrameHeader *) _blocList[j].text_mem->ad;
+void FontRenderer::printTextBlocs(void) {
+	for (uint i = 0; i < MAX_text_blocs; i++) {
+		if (_blocList[i].text_mem) {
+			FrameHeader *frame = (FrameHeader *) _blocList[i].text_mem->ad;
+			SpriteInfo spriteInfo;
 
-			spriteInfo.x = _blocList[j].x;
-			spriteInfo.y = _blocList[j].y;
+			spriteInfo.x = _blocList[i].x;
+			spriteInfo.y = _blocList[i].y;
 			spriteInfo.w = frame->width;
 			spriteInfo.h = frame->height;
 			spriteInfo.scale = 0;
 			spriteInfo.scaledWidth = 0;
 			spriteInfo.scaledHeight = 0;
-			spriteInfo.type = _blocList[j].type;
+			spriteInfo.type = _blocList[i].type;
 			spriteInfo.blend = 0;
-			spriteInfo.data = _blocList[j].text_mem->ad + sizeof(FrameHeader);
+			spriteInfo.data = _blocList[i].text_mem->ad + sizeof(FrameHeader);
 			spriteInfo.colourTable = 0;
 
-			rv = _vm->_graphics->drawSprite(&spriteInfo);
+			uint32 rv = _vm->_graphics->drawSprite(&spriteInfo);
 			if (rv)
-				error("Driver Error %.8x in Print_text_blocs", rv);
+				error("Driver Error %.8x in printTextBlocs", rv);
 		}
 	}
 }
 
 void FontRenderer::killTextBloc(uint32 bloc_number) {
-	//back to real
 	bloc_number--;
-
-	if (_blocList[bloc_number].text_mem) {
-		// release the floating memory and mark it as free
-		_vm->_memory->freeMemory(_blocList[bloc_number].text_mem);
-		_blocList[bloc_number].text_mem = 0;
-	} else {
-		// illegal kill - stop the system
-		error("closing closed text bloc number %d", bloc_number);
-	}
+	assert(_blocList[bloc_number].text_mem);
+	_vm->_memory->freeMemory(_blocList[bloc_number].text_mem);
+	_blocList[bloc_number].text_mem = 0;
 }
 
-// The rest of this file doesn't belong in the FontRenderer class!
-
-// called from InitialiseGame() in sword2.cpp
-
-// resource 3258 contains text from location script for 152 (install, save &
+// Resource 3258 contains text from location script for 152 (install, save &
 // restore text, etc)
 
 #define TEXT_RES	3258
 
-// local line number of "save" (actor no. 1826)
+// Local line number of "save" (actor no. 1826)
 
 #define SAVE_LINE_NO	1
 
 void Sword2Engine::initialiseFontResourceFlags(void) {
-	uint8 *textFile, *textLine;
-	uint8 language;
-
-	// open the text resource
-	textFile = _resman->openResource(TEXT_RES);
+	uint8 *textFile = _resman->openResource(TEXT_RES);
 
 	// If language is Polish or Finnish it requires alternate fonts.
 	// Otherwise, use regular fonts
 
-	// get the text line (& skip the 2 chars containing the wavId)
-
-	textLine = fetchTextLine(textFile, SAVE_LINE_NO) + 2;
-
 	// "talenna"	Finnish for "save"
 	// "zapisz"	Polish for "save"
 
-	if (strcmp((char *) textLine, "tallenna") == 0)
-		language = FINNISH_TEXT;
-	else if (strcmp((char *) textLine, "zapisz") == 0)
-		language = POLISH_TEXT;
-	else
-		language = DEFAULT_TEXT;
+	// Get the text line (& skip the 2 chars containing the wavId)
+	char *textLine = (char *) fetchTextLine(textFile, SAVE_LINE_NO) + 2;
 
-	// Set the game to use the appropriate fonts
-	initialiseFontResourceFlags(language);
+	if (strcmp(textLine, "tallenna") == 0)
+		initialiseFontResourceFlags(FINNISH_TEXT);
+	else if (strcmp(textLine, "zapisz") == 0)
+		initialiseFontResourceFlags(POLISH_TEXT);
+	else
+		initialiseFontResourceFlags(DEFAULT_TEXT);
 
 	// Get the game name for the windows application
 
-	// Get the text line - skip the 2 chars containing the wavId
-
-	if (Logic::_scriptVars[DEMO])
-		textLine = fetchTextLine(textFile, 451) + 2;
-	else
-		textLine = fetchTextLine(textFile, 54) + 2;
-
 	// According to the GetNameFunction(), which was never called and has
 	// therefore been removed, the name of the game is:
 	//
@@ -592,28 +528,35 @@ void Sword2Engine::initialiseFontResourceFlags(void) {
 	// AMERICAN: "Circle of Blood II"
 	// GERMAN:   "Baphomet's Fluch II"
 	// default:  "Some game or other, part 86"
+	//
+	// But we get it from the text resource instead.
 
-	_graphics->setWindowName((char *) textLine);
+	if (Logic::_scriptVars[DEMO])
+		textLine = (char *) fetchTextLine(textFile, 451) + 2;
+	else
+		textLine = (char *) fetchTextLine(textFile, 54) + 2;
 
-	// now ok to close the text file
+	_graphics->setWindowName(textLine);
 	_resman->closeResource(TEXT_RES);
 }
 
-// called from the above function, and also from console.cpp
+/**
+ * Called from initialiseFontResourceFlags(), and also from console.cpp
+ */
 
 void Sword2Engine::initialiseFontResourceFlags(uint8 language) {
 	switch (language) {
-	case FINNISH_TEXT:	// special Finnish fonts
+	case FINNISH_TEXT:
 		_speechFontId = FINNISH_SPEECH_FONT_ID;
 		_controlsFontId = FINNISH_CONTROLS_FONT_ID;
 		_redFontId = FINNISH_RED_FONT_ID;
 		break;
-	case POLISH_TEXT:	// special Polish fonts
+	case POLISH_TEXT:
 		_speechFontId = POLISH_SPEECH_FONT_ID;
 		_controlsFontId = POLISH_CONTROLS_FONT_ID;
 		_redFontId = POLISH_RED_FONT_ID;
 		break;
-	default:		// DEFAULT_TEXT	- regular fonts
+	default:
 		_speechFontId = ENGLISH_SPEECH_FONT_ID;
 		_controlsFontId = ENGLISH_CONTROLS_FONT_ID;
 		_redFontId = ENGLISH_RED_FONT_ID;
diff --git a/sword2/maketext.h b/sword2/maketext.h
index 7e4b46fde8..c249ad3a1a 100644
--- a/sword2/maketext.h
+++ b/sword2/maketext.h
@@ -17,64 +17,28 @@
  * $Header$
  */
 
-/****************************************************************************
- * MAKETEXT.H - Function prototype for text sprite builder routine JEL Oct96
- *
- * The routine returns a memory handle to a movable memory block containing
- * the required sprite, which must be locked before use. ie. lock, draw
- * sprite, unlock/free.
- * 
- * The sprite data contains a frameHeader, but not a standard file header.
- *
- * Debugger will trap error when word too big for line (maxWidth) or when
- * more lines needed than max expected (MAX_LINES)
- *
- * PARAMETERS:
- *
- * 'sentence' points to a NULL-TERMINATED STRING
- *      - string must contain no leading/tailing/extra spaces
- *      - out-of-range characters in the string are forced to the output as
- *        a special error-signal character (chequered flag)
- *
- * 'maxWidth' is the maximum allowed text sprite width, in PIXELS
- *
- * 'pen' is the desired colour (0-255) for the main body of each character
- * 
- * NB. Border colour is #DEFINEd in textsprt.c (to a colour value for BLACK)
- * if 'pen' is zero, the characters are copied directly and NOT remapped.
- *
- * 'charSet' points to the beginning of the standard file header for the
- * desired character set
- *
- * NB. The first and last characters in the set are #DEFINEd in textsprt.c
- *
- * RETURNS:
- *
- * 'textSprite' points to the handle to be used for the text sprite
- *
- ****************************************************************************/
-
 #ifndef _MAKETEXT_H
 #define _MAKETEXT_H
 
 #include "sword2/debug.h"
 
+namespace Sword2 {
+
 // Output colour for character border - should be be black but note that we
 // have to use a different pen number during sequences
 
 #define BORDER_PEN 194
 
-namespace Sword2 {
-
-// allow enough for all the debug text blocks (see debug.cpp)
-#define MAX_text_blocs MAX_DEBUG_TEXT_BLOCKS + 1
+// Usually the only texts on screen are the subtitles and the mouse-over text,
+// but there can also be a considerable number of debugging messages...
+    
+#define MAX_text_blocs MAX_DEBUG_TEXTS + 1
 
 enum {
-	// only for debug text, since it doesn't keep text inside the screen
-	// margin!
+	// Doesn't keep the text inside the screen - only for debug text!
 	NO_JUSTIFICATION = 0,
 
-	// these all force text inside the screen edge margin when necessary
+	// These all force text inside the screen edge margin when necessary
 	POSITION_AT_CENTRE_OF_BASE = 1,
 	POSITION_AT_CENTRE_OF_TOP = 2,
 	POSITION_AT_LEFT_OF_TOP = 3,
@@ -91,18 +55,20 @@ enum {
 	POLISH_TEXT = 2
 };
 
-struct TextBloc {
+// Info about the text, used to create the SpriteInfo struct
+
+ struct TextBloc {
 	int16 x;
 	int16 y;
-	// RDSPR_ status bits - see defintion of SpriteInfo structure for
-	// correct size!
 	uint16 type;
 	Memory *text_mem;
 };
 
+// Info for each line of words in the output text sprite
+
 struct LineInfo {
-	uint16 width;	// width of line in pixels
-	uint16 length;	// length of line in characters
+	uint16 width;	// Width in pixels
+	uint16 length;	// Length in characters
 };
 
 class FontRenderer {
@@ -110,8 +76,8 @@ private:
 	Sword2Engine *_vm;
 	TextBloc _blocList[MAX_text_blocs];
 
-	// layout variables - these used to be defines, but now we're dealing
-	// with 2 character sets
+	// Layout variables - these used to be defines, but now we're dealing
+	// with three character sets
 
 	int8 _lineSpacing;	// no. of pixels to separate lines of
 				// characters in the output sprite - negative