>From d317f25abafe012e0a678ac0c0cc3b372d22113e Mon Sep 17 00:00:00 2001 From: Eric Abrahamsen Date: Sat, 7 Oct 2017 13:01:14 -0700 Subject: [PATCH] New function org-insert-structure-template * lisp/org.el (org-insert-structure-template): New function for wrapping region (or element at point) in a begin/end block. * doc/org.texi (Structure of code blocks, Easy templates): And in manual. * testing/lisp/test-org.el (test-org/insert-template): New test. --- doc/org.texi | 21 +++++++++++++++------ etc/ORG-NEWS | 4 ++++ lisp/org.el | 38 ++++++++++++++++++++++++++++++++++++++ testing/lisp/test-org.el | 42 ++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 99 insertions(+), 6 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index 728e73f87..3a4068ce5 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -15233,12 +15233,13 @@ 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 src code blocks: a template +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: @@ -17409,6 +17410,14 @@ 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 address@hidden C-c C-x t +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 bound to @kbd{C-c C-x t} by default. + @node Speed keys @section Speed keys @cindex speed keys diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS index 1076dd970..d02148e84 100644 --- a/etc/ORG-NEWS +++ b/etc/ORG-NEWS @@ -109,6 +109,10 @@ you should expect to see something like: #+END_EXAMPLE ** New functions +*** ~org-insert-structure-template~ + +This function can be used to wrap existing text of Org elements in +a #+BEGIN_FOO/#+END_FOO block. Bound to C-c C-x t by default. *** ~org-export-excluded-from-toc-p~ diff --git a/lisp/org.el b/lisp/org.el index 99eba2da3..c5f6279d4 100644 --- a/lisp/org.el +++ b/lisp/org.el @@ -12188,6 +12188,43 @@ 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. With an element under +point, wrap the element in the block. Otherwise, insert an empty +block." + (interactive "sBlock type: ") + (unless (use-region-p) + (when (org-element-at-point) + (org-mark-element))) + (let ((s (if (use-region-p) + (region-beginning) + (point))) + (e (copy-marker (if (use-region-p) + (region-end) + (point)) + t)) + column) + (when (string-equal (downcase type) "example") + (org-escape-code-in-region s e)) + (goto-char s) + (setq column (current-indentation)) + (beginning-of-line) + (indent-to column) + (insert (format "#+BEGIN_%s\n" type)) + (goto-char e) + (if (bolp) + (progn + (skip-chars-backward " \n\t") + (forward-line)) + (end-of-line) + (insert "\n")) + (indent-to column) + (insert (format "#+END_%s\n" + type)) + (set-marker e nil))) + ;;;; TODO, DEADLINE, Comments (defun org-toggle-comment () @@ -19651,6 +19688,7 @@ COMMANDS is a list of alternating OLDDEF NEWDEF command names." (org-defkey org-mode-map "\C-c\C-xE" 'org-inc-effort) (org-defkey org-mode-map "\C-c\C-xo" 'org-toggle-ordered-property) (org-defkey org-mode-map "\C-c\C-xi" 'org-columns-insert-dblock) +(org-defkey org-mode-map "\C-c\C-xt" 'org-insert-structure-template) (org-defkey org-mode-map [(control ?c) (control ?x) ?\;] 'org-timer-set-timer) (org-defkey org-mode-map "\C-c\C-x." 'org-timer) diff --git a/testing/lisp/test-org.el b/testing/lisp/test-org.el index fbe053fbb..5c238a75c 100644 --- a/testing/lisp/test-org.el +++ b/testing/lisp/test-org.el @@ -4026,6 +4026,48 @@ Text. (org-next-block 1 nil "^[ \t]*#\\+BEGIN_QUOTE") (looking-at "#\\+begin_quote"))))) +(ert-deftest test-org/insert-template () + "Test `org-insert-structure-template'." + ;; Test in empty buffer. + (should + (string= "#+BEGIN_FOO\n#+END_FOO\n" + (org-test-with-temp-text "" + (org-insert-structure-template "FOO") + (buffer-string)))) + ;; Test with text in buffer, but no region set. + (should + (string= "#+BEGIN_FOO\nI'm a paragraph\n#+END_FOO\n\nI'm a second paragraph" + (org-test-with-temp-text "I'm a paragraph\n\nI'm a second paragraph" + (org-insert-structure-template "FOO") + (buffer-string)))) + ;; Test with text in buffer, no region, no final newline. + (should + (string= "#+BEGIN_FOO\nI'm a paragraph.\n#+END_FOO\n" + (org-test-with-temp-text "I'm a paragraph." + (org-insert-structure-template "FOO") + (buffer-string)))) + ;; Test with text in buffer and region set. + (should + (string= "#+BEGIN_FOO\nI'm a paragraph\n\nI'm a second paragrah\n#+END_FOO\n" + (org-test-with-temp-text "I'm a paragraph\n\nI'm a second paragrah" + (goto-char (point-min)) + (set-mark (point)) + (goto-char (point-max)) + (org-insert-structure-template "FOO") + (buffer-string)))) + ;; Test with example escaping. + (should + (string= "#+BEGIN_EXAMPLE\n,* Heading\n#+END_EXAMPLE\n" + (org-test-with-temp-text "* Heading" + (org-insert-structure-template "EXAMPLE") + (buffer-string)))) + ;; Test with indentation. + (should + (string= " #+BEGIN_FOO\n This is a paragraph\n #+END_FOO\n" + (org-test-with-temp-text " This is a paragraph" + (org-insert-structure-template "FOO") + (buffer-string))))) + (ert-deftest test-org/previous-block () "Test `org-previous-block' specifications." ;; Regular test. -- 2.14.2