[gegl/soc-2012-ops] docs: Improve journal specification a bit

[Hans Shu Lo <hanslo src gnome org>]

commit a12ab3c69d90a32330c48eaf872e173ac5dda2cf
Author: Jon Nordby <jononor gmail com>
Date:   Fri Jun 8 14:15:16 2012 +0200

    docs: Improve journal specification a bit
    
    Add an abstract and fix the proposed API to include
    a reference to the GeglGraph being operated on.

 docs/journal.txt |   45 +++++++++++++++++++++++++++++++--------------
 1 files changed, 31 insertions(+), 14 deletions(-)
---
diff --git a/docs/journal.txt b/docs/journal.txt
index 7dc2fc5..9b38a37 100644
--- a/docs/journal.txt
+++ b/docs/journal.txt
@@ -1,10 +1,16 @@
 Journal / transaction log
 
+The journal stores the changes done to a GEGL graph as a set of transactions.
+This journal can be used as a syncronization point for multiple users of
+a GEGL graph, and can be stored as a file. This file can be embedded into
+a higher level file format to persist undo/redo history across saves/loads
+of a document.
+A program using GEGL may use several independent GEGL graphs, and thus several
+independent journals.
+
 == Usecases ==
-* Base for undo/redo stacks
-* Automated testing
- * of view widgets
- * graph manipulation API
+* Base for undo/redo stacks in GEGL based applications
+* Automated testing of GEGL graph manipulation API and interactive view widgets
 * Sharing and manipulation of a GEGL graph between multiple programs
 
 == Operations ==
@@ -17,8 +23,6 @@ Journal / transaction log
 - Change property. int node_id, char *key, char *value (using property-type specific serialization serialized)
 - Change operation. int node_id, char *new_operation_name
 
-- Recall state. (go back to a previous transaction). Specified using the block number for the transaction_start.
-
 Node references:
 - GEGL to maintain an (graph) unique identifier for each node: Add an integer identifier to node when added to the graph.
 - The identifier must be be maintained when changing operations.
@@ -30,6 +34,11 @@ If no transaction is explicitly opened, an implicit transaction for the duration
 
 After a add node operation, one or mor change property and change operation operations must follow.
 
+Transaction operation:
+- Recall state. int block_no
+  The block_no must be for a transaction start
+  Sets the graph state back to that of a previous transaction
+
 == File format ==
 Append only file format consisting of a series of entries.
 
@@ -88,31 +97,39 @@ Each entry (see above list) has a format depending on its type.
 
 == Public API ==
 
-void gegl_graph_transaction_start(const char *description);
+void gegl_graph_transaction_start(GeglGraph *graph, const char *description);
+ @graph: top-level node in a GEGL graph
  @description a human readable description of the change. UTF-8 encoded
 
-void gegl_graph_transaction_end(void);
+void gegl_graph_transaction_end(GeglGraph *graph);
+ @graph: top-level node in a GEGL graph
 
-int gegl_graph_transaction_previous (int block_no);
+int gegl_graph_transaction_previous(GeglGraph *graph, int block_no);
+ @graph: top-level node in a GEGL graph
  @block_no <= 0 means end of journal. Only block numbers for transaction start entries are valid
  @return -1 on invalid block_no, else the block number of the previous transaction
 
-int gegl_graph_transaction_recall(int block_no);
+int gegl_graph_transaction_recall(GeglGraph *graph, int block_no);
+ @graph: top-level node in a GEGL graph
  @block_no <= 0 means end of journal. Only block numbers for transaction start entries are valid
  @return -1 on invalid block_no, 
 
-char *gegl_graph_transaction_get_description(int block_no);
+char *gegl_graph_transaction_get_description(GeglGraph *graph, int block_no);
+ @graph: top-level node in a GEGL graph
  @block_no Only block numbers for transaction start entries are valid
  @return NULL on invalid block_no, else the human readable description passed to transaction_start
 
 == Implementation notes ==
 
-TODO
+The implementation could be based on the GeglBuffer file format implementation.
+It is suggested to keep the implementations separate, to risk avoid introducing
+regressions in exist code and because it is possible that GeglBuffer will be
+moved to a separate library at some point.
 
 == Ideas ==
 * Add a non-blocking version of transactions.
 Note: not guaranteed to succeed. Applications must gracefully handle the transaction being rejected.
 
-  gegl_graph_transaction_new(const char *description);
-  gboolean gegl_graph_transaction_commit();
+  void gegl_graph_transaction_open(GeglGraph *graph, const char *description);
+  gboolean gegl_graph_transaction_commit(GeglGraph *graph);