[Libreoffice-commits] core.git: svl/README sw/README

[Michael Stahl]

 svl/README |   38 +++++++++++++++++++++++++++++
 sw/README  |   79 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 117 insertions(+)

New commits:
commit fdf5152552c1df59d73a32cb8ae1f259e5cb4f80
Author: Michael Stahl <mstahl at redhat.com>
Date:   Fri Jun 28 23:22:43 2013 +0200

    more README
    
    Change-Id: I569e7fd3cf9e418af03285f4f499f5ea3a0c0dc0

diff --git a/svl/README b/svl/README
index 2ab2f1d..c2cca3f 100644
--- a/svl/README
+++ b/svl/README
@@ -10,3 +10,41 @@ formats, to Chart regression line properties.
 
 There are lots of other useful helpers in here for various office
 tasks; much of this code was originally moved from svx/sfx2.
+
+== Items, Pools and Sets ==
+
+=== SfxPoolItem ===
+
+A small reference counted piece of data.  Many subclasses, each with a
+unique integer to identify its type (WhichId).  Can be compared for equality
+(operator==), Clone()d, and converted to/from uno::Any (QueryValue/PutValue).
+
+A pool item may have value semantics (SFX_ITEM_POOLABLE), meaning that
+there will generally be only one instance that compares equal per item pool,
+or not, in which case the item will be Clone()d quite a bit.
+
+=== SfxItemPool ===
+
+Usually there is one item pool per document, with a range of valid WhichIds
+that is specific to the type of document.
+
+The item pool owns all instances of SfxPoolItem or its subclasses that have
+ever been added to an item set.  It also contains a default item for
+every WhichId, which will be (depending on parameters) returned from item
+sets if the set does not contain an item at this WhichId.
+
+=== SfxItemSet ===
+
+The item set can be created with a user-supplied range of WhichIds; it
+will accept SfxPoolItems with matching WhichIds and ignore attempts to
+insert items with non-matching WhichIds.
+
+Items that are succesfully inserted into the set will be stored in the
+set's SfxItemPool, and for poolable items only a single instance that
+compares equal under the predicate operator== will be stored in the pool,
+regardless of how many sets contain it, thus conserving memory.
+
+There are members _pWhichRanges for the valid ranges (as pairs of WhichIds),
+_nCount for the number of items contained, and _aItems for the pointers to
+the actual items.
+
diff --git a/sw/README b/sw/README
index 1b979dd..f78020ad 100644
--- a/sw/README
+++ b/sw/README
@@ -25,3 +25,82 @@ comments show that Writer core dates back until at least November
    * ww8: DOC import, DOC/DOCX/RTF export
    * xml: ODF import/export, subclassed from xmloff (where most of the work is done)
  * ui: user interface
+
+== 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.
+
+This is a huge class with hundreds of methods; there are some efforts
+to split up the class into many smaller classes that implement more
+specific interfaces but this is not fully implemented yet; see the various
+IDocument* classes.
+
+=== 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
+SwTxtNode::m_pSwpHints.  There is a base class SwTxtAttr with numerous
+subclasses; the SwTxtAttr has a start and end index and a SfxPoolItem
+to store the actual formatting attribute.
+
+There are several sub-categories of SwTxtAttr:
+
+- formatting attributes: Character Styles (SwTxtCharFmt, 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 (SwTxtINetFmt, RES_TXTATR_INETFMT),
+  Ruby (SwTxtRuby, RES_TXTATR_CJK_RUBY) and Meta/MetaField (SwTxtMeta,
+  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.
+
+