- Comments and formatting changes.

1 files changed, 78 insertions, 21 deletions

diff --git a/src/xmlcomposer.h b/src/xmlcomposer.h
index deba4ba..4e5c739 100644
--- a/src/xmlcomposer.h
+++ b/src/xmlcomposer.h
@@ -36,68 +36,102 @@
  *
  */
 
+// RENAME: xmlcomposer.h
+
 #ifndef __RTFPARSER_H__
 #define __RTFPARSER_H__
 
 #include "levelhandler.h"
 
-struct RtfParserOptions
+struct XmlComposerOptions
 {
-	RtfParserOptions()
+	XmlComposerOptions()
 		{ memset(this, 0, sizeof(*this)); }
 
 	bool doColors;
 };
 
-class RtfParser : public LevelHandler
+/*
+ * XmlComposer
+ *
+ * This is where the RTF gets initially converted to XML. RtfParser sends
+ * notifications to this class's RtfHandler interface. It forwards them to
+ * the current analysers and destinations which produce XML content.
+ * (see xmlcomposehelpers.h)
+ *
+ * Not all conversion is completed here. Because RTF is so very wierd we
+ * have to run lots of fixups are run in endDocument (see rtffixups.h)
+ */
+class XmlComposer :
+    public LevelHandler
 {
 public:
-	RtfParser(const RtfParserOptions& options);
-	virtual ~RtfParser();
+	XmlComposer(const XmlComposerOptions& options);
+	virtual ~XmlComposer();
 
-	virtual void startDocument(RtfReader* reader);
+    // Handler Overrides
+	virtual void startDocument(RtfParser* reader);
 	virtual void endDocument();
 	virtual void controlWord(const string& cw, int flags, int param);
 	virtual void groupStart();
 	virtual void groupEnd();
 	virtual void charData(wstring data);
 
-	// Element management functions
+	// Create an XML element with given name
 	DOM::Element createElement(const string& name);
+
+    // Push an XML element on the current level
 	void pushElement(const DOM::Element& element);
+
+    // Replace current XML element with given element
 	void replaceElement(const DOM::Element& element);
+
+    // Move up one XML element level without changing RTF level
 	DOM::Element popElement();
+
+    // Set attributes on the current XML Element
 	void setAttribute(const string& name, const wstring& value, DOM::Element el = DOM::Element());
     void setAttribute(const string& name, int value, DOM::Element el = DOM::Element());
 
-	// Changing the current parser functions
+	// The current analyser in use
+    AnalyserPtr getAnalyser();
 	void setAnalyser(AnalyserPtr analy);
+
+    // The current destination in use
+    DestinationPtr getDestination();
 	void setDestination(DestinationPtr dest);
+
+    // Replace the current destination (sets level deep)
 	DestinationPtr replaceDestination(DestinationPtr dest);
 
-    // The types of auto counters
+
+    // The types of auto numbering
     enum
     {
        AUTOCOUNT_FOOTNOTE,
        AUTOCOUNT_MAX
     };
 
-    // Functions for auto numbering
+    // Functions for RTF auto numbering
     int getAutoCount(int type);
     void incrementAutoCount(int type);
 
-	// Current status functions
+
+	// Get the current formatting options
 	RtfFormatting& getTextFormatting();
-	AnalyserPtr getAnalyser();
-	DestinationPtr getDestination();
+
 	DOM::Document getDocument()
 		{ return m_document; }
 
 	const RtfParserOptions& getOptions()
 		{ return m_options; }
 
+
+    // TODO: Should this be somewhere else?
     static wstring formatInt(int num);
 
+
+// LevelHandler override
 protected:
 	virtual void clear();
 
@@ -110,12 +144,12 @@ protected:
     int m_autocount[AUTOCOUNT_MAX];        // Auto counters for the document
 
 
-
 // Sub classes
 protected:
+
 	#define DESTINATION(cls) class cls : public Destination { public:
 	#define END_DESTINATION };
-	#define ANALYSER(cls) class cls : public ParseAnalyser { public:
+	#define ANALYSER(cls) class cls : public BaseAnalyser { public:
 	#define END_ANALYSER };
 	#define DATA_PORTION protected:
 	#define INITIALIZE virtual void initialize();
@@ -125,6 +159,7 @@ protected:
 	#define GROUPEND virtual void groupEnd();
 	#define DONE virtual void done();
 
+    // Main destination for document character content
 	DESTINATION(Content)
 		INITIALIZE
 		CHARDATA
@@ -133,14 +168,16 @@ protected:
 		DOM::Element parent;
 	END_DESTINATION
 
-
+    // Discards character data
 	DESTINATION(Null)
 	END_DESTINATION
 
+    // Copies raw character data to output
 	DESTINATION(Raw)
 		CHARDATA
 	END_DESTINATION
 
+    // Copies character data to an XML attribute
 	DESTINATION(Attribute)
 		Attribute(const string& nm) : name(nm) {}
 		INITIALIZE
@@ -150,7 +187,9 @@ protected:
 		DOM::Element element;
 	END_DESTINATION
 
-	class ParseAnalyser :
+
+    // Base class for analysers with some helper functions
+	class BaseAnalyser :
 		public Analyser
 	{
 	public:
@@ -158,23 +197,34 @@ protected:
 			{ processDefault(cw, flags, param); }
 
 	protected:
-		// Some helper functions
+        // Process a standard set of tags that can be found anywhere
 		bool processDefault(const string& cw, int flags, int param);
+
+        // Process text formatting tags
 		bool processTextFormatting(const string& cw, int flags, int param, RtfFormatting& format);
+        bool processTextFormatting(const string& cw, int flags, int param);
+
+        // Creates 'fix' tags for paragraph formatting in element
+        void applyParaFormatting(RtfFormatting* format, DOM::Element& el);
+
+        // Process tags that are either text content, or change context
 		bool processTextContent(const string& cw, int flags, int param);
-		bool processTextFormatting(const string& cw, int flags, int param);
+
+        // Process tags that generate text content (like auto-numbering, fields)
         bool processTextAutoContent(const string& cw, int flags, int param);
 
+        // Convenience function
 		DOM::Element getCurrentBlock();
-		void applyParaFormatting(RtfFormatting* format, DOM::Element& el);
 	};
 
 
+    // Skip tags and groups
 	ANALYSER(Skip)
 		INITIALIZE
 		GROUPSTART
 	END_ANALYSER
 
+    // Unicode block analyser
 	ANALYSER(Upr)
 		Upr(AnalyserPtr prv);
 		GROUPSTART
@@ -183,11 +233,13 @@ protected:
 		AnalyserPtr prev;
 	END_ANALYSER
 
+    // Handle Stylesheets
 	ANALYSER(Stylesheet)
 		INITIALIZE
 		GROUPSTART
 	END_ANALYSER
 
+    // Handle a style in a stylesheet
 	ANALYSER(Style)
 		INITIALIZE
 		CONTROLWORD
@@ -197,11 +249,13 @@ protected:
 		bool haveStyle;
 	END_ANALYSER
 
+    // Handle the list definitions
 	ANALYSER(ListTable)
 		INITIALIZE
 		GROUPSTART
 	END_ANALYSER
 
+    // Handle a list in the list definitions
 	ANALYSER(List)
 		INITIALIZE
 		CONTROLWORD
@@ -210,27 +264,30 @@ protected:
 		int levelsSeen;
 	END_ANALYSER
 
+    // Handle list overrides
 	ANALYSER(ListOverrideTable)
 		INITIALIZE
 		CONTROLWORD
 		GROUPSTART
-		GROUPEND
 	DATA_PORTION
 		DOM::NodeList lists;
 		int lsId;
 		DOM::Element curList;
 	END_ANALYSER
 
+    // Creates the info block
 	ANALYSER(Info)
 		INITIALIZE
 		CONTROLWORD
 	END_ANALYSER
 
+    // The main root analyser
 	ANALYSER(Root)
 		INITIALIZE
 		CONTROLWORD
 	END_ANALYSER
 
+    // Handles footnotes
     ANALYSER(FootNote)
         INITIALIZE
         CONTROLWORD