Adding upstream version 1:7.0.4.upstream/1%7.0.4upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 211 insertions, 0 deletions

diff --git a/sw/README b/sw/README
new file mode 100644
index 000000000..54feb78fa
--- /dev/null
+++ b/sw/README
@@ -0,0 +1,211 @@
+Writer application code.
+
+Exact history was lost before Sept. 18th, 2000, but old source code
+comments show that Writer core dates back until at least November
+1990.
+
+== Module contents ==
+ * inc: headers available to all source files inside the module
+ * qa: unit, slow and subsequent tests
+ * sdi
+ * source: see below
+ * uiconfig: user interface configuration
+ * util: UNO passive registration config
+
+== Source contents ==
+ * core: Writer core (document model, layout, UNO API implementation)
+ * filter: Writer internal filters
+   * ascii: plain text filter
+   * basflt
+   * docx: wrapper for the UNO DOCX import filter (in writerfilter) for autotext purposes
+   * html: HTML filter
+   * inc: include files for filters
+   * rtf: thin copy&paste helper around the UNO RTF import filter (in writerfilter)
+   * writer
+   * ww8: DOC import, DOC/DOCX/RTF export
+   * xml: ODF import/export, subclassed from xmloff (where most of the work is done)
+ * uibase: user interface (those parts that are linked into sw & always loaded)
+ * ui: user interface (optional parts that are loaded on demand (swui))
+
+== Core ==
+
+There is a good overview documentation of basic architecture of Writer core
+in the OOo wiki:
+
+http://wiki.openoffice.org/wiki/Writer/Core_And_Layout
+http://wiki.openoffice.org/wiki/Writer/Text_Formatting
+
+Writer specific WhichIds are defined in sw/inc/hintids.hxx.
+
+The details below are mainly about details missing from the Wiki pages.
+
+=== SwDoc ===
+
+The central class for a document is SwDoc, which represents a document.
+
+A lot of the functionality is split out into separate Manager classes,
+each of which implements some IDocument* interface; there are
+SwDoc::getIDocument*() methods to retrieve the managers.
+
+However there are still too many members and methods in this class,
+many of which could be moved to some Manager or other...
+
+=== SwNodes ===
+
+Basically a (fancy) array of SwNode pointers.  There are special subclasses of
+SwNode (SwStartNode and SwEndNode) which are used to encode a nested tree
+structure into the flat array; the range of nodes from SwStartNode to its
+corresponding SwEndNode is sometimes called a "section" (but is not necessarily
+what the high-level document model calls a "Section"; that is just one of the
+possibilities).
+
+The SwNodes contains the following top-level sections:
+
+1. Empty
+2. Footnote content
+3. Frame / Header / Footer content
+4. Deleted Change Tracking content
+5. Body content
+
+=== Undo ===
+
+The Undo/Redo information is stored in a sw::UndoManager member of SwDoc,
+which implements the IDocumentUndoRedo interface.
+Its members include a SwNodes array containing the document content that
+is currently not in the actual document but required for Undo/Redo, and
+a stack of SwUndo actions, each of which represents one user-visible
+Undo/Redo step.
+
+There are also ListActions which internally contain several individual SwUndo
+actions; these are created by the StartUndo/EndUndo wrapper methods.
+
+=== Text Attributes ===
+
+The sub-structure of paragraphs is stored in the SwpHintsArray member
+SwTextNode::m_pSwpHints.  There is a base class SwTextAttr with numerous
+subclasses; the SwTextAttr has a start and end index and a SfxPoolItem
+to store the actual formatting attribute.
+
+There are several sub-categories of SwTextAttr:
+
+- formatting attributes: Character Styles (SwTextCharFormat, RES_TXTATR_CHARFMT)
+  and Automatic Styles (no special class, RES_TXTATR_AUTOFMT):
+  these are handled by SwpHintsArray::BuildPortions and MergePortions,
+  which create non-overlapping portions of formatting attributes.
+
+- nesting attributes: Hyperlinks (SwTextINetFormat, RES_TXTATR_INETFMT),
+  Ruby (SwTextRuby, RES_TXTATR_CJK_RUBY) and Meta/MetaField (SwTextMeta,
+  RES_TXTATR_META/RES_TXTATR_METAFIELD):
+  these maintain a properly nested tree structure.
+  The Meta/Metafield are "special" because they have both start/end
+  and a dummy character at the start.
+
+- misc. attributes: Reference Marks, ToX Marks
+
+- attributes without end: Fields, Footnotes, Flys (AS_CHAR)
+  These all have a corresponding dummy character in the paragraph text, which
+  is a placeholder for the "expansion" of the attribute, e.g. field content.
+
+=== Fields ===
+
+There are multiple model classes involved for fields:
+
+- enum SwFieldIds enumerates the different types of fields.
+- SwFieldType contains some shared stuff for all fields of a type.
+  There are many subclasses of SwFieldType, one for each different type
+  of field.
+  For most types of fields there is one shared instance of this per type,
+  which is created in DocumentFieldsManager::InitFieldTypes()
+  but for some there are more than one, and they are dynamically created, see
+  DocumentFieldsManager::InsertFieldType().  An example for the latter are
+  variable fields (SwFieldIds::GetExp/SwFieldIds::SetExp), with one SwFieldType per
+  variable.
+- SwXFieldMaster is the UNO wrapper of a field type.
+  It is a SwClient registered at the SwFieldType.
+  Its life-cycle is determined by UNO clients outside of sw; it will get
+  disposed when the SwFieldType dies.
+- SwFormatField is the SfxPoolItem of a field.
+  The SwFormatField is a SwClient registered at its SwFieldType.
+  The SwFormatField owns the SwField of the field.
+- SwField contains the core logic of a field.
+  The SwField is owned by the SwFormatField of the field.
+  There are many subclasses of SwField, one for each different type of field.
+  Note that there are not many places that can Expand the field to its
+  correct value, since for example page number fields require a View
+  with an up to date layout; therefore the correct expansion is cached.
+- SwTextField is the text attribute of a field.
+  It owns the SwFormatField of the field (like all text attributes).
+- SwXTextField is the UNO wrapper object of a field.
+  It is a SwClient registered at the SwFormatField.
+  Its life-cycle is determined by UNO clients outside of sw; it will get
+  disposed when the SwFormatField dies.
+
+=== Lists ===
+
+- SwNumFormat (subclass of SvxNumFormat) determines the formatting of a single
+  numbering level.
+
+- SwNumRule (NOT a subclass of SvxNumRule) is a *list style*, containing one
+  SwNumFormat per list level.
+  SwNumRule::maTextNodeList is the list of SwTextNode that have this list style
+  applied.
+
+- SwNumberTreeNode is a base class that represents an abstract node in a
+  hierarchical tree of numbered nodes.
+
+- SwNodeNum is the subclass of SwNumberTreeNode that connects it with an
+  actual SwTextNode and also with a SwNumRule;
+  SwTextNode::mpNodeNum points back in the other direction
+
+- SwList represents a list, which is (mostly) a vector of SwNodeNum trees,
+  one per SwNodes top-level section (why that?).
+
+- IDocumentListsAccess, sw::DocumentListsManager owns all SwList instances,
+  and maintains mappings:
+  + from list-id to SwList
+  + from list style name to SwList (the "default" SwList for that list style)
+
+- IDocumentListItems, sw::DocumentListItemsManager contains a set of all
+  SwNodeNum instances, ordered by SwNode index
+
+- the special Outline numbering rule: SwDoc::mpOutlineRule
+
+- IDocumentOutlineNodes, sw::DocumentOutlineNodesManager maintain
+  a list (which is actually stored in SwNodes::m_pOutlineNodes) of SwTextNodes
+  that either have the Outline numrule applied,
+  or have the RES_PARATR_OUTLINELEVEL item set (note that in the latter case,
+  the SwTextNode does not have a SwNodeNum and is not associated with the
+  SwDoc::mpOutlineRule).
+
+- SwTextNodes and paragraph styles have items/properties:
+  + RES_PARATR_OUTLINELEVEL/"OutlineLevel" to specify an outline level without
+    necessarily having the outline SwNumRule assigned
+  + RES_PARATR_NUMRULE/"NumberingStyleName" the list style to apply; may be
+    empty "" which means no list style (to override inherited value)
+  Only SwTextNode has these items:
+  + RES_PARATR_LIST_ID/"ListId"
+    determines the SwList to which the node is added
+  + RES_PARATR_LIST_LEVEL/"NumberingLevel"
+    the level at which the SwTextNode will appear in the list
+  + RES_PARATR_LIST_ISRESTART/"ParaIsNumberingRestart"
+    restart numbering sequence at this SwTextNode
+  + RES_PARATR_LIST_RESTARTVALUE/"NumberingStartValue"
+    restart numbering sequence at this SwTextNode with this value
+  + RES_PARATR_LIST_ISCOUNTED/"NumberingIsNumber"
+    determines if the node is actually counted in the numbering sequence;
+    these are different from "phantoms" because there's still a SwTextNode.
+
+Note that there is no UNO service to represent a list.
+
+=== Layout ===
+
+The layout is a tree of SwFrame subclasses, the following relationships are
+possible between frames:
+
+- You can visit the tree by following the upper, lower, next and previous pointers.
+- The functionality of flowing of a frame across multiple parents (e.g. pages)
+  is implemented in SwFlowFrame, which is not an SwFrame subclass. The logical
+  chain of such frames can be visited using the follow and precede pointers.
+  ("Leaf" is a term that refers to such a relationship.)
+- In case a frame is split into multiple parts, then the first one is called
+  master, while the others are called follows.