>From 0ffb541d10ff4516a869a8c521683e8a6b0a0577 Mon Sep 17 00:00:00 2001
From: Eric Abrahamsen <address@hidden>
Date: Fri, 8 Sep 2017 11:48:45 -0700
Subject: [PATCH] New function org-insert-structure-template

* lisp/org.el (org-insert-structure-template): Wraps the region or
  current element in a #+BEGIN_FOO/#+END_FOO block.
* doc/org.texi: Document.
* etc/ORG-NEWS: Note in news.
---
 doc/org.texi | 21 +++++++++++++++------
 etc/ORG-NEWS |  5 ++++-
 lisp/org.el  | 26 ++++++++++++++++++++++++++
 3 files changed, 45 insertions(+), 7 deletions(-)

diff --git a/doc/org.texi b/doc/org.texi
index f40f458e3..094e9b48b 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -15212,12 +15212,14 @@ A @samp{src} block conforms to this structure:
 #+END_SRC
 @end example
 
-Org mode's templates system (@pxref{Easy templates}) speeds up creating
address@hidden code blocks with just three keystrokes.  Do not be put-off by
-having to remember the source block syntax.  Org also works with other
-completion systems in Emacs, some of which predate Org and have custom
-domain-specific languages for defining templates.  Regular use of templates
-reduces errors, increases accuracy, and maintains consistency.
+Do not be put off by having to remember the source block syntax.  Org mode
+offers two ways of speeding up the creation of @samp{src} code blocks: a
+templates system that can create a new block with just three keystrokes, and
+a command for wrapping existing text in a block (@pxref{Easy templates}).
+Org also works with other completion systems in Emacs, some of which predate
+Org and have custom domain-specific languages for defining templates.
+Regular use of templates reduces errors, increases accuracy, and maintains
+consistency.
 
 @cindex source code, inline
 An inline code block conforms to this structure:
@@ -17388,6 +17390,13 @@ Org comes with these pre-defined easy templates:
 More templates can added by customizing the variable
 @code{org-structure-template-alist}, whose docstring has additional details.
 
address@hidden org-insert-structure-template
+Easy templates are ideal when writing new content, but sometimes it is
+necessary to mark up existing content.  For these cases, Org provides the
+function @code{org-insert-structure-template}, which prompts for a block
+type, and wraps either the active region or the current Org element in that
+block.  This command is not bound to a key by default.
+
 @node Speed keys
 @section Speed keys
 @cindex speed keys
diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index e6ad838a6..3b98a7713 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -38,7 +38,6 @@ Archiving headers through ~org-archive-subtree~ and
 #+END_SRC
 
 Will update the status cookie in the top level header.
-
 *** Disable =org-agenda-overriding-header= by setting to empty string
 
 The ~org-agenda-overriding-header~ inserted into agenda views can now
@@ -57,7 +56,11 @@ size.
 #+BEGIN_EXAMPLE
   ,#+STARTUP: shrink
 #+END_EXAMPLE
+** New functions
+*** ~org-insert-structure-template~
 
+This function can be used to wrap existing text or Org elements in
+a #+BEGIN_FOO/#+END_FOO block.  Not bound to a key by default.
 * Version 9.1
 
 ** Incompatible changes
diff --git a/lisp/org.el b/lisp/org.el
index 8fd01ffb2..2c234de48 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -12215,6 +12215,32 @@ expands them."
     (insert rpl)
     (when (re-search-backward "\\?" start t) (delete-char 1))))
 
+(defun org-insert-structure-template (type)
+  "Insert a block structure of the type #+BEGIN_FOO/#+END_FOO.
+Prompts for a block type, and inserts the block.  With an active
+region, wrap the region in the block."
+  (interactive "sBlock type: ")
+  (unless (use-region-p)
+    (org-mark-element))
+  (let ((s (copy-marker (min (point) (mark))))
+	(e (copy-marker (max (point) (mark)))))
+    (when (string-equal (downcase type) "example")
+      (org-escape-code-in-region s e))
+    (goto-char s)
+    (beginning-of-line)
+    (insert (format "#+BEGIN_%s" type))
+    (newline-and-indent)
+    (goto-char e)
+    (unless (bolp)
+      (end-of-line)
+      (newline-and-indent))
+    (insert (format "#+END_%s" type))
+    (newline-and-indent)
+    (goto-char s)
+    (end-of-line)
+    (set-marker s nil)
+    (set-marker e nil))))
+
 ;;;; TODO, DEADLINE, Comments
 
 (defun org-toggle-comment ()
-- 
2.14.1