[PATCH] Allow more control over inserted whitespace in capture templates

[Toby Cubitt <tsc25@cantab.net>]

[-- Attachment #1: Type: text/plain, Size: 3468 bytes --]

When capturing an item as a subheading, the capture template :empty-lines
property is not sufficient to ensure the correct document layout is
maintained after capturing.

This patch fixes the capture behaviour to insert new subheadings
immediately after the previous heading (rather than immediately before
the next one). And it adds new :empty-lines-before and :empty-lines-after
capture template properties. (I can split these two changes into
separated patches, if desired.)

When set, the new :empty-lines-before and :empty-lines-after properties
take precedence over :empty-lines in determining the amount of whitespace
to add before or after the captured item, respectively. Together, these
changes allow the correct document layout to be achieved after capturing,
without any manual editing.

(Since the whole idea of org-capture is to rapidly capture new ideas or
todos, having to manually edit whitespace after capturing to fix the
document layout is far from ideal.)


To give a more detailed example of why I think these changes are needed,
consider for example an org-mode document in which headings are separated
by two empty lines, and subheadings are separated by a single empty
line. (This is a natural layout if one wants headings to be separated by
whitespace when folded, but subheadings not to be separated when folded):

------------------------
* heading 1
** subheading 1.1

** subheading 1.2


* heading 2
** subheading 2.1
------------------------

Let's say I want add a captured item as a new "subheading 1.3" under
"heading 1", preserving this layout structure. Then we need to add the
new item immediately after "subheading 1.2", inserting one empty line
before and two empty lines after. There appears to be no way to do this
using :empty-lines.

In fact, the existing implementation adds the new capture item
immediately *before* the *following* heading ("heading 2" in this case),
which seems to be altogether wrong, as it effectively forces two empty
lines before the new item, regardless of the :empty-lines setting.

Currently, setting :empty-lines to 0 leaves the document looking like
this:

------------------------
* heading 1
** subheading 1.1

** subheading 1.2


** subheading 1.3
* heading 2
** subheading 2.1
------------------------

whilst setting :empty-lines to 1 leaves the document looking like this:

------------------------
* heading 1
** subheading 1.1

** subheading 1.2



** subheading 1.3

* heading 2
** subheading 2.1
------------------------

neither of which are likely to ever be what we want.

With this patch, setting the new :empty-lines-before to 1 and
:empty-lines-after to 2 results in the correct structure after capturing:

------------------------
* heading 1
** subheading 1.1

** subheading 1.2

** subheading 1.3


* heading 2
** subheading 2.1
------------------------


I think this patch is largely orthogonal to the recent "removing
whitespace from new captures" patch (currently in patchwork). That patch
causes `whitespace-cleanup' to be called in the CAPTURE buffer before
finalizing, which doesn't affect the additional whitespace inserted later
on by the :empty-lines property. This patch allows more control over the
latter, by providing a fairly simple extension of the existing
:empty-lines property.

Toby
-- 
Dr T. S. Cubitt
Mathematics and Quantum Information group
Department of Mathematics
Complutense University
Madrid, Spain

email: tsc25@cantab.net
web:   www.dr-qubit.org

[-- Attachment #2: 0001-Capture-Allow-more-control-over-inserted-whitespace-.patch --]
[-- Type: text/x-patch, Size: 3667 bytes --]

From 37cfa6214f0875ed7ddceae27948394cf78d18d6 Mon Sep 17 00:00:00 2001
From: Toby S. Cubitt <tsc25@cantab.net>
Date: Sun, 29 Jan 2012 16:52:08 +0100
Subject: [PATCH] Capture: Allow more control over inserted whitespace in capture templates

* lisp/org-capture.el (org-capture-place-entry): Place captured entry
immediately after last subheading of target, instead of just before
next heading at same level as target.
* lisp/org-capture.el (org-capture-templates): Document new capture
template properties.
* lisp/org-capture.el (org-capture-place-entry,
org-capture-empty-lines-before): Make new :empty-lines-before property
override :empty-lines when inserting empty lines before captured
captured entry.
* lisp/org-capture.el (org-capture-finalize,
org-capture-empty-lines-after): Make new :empty-lines-after property
override :empty-lines when inserting empty lines after captured
captured entry.
---
 lisp/org-capture.el |   19 +++++++++++++++----
 1 files changed, 15 insertions(+), 4 deletions(-)

diff --git a/lisp/org-capture.el b/lisp/org-capture.el
index 01ec85d..d79c5a4 100644
--- a/lisp/org-capture.el
+++ b/lisp/org-capture.el
@@ -183,6 +183,14 @@ properties are:
                      before and after the new item.  Default 0, only common
                      other value is 1.
 
+ :empty-lines-before Set this to the number of lines the should be inserted
+                     before the new item. Overrides :empty-lines for the
+                     number lines inserted before.
+
+ :empty-lines-after  Set this to the number of lines the should be inserted
+                     after the new item. Overrides :empty-lines for the
+                     number of lines inserted after.
+
  :clock-in           Start the clock in this item.
 
  :clock-keep         Keep the clock running when filing the captured entry.
@@ -574,7 +582,8 @@ captured item after finalizing."
 	  (goto-char end)
 	  (or (bolp) (newline))
 	  (org-capture-empty-lines-after
-	   (or (org-capture-get :empty-lines 'local) 0))))
+	   (or (org-capture-get :empty-lines-after 'local)
+	       (org-capture-get :empty-lines 'local) 0))))
       ;; Postprocessing:  Update Statistics cookies, do the sorting
       (when (eq major-mode 'org-mode)
 	(save-excursion
@@ -890,7 +899,7 @@ it.  When it is a variable, retrieve the value.  Return whatever we get."
 	  (progn
 	    (outline-next-heading)
 	    (or (bolp) (insert "\n")))
-	(org-end-of-subtree t t)
+	(org-end-of-subtree t nil)
 	(or (bolp) (insert "\n")))))
     (org-capture-empty-lines-before)
     (setq beg (point))
@@ -1125,7 +1134,8 @@ Of course, if exact position has been required, just put it there."
 (defun org-capture-empty-lines-before (&optional n)
   "Arrange for the correct number of empty lines before the insertion point.
 Point will be after the empty lines, so insertion can directly be done."
-  (setq n (or n (org-capture-get :empty-lines) 0))
+  (setq n (or n (org-capture-get :empty-lines-before)
+	      (org-capture-get :empty-lines) 0))
   (let ((pos (point)))
     (org-back-over-empty-lines)
     (delete-region (point) pos)
@@ -1134,7 +1144,8 @@ Point will be after the empty lines, so insertion can directly be done."
 (defun org-capture-empty-lines-after (&optional n)
   "Arrange for the correct number of empty lines after the inserted string.
 Point will remain at the first line after the inserted text."
-  (setq n (or n (org-capture-get :empty-lines) 0))
+  (setq n (or n (org-capture-get :empty-lines-after)
+	      (org-capture-get :empty-lines) 0))
   (org-back-over-empty-lines)
   (while (looking-at "[ \t]*\n") (replace-match ""))
   (let ((pos (point)))
-- 
1.7.3.4