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