Index: libcschem/undo_and_ptrs.txt
===================================================================
--- libcschem/undo_and_ptrs.txt	(nonexistent)
+++ libcschem/undo_and_ptrs.txt	(revision 5642)
@@ -0,0 +1,32 @@
+In libcschem, it is safe to reference concrete objects by pointers, because
+of the undo system.
+
+Every concrete object is also part of a doubly linked list. This list is
+one of the sheet's 'active' or 'deleted' lists. This is true for all
+objects in both the direct and the indirect subtrees.
+
+Existing objects are part of the 'active' list. Once they are deleted, they
+are moved to the 'deleted' list by the 'redo' operation of the deletion and
+if it is undone, the 'undo' operation will move the object back from the
+'deleted' list to the 'active' list.
+
+Order of objects on these two lists does not matter. The lists are there
+for only one purpose: to make sure no object is lost.
+
+This also means that once an object is created, it is never freed until
+the whole sheet is freed. It may change its state from active to deleted
+or back, but the address of the object is preserved.
+
+Furthermore each concrete object is part of exactly one sheet. A paste buffer
+is a sheet too. When an object travels between sheets, the object needs to
+be copied. The 'deleted' list of a sheet used as a paste buffer is always
+empty: buffers are not edited, they are created and destroyed and re-created
+from real sheets.
+
+
+Conclusion: this makes referencing by pointer safe, even without having
+to use a reference counter:
+
+- a concret object is always within a sheet
+- it is created once, and will never be deleted until the whole sheet is deleted
+- the address of the object is immutable
Index: libcschem/xorcache.txt
===================================================================
--- libcschem/xorcache.txt	(nonexistent)
+++ libcschem/xorcache.txt	(revision 5642)
@@ -0,0 +1,11 @@
+For concrete molde objects there are fields, typically holding
+oid-paths, that have a textual description on input but should be
+tracked by object pointers after load.
+
+These fields are stored in a pair of struct fields marked xorcache:
+either the text version or the object-pointer version is NULL. After
+load, the text is valid, the pointer is NULL. Upon the first access,
+the reference is resolved and the code uses the pointer. Whenever
+this happens, the text field is free'd and set to NULL.
+
+Export code rebuilds the textual reference from the pointer.