Add: Insert Property Drawer notes and basic code

2 files changed, 70 insertions, 2 deletions

diff --git a/annotations b/annotations
index 6c19cc6..9f8511f 100644
--- a/annotations
+++ b/annotations
@@ -1,3 +1,3 @@
 (("~/projects/coorgi-client/coorgi-client.org" ((109 325 "please refine this block, i know you've got some good language for it out there -g" "Coorgi stands for \"cooperative org interchange\", and intends to enable
 multiple users to sync org documents between one another. Possible uses
-include issue trackers, shared agendas, and near real-time collaboration.")) "80a7138d69b10cf76e6d481cc6426e63"))
\ No newline at end of file
+include issue trackers, shared agendas, and near real-time collaboration.")) "fd9653579213d5ac89bc604c229ee18c"))
\ No newline at end of file
diff --git a/coorgi-client.org b/coorgi-client.org
index f9bc542..1ac82f5 100644
--- a/coorgi-client.org
+++ b/coorgi-client.org
@@ -72,7 +72,7 @@ therefore, we /should/ be able to act upon the parsed data with Coorgi
 functions to update the document, rather than mucking with live buffer
 edits and updates.
 
-*** TODO example proof of concept
+*** TODO Proof of Concept - Insert Property Drawer
 
 First lets start with an un-coorgified org document with one headline:
 
@@ -87,6 +87,74 @@ If we want to programmatically add a property drawer to this headline
 by modifying the parsed org document tree, it will require several
 steps.
 
+**** Simplified tree structure
+
+The first non-blank line after a ~headline~ begins a ~section~ element
+which holds the rest of the headline's child elements. Basic text in a
+section is held in a ~paragraph~ element. A headline's ~property-drawer~
+element will be the [[info:org#Property Syntax][first thing]] (aside from a planning line) within
+the ~section~ element. So, after inserting a property drawer to the
+=uncoorgified-example-1= above, the tree structure will look like this:
+
+#+begin_src emacs-lisp
+  '(headline (props...)
+     (section (props...)
+       (property-drawer (props...))
+       (paragraph (props...))))
+#+end_src
+
+The [[uncoorgified-example-1][example document]] above already has a section and paragraph, so
+we need to insert the ~property-drawer~ /after/ the ~section~ element but
+before the ~paragraph~. The drawer's parent will be the ~section~ and we
+may (will?) need to adjust the buffer position properties of the rest of
+the org document data. Thankfully, ~org-element.el~ already has a function
+to help us with that: ~org-element-insert-before~.
+
+**** TODO Building a property-drawer element
+
+Here's an example of an actually parsed property-drawer element:
+
+#+begin_src emacs-lisp
+  (property-drawer
+   (:begin 7 :end 136
+    :contents-begin 20 :contents-end 129
+    :post-blank 1 :post-affiliated 7 :parent #1)
+#+end_src
+
+All of the properties except ~:post-blank~ and ~:parent~ refer to
+buffer positions. We'll need to pass in the ~:begin~ position and
+calculate the others. ~:post-affiliated~ is required, but is just
+the same as ~:begin~ for a property-drawer. Here's the documentation
+I found about it:
+
+#+begin_quote
+  Also, :post-affiliated property is attached to all elements.
+  It refers to the buffer position after any affiliated keyword,
+  when applicable, or to the beginning of the element otherwise.
+#+end_quote
+
+We also need to pass in the parent reference, likely as part of
+an ~org-element-map~ function?
+
+#+name: build-property-element
+#+begin_src emacs-lisp :var begin=3 parent="fake" :results code
+  (let* ((len (length ":PROPERTIES:\n:END:\n"))
+         (end (+ begin len))
+	 (contents-begin (+ begin (length ":PROPERTIES:\n")))
+	 (contents-end (+ begin (- end (length "\n:END:\n")))))
+    (list
+     'property-drawer
+     (list :begin begin :end end 
+	   :contents-begin contents-begin :contents-end contents-end
+	   :post-blank 1 :post-affiliated begin :parent parent)))
+#+end_src
+
+#+RESULTS: build-property-element
+#+begin_src emacs-lisp
+(property-drawer
+ (:begin 3 :end 22 :contents-begin 16 :contents-end 18 :post-blank 1 ...))
+#+end_src
+  
 **** DONE Calculate where the property drawer should begin
 
 A property drawer always starts immediately after the headline,