add some hacking notes

Change-Id: Ib0fd2ae0eae1e83ec9f4de961148ab0506c96cb5

1 files changed, 43 insertions, 0 deletions

diff --git a/HACKING b/HACKING
index e0bf419..b81dcd2 100644
--- a/HACKING
+++ b/HACKING
@@ -78,3 +78,46 @@ problem and is even encouraged.
 
 Remember, the important thing is to have fun. :-) These rules are a means,
 not an end. Happy hacking!
+
+= Hacking notes =
+
+== Main entities ==
+
+* *Parser: a parser :-) Passes raw data to collector for further processing.
+* *Collector: an output producer; uses the data passed to it from parser.
+* IWORKPropertyMap: a type-safe property map. A property map is
+  typically not used directly, except in the parser. Instead, it is
+  wrapped in an IWORKStyle.
+* IWORKStyleStack: a hierarchy of currently applied styles. It allows
+  lookup of properties without checking multiple styles explicitly.
+* IWORKDocumentInterface: an amalgamation of librevenge document interfaces,
+  to allow common handling of some parts of the file format.
+
+See the documentation for concrete classes for more details.
+
+== Tokenizer ==
+
+We use gperf to generate lookup maps for XML tokens. These are split by
+namespace: names in 'sf' and 'sfa' namespaces are in IWORKToken, 'key'
+in in KEYToken, 'ls' in NUMToken and 'sl' in PAGToken. To add a new
+token, add it into the enum in appropriate *Token.h and define it in
+*Token.gperf.
+
+== Type-safe property map ==
+
+To add a new property, declare it in IWORKProperties.h and define in
+IWORKProperties.cpp.
+
+== XML Parser ==
+
+Parsing is done by parser context classes. These handle a specific XML
+element or a class of elements (e.g., references or styles). The
+contexts have access to a global state (which is format-specific), but
+most of the results are passed either to the collector or up to the
+parent context. In the later case, the output is saved through
+references to boost::optional<Foo> passed in the constructor.
+
+The context classes employ various suffixes for better orientation.
+'Context' is common for several elements, 'Element' is for a single
+element, 'Base' is a base class adding a common functionality, which is
+not supposed to be used directly.