function for inserting a block

function for inserting a block

[Eric Abrahamsen]

The easy template entry thing is useful as far as it goes, but for some
reason I find myself "marking up" existing text in Org as least as often
as I'm writing new text from scratch. I've always wanted a "wrap region
in block" command, and finally wrote one. Don't know why it took me so
long. Would something like this be attractive for inclusion in Org?

(defun org-insert-structure-template (type start end)
  "Insert a block structure as in #+BEGIN_TYPE/#+END_TYPE.

Prompts for a block TYPE, and inserts the block.  With an active
region, wrap the region in the block."
  (interactive "sBlock type: \nr")
  (let ((s (set-marker (make-marker) start))
	(e (set-marker (make-marker) end)))
   (goto-char s)
   (goto-char (line-beginning-position))
   (insert (format "#+BEGIN_%s\n" (upcase type)))
   (goto-char e)
   (goto-char (line-end-position))
   (insert (format "\n#+END_%s" (upcase type)))))

Other possibilities:

- A "close current block" command, a la `sgml-close-tag'. Inserts
  a #+END_FOO tag if needed.
- Provide completion for the block type prompt, though that might create
  some redundancy with `org-structure-template-alist'.

If this is acceptable, I'd like to bind it to "C-c i", and would provide
docs.

Eric

Re: function for inserting a block

[Adam Porter]

Hi Eric,

Thanks for doing this.  I've had some similar code in my config for a
while.  I'll share some of it here in case you find it useful in doing
this.  You especially might find the org-read-structure-template
function useful.

Note that some of this uses s and hydra, which obviously isn't suitable
for Org proper, but that could be fixed.

#+BEGIN_SRC elisp
(defun ap/org-copy-block (prefix)
    "Copy current \"#+BEGIN_...\" block to the kill-ring."
    (interactive "p")
    (kill-new (ap/org-block-contents (>= prefix 4))))

  (defun ap/org-block-contents (&optional whole)
    "Return contents of current \"BEGIN_...\" block.
When WHOLE is non-nil, include enclosing meta lines."
    (let ((bounds (ap/org-block-boundaries (not whole))))
      (buffer-substring-no-properties (car bounds) (cdr bounds))))

  (defun ap/org-block-boundaries (&optional contents)
    "Return (BEGINNING . END) of current \"#+BEGIN_...\" block.
    If CONTENTS is non-nil, return the boundaries of the block's
    contents rather than the entire block."
    (let ((case-fold-search t)
          (re "#\\+begin_\\(\\sw+\\)")
          block-beg block-end contents-beg contents-end)
      (save-excursion
        ;; Get block
        (unless (looking-at re)
          ;; If point is in the middle of the "#+BEGIN...",
          ;; `search-backward-regexp' fails, so go to end of line first.
          (end-of-line)
          (condition-case nil
              (search-backward-regexp re)
            (error "Not in a block.")))
        (setq block-beg (point))
        (setq block-end (search-forward-regexp (concat (rx bol (optional (1+ space)) "#+end_") (match-string 1))))
        (goto-char block-beg)
        (forward-line)
        (setq contents-beg (point))
        (goto-char block-end)
        (end-of-line 0)
        (setq contents-end (point)))
      (if contents
          `(,contents-beg . ,contents-end)
        `(,block-beg . ,block-end))))

  (defun ap/org-read-structure-template ()
    "Read org-mode structure template with completion.  Returns template string."
    (let* ((templates (map 'list 'second org-structure-template-alist))
           (prefixes (map 'list (lambda (tp)
                                  ;; Get template and pre-whitespace prefix for completion
                                  (reverse (s-match (rx (group
                                                         (1+ (not (any "\n" space))))
                                                        (1+ anything))
                                                    tp)))
                          templates))
           (prefix (completing-read "Template: " prefixes nil t))
           (template (second (assoc prefix prefixes))))
      template))

  (defun ap/org-in-block-p ()
    "Non-nil when point belongs to a block.

Return first block name matched, or nil.  Beware that in case of
nested blocks, the returned name may not belong to the closest
block from point."
    (save-match-data
      (let ((case-fold-search t)
            (lim-up (save-excursion (outline-previous-heading)))
            (lim-down (save-excursion (outline-next-heading))))
        (org-between-regexps-p "^[ \t]*#\\+begin_" "^[ \t]*#\\+end_"
                               lim-up lim-down))))

  (defun ap/org-indent-src-block ()
    (interactive)
    (when (ap/org-in-block-p)
      (org-edit-src-code)
      (insert (replace-regexp-in-string
               " +" " " (delete-and-extract-region (point-min) (point-max))))
      (ap/indent-whole-buffer)
      (whitespace-cleanup)
      (org-edit-src-exit)))

  (defun ap/org-insert-structure-template-or-enclose-region ()
    "Insert structure block template.  When region is active, enclose region in block."
    (require 's)
    (interactive)
    (let* ((template (ap/org-read-structure-template))
           (text "")
           enclosed-text)
      (when (use-region-p)
        (setq text (buffer-substring-no-properties (region-beginning) (region-end)))
        (delete-region (region-beginning) (region-end)))
      (setq enclosed-text (s-replace "?" text template))
      (insert enclosed-text)
      (backward-char (- (length enclosed-text) (length (s-shared-start enclosed-text template))))))

  (defun ap/org-change-block-types ()
    "Change the type of org-mode block at point, or blocks in region."
    (interactive)
    (if (use-region-p)
        (progn
          (deactivate-mark)
          (goto-char (region-beginning))
          (while (re-search-forward  "^ *#\\+BEGIN_" (region-end) nil)
            (ap/org-change-block-type-at-point)))
      (ap/org-change-block-type-at-point)))

  (defun ap/org-change-block-type-at-point ()
    "Change type of org-mode block at point."
    (interactive)
    (unless (ap/org-in-block-p)
      (error "Not in an org-mode block."))
    (let* ((template (ap/org-read-structure-template))
           (case-fold-search t)
           (re "#\\+begin_\\(\\sw+\\)")
           (block-bounds (ap/org-block-boundaries))
           (block-beg (car block-bounds))
           (block-end (cdr block-bounds))
           (contents (ap/org-block-contents))
           new-block)
      ;; Insert contents into template
      (setq new-block (replace-regexp-in-string (rx "?") contents template))
      ;; Remove extra newline from e.g. SRC blocks
      (setq new-block (replace-regexp-in-string (rx "\n\n#+END") "\n#+END" new-block))
      ;; Replace old block with new one
      (goto-char block-beg)
      (delete-region block-beg block-end)
      (insert new-block)
      ;; Position cursor (especially for SRC blocks, allowing the user to enter the type)
      (search-backward-regexp re)
      (search-forward-regexp (rx space))))

;; From https://github.com/abo-abo/hydra/wiki/Org-mode-block-templates
;; With "<" bound to ap/hydra-org-expand-block-template in org-mode-map:

(defhydra hydra-org-block-template (:color blue :hint nil)
  "
   _c_enter _q_uote _e_macs-lisp _L_aTeX:
   _l_atex _E_xample _p_erl _i_ndex:
   _a_scii _v_erse _P_erl tangled _I_NCLUDE:
   _s_rc ^ ^ plant_u_ml _H_TML:
   _h_tml ^ ^ ^ ^ _A_SCII:
   "
  ("s" (ap/org-hydra-expand-template "<s"))
  ("E" (ap/org-hydra-expand-template "<e"))
  ("q" (ap/org-hydra-expand-template "<q"))
  ("v" (ap/org-hydra-expand-template "<v"))
  ("c" (ap/org-hydra-expand-template "<c"))
  ("l" (ap/org-hydra-expand-template "<l"))
  ("h" (ap/org-hydra-expand-template "<h"))
  ("a" (ap/org-hydra-expand-template "<a"))
  ("L" (ap/org-hydra-expand-template "<L"))
  ("i" (ap/org-hydra-expand-template "<i"))
  ("e" (ap/org-hydra-expand-template "<s" "elisp"))
  ("p" (ap/org-hydra-expand-template "<s" "perl"))
  ("u" (ap/org-hydra-expand-template "<s" "plantuml :file CHANGE.png"))
  ("P" (progn
         (insert "#+HEADERS: :results output :exports both :shebang \"#!/usr/bin/env perl\"\n")
         (ap/org-hydra-expand-template "<s" "perl")))
  ("I" (ap/org-hydra-expand-template "<I"))
  ("H" (ap/org-hydra-expand-template "<H"))
  ("A" (ap/org-hydra-expand-template "<A"))
  ("<" self-insert-command "ins")
  ("o" nil "quit"))

(defun ap/hydra-org-expand-block-template ()
    (interactive)
    (if (or (use-region-p) (looking-back "^"))
        (hydra-org-block-template/body)
      (self-insert-command 1)))

(defun ap/org-hydra-expand-template (str &optional mod)
  "Expand org template."
  (let (text)
    (when (use-region-p)
      (setq text (buffer-substring (region-beginning) (region-end)))
      (delete-region (region-beginning) (region-end)))
    (insert str)
    (org-try-structure-completion)
    (when mod (insert mod) (forward-line))
    (when text (insert text))))
#+END_SRC

Re: function for inserting a block

[Kaushal Modi]

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

On Sat, Sep 2, 2017, 10:23 PM Adam Porter <adam@alphapapa.net> wrote:

> Hi Eric,
>
> Thanks for doing this.  I've had some similar code in my config for a
> while.  I'll share some of it here in case you find it useful in doing
> this.  You especially might find the org-read-structure-template
> function useful.
>

And here's my version, which also uses hydra. But the function
modi/org-template-expand to insert the BEGIN_../END_.. blocks can be
reused.

This at least tells that there's a good need to have the easy template do
the right thing when it is called with a region selected.

@Adam: Looks like your code is doing a lot more than just that. I'll put
that to my list to understand once I get to a computer.

>
    (defun modi/org-template-expand (str &optional lang)
      "Expand Org template."
      (let (beg old-beg end content)
        ;; Save restriction to automatically undo the upcoming
`narrow-to-region'
        (save-restriction
          (when (use-region-p)
            (setq beg (region-beginning))
            (setq end (region-end))
            ;; Note that regardless of the direction of selection, we
will always
            ;; have (region-beginning) < (region-end).
            (save-excursion
              ;; If `point' is at `end', exchange point and mark so that now the
              ;; `point' is now at `beg'
              (when (> (point) (mark))
                (exchange-point-and-mark))
              ;; Insert a newline if `beg' is *not* at beginning of the line.
              ;; Example: You have ^abc$ where ^ is bol and $ is eol.
              ;;          "bc" is selected and <e is pressed to result in:
              ;;            a
              ;;            #+BEGIN_EXAMPLE
              ;;            bc
              ;;            #+END_EXAMPLE
              (when (/= beg (line-beginning-position))
                (electric-indent-just-newline 1)
                (setq old-beg beg)
                (setq beg (point))
                ;; Adjust the `end' due to newline
                (setq end (+ end (- beg old-beg)))))
            (save-excursion
              ;; If `point' is at `beg', exchange point and mark so that now the
              ;; `point' is now at `end'
              (when (< (point) (mark))
                (exchange-point-and-mark))
              ;; If the `end' position is at the beginning of a line decrement
              ;; the position by 1, so that the resultant position is eol on
              ;; the previous line.
              (when (= end (line-beginning-position))
                (setq end (1- end)))
              ;; Insert a newline if `point'/`end' is *not* at end of the line.
              ;; Example: You have ^abc$ where ^ is bol and $ is eol.
              ;;          "a" is selected and <e is pressed to result in:
              ;;            #+BEGIN_EXAMPLE
              ;;            a
              ;;            #+END_EXAMPLE
              ;;            bc
              (when (not (looking-at "[[:blank:]]*$"))
                (electric-indent-just-newline 1)))
            ;; Narrow to region so that the text surround the region does
            ;; not mess up the upcoming `org-try-structure-completion' eval
            (narrow-to-region beg end)
            (setq content (delete-and-extract-region beg end)))
          (insert str)
          (org-try-structure-completion)
          (when (string= "<s" str)
            (cond
             (lang
              (insert lang)
              (forward-line))
             ((and content (not lang))
              (insert "???")
              (forward-line))
             (t
              )))
          ;; At this point the cursor will be between the #+BEGIN and
#+END lines
          (when content
            (insert content)
            (deactivate-mark)))))

    (defhydra hydra-org-template (:color blue
                                  :hint nil)
      "
org-template:  _c_enter        _s_rc          _e_xample
_v_erilog        _t_ext           _I_NCLUDE:
               _l_atex         _h_tml         _V_erse
_m_atlab         _L_aTeX:         _H_TML:
               _a_scii         _q_uote        _E_macs-lisp
_n_im            _i_ndex:         _A_SCII:
               ^^              ^^             _S_hell
_p_ython         ^^               ^^
"
      ("s" (modi/org-template-expand "<s")) ;#+BEGIN_SRC ... #+END_SRC
      ("E" (modi/org-template-expand "<s" "emacs-lisp"))
      ("v" (modi/org-template-expand "<s" "systemverilog"))
      ("m" (modi/org-template-expand "<s" "matlab"))
      ("n" (modi/org-template-expand "<s" "nim"))
      ("S" (modi/org-template-expand "<s" "shell"))
      ("p" (modi/org-template-expand "<s" "python"))
      ("t" (modi/org-template-expand "<s" "text"))
      ("e" (modi/org-template-expand "<e")) ;#+BEGIN_EXAMPLE ... #+END_EXAMPLE
      ("x" (modi/org-template-expand "<e")) ;#+BEGIN_EXAMPLE ... #+END_EXAMPLE
      ("q" (modi/org-template-expand "<q")) ;#+BEGIN_QUOTE ... #+END_QUOTE
      ("V" (modi/org-template-expand "<v")) ;#+BEGIN_VERSE ... #+END_VERSE
      ("c" (modi/org-template-expand "<c")) ;#+BEGIN_CENTER ... #+END_CENTER
      ("l" (modi/org-template-expand "<l")) ;#+BEGIN_EXPORT latex ...
#+END_EXPORT
      ("L" (modi/org-template-expand "<L")) ;#+LaTeX:
      ("h" (modi/org-template-expand "<h")) ;#+BEGIN_EXPORT html ...
#+END_EXPORT
      ("H" (modi/org-template-expand "<H")) ;#+HTML:
      ("a" (modi/org-template-expand "<a")) ;#+BEGIN_EXPORT ascii ...
#+END_EXPORT
      ("A" (modi/org-template-expand "<A")) ;#+ASCII:
      ("i" (modi/org-template-expand "<i")) ;#+INDEX: line
      ("I" (modi/org-template-expand "<I")) ;#+INCLUDE: line
      ("<" self-insert-command "<")
      ("o" nil "quit"))

    (defun modi/org-template-maybe ()
      "Insert org-template if point is at the beginning of the line, or is a
region is selected. Else call `self-insert-command'."
      (interactive)
      (let ((regionp (use-region-p)))
        (if (or regionp
                (and (not regionp)
                     (looking-back "^")))
            (hydra-org-template/body)
          (self-insert-command 1))))

[-- Attachment #2: Type: text/html, Size: 7927 bytes --]

Re: function for inserting a block

[Eric Abrahamsen]

Kaushal Modi <kaushal.modi@gmail.com> writes:

> On Sat, Sep 2, 2017, 10:23 PM Adam Porter <adam@alphapapa.net> wrote:
>
>  Hi Eric,
>
>  Thanks for doing this.  I've had some similar code in my config for a
>  while.  I'll share some of it here in case you find it useful in doing
>  this.  You especially might find the org-read-structure-template
>  function useful.
>
> And here's my version, which also uses hydra. But the function modi/org-template-expand to insert the BEGIN_../END_.. blocks can be reused. 
>
> This at least tells that there's a good need to have the easy template do the right thing when it is called with a region selected. 

That's the vast majority of what I wanted. So long as we've got that,
and it doesn't depend on random other packages, I'm happy.

Re: function for inserting a block

[Nicolas Goaziou]

Hello,

Eric Abrahamsen <eric@ericabrahamsen.net> writes:

> The easy template entry thing is useful as far as it goes, but for some
> reason I find myself "marking up" existing text in Org as least as often
> as I'm writing new text from scratch. I've always wanted a "wrap region
> in block" command, and finally wrote one. Don't know why it took me so
> long. Would something like this be attractive for inclusion in Org?

Thanks. I agree Org needs something like this.

> (defun org-insert-structure-template (type start end)
>   "Insert a block structure as in #+BEGIN_TYPE/#+END_TYPE.
>
> Prompts for a block TYPE, and inserts the block.  With an active
> region, wrap the region in the block."
>   (interactive "sBlock type: \nr")
>   (let ((s (set-marker (make-marker) start))
> 	(e (set-marker (make-marker) end)))

(set-marker (make-marker) start) -> (copy-marker start)

You need to clean these markers at the end of the function. Markers set
to a position are never garbage-collected. Usually, it happens at the
end of an `unwind-protect'.

>    (goto-char s)
>    (goto-char (line-beginning-position))
>    (insert (format "#+BEGIN_%s\n" (upcase type)))

(upcase type) is wrong, because special blocks are case sensitive.

>    (goto-char e)
>    (goto-char (line-end-position))

(end-of-line) ?

>    (insert (format "\n#+END_%s" (upcase type)))))

The function also needs to take care about global indentation. Inserting
at column 0 may not be desirable.

What happens if no region is active? Can it mark the element at point
(see `org-mark-element')? What happens if the chosen type is verbatim
(e.g. "example"), can it protect "#+", "*" and so on with commas (see
`org-escape-code-in-region')?

> If this is acceptable, I'd like to bind it to "C-c i", and would provide
> docs.

We cannot bind it to "C-c i", this is a reserved key-binding. But we can
suggest users to do so in the manual. Or find another binding.


Regards,

-- 
Nicolas Goaziou

Re: function for inserting a block

[Adam Porter]

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> You need to clean these markers at the end of the function. Markers set
> to a position are never garbage-collected. Usually, it happens at the
> end of an `unwind-protect'.

Not that I oppose cleaning up markers after you're done with them, but
are they actually never collected?  The manual says:

"...it is a good idea to make a marker point nowhere if you are sure you
don’t need it any more.  Markers that can no longer be accessed are
eventually removed (*note Garbage Collection::)."

I asked on /r/emacs about this but never got a firm answer; some thought
that they are never collected and require manual clearing, others
thought that ones that go out-of-scope are eventually collected and that
it's not typically necessary to clear them manually.  I also recall
seeing some code recently that didn't manually clear the markers it
created, so I wonder if that is true.

Re: function for inserting a block

[Nicolas Goaziou]

Adam Porter <adam@alphapapa.net> writes:

> "...it is a good idea to make a marker point nowhere if you are sure you
> don’t need it any more.  Markers that can no longer be accessed are
> eventually removed (*note Garbage Collection::)."
>
> I asked on /r/emacs about this but never got a firm answer; some thought
> that they are never collected and require manual clearing, others
> thought that ones that go out-of-scope are eventually collected and that
> it's not typically necessary to clear them manually.  I also recall
> seeing some code recently that didn't manually clear the markers it
> created, so I wonder if that is true.

The are not collected as long as the buffer they point to is alive. If
they are not attached to any buffer, they are marked for garbage
collection.

Regards,

Re: function for inserting a block

[Eric Abrahamsen]

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Hello,
>
> Eric Abrahamsen <eric@ericabrahamsen.net> writes:
>
>> The easy template entry thing is useful as far as it goes, but for some
>> reason I find myself "marking up" existing text in Org as least as often
>> as I'm writing new text from scratch. I've always wanted a "wrap region
>> in block" command, and finally wrote one. Don't know why it took me so
>> long. Would something like this be attractive for inclusion in Org?
>
> Thanks. I agree Org needs something like this.
>
>> (defun org-insert-structure-template (type start end)
>>   "Insert a block structure as in #+BEGIN_TYPE/#+END_TYPE.
>>
>> Prompts for a block TYPE, and inserts the block.  With an active
>> region, wrap the region in the block."
>>   (interactive "sBlock type: \nr")
>>   (let ((s (set-marker (make-marker) start))
>> 	(e (set-marker (make-marker) end)))
>
> (set-marker (make-marker) start) -> (copy-marker start)
>
> You need to clean these markers at the end of the function. Markers set
> to a position are never garbage-collected. Usually, it happens at the
> end of an `unwind-protect'.

Okay.

>>    (goto-char s)
>>    (goto-char (line-beginning-position))
>>    (insert (format "#+BEGIN_%s\n" (upcase type)))
>
> (upcase type) is wrong, because special blocks are case sensitive.

I discovered that the moment I started using it!

>>    (goto-char e)
>>    (goto-char (line-end-position))
>
> (end-of-line) ?

Bah, I can never keep track of what's available.

>>    (insert (format "\n#+END_%s" (upcase type)))))
>
> The function also needs to take care about global indentation. Inserting
> at column 0 may not be desirable.
>
> What happens if no region is active? Can it mark the element at point
> (see `org-mark-element')? What happens if the chosen type is verbatim
> (e.g. "example"), can it protect "#+", "*" and so on with commas (see
> `org-escape-code-in-region')?

The "r" interactive code just isn't that useful, I wish it wouldn't
raise an error.

Here's another stab at it. Is "example" the only block that should be
verbatim? Will using `newline-and-indent' instead of inserting literal
newlines solve the indentation problem?


(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 no active region, wrap the
current element."
  (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)
    (set-marker s nil)
    (set-marker e nil)))

>> If this is acceptable, I'd like to bind it to "C-c i", and would provide
>> docs.
>
> We cannot bind it to "C-c i", this is a reserved key-binding. But we can
> suggest users to do so in the manual. Or find another binding.

That's fine. Incidentally, why is "C-c i" reserved? It's not bound to
anything here. Does it look like <TAB> in terminal Emacs?

Eric

Re: function for inserting a block

[Josiah Schwab]

Hi Eric,

>> We cannot bind it to "C-c i", this is a reserved key-binding. But we can
>> suggest users to do so in the manual. Or find another binding.
>
> That's fine. Incidentally, why is "C-c i" reserved? It's not bound to
> anything here. Does it look like <TAB> in terminal Emacs?

The keybinding convention docs say:

Don't define C-c letter as a key in Lisp programs. Sequences consisting
of C-c and a letter (either upper or lower case) are reserved for users;
they are the only sequences reserved for users, so do not block them.

See https://www.gnu.org/software/emacs/manual/html_node/elisp/Key-Binding-Conventions.html

Josiah

Re: function for inserting a block

[Eric Abrahamsen]

Josiah Schwab <jschwab@gmail.com> writes:

> Hi Eric,
>
>>> We cannot bind it to "C-c i", this is a reserved key-binding. But we can
>>> suggest users to do so in the manual. Or find another binding.
>>
>> That's fine. Incidentally, why is "C-c i" reserved? It's not bound to
>> anything here. Does it look like <TAB> in terminal Emacs?
>
> The keybinding convention docs say:
>
> Don't define C-c letter as a key in Lisp programs. Sequences consisting
> of C-c and a letter (either upper or lower case) are reserved for users;
> they are the only sequences reserved for users, so do not block them.
>
> See https://www.gnu.org/software/emacs/manual/html_node/elisp/Key-Binding-Conventions.html

Erm, I'd be surprised if there's a single Org mode binding that
*doesn't* start with C-c. That convention is right out the window with
Org...

Re: function for inserting a block

[Josiah Schwab]

Hi Eric,

> Erm, I'd be surprised if there's a single Org mode binding that
> *doesn't* start with C-c. That convention is right out the window with
> Org...

To be clear, this is referring to C-c and then a single ASCII letter,
not just any binding that starts with C-c.

The manual /suggests/ globally binding things to C-c a, C-c b, C-c c and
C-c l, and then proceeds as if you have, but I really don't think it is
correct to say this convention is out the window.

Josiah

Re: function for inserting a block

[Eric Abrahamsen]

Josiah Schwab <jschwab@gmail.com> writes:

> Hi Eric,
>
>> Erm, I'd be surprised if there's a single Org mode binding that
>> *doesn't* start with C-c. That convention is right out the window with
>> Org...
>
> To be clear, this is referring to C-c and then a single ASCII letter,
> not just any binding that starts with C-c.
>
> The manual /suggests/ globally binding things to C-c a, C-c b, C-c c and
> C-c l, and then proceeds as if you have, but I really don't think it is
> correct to say this convention is out the window.
>
> Josiah

I stand corrected! I hadn't realized the conventions were that narrowly
defined, and now I see that Org indeed doesn't bind "C-c [a-zA-Z]".
Thanks for pointing that out.

Eric

Re: function for inserting a block

[Eric Abrahamsen]

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

Eric Abrahamsen <eric@ericabrahamsen.net> writes:

[...]

> Here's another stab at it. Is "example" the only block that should be
> verbatim? Will using `newline-and-indent' instead of inserting literal
> newlines solve the indentation problem?
>
>
> (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 no active region, wrap the
> current element."
>   (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)
>     (set-marker s nil)
>     (set-marker e nil)))

And here's an actual patch, with docs.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-New-function-org-insert-structure-template.patch --]
[-- Type: text/x-diff, Size: 4344 bytes --]

From 0ffb541d10ff4516a869a8c521683e8a6b0a0577 Mon Sep 17 00:00:00 2001
From: Eric Abrahamsen <eric@ericabrahamsen.net>
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
-@samp{src} 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.
 
+@findex 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

Re: function for inserting a block

[Nicolas Goaziou]

Hello,

Eric Abrahamsen <eric@ericabrahamsen.net> writes:

> And here's an actual patch, with docs.

Thank you! Some comments follow.

> +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.

Some free key bindings:
- C-c C-x C-e
- C-c C-x C-g
- C-c C-x C-h
- C-c C-x C-k
- C-c C-x h
- C-c C-x j
- C-c C-x k
- C-c C-x l
- C-c C-x m
- C-c C-x n
- C-c C-x r
- C-c C-x s
- C-c C-x t
- C-c C-x u
- C-c C-x w
- C-c C-x x
- C-c C-x y
- C-c C-x z

For the record, `C-c C-x C-f' is `org-emphasize', which is related.

> +(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)))))

Use:

  (region-beginning)
  (region-end)

not

  (mark)

If there is no active region, is it better to mark element or to create
an empty block at point?

> +    (when (string-equal (downcase type) "example")
> +      (org-escape-code-in-region s e))
> +    (goto-char s)
> +    (beginning-of-line)
> +    (insert (format "#+BEGIN_%s" type))

I would store current indentation here and insert it in front of the
block openening, and closing, line. In any case, I would not use
`newline-and-indent' which could do unrelated stuff (e.g., re-indenting
a whole part of the buffer).

> +    (newline-and-indent)
> +    (goto-char e)
> +    (unless (bolp)
> +      (end-of-line)
> +      (newline-and-indent))
> +    (insert (format "#+END_%s" type))
> +    (newline-and-indent)

See above.

> +    (goto-char s)
> +    (end-of-line)

Why going to S? Initial position might be at the end of the region.

Also, could you write some tests along with your function?

Regards,

-- 
Nicolas Goaziou

Re: function for inserting a block

[Eric Abrahamsen]

On 09/10/17 14:44 PM, Nicolas Goaziou wrote:

[...]

> Some free key bindings:
> - C-c C-x C-e
> - C-c C-x C-g
> - C-c C-x C-h
> - C-c C-x C-k
> - C-c C-x h
> - C-c C-x j
> - C-c C-x k
> - C-c C-x l
> - C-c C-x m
> - C-c C-x n
> - C-c C-x r
> - C-c C-x s
> - C-c C-x t
> - C-c C-x u
> - C-c C-x w
> - C-c C-x x
> - C-c C-x y
> - C-c C-x z
>
> For the record, `C-c C-x C-f' is `org-emphasize', which is related.

How about `C-c C-x C-t', for "template"?

>> +(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)))))
>
> Use:
>
>   (region-beginning)
>   (region-end)
>
> not
>
>   (mark)

Whoops.

> If there is no active region, is it better to mark element or to create
> an empty block at point?

That was your suggestion! :) We've already got easy templates for
creating an empty block, so it seemed like a good one.

>> +    (when (string-equal (downcase type) "example")
>> +      (org-escape-code-in-region s e))
>> +    (goto-char s)
>> +    (beginning-of-line)
>> +    (insert (format "#+BEGIN_%s" type))
>
> I would store current indentation here and insert it in front of the
> block openening, and closing, line. In any case, I would not use
> `newline-and-indent' which could do unrelated stuff (e.g., re-indenting
> a whole part of the buffer).

Gotcha, I was not sure about that part.

>> +    (newline-and-indent)
>> +    (goto-char e)
>> +    (unless (bolp)
>> +      (end-of-line)
>> +      (newline-and-indent))
>> +    (insert (format "#+END_%s" type))
>> +    (newline-and-indent)
>
> See above.
>
>> +    (goto-char s)
>> +    (end-of-line)
>
> Why going to S? Initial position might be at the end of the region.

I was just thinking that a common use-case would be to add more
options/arguments to the block beginning. I don't mind much either way.

> Also, could you write some tests along with your function?

Will do.

Re: function for inserting a block

[Nicolas Goaziou]

Hello,

Eric Abrahamsen <eric@ericabrahamsen.net> writes:

> On 09/10/17 14:44 PM, Nicolas Goaziou wrote:
>
> [...]
>
>> Some free key bindings:
>> - C-c C-x C-e
>> - C-c C-x C-g
>> - C-c C-x C-h
>> - C-c C-x C-k
>> - C-c C-x h
>> - C-c C-x j
>> - C-c C-x k
>> - C-c C-x l
>> - C-c C-x m
>> - C-c C-x n
>> - C-c C-x r
>> - C-c C-x s
>> - C-c C-x t
>> - C-c C-x u
>> - C-c C-x w
>> - C-c C-x x
>> - C-c C-x y
>> - C-c C-x z
>>
>> For the record, `C-c C-x C-f' is `org-emphasize', which is related.
>
> How about `C-c C-x C-t', for "template"?

C-c C-x C-t is `org-toggle-time-stamp-overlays'. I listed all free
keybindings following the scheme 

  C-c C-x C-<LETTER>

or

  C-c C-x <LETTER>

C-c C-x t is free, tho.

Regards,

-- 
Nicolas Goaziou

Re: function for inserting a block

[Eric Abrahamsen]

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

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:


[...]

> C-c C-x t is free, tho.

Oops, I think that's what I meant to type. Here's the latest version of
the patch -- I removed the bit fooling with the location of point at the
end, as it seemed simpler was better. How's this look?

Eric


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-New-function-org-insert-structure-template.patch --]
[-- Type: text/x-diff, Size: 4655 bytes --]

From b8636d918e9ff79cac320003361c5a16846f156c Mon Sep 17 00:00:00 2001
From: Eric Abrahamsen <eric@ericabrahamsen.net>
Date: Sat, 30 Sep 2017 13:23:05 -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.
* etc/ORG-NEWS: Mention in news.
* doc/org.texi (Structure of code blocks, Easy templates): And in
  manual.
---
 doc/org.texi | 21 +++++++++++++++------
 etc/ORG-NEWS |  5 +++++
 lisp/org.el  | 25 +++++++++++++++++++++++++
 3 files changed, 45 insertions(+), 6 deletions(-)

diff --git a/doc/org.texi b/doc/org.texi
index 1c79d8330..2274e584a 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -15215,12 +15215,14 @@ A @samp{src} block conforms to this structure:
 #+END_SRC
 @end example
 
-Org mode's templates system (@pxref{Easy templates}) speeds up creating
-@samp{src} 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:
@@ -17391,6 +17393,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.
 
+@findex 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 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 7c69efa89..1a3aa9e92 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -105,6 +105,11 @@ you should expect to see something like:
   ,#+STARTUP: shrink
 #+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.
 ** Miscellaneous
 
 *** ~org-publish-resolve-external-link~ accepts a new optional argument.
diff --git a/lisp/org.el b/lisp/org.el
index 1ffea80fe..fe7bfd1c5 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -12199,6 +12199,30 @@ 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)
+    (set-marker s nil)
+    (set-marker e nil))))
+
 ;;;; TODO, DEADLINE, Comments
 
 (defun org-toggle-comment ()
@@ -19660,6 +19684,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)
-- 
2.14.2

Re: function for inserting a block

[Nicolas Goaziou]

Hello,

Eric Abrahamsen <eric@ericabrahamsen.net> writes:

> Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:
>
>
> [...]
>
>> C-c C-x t is free, tho.
>
> Oops, I think that's what I meant to type. Here's the latest version of
> the patch -- I removed the bit fooling with the location of point at the
> end, as it seemed simpler was better. How's this look?

`newline-and-indent' and `mark' shouldn't be used in the function.

Otherwise, it looks good. Could you provide some tests for that in
"test-org.el"?

Thank you.

Regards,

-- 
Nicolas Goaziou

Re: function for inserting a block

[Eric Abrahamsen]

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

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Hello,
>
> Eric Abrahamsen <eric@ericabrahamsen.net> writes:
>
>> Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:
>>
>>
>> [...]
>>
>>> C-c C-x t is free, tho.
>>
>> Oops, I think that's what I meant to type. Here's the latest version of
>> the patch -- I removed the bit fooling with the location of point at the
>> end, as it seemed simpler was better. How's this look?
>
> `newline-and-indent' and `mark' shouldn't be used in the function.

This must be a personal record for number of screw-ups in a single
commit... That was an old version from a different computer.

But still, I'm not entirely confident about the indentation handling.
This is my best guess -- it seems to work, and doesn't get confused by
`org-indent-mode'.

> Otherwise, it looks good. Could you provide some tests for that in
> "test-org.el"?

How does this look?

Eric


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-New-function-org-insert-structure-template.patch --]
[-- Type: text/x-diff, Size: 6970 bytes --]

From d859c241053aef2dd2f2a9b04f4030de54eb330d Mon Sep 17 00:00:00 2001
From: Eric Abrahamsen <eric@ericabrahamsen.net>
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.
* etc/ORG-NEWS: Mention in news.
* 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             |  5 +++++
 lisp/org.el              | 40 ++++++++++++++++++++++++++++++++++++++++
 testing/lisp/test-org.el | 36 ++++++++++++++++++++++++++++++++++++
 4 files changed, 96 insertions(+), 6 deletions(-)

diff --git a/doc/org.texi b/doc/org.texi
index fd26d9790..fd537ded4 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -15215,12 +15215,14 @@ A @samp{src} block conforms to this structure:
 #+END_SRC
 @end example
 
-Org mode's templates system (@pxref{Easy templates}) speeds up creating
-@samp{src} 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:
@@ -17391,6 +17393,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.
 
+@findex 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 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 53d604b8c..ed487b20f 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -105,6 +105,11 @@ you should expect to see something like:
   ,#+STARTUP: shrink
 #+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.
 ** Miscellaneous
 
 *** ~org-publish-resolve-external-link~ accepts a new optional argument.
diff --git a/lisp/org.el b/lisp/org.el
index 5a60e34cb..f888af09c 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -12199,6 +12199,45 @@ 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 (copy-marker (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))
+    (back-to-indentation)
+    (insert (format "#+BEGIN_%s\n"
+		    type))
+    (indent-to column)
+    (goto-char e)
+    (if (bolp)
+	(progn
+	  (skip-chars-backward " \n\t")
+	  (forward-char))
+      (end-of-line)
+      (insert "\n"))
+    (indent-to column)
+    (insert (format "#+END_%s\n"
+		    type))
+    (set-marker s nil)
+    (set-marker e nil)))
+
 ;;;; TODO, DEADLINE, Comments
 
 (defun org-toggle-comment ()
@@ -19662,6 +19701,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 a185cff1f..35bcfa309 100644
--- a/testing/lisp/test-org.el
+++ b/testing/lisp/test-org.el
@@ -4022,6 +4022,42 @@ 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 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

Re: function for inserting a block

[Nicolas Goaziou]

Hello,

Eric Abrahamsen <eric@ericabrahamsen.net> writes:

> How does this look?

Thank you! I have some questions and remarks.

> * etc/ORG-NEWS: Mention in news.

This doesn't need to be added to the commit message.

> +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:

  src code blocks

is enough, IMO. There are may of them across the manual, and it just
makes reading more tedious.

> +@findex org-insert-structure-template

I would also add

  @kindex C-c C-x t

> +  (let ((s (copy-marker (if (use-region-p)
> +			    (region-beginning)
> +			  (point))))

Does it really need to be a marker? AFAICT, nothing really changes this
position.

> +    (back-to-indentation)
> +    (insert (format "#+BEGIN_%s\n"
> +		    type))
> +    (indent-to column)

What about

  (beginning-of-line)
  (indent-to column)
  (insert (format "#+BEGIN_%s\n" type))

?

It avoids `back-to-indentation'.

> +    (if (bolp)
> +	(progn
> +	  (skip-chars-backward " \n\t")
> +	  (forward-char))
> +      (end-of-line)
> +      (insert "\n"))

I don't understand this part. In particular, the `forward-char' looks
wrong. Do you mean `forward-line' ? If so, do you handle the case where
buffer doesn't end with a newline character?

> +    (set-marker s nil)

See above.

Regards,

-- 
Nicolas Goaziou

Re: function for inserting a block

[Eric Abrahamsen]

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Hello,
>
> Eric Abrahamsen <eric@ericabrahamsen.net> writes:
>
>> How does this look?
>
> Thank you! I have some questions and remarks.
>
>> * etc/ORG-NEWS: Mention in news.
>
> This doesn't need to be added to the commit message.
>
>> +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:
>
>   src code blocks
>
> is enough, IMO. There are may of them across the manual, and it just
> makes reading more tedious.
>
>> +@findex org-insert-structure-template
>
> I would also add
>
>   @kindex C-c C-x t
>
>> +  (let ((s (copy-marker (if (use-region-p)
>> +			    (region-beginning)
>> +			  (point))))
>
> Does it really need to be a marker? AFAICT, nothing really changes this
> position.
>
>> +    (back-to-indentation)
n>> +    (insert (format "#+BEGIN_%s\n"
>> +		    type))
>> +    (indent-to column)
>
> What about
>
>   (beginning-of-line)
>   (indent-to column)
>   (insert (format "#+BEGIN_%s\n" type))
>
> ?
>
> It avoids `back-to-indentation'.

Cool, I will make all of the above changes, thanks for the notes.

>> +    (if (bolp)
>> +	(progn
>> +	  (skip-chars-backward " \n\t")
>> +	  (forward-char))
>> +      (end-of-line)
>> +      (insert "\n"))
>
> I don't understand this part. In particular, the `forward-char' looks
> wrong. Do you mean `forward-line' ? If so, do you handle the case where
> buffer doesn't end with a newline character?

This was a bit of finicky code mostly for aesthetic purposes. It has to
do with this case (the second clause in the test I added):

#+BEGIN_SRC org
This is a paragraph

This is another paragraph
#+END_SRC

If point is on the first paragraph and the region is not active,
`org-mark-element' will mark the paragraph and all following whitespace,
which means we end up with:

#+BEGIN_SRC org
#+BEGIN_FOO
This is a paragraph.

#+END_FOO
This is another paragraph.
#+END_SRC

Which just looked bad to me (even though it probably behaves perfectly
correctly). So if point is at bol, it skips back over the whitespace and
then moves forward one char, presumably leaving point right after the
marked element.

Maybe it should only skip back over newlines (though then indentation
will confuse it). Or maybe I should just not be so picky about
appearances...

Eric

Re: function for inserting a block

[Eric Abrahamsen]

Eric Abrahamsen <eric@ericabrahamsen.net> writes:


[...]

> #+BEGIN_SRC org
> #+BEGIN_FOO
> This is a paragraph.
>
> #+END_FOO
>
> This is another paragraph.
> #+END_SRC

Make that:

#+BEGIN_FOO
This is a paragraph

#+END_FOO
This is another paragraph

Re: function for inserting a block

[Nicolas Goaziou]

Hello,

Eric Abrahamsen <eric@ericabrahamsen.net> writes:

> Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

>>> +    (if (bolp)
>>> +	(progn
>>> +	  (skip-chars-backward " \n\t")
>>> +	  (forward-char))
>>> +      (end-of-line)
>>> +      (insert "\n"))
>>
>> I don't understand this part. In particular, the `forward-char' looks
>> wrong. Do you mean `forward-line' ? If so, do you handle the case where
>> buffer doesn't end with a newline character?
>
> This was a bit of finicky code mostly for aesthetic purposes. It has to
> do with this case (the second clause in the test I added):
>
> #+BEGIN_SRC org
> This is a paragraph
>
> This is another paragraph
> #+END_SRC
>
>
> If point is on the first paragraph and the region is not active,
> `org-mark-element' will mark the paragraph and all following whitespace,
> which means we end up with:
>
> #+BEGIN_SRC org
> #+BEGIN_FOO
> This is a paragraph.
>
> #+END_FOO
>
> This is another paragraph.
> #+END_SRC
>
> Which just looked bad to me (even though it probably behaves perfectly
> correctly). So if point is at bol, it skips back over the whitespace and
> then moves forward one char, presumably leaving point right after the
> marked element.

Then it's `forward-line', not `forward-char', because there could be
trailing spaces at the end of the paragraph, e.g.

   This is a paragraph.<SPC><SPC>

Also, my question still holds, what about the last paragraph in a buffer
not ending with a newline character, e.g.

  This is the last paragraph.<EOB>

You need to insert a newline character in this case.

Regards,

-- 
Nicolas Goaziou

Re: function for inserting a block

[Eric Abrahamsen]

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

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:


[...]

> Then it's `forward-line', not `forward-char', because there could be
> trailing spaces at the end of the paragraph, e.g.
>
>    This is a paragraph.<SPC><SPC>

Okay, changed to `forward-line'.

> Also, my question still holds, what about the last paragraph in a buffer
> not ending with a newline character, e.g.
>
>   This is the last paragraph.<EOB>
>
> You need to insert a newline character in this case.

I'm still not quite seeing this. This chunk should take care of it:

    (goto-char e)
    (if (bolp)
	(progn
	  (skip-chars-backward " \n\t")
	  (forward-line))
      (end-of-line)
      (insert "\n"))

If "e" is EOB, we do `end-of-line' and insert a newline, it should be
taken care of. I added a new clause in the test for this case, and it
seems to work fine... Am I missing anything?

Eric


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Move-org-completing-read-into-org-macs.el.patch --]
[-- Type: text/x-diff, Size: 2984 bytes --]

From 7ac8883394bc2979dee731c54ef65c0a9c135d0b Mon Sep 17 00:00:00 2001
From: Nicolas Goaziou <mail@nicolasgoaziou.fr>
Date: Tue, 17 Oct 2017 10:11:21 +0200
Subject: [PATCH] Move `org-completing-read' into "org-macs.el"

* lisp/org-macs.el (org-completing-read): Moved here...
* lisp/org.el: ... from there.
---
 lisp/org-macs.el | 35 +++++++++++++++++++++++++----------
 lisp/org.el      | 10 ----------
 2 files changed, 25 insertions(+), 20 deletions(-)

diff --git a/lisp/org-macs.el b/lisp/org-macs.el
index 1a2d8a49d..196a2ce22 100644
--- a/lisp/org-macs.el
+++ b/lisp/org-macs.el
@@ -168,6 +168,31 @@ point nowhere."
 
 
 \f
+;;; Input
+
+(defun org-read-function (prompt &optional allow-empty?)
+  "Prompt for a function.
+If ALLOW-EMPTY? is non-nil, return nil rather than raising an
+error when the user input is empty."
+  (let ((func (completing-read prompt obarray #'fboundp t)))
+    (cond ((not (string= func ""))
+	   (intern func))
+	  (allow-empty? nil)
+	  (t (user-error "Empty input is not valid")))))
+
+(defun org-completing-read (&rest args)
+  "Completing-read with SPACE being a normal character."
+  (let ((enable-recursive-minibuffers t)
+	(minibuffer-local-completion-map
+	 (copy-keymap minibuffer-local-completion-map)))
+    (org-defkey minibuffer-local-completion-map " " 'self-insert-command)
+    (org-defkey minibuffer-local-completion-map "?" 'self-insert-command)
+    (org-defkey minibuffer-local-completion-map (kbd "C-c !")
+		'org-time-stamp-inactive)
+    (apply #'completing-read args)))
+
+
+\f
 ;;; Logic
 
 (defsubst org-xor (a b)
@@ -469,16 +494,6 @@ The number of levels is controlled by `org-inlinetask-min-level'"
 			  limit-level)))
 	   (format "\\*\\{1,%d\\} " nstars)))))
 
-(defun org-read-function (prompt &optional allow-empty?)
-  "Prompt for a function.
-If ALLOW-EMPTY? is non-nil, return nil rather than raising an
-error when the user input is empty."
-  (let ((func (completing-read prompt obarray #'fboundp t)))
-    (cond ((not (string= func ""))
-	   (intern func))
-	  (allow-empty? nil)
-	  (t (user-error "Empty input is not valid")))))
-
 
 (provide 'org-macs)
 
diff --git a/lisp/org.el b/lisp/org.el
index e3b4ccef1..99eba2da3 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -10322,16 +10322,6 @@ Use TAB to complete link prefixes, then RET for type-specific completion support
 		   (match-string 1 (expand-file-name file))))
 	  (t (concat "file:" file)))))
 
-(defun org-completing-read (&rest args)
-  "Completing-read with SPACE being a normal character."
-  (let ((enable-recursive-minibuffers t)
-	(minibuffer-local-completion-map
-	 (copy-keymap minibuffer-local-completion-map)))
-    (org-defkey minibuffer-local-completion-map " " 'self-insert-command)
-    (org-defkey minibuffer-local-completion-map "?" 'self-insert-command)
-    (org-defkey minibuffer-local-completion-map (kbd "C-c !")
-		'org-time-stamp-inactive)
-    (apply #'completing-read args)))
 
 ;;; Opening/following a link
 
-- 
2.14.2

Re: function for inserting a block

[Nicolas Goaziou]

Eric Abrahamsen <eric@ericabrahamsen.net> writes:

> I'm still not quite seeing this. This chunk should take care of it:
>
>     (goto-char e)
>     (if (bolp)
> 	(progn
> 	  (skip-chars-backward " \n\t")
> 	  (forward-line))
>       (end-of-line)
>       (insert "\n"))
>
> If "e" is EOB, we do `end-of-line' and insert a newline, it should be
> taken care of. I added a new clause in the test for this case, and it
> seems to work fine... Am I missing anything?

I don't think so. It looks correct, indeed.

However, you sent the wrong patch. Could you send the updated patch
again?

Thank you.

Regards,

Re: function for inserting a block

[Eric Abrahamsen]

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Eric Abrahamsen <eric@ericabrahamsen.net> writes:
>
>> I'm still not quite seeing this. This chunk should take care of it:
>>
>>     (goto-char e)
>>     (if (bolp)
>> 	(progn
>> 	  (skip-chars-backward " \n\t")
>> 	  (forward-line))
>>       (end-of-line)
>>       (insert "\n"))
>>
>> If "e" is EOB, we do `end-of-line' and insert a newline, it should be
>> taken care of. I added a new clause in the test for this case, and it
>> seems to work fine... Am I missing anything?
>
> I don't think so. It looks correct, indeed.
>
> However, you sent the wrong patch. Could you send the updated patch
> again?

Ooof, maybe I need to take a little vacation from the computer. This
should be the right one.

Thanks,
Eric

Re: function for inserting a block

[Eric Abrahamsen]

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

Eric Abrahamsen <eric@ericabrahamsen.net> writes:

> Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:
>
>> Eric Abrahamsen <eric@ericabrahamsen.net> writes:
>>
>>> I'm still not quite seeing this. This chunk should take care of it:
>>>
>>>     (goto-char e)
>>>     (if (bolp)
>>> 	(progn
>>> 	  (skip-chars-backward " \n\t")
>>> 	  (forward-line))
>>>       (end-of-line)
>>>       (insert "\n"))
>>>
>>> If "e" is EOB, we do `end-of-line' and insert a newline, it should be
>>> taken care of. I added a new clause in the test for this case, and it
>>> seems to work fine... Am I missing anything?
>>
>> I don't think so. It looks correct, indeed.
>>
>> However, you sent the wrong patch. Could you send the updated patch
>> again?
>
> Ooof, maybe I need to take a little vacation from the computer. This
> should be the right one.

Backing away from the keyboard now...


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-New-function-org-insert-structure-template.patch --]
[-- Type: text/x-diff, Size: 7088 bytes --]

From d317f25abafe012e0a678ac0c0cc3b372d22113e Mon Sep 17 00:00:00 2001
From: Eric Abrahamsen <eric@ericabrahamsen.net>
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
-@samp{src} 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.
 
+@findex org-insert-structure-template
+@kindex 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

Re: function for inserting a block

[Carsten Dominik]

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

Dear all,

this is great added functionality that I have missed a lot myself.  Thanks
for this!  Also, I like the key binding.

One improvement I can think of it to read the block type with completion
(but still allow any word to be used).

Carsten

On Wed, Oct 18, 2017 at 12:03 AM, Eric Abrahamsen <eric@ericabrahamsen.net>
wrote:

> Eric Abrahamsen <eric@ericabrahamsen.net> writes:
>
> > Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:
> >
> >> Eric Abrahamsen <eric@ericabrahamsen.net> writes:
> >>
> >>> I'm still not quite seeing this. This chunk should take care of it:
> >>>
> >>>     (goto-char e)
> >>>     (if (bolp)
> >>>     (progn
> >>>       (skip-chars-backward " \n\t")
> >>>       (forward-line))
> >>>       (end-of-line)
> >>>       (insert "\n"))
> >>>
> >>> If "e" is EOB, we do `end-of-line' and insert a newline, it should be
> >>> taken care of. I added a new clause in the test for this case, and it
> >>> seems to work fine... Am I missing anything?
> >>
> >> I don't think so. It looks correct, indeed.
> >>
> >> However, you sent the wrong patch. Could you send the updated patch
> >> again?
> >
> > Ooof, maybe I need to take a little vacation from the computer. This
> > should be the right one.
>
> Backing away from the keyboard now...
>
>

[-- Attachment #2: Type: text/html, Size: 2153 bytes --]

Re: function for inserting a block

[Eric Abrahamsen]

Carsten Dominik <dominik@uva.nl> writes:

> Dear all,
>
> this is great added functionality that I have missed a lot myself.  Thanks for this!  Also, I like the key binding.

I do too, though I also notice it conflicts with inlinetask insertion.

> One improvement I can think of it to read the block type with completion (but still allow any word to be used).

I'd be happy to do that. There would be a tiny bit of redundancy with
`org-structure-template-alist', but nothing too terrible.

Eric

Re: function for inserting a block

[Carsten Dominik]

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

Hi Eric,



On Wed, Oct 18, 2017 at 4:58 PM, Eric Abrahamsen <eric@ericabrahamsen.net>
wrote:

> Carsten Dominik <dominik@uva.nl> writes:
>
> > Dear all,
> >
> > this is great added functionality that I have missed a lot myself.
> Thanks for this!  Also, I like the key binding.
>
> I do too, though I also notice it conflicts with inlinetask insertion.
>


Ooops.  I overlooked that. Hmmm, that is not ideal.

Maybe then C-c C-x w would be better, w can stand for "wrap".


>
> > One improvement I can think of it to read the block type with completion
> (but still allow any word to be used).
>
> I'd be happy to do that. There would be a tiny bit of redundancy with
> `org-structure-template-alist', but nothing too terrible.
>

I agree.  You could pull it would of the alist, but I am not sure it is
worth it.

Carsten


>
> Eric
>
>
>

[-- Attachment #2: Type: text/html, Size: 1797 bytes --]

Re: function for inserting a block

[Eric Abrahamsen]

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

Carsten Dominik <dominik@uva.nl> writes:

> Hi Eric,
>
> On Wed, Oct 18, 2017 at 4:58 PM, Eric Abrahamsen <eric@ericabrahamsen.net> wrote:
>
>  Carsten Dominik <dominik@uva.nl> writes:
>
>  > Dear all,
>  >
>  > this is great added functionality that I have missed a lot myself.  Thanks for this!  Also, I like the key binding.
>
>  I do too, though I also notice it conflicts with inlinetask insertion.
>
> Ooops.  I overlooked that. Hmmm, that is not ideal.
>
> Maybe then C-c C-x w would be better, w can stand for "wrap".
>  
>  
>  > One improvement I can think of it to read the block type with completion (but still allow any word to be used).
>
>  I'd be happy to do that. There would be a tiny bit of redundancy with
>  `org-structure-template-alist', but nothing too terrible.
>
> I agree.  You could pull it would of the alist, but I am not sure it is worth it.

Okay, here's another version, with a new keybinding and completion. The
completion strings are uppercase, which might not always be the right
thing, but probably more often than not.

Eric


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-New-function-org-insert-structure-template.patch --]
[-- Type: text/x-diff, Size: 7894 bytes --]

From cb6f1815259094f7f9b68459dcded5dce14d3154 Mon Sep 17 00:00:00 2001
From: Eric Abrahamsen <eric@ericabrahamsen.net>
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.
  (org-structure-predefined-blocks): New option holding predefined
  blocks, for completion.
* 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              | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 testing/lisp/test-org.el | 42 ++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 108 insertions(+), 6 deletions(-)

diff --git a/doc/org.texi b/doc/org.texi
index c54f2615a..6ad9d1c15 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -15242,12 +15242,13 @@ A @samp{src} block conforms to this structure:
 #+END_SRC
 @end example
 
-Org mode's templates system (@pxref{Easy templates}) speeds up creating
-@samp{src} 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:
@@ -17418,6 +17419,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.
 
+@findex org-insert-structure-template
+@kindex C-c C-x w
+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 w} by default.
+
 @node Speed keys
 @section Speed keys
 @cindex speed keys
diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 1076dd970..190a6b8bc 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 w by default.
 
 *** ~org-export-excluded-from-toc-p~
 
diff --git a/lisp/org.el b/lisp/org.el
index 54687abc7..e1cf14cae 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -12117,6 +12117,13 @@ keywords relative to each registered export back-end."
     "PRIORITIES:" "SELECT_TAGS:" "SEQ_TODO:" "SETUPFILE:" "STARTUP:" "TAGS:"
     "TITLE:" "TODO:" "TYP_TODO:" "SELECT_TAGS:" "EXCLUDE_TAGS:"))
 
+(defcustom org-structure-predefined-blocks
+  '("SRC" "EXAMPLE" "QUOTE" "VERSE" "VERBATIM" "CENTER" "COMMENT" "EXPORT")
+  "Block structure completion names."
+  :group 'org-completion
+  :type '(repeat string)
+  :package-version '(Org . "9.1.3"))
+
 (defcustom org-structure-template-alist
   '(("s" "#+BEGIN_SRC ?\n\n#+END_SRC")
     ("e" "#+BEGIN_EXAMPLE\n?\n#+END_EXAMPLE")
@@ -12189,6 +12196,45 @@ expands them."
     (insert rpl)
     (when (re-search-backward "\\?" start t) (delete-char 1))))
 
+(defun org-insert-structure-template (&optional 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)
+  (setq type (or type (completing-read "Block type: "
+				       org-structure-predefined-blocks)))
+  (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 ()
@@ -19652,6 +19698,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-xw"    '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 f94079b7e..84924eb23 100644
--- a/testing/lisp/test-org.el
+++ b/testing/lisp/test-org.el
@@ -4033,6 +4033,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

Re: function for inserting a block

[Kaushal Modi]

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

On Fri, Oct 20, 2017 at 2:07 PM Eric Abrahamsen <eric@ericabrahamsen.net>
wrote:

> Okay, here's another version, with a new keybinding and completion. The
> completion strings are uppercase, which might not always be the right
> thing, but probably more often than not.
>

Hi Eric,

I just tried it out, and it works great!

I have a comment about

(when (string-equal (downcase type) "example")
      (org-escape-code-in-region s e))

I have never needed to escape org in example, blocks, but I *have* needed
to do that in org src blocks.

Should type string be also matched with "src org"?

Actually should the type string be matched only with "src org"? Because I
see the Org example blocks as <pre> <code> blocks in HTML with no syntax
highlighting.. so those can contain code from any language.

Also as this is part of org and emacs, org-structure-predefined-blocks
deserves "SRC org" and "SRC emacs-lisp" too? :)
-- 

Kaushal Modi

[-- Attachment #2: Type: text/html, Size: 1617 bytes --]

Re: function for inserting a block

[Kaushal Modi]

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

Also, if the type is "src", shouldn't the point end up after "#+BEGIN_SRC"?
Because the user will anyways need to type something there.

Finally, I am trying to understand what this does:

(if (bolp)
    (progn
      (skip-chars-backward " \n\t")
      (forward-line))
  ;; snip
  )

If the point is at BOL, wouldn't that progn bring the point exactly to
where it was, as the same BOL? Also isn't that progn equivalent to
(forward-line 0)?

I am probably missing something.. but seems to work the same with

(unless (bolp)
      (end-of-line)
      (insert "\n"))

replacing that whole (if ..) form.
-- 

Kaushal Modi

[-- Attachment #2: Type: text/html, Size: 1055 bytes --]

Re: function for inserting a block

[Eric Abrahamsen]

Kaushal Modi <kaushal.modi@gmail.com> writes:

> Also, if the type is "src", shouldn't the point end up after "#+BEGIN_SRC"? Because the user will anyways need to type something there.

My original version did that. It might be nice to still do that
selectively if the user adds a SRC or EXPORT block.

> Finally, I am trying to understand what this does:
>
> (if (bolp)
>     (progn
>       (skip-chars-backward " \n\t")
>       (forward-line))
>   ;; snip
>   )
>
> If the point is at BOL, wouldn't that progn bring the point exactly to where it was, as the same BOL? Also isn't that progn equivalent to (forward-line 0)?
>
> I am probably missing something.. but seems to work the same with 
>
> (unless (bolp)
>       (end-of-line)
>       (insert "\n"))
>
> replacing that whole (if ..) form.

The case this is addressing is if there are multiple newlines after the
org element we're wrapping (one of the clauses in the test shows this).
The skip-chars-backward is there to go back over multiple newlines, so
that the #+END_FOO string always comes right after the end of the text.

Eric

Re: function for inserting a block

[Eric Abrahamsen]

Kaushal Modi <kaushal.modi@gmail.com> writes:

> On Fri, Oct 20, 2017 at 2:07 PM Eric Abrahamsen <eric@ericabrahamsen.net> wrote:
>
>  Okay, here's another version, with a new keybinding and completion. The
>  completion strings are uppercase, which might not always be the right
>  thing, but probably more often than not.
>
> Hi Eric,
>
> I just tried it out, and it works great!
>
> I have a comment about
>
> (when (string-equal (downcase type) "example")
>       (org-escape-code-in-region s e)) 
>
> I have never needed to escape org in example, blocks, but I *have* needed to do that in org src blocks. 
>
> Should type string be also matched with "src org"?
>
> Actually should the type string be matched only with "src org"? Because I see the Org example blocks as <pre> <code> blocks in HTML with no syntax highlighting.. so
> those can contain code from any language.
>
> Also as this is part of org and emacs, org-structure-predefined-blocks deserves "SRC org" and "SRC emacs-lisp" too? :)

The template really only inserts the block type, not anything specific
like the source language or export backend. I think prompting for
"second-level" information like that might be a little overkill.

As for what should be escaped and what shouldn't, I defer to Nicolas,
let's see what he says.

Eric

Re: function for inserting a block

[Kaushal Modi]

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

On Fri, Oct 20, 2017 at 5:15 PM Eric Abrahamsen <eric@ericabrahamsen.net>
wrote:

> The template really only inserts the block type, not anything specific
> like the source language or export backend.


Right, but based on the code you have, you can easily add "SRC org", "SRC
emacs-lisp" to the default value of that list. Looking at that, users can
also get an idea that they can add their favorite languages to that list
too.


> I think prompting for
> "second-level" information like that might be a little overkill.
>

I second that. The first-level prompt also feels a bit slow, honestly,
compared to using easy templates like "<e". So in my config, I make "<e"
(just an example) to insert the, well, EXAMPLE block as usual. But *if
region is selected*, it does the wrapping as in your code.

This is what I mean (GIF animation):

https://i.imgur.com/201TISW.gifv

I use hydra to provide those awesome hints.. but the same can be done
without hydras too.

As for what should be escaped and what shouldn't, I defer to Nicolas,
> let's see what he says.
>
-- 

Kaushal Modi

[-- Attachment #2: Type: text/html, Size: 1931 bytes --]

Re: function for inserting a block

[Xebar Saram]

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

Hi all

this looks really cool and would love to try. as a non technical user, how
does one use the patch to get the functionality? is there a way to create a
clean function only version from the patch i can try?

thx!

Z

On Sat, Oct 21, 2017 at 12:43 AM, Kaushal Modi <kaushal.modi@gmail.com>
wrote:

> On Fri, Oct 20, 2017 at 5:15 PM Eric Abrahamsen <eric@ericabrahamsen.net>
> wrote:
>
>> The template really only inserts the block type, not anything specific
>> like the source language or export backend.
>
>
> Right, but based on the code you have, you can easily add "SRC org", "SRC
> emacs-lisp" to the default value of that list. Looking at that, users can
> also get an idea that they can add their favorite languages to that list
> too.
>
>
>> I think prompting for
>> "second-level" information like that might be a little overkill.
>>
>
> I second that. The first-level prompt also feels a bit slow, honestly,
> compared to using easy templates like "<e". So in my config, I make "<e"
> (just an example) to insert the, well, EXAMPLE block as usual. But *if
> region is selected*, it does the wrapping as in your code.
>
> This is what I mean (GIF animation):
>
> https://i.imgur.com/201TISW.gifv
>
> I use hydra to provide those awesome hints.. but the same can be done
> without hydras too.
>
> As for what should be escaped and what shouldn't, I defer to Nicolas,
>> let's see what he says.
>>
> --
>
> Kaushal Modi
>

[-- Attachment #2: Type: text/html, Size: 2783 bytes --]

Re: function for inserting a block

[Marco Wahl]

Hi!

Xebar Saram <zeltakc@gmail.com> writes:

> this looks really cool and would love to try. as a non technical user, how
> does one use the patch to get the functionality? is there a way to create a
> clean function only version from the patch i can try?

You could simply pick the relevant parts from the patch and evaluate
them.

Concretely you could do:

1. Copy Eric's code to empty buffer *scratch*.  The relevant code is

#+BEGIN_SRC elisp
(defcustom org-structure-predefined-blocks
  '("SRC" "EXAMPLE" "QUOTE" "VERSE" "VERBATIM" "CENTER" "COMMENT" "EXPORT")
  "Block structure completion names."
  :group 'org-completion
  :type '(repeat string)
  :package-version '(Org . "9.1.3"))

(defun org-insert-structure-template (&optional 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)
  (setq type (or type (completing-read "Block type: "
				       org-structure-predefined-blocks)))
  (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)))

(org-defkey org-mode-map "\C-c\C-xw"    'org-insert-structure-template)
#+END_SRC

2. In buffer *scratch* do

    M-x eval-buffer

3. Voila!  Check out C-c C-x w in an org mode buffer.


Best regards
            Marco

Re: function for inserting a block

[Xebar Saram]

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

thx thats perfect

Z

On Sat, Oct 21, 2017 at 2:59 PM, Marco Wahl <marcowahlsoft@gmail.com> wrote:

> The following message is a courtesy copy of an article
> that has been posted to gmane.emacs.orgmode as well.
>
> Hi!
>
> Xebar Saram <zeltakc@gmail.com> writes:
>
> > this looks really cool and would love to try. as a non technical user,
> how
> > does one use the patch to get the functionality? is there a way to
> create a
> > clean function only version from the patch i can try?
>
> You could simply pick the relevant parts from the patch and evaluate
> them.
>
> Concretely you could do:
>
> 1. Copy Eric's code to empty buffer *scratch*.  The relevant code is
>
> #+BEGIN_SRC elisp
> (defcustom org-structure-predefined-blocks
>   '("SRC" "EXAMPLE" "QUOTE" "VERSE" "VERBATIM" "CENTER" "COMMENT" "EXPORT")
>   "Block structure completion names."
>   :group 'org-completion
>   :type '(repeat string)
>   :package-version '(Org . "9.1.3"))
>
> (defun org-insert-structure-template (&optional 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)
>   (setq type (or type (completing-read "Block type: "
>                                        org-structure-predefined-blocks)))
>   (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)))
>
> (org-defkey org-mode-map "\C-c\C-xw"    'org-insert-structure-template)
> #+END_SRC
>
> 2. In buffer *scratch* do
>
>     M-x eval-buffer
>
> 3. Voila!  Check out C-c C-x w in an org mode buffer.
>
>
> Best regards
>             Marco
>

[-- Attachment #2: Type: text/html, Size: 3757 bytes --]

Re: function for inserting a block

[Eric Abrahamsen]

Kaushal Modi <kaushal.modi@gmail.com> writes:

> On Fri, Oct 20, 2017 at 5:15 PM Eric Abrahamsen <eric@ericabrahamsen.net> wrote:
>
>  The template really only inserts the block type, not anything specific
>  like the source language or export backend.
>
> Right, but based on the code you have, you can easily add "SRC org", "SRC emacs-lisp" to the default value of that list. Looking at that, users can also get an idea that
> they can add their favorite languages to that list too.
>  
>  I think prompting for
>  "second-level" information like that might be a little overkill.
>
> I second that. The first-level prompt also feels a bit slow, honestly, compared to using easy templates like "<e". So in my config, I make "<e" (just an example) to insert
> the, well, EXAMPLE block as usual. But *if region is selected*, it does the wrapping as in your code.

Perhaps it would make sense to combine the two functionalities; that's
not a decision I can make, though.

Re: function for inserting a block

[Kaushal Modi]

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

On Fri, Oct 20, 2017, 5:43 PM Kaushal Modi <kaushal.modi@gmail.com> wrote:

> On Fri, Oct 20, 2017 at 5:15 PM Eric Abrahamsen <eric@ericabrahamsen.net>
> wrote:
>
>> The template really only inserts the block type, not anything specific
>> like the source language or export backend.
>
>
> Right, but based on the code you have, you can easily add "SRC org", "SRC
> emacs-lisp" to the default value of that list. Looking at that, users can
> also get an idea that they can add their favorite languages to that list
> too.
>
>
>> I think prompting for
>> "second-level" information like that might be a little overkill.
>>
>
> I second that. The first-level prompt also feels a bit slow, honestly,
> compared to using easy templates like "<e". So in my config, I make "<e"
> (just an example) to insert the, well, EXAMPLE block as usual. But *if
> region is selected*, it does the wrapping as in your code.
>
> This is what I mean (GIF animation):
>
> https://i.imgur.com/201TISW.gifv
>
> I use hydra to provide those awesome hints.. but the same can be done
> without hydras too.
>

Hello all,

Above, I suggested merging the template insertion function with the current
easy template code.

With that, the easy template behavior will remain unchanged if no region is
selected. But if a region is selected, the same template (example: "<e")
Will wrap that region with that template.

I also have a GIF showing that behavior in action (linked in my previous
reply).

Benefits:
- Quicker as there are no prompts.. the user simply types the template
string as configured by them.
- Also one doesn't need to do a context switch to use a different binding
based on if region is selected or not.

@Eric: I believe you were sort of onboard with this suggestion, just gated
by a doubt if this actually can make into master.

So, checking with Nicolas, and the thread if the proposed behavior change
with easy templates (only when region is selected) would be accepted.

> --

Kaushal Modi

[-- Attachment #2: Type: text/html, Size: 3506 bytes --]

Re: function for inserting a block

[Carsten Dominik]

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

On Mon, Oct 23, 2017 at 12:52 PM, Kaushal Modi <kaushal.modi@gmail.com>
wrote:

> On Fri, Oct 20, 2017, 5:43 PM Kaushal Modi <kaushal.modi@gmail.com> wrote:
>
>> On Fri, Oct 20, 2017 at 5:15 PM Eric Abrahamsen <eric@ericabrahamsen.net>
>> wrote:
>>
>>> The template really only inserts the block type, not anything specific
>>> like the source language or export backend.
>>
>>
>> Right, but based on the code you have, you can easily add "SRC org", "SRC
>> emacs-lisp" to the default value of that list. Looking at that, users can
>> also get an idea that they can add their favorite languages to that list
>> too.
>>
>>
>>> I think prompting for
>>> "second-level" information like that might be a little overkill.
>>>
>>
>> I second that. The first-level prompt also feels a bit slow, honestly,
>> compared to using easy templates like "<e". So in my config, I make "<e"
>> (just an example) to insert the, well, EXAMPLE block as usual. But *if
>> region is selected*, it does the wrapping as in your code.
>>
>> This is what I mean (GIF animation):
>>
>> https://i.imgur.com/201TISW.gifv
>>
>> I use hydra to provide those awesome hints.. but the same can be done
>> without hydras too.
>>
>
> Hello all,
>
> Above, I suggested merging the template insertion function with the
> current easy template code.
>
> With that, the easy template behavior will remain unchanged if no region
> is selected. But if a region is selected, the same template (example: "<e")
> Will wrap that region with that template.
>

I Kaustal,

I am not sure I understand, at least with transient-region turned on.
Typing <e will deactivate the region, so there is no effect.

Or do you mean to actually put "<" into a keymap?

Carsten


>
> I also have a GIF showing that behavior in action (linked in my previous
> reply).
>
> Benefits:
> - Quicker as there are no prompts.. the user simply types the template
> string as configured by them.
> - Also one doesn't need to do a context switch to use a different binding
> based on if region is selected or not.
>
> @Eric: I believe you were sort of onboard with this suggestion, just gated
> by a doubt if this actually can make into master.
>
> So, checking with Nicolas, and the thread if the proposed behavior change
> with easy templates (only when region is selected) would be accepted.
>
>> --
>
> Kaushal Modi
>

[-- Attachment #2: Type: text/html, Size: 4479 bytes --]

Re: function for inserting a block

[Kaushal Modi]

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

On Mon, Oct 23, 2017 at 10:00 AM Carsten Dominik <dominik@uva.nl> wrote:

> I am not sure I understand, at least with transient-region turned on.
> Typing <e will deactivate the region, so there is no effect.
>

You're correct.


> Or do you mean to actually put "<" into a keymap?
>

I actually do that in my personal config .. Maybe binding "<" in org keymap
is the simplest way.

I have this function in my config bound to "<":

(defun modi/org-template-maybe ()
  "Insert org-template if point is at the beginning of the line,
or if a region is selected.  Else call `self-insert-command'."
  (interactive)
  (let ((is-region? (use-region-p)))
    (if (or is-region?
            (and (not is-region?)
                 (looking-back "^[[:blank:]]*")))
        (hydra-org-template/body) ;Wrapper function for
`org-try-structure-completion'
      (self-insert-command 1))))
-- 

Kaushal Modi

[-- Attachment #2: Type: text/html, Size: 1916 bytes --]

Re: function for inserting a block

[Eric Abrahamsen]

Kaushal Modi <kaushal.modi@gmail.com> writes:

> On Fri, Oct 20, 2017, 5:43 PM Kaushal Modi <kaushal.modi@gmail.com> wrote:

[...]

> @Eric: I believe you were sort of onboard with this suggestion, just gated by a doubt if this actually can make into master. 

In principle yes, I agree it's odd to have two completely different
systems for essentially doing the same thing.

> So, checking with Nicolas, and the thread if the proposed behavior change with easy templates (only when region is selected) would be accepted. 

Re: function for inserting a block

[Nicolas Goaziou]

Hello,

Eric Abrahamsen <eric@ericabrahamsen.net> writes:

> Kaushal Modi <kaushal.modi@gmail.com> writes:
>
>> On Fri, Oct 20, 2017, 5:43 PM Kaushal Modi <kaushal.modi@gmail.com> wrote:
>
> [...]
>
>> @Eric: I believe you were sort of onboard with this suggestion, just gated by a doubt if this actually can make into master. 
>
> In principle yes, I agree it's odd to have two completely different
> systems for essentially doing the same thing.

I agree, but I don't like much the easy template system. We're basically
re-inventing the wheel. Better solutions already exist. Some of them
even ship with Emacs.

I think the function could replace the template system altogether. It's
easy enough to mimic current system with, e.g., Yasnippet.

Regards,

-- 
Nicolas Goaziou

Re: function for inserting a block

[Eric Abrahamsen]

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Hello,
>
> Eric Abrahamsen <eric@ericabrahamsen.net> writes:
>
>> Kaushal Modi <kaushal.modi@gmail.com> writes:
>>
>>> On Fri, Oct 20, 2017, 5:43 PM Kaushal Modi <kaushal.modi@gmail.com> wrote:
>>
>> [...]
>>
>>> @Eric: I believe you were sort of onboard with this suggestion, just gated by a doubt if this actually can make into master. 
>>
>> In principle yes, I agree it's odd to have two completely different
>> systems for essentially doing the same thing.
>
> I agree, but I don't like much the easy template system. We're basically
> re-inventing the wheel. Better solutions already exist. Some of them
> even ship with Emacs.
>
> I think the function could replace the template system altogether. It's
> easy enough to mimic current system with, e.g., Yasnippet.

In that case, would you be more in favor of a keymap-plus-subkey system,
or a keymap-plus-prompt system?

Re: function for inserting a block

[Eric Abrahamsen]

Eric Abrahamsen <eric@ericabrahamsen.net> writes:

> Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:
>
>> Hello,
>>
>> Eric Abrahamsen <eric@ericabrahamsen.net> writes:
>>
>>> Kaushal Modi <kaushal.modi@gmail.com> writes:
>>>
>>>> On Fri, Oct 20, 2017, 5:43 PM Kaushal Modi <kaushal.modi@gmail.com> wrote:
>>>
>>> [...]
>>>
>>>> @Eric: I believe you were sort of onboard with this suggestion, just gated by a doubt if this actually can make into master. 
>>>
>>> In principle yes, I agree it's odd to have two completely different
>>> systems for essentially doing the same thing.
>>
>> I agree, but I don't like much the easy template system. We're basically
>> re-inventing the wheel. Better solutions already exist. Some of them
>> even ship with Emacs.
>>
>> I think the function could replace the template system altogether. It's
>> easy enough to mimic current system with, e.g., Yasnippet.
>
> In that case, would you be more in favor of a keymap-plus-subkey system,
> or a keymap-plus-prompt system?
       ^^^^^^^^^^^^^^^^^^
I mean, keybinding-plus-prompt...

Re: function for inserting a block

[Nicolas Goaziou]

Hello,

Eric Abrahamsen <eric@ericabrahamsen.net> writes:

> In that case, would you be more in favor of a keymap-plus-subkey system,
> or a keymap-plus-prompt system?

I have no strong opinion, but a keymap-plus-subkey system (subkeys
matching current keys in `org-structure-template-alist') with an
additional key (e.g. <TAB>) for "free" seems quite efficient.

Regards,

-- 
Nicolas Goaziou

Re: function for inserting a block

[Eric Abrahamsen]

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Hello,
>
> Eric Abrahamsen <eric@ericabrahamsen.net> writes:
>
>> In that case, would you be more in favor of a keymap-plus-subkey system,
>> or a keymap-plus-prompt system?
>
> I have no strong opinion, but a keymap-plus-subkey system (subkeys
> matching current keys in `org-structure-template-alist') with an
> additional key (e.g. <TAB>) for "free" seems quite efficient.

This will get there eventually! Because there's likely to be more
tweaking, I haven't touched the manual or the tests yet, just reworked
the option and function:

#+BEGIN_SRC elisp
(defcustom org-structure-template-alist
  '((?s . "SRC")
    (?e . "EXAMPLE")
    (?E . "EXPORT")
    (?q . "QUOTE")
    (?v . "VERSE")
    (?V . "VERBATIM")
    (?c . "CENTER")
    (?C . "COMMENT")
    (?l . "EXPORT latex")
    (?L . "#+LaTeX")
    (?h . "EXPORT html")
    (?H . "#+HTML")
    (?a . "EXPORT ascii")
    (?A . "#+ASCII")
    (?i . "#+INDEX")
    (?I . "#+INCLUDE"))
  "Structure completion elements.
This is an alist of characters and values.  When
`org-insert-structure-template' is called, an additional key is
read.  The key is first looked up in this alist, and the
corresponding structure is inserted.  Hitting <TAB> will prompt
for a structure.

Structure strings prefixed with a \"#+\" are inserted with no
further processing.  Strings without this prefix are used to
create a block structure, with \"#+BEGIN\" and \"#+END\" added
automatically.

WHAT TO DO ABOUT THIS PART?
There are two templates for each key, the first uses the original Org syntax,
the second uses Emacs Muse-like syntax tags.  These Muse-like tags become
the default when the /org-mtags.el/ module has been loaded.  See also the
variable `org-mtags-prefer-muse-templates'."
  :group 'org-completion
  :type '(repeat
	  (cons
	   (character :tag "Key")
	   (string :tag "Template")))
  :version "26.1"
  :package-version '(Org . "8.3"))

(defun org-insert-structure-template (&optional type)
  "Insert a block structure of the type #+BEGIN_FOO/#+END_FOO.
This function first reads a character, which can be one of the
keys in `org-structure-template-alist'.  It can also be <TAB>, in
which case the user is prompted for a string to use.  With an
active region, wrap the region in the block.  Otherwise, insert
an empty block."
  (interactive)
  (let* ((key (read-key "Key: "))
	 (struct-string
	  (or (cdr-safe (assq key org-structure-template-alist))
	      (when (= key ?\t)
		(read-string "Structure type: "))
	      (error "'%c' has no structure definition" key))))
    (if (string-prefix-p "#+" struct-string)
	(progn
	  (insert (format "%s: " struct-string))
	  (when (string= "#+INCLUDE" struct-string)
	    (insert
	     (format "\"%s\""
		     (abbreviate-file-name
		      (read-file-name "Include file: "))))))
      (let ((s (if (use-region-p)
		   (region-beginning)
		 (point)))
	    (e (copy-marker (if (use-region-p)
				(region-end)
			      (point))
			    t))
	    column)
	(when (string-match-p
	       (concat "\\`"
		       (regexp-opt '("example" "export" "src")))
	       struct-string)
	  (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" struct-string))
	(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"
			(car (split-string struct-string))))
	(when (or (string-match-p "SRC\\|\\`EXPORT\\'" struct-string)
		  (null (use-region-p)))
	  (goto-char s)
	  (end-of-line))
	(set-marker e nil)))))
#+END_SRC

Re: function for inserting a block

[Nicolas Goaziou]

Hello,

Eric Abrahamsen <eric@ericabrahamsen.net> writes:

> This will get there eventually! Because there's likely to be more
> tweaking, I haven't touched the manual or the tests yet, just reworked
> the option and function:

Thank you. Some comments follow.

> #+BEGIN_SRC elisp
> (defcustom org-structure-template-alist
>   '((?s . "SRC")
>     (?e . "EXAMPLE")
>     (?E . "EXPORT")
>     (?q . "QUOTE")
>     (?v . "VERSE")
>     (?V . "VERBATIM")

This block type doesn't exist. You can remove it.

>     (?c . "CENTER")
>     (?C . "COMMENT")
>     (?l . "EXPORT latex")
>     (?L . "#+LaTeX")

#+LATEX or #+latex (see below)

>     (?h . "EXPORT html")
>     (?H . "#+HTML")
>     (?a . "EXPORT ascii")
>     (?A . "#+ASCII")
>     (?i . "#+INDEX")
>     (?I . "#+INCLUDE"))

As suggested by Rasmus once, maybe we could get away from FORTRAN touch
and insert everything lowercase.

>   "Structure completion elements.
> This is an alist of characters and values.  When
> `org-insert-structure-template' is called, an additional key is
> read.  The key is first looked up in this alist, and the
> corresponding structure is inserted.  Hitting <TAB> will prompt
> for a structure.

I would remove "Hitting <TAB> prompts for a structure." which belongs to
the function's docstring, not to variable's.

> Structure strings prefixed with a \"#+\" are inserted with no
> further processing.  Strings without this prefix are used to
> create a block structure, with \"#+BEGIN\" and \"#+END\" added
> automatically.

I'm not sure about this part. I understand the backward-compatibility
concern, but it sounds a bit alien to the purpose of the function, i.e.,
there is no wrapping around, it is not an "environment" either. WDYT?

> WHAT TO DO ABOUT THIS PART?
> There are two templates for each key, the first uses the original Org
> syntax,

You can remove it.

> the second uses Emacs Muse-like syntax tags.  These Muse-like tags become
> the default when the /org-mtags.el/ module has been loaded.  See also the
> variable `org-mtags-prefer-muse-templates'."
>   :group 'org-completion
>   :type '(repeat
> 	  (cons
> 	   (character :tag "Key")
> 	   (string :tag "Template")))
>   :version "26.1"
>   :package-version '(Org . "8.3"))

You need to update :version and :package-version. Technically,
if :package-version is provided, we should only use it, IIUC.

> (defun org-insert-structure-template (&optional type)
>   "Insert a block structure of the type #+BEGIN_FOO/#+END_FOO.
> This function first reads a character, which can be one of the
> keys in `org-structure-template-alist'.  It can also be <TAB>, in
> which case the user is prompted for a string to use.  

"When it is <TAB>, prompt the user for a string to use."

>   (interactive)
>   (let* ((key (read-key "Key: "))
> 	 (struct-string
> 	  (or (cdr-safe (assq key org-structure-template-alist))

`cdr-safe' -> `cdr'

> 	      (when (= key ?\t)
> 		(read-string "Structure type: "))

Nitpick: (and (eq key ?\t) (read-string ...))

> 	      (error "'%c' has no structure definition" key))))
>     (if (string-prefix-p "#+" struct-string)
> 	(progn
> 	  (insert (format "%s: " struct-string))
> 	  (when (string= "#+INCLUDE" struct-string)
> 	    (insert
> 	     (format "\"%s\""
> 		     (abbreviate-file-name
> 		      (read-file-name "Include file: "))))))

See above.


Regards,

-- 
Nicolas Goaziou

Re: function for inserting a block

[Eric S Fraga]

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

On Monday, 30 Oct 2017 at 12:05, Nicolas Goaziou wrote:

[...]

> As suggested by Rasmus once, maybe we could get away from FORTRAN touch
> and insert everything lowercase.

+1 (repeat many times)

-- 
: Eric S Fraga via Emacs 27.0.50, Org release_9.1.2-155-gf474c7

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 194 bytes --]

Re: function for inserting a block

[Eric Abrahamsen]

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

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Hello,
>
> Eric Abrahamsen <eric@ericabrahamsen.net> writes:
>
>> This will get there eventually! Because there's likely to be more
>> tweaking, I haven't touched the manual or the tests yet, just reworked
>> the option and function:
>
> Thank you. Some comments follow.
>
>> #+BEGIN_SRC elisp
>> (defcustom org-structure-template-alist
>>   '((?s . "SRC")
>>     (?e . "EXAMPLE")
>>     (?E . "EXPORT")
>>     (?q . "QUOTE")
>>     (?v . "VERSE")
>>     (?V . "VERBATIM")
>
> This block type doesn't exist. You can remove it.
>
>>     (?c . "CENTER")
>>     (?C . "COMMENT")
>>     (?l . "EXPORT latex")
>>     (?L . "#+LaTeX")
>
> #+LATEX or #+latex (see below)
>
>>     (?h . "EXPORT html")
>>     (?H . "#+HTML")
>>     (?a . "EXPORT ascii")
>>     (?A . "#+ASCII")
>>     (?i . "#+INDEX")
>>     (?I . "#+INCLUDE"))
>
> As suggested by Rasmus once, maybe we could get away from FORTRAN touch
> and insert everything lowercase.

Sounds good to me.

>>   "Structure completion elements.
>> This is an alist of characters and values.  When
>> `org-insert-structure-template' is called, an additional key is
>> read.  The key is first looked up in this alist, and the
>> corresponding structure is inserted.  Hitting <TAB> will prompt
>> for a structure.
>
> I would remove "Hitting <TAB> prompts for a structure." which belongs to
> the function's docstring, not to variable's.
>
>> Structure strings prefixed with a \"#+\" are inserted with no
>> further processing.  Strings without this prefix are used to
>> create a block structure, with \"#+BEGIN\" and \"#+END\" added
>> automatically.
>
> I'm not sure about this part. I understand the backward-compatibility
> concern, but it sounds a bit alien to the purpose of the function, i.e.,
> there is no wrapping around, it is not an "environment" either. WDYT?

It was a hack; I was trying to make the smallest change possible. But
that does turn it into a bit of a Frankenstein, and I would prefer to
remove it. As you mentioned earlier, Emacs already has mechanism for
inserting snippets.

The "include" case is a little different, since it does provide some
extra convenience. I've still taken it out in the next version below, though.

>> WHAT TO DO ABOUT THIS PART?
>> There are two templates for each key, the first uses the original Org
>> syntax,
>
> You can remove it.
>
>> the second uses Emacs Muse-like syntax tags.  These Muse-like tags become
>> the default when the /org-mtags.el/ module has been loaded.  See also the
>> variable `org-mtags-prefer-muse-templates'."
>>   :group 'org-completion
>>   :type '(repeat
>> 	  (cons
>> 	   (character :tag "Key")
>> 	   (string :tag "Template")))
>>   :version "26.1"
>>   :package-version '(Org . "8.3"))
>
> You need to update :version and :package-version. Technically,
> if :package-version is provided, we should only use it, IIUC.

I've never really understood the difference. Current version is 9.1.2,
will this function be present in 9.1.3, or 9.2.0? I've assumed 9.2.0 in
the next version of the patch.

>> (defun org-insert-structure-template (&optional type)
>>   "Insert a block structure of the type #+BEGIN_FOO/#+END_FOO.
>> This function first reads a character, which can be one of the
>> keys in `org-structure-template-alist'.  It can also be <TAB>, in
>> which case the user is prompted for a string to use.
>
> "When it is <TAB>, prompt the user for a string to use."
>
>>   (interactive)
>>   (let* ((key (read-key "Key: "))
>> 	 (struct-string
>> 	  (or (cdr-safe (assq key org-structure-template-alist))
>
> `cdr-safe' -> `cdr'
>
>> 	      (when (= key ?\t)
>> 		(read-string "Structure type: "))
>
> Nitpick: (and (eq key ?\t) (read-string ...))

Out of curiosity is this a style thing, or semantics, or performance?

>> 	      (error "'%c' has no structure definition" key))))
>>     (if (string-prefix-p "#+" struct-string)
>> 	(progn
>> 	  (insert (format "%s: " struct-string))
>> 	  (when (string= "#+INCLUDE" struct-string)
>> 	    (insert
>> 	     (format "\"%s\""
>> 		     (abbreviate-file-name
>> 		      (read-file-name "Include file: "))))))
>

If we take out special handling of "#+" strings, this part is gone
anyway.

Here's a new version with all the above changes made, and the docs
tweaked accordingly.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Replacing-easy-templates-with-function-org-insert-st.patch --]
[-- Type: text/x-diff, Size: 130057 bytes --]

From 086733d275ebfb10726144e92ccd30be605c5516 Mon Sep 17 00:00:00 2001
From: Eric Abrahamsen <eric@ericabrahamsen.net>
Date: Mon, 30 Oct 2017 09:19:15 -0700
Subject: [PATCH] Replacing easy templates with 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.
  (org-structure-predefined-blocks): New option holding predefined
  blocks, for completion.
  (org-try-structure-completion,
  org-complete-expand-structure-template): Remove functions.
* doc/org.texi (Inserting structure templates): Document.
* testing/lisp/test-org.el (test-org/insert-template): New test.
---
 doc/org.texi             | 749 +++++++++++++++++++++++------------------------
 etc/ORG-NEWS             |   4 +
 lisp/org.el              | 132 ++++-----
 testing/lisp/test-org.el |  46 +++
 4 files changed, 488 insertions(+), 443 deletions(-)

diff --git a/doc/org.texi b/doc/org.texi
index 77da6d335..e08e843ad 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -652,7 +652,7 @@ Texinfo export
 * Texinfo specific export settings::  Setting the environment.
 * Texinfo file header::         Generating the header.
 * Texinfo title and copyright page::  Creating preamble pages.
-* Info directory file::     Installing a manual in Info file hierarchy.
+* Info directory file::         Installing a manual in Info file hierarchy.
 * Headings and sectioning structure::  Building document structure.
 * Indices::                     Creating indices.
 * Quoting Texinfo code::        Incorporating literal Texinfo code.
@@ -749,7 +749,7 @@ Specific header arguments
 Miscellaneous
 
 * Completion::                  M-TAB guesses completions
-* Easy templates::              Quick insertion of structural elements
+* Inserting structure templates::  Wrapping text in code blocks
 * Speed keys::                  Electric commands at the beginning of a headline
 * Code evaluation security::    Org mode files evaluate inline code
 * Customization::               Adapting Org to changing tastes
@@ -796,7 +796,7 @@ MobileOrg
 @end detailmenu
 @end menu
 
-@node Introduction
+@node Introduction, Document structure, Top, Top
 @chapter Introduction
 @cindex introduction
 
@@ -808,7 +808,7 @@ MobileOrg
 * Conventions::                 Typesetting conventions in the manual
 @end menu
 
-@node Summary
+@node Summary, Installation, Introduction, Introduction
 @section Summary
 @cindex summary
 
@@ -864,7 +864,7 @@ Network Theory Ltd.}
 
 @page
 
-@node Installation
+@node Installation, Activation, Summary, Introduction
 @section Installation
 @cindex installation
 
@@ -940,7 +940,7 @@ For more detailed explanations on Org's build system, please check the Org
 Build System page on @uref{http://orgmode.org/worg/dev/org-build-system.html,
 Worg}.
 
-@node Activation
+@node Activation, Feedback, Installation, Introduction
 @section Activation
 @cindex activation
 @cindex autoload
@@ -991,7 +991,7 @@ the default.  If you do not like @code{transient-mark-mode}, you can create
 an active region by using the mouse to select a region, or pressing
 @kbd{C-@key{SPC}} twice before moving the cursor.
 
-@node Feedback
+@node Feedback, Conventions, Activation, Introduction
 @section Feedback
 @cindex feedback
 @cindex bug reports
@@ -1091,7 +1091,7 @@ screen.  Save this buffer to a file (for example using @kbd{C-x C-w}) and
 attach it to your bug report.
 @end enumerate
 
-@node Conventions
+@node Conventions,  , Feedback, Introduction
 @section Typesetting conventions used in this manual
 
 @subsubheading TODO keywords, tags, properties, etc.
@@ -1141,7 +1141,7 @@ will be listed to call @code{org-table-move-column-right}.  If you prefer,
 you can compile the manual without the command names by unsetting the flag
 @code{cmdnames} in @file{org.texi}.
 
-@node Document structure
+@node Document structure, Tables, Introduction, Top
 @chapter Document structure
 @cindex document structure
 @cindex structure of document
@@ -1164,7 +1164,7 @@ edit the structure of the document.
 * Org syntax::                  Formal description of Org's syntax
 @end menu
 
-@node Outlines
+@node Outlines, Headlines, Document structure, Document structure
 @section Outlines
 @cindex outlines
 @cindex Outline mode
@@ -1178,7 +1178,7 @@ currently being worked on.  Org greatly simplifies the use of
 outlines by compressing the entire show/hide functionality into a single
 command, @command{org-cycle}, which is bound to the @key{TAB} key.
 
-@node Headlines
+@node Headlines, Visibility cycling, Outlines, Document structure
 @section Headlines
 @cindex headlines
 @cindex outline tree
@@ -1220,7 +1220,7 @@ least two empty lines, one empty line will remain visible after folding
 the subtree, in order to structure the collapsed view.  See the
 variable @code{org-cycle-separator-lines} to modify this behavior.
 
-@node Visibility cycling
+@node Visibility cycling, Motion, Headlines, Document structure
 @section Visibility cycling
 @cindex cycling, visibility
 @cindex visibility cycling
@@ -1234,7 +1234,7 @@ variable @code{org-cycle-separator-lines} to modify this behavior.
 * Catching invisible edits::    Preventing mistakes when editing invisible parts
 @end menu
 
-@node Global and local cycling
+@node Global and local cycling, Initial visibility, Visibility cycling, Visibility cycling
 @subsection Global and local cycling
 
 Outlines make it possible to hide parts of the text in the buffer.
@@ -1315,7 +1315,7 @@ a @kbd{C-u} prefix, do not remove the previously used indirect buffer.
 Copy the @i{visible} text in the region into the kill ring.
 @end table
 
-@node Initial visibility
+@node Initial visibility, Catching invisible edits, Global and local cycling, Visibility cycling
 @subsection Initial visibility
 
 @cindex visibility, initialize
@@ -1355,7 +1355,7 @@ requested by startup options and @samp{VISIBILITY} properties in individual
 entries.
 @end table
 
-@node Catching invisible edits
+@node Catching invisible edits,  , Initial visibility, Visibility cycling
 @subsection Catching invisible edits
 
 @vindex org-catch-invisible-edits
@@ -1366,7 +1366,7 @@ confused on what has been edited and how to undo the mistake.  Setting
 docstring of this option on how Org should catch invisible edits and process
 them.
 
-@node Motion
+@node Motion, Structure editing, Visibility cycling, Document structure
 @section Motion
 @cindex motion, between headlines
 @cindex jumping, to headlines
@@ -1406,7 +1406,7 @@ q            @r{Quit}
 See also the option @code{org-goto-interface}.
 @end table
 
-@node Structure editing
+@node Structure editing, Sparse trees, Motion, Document structure
 @section Structure editing
 @cindex structure editing
 @cindex headline, promotion and demotion
@@ -1542,7 +1542,7 @@ inside a table (@pxref{Tables}), the Meta-Cursor keys have different
 functionality.
 
 
-@node Sparse trees
+@node Sparse trees, Plain lists, Structure editing, Document structure
 @section Sparse trees
 @cindex sparse trees
 @cindex trees, sparse
@@ -1609,7 +1609,7 @@ To print a sparse tree, you can use the Emacs command
 document.  Or you can use @kbd{C-c C-e C-v} to export only the visible part
 of the document and print the resulting file.
 
-@node Plain lists
+@node Plain lists, Drawers, Sparse trees, Document structure
 @section Plain lists
 @cindex plain lists
 @cindex lists, plain
@@ -1813,7 +1813,7 @@ numerically, alphabetically, by time, by checked status for check lists,
 or by a custom function.
 @end table
 
-@node Drawers
+@node Drawers, Blocks, Plain lists, Document structure
 @section Drawers
 @cindex drawers
 @cindex visibility cycling, drawers
@@ -1866,7 +1866,7 @@ You can select the name of the drawers which should be exported with
 export output.  Property drawers are not affected by this variable: configure
 @code{org-export-with-properties} instead.
 
-@node Blocks
+@node Blocks, Footnotes, Drawers, Document structure
 @section Blocks
 
 @vindex org-hide-block-startup
@@ -1885,7 +1885,7 @@ or on a per-file basis by using
 #+STARTUP: nohideblocks
 @end example
 
-@node Footnotes
+@node Footnotes, Orgstruct mode, Blocks, Document structure
 @section Footnotes
 @cindex footnotes
 
@@ -1990,7 +1990,7 @@ a separate window.  The window can be closed by pressing @kbd{C-c '}.
 
 @end table
 
-@node Orgstruct mode
+@node Orgstruct mode, Org syntax, Footnotes, Document structure
 @section The Orgstruct minor mode
 @cindex Orgstruct mode
 @cindex minor mode for structure editing
@@ -2025,7 +2025,7 @@ Lisp files, you will be able to fold and unfold headlines in Emacs Lisp
 commented lines.  Some commands like @code{org-demote} are disabled when the
 prefix is set, but folding/unfolding will work correctly.
 
-@node Org syntax
+@node Org syntax,  , Orgstruct mode, Document structure
 @section Org syntax
 @cindex Org syntax
 
@@ -2051,7 +2051,7 @@ rely on the syntactic meaning of the surrounding context.
 @cindex linter
 You can check syntax in your documents using @code{org-lint} command.
 
-@node Tables
+@node Tables, Hyperlinks, Document structure, Top
 @chapter Tables
 @cindex tables
 @cindex editing tables
@@ -2069,7 +2069,7 @@ calculations are supported using the Emacs @file{calc} package
 * Org-Plot::                    Plotting from org tables
 @end menu
 
-@node Built-in table editor
+@node Built-in table editor, Column width and alignment, Tables, Tables
 @section The built-in table editor
 @cindex table editor, built-in
 
@@ -2289,7 +2289,7 @@ it off with
 @noindent Then the only table command that still works is
 @kbd{C-c C-c} to do a manual re-align.
 
-@node Column width and alignment
+@node Column width and alignment, Column groups, Built-in table editor, Tables
 @section Column width and alignment
 @cindex narrow columns in tables
 @cindex alignment in tables
@@ -2380,7 +2380,7 @@ alignment and field width like this: @samp{<r10>}.
 Lines which only contain these formatting cookies are removed automatically
 upon exporting the document.
 
-@node Column groups
+@node Column groups, Orgtbl mode, Column width and alignment, Tables
 @section Column groups
 @cindex grouping columns in tables
 
@@ -2415,7 +2415,7 @@ every vertical line you would like to have:
 | /  | <   |     |     | <       |            |
 @end example
 
-@node Orgtbl mode
+@node Orgtbl mode, The spreadsheet, Column groups, Tables
 @section The Orgtbl minor mode
 @cindex Orgtbl mode
 @cindex minor mode for tables
@@ -2436,7 +2436,7 @@ construct @LaTeX{} tables with the underlying ease and power of
 Orgtbl mode, including spreadsheet capabilities.  For details, see
 @ref{Tables in arbitrary syntax}.
 
-@node The spreadsheet
+@node The spreadsheet, Org-Plot, Orgtbl mode, Tables
 @section The spreadsheet
 @cindex calculations, in tables
 @cindex spreadsheet capabilities
@@ -2465,7 +2465,7 @@ formula, moving these references by arrow keys
 * Advanced features::           Field and column names, parameters and automatic recalc
 @end menu
 
-@node References
+@node References, Formula syntax for Calc, The spreadsheet, The spreadsheet
 @subsection References
 @cindex references
 
@@ -2657,7 +2657,7 @@ table.  For example @code{remote($1, @@>$2)} => @code{remote(year_2013,
 @@>$1)}.  The format @code{B3} is not supported because it can not be
 distinguished from a plain table name or ID.
 
-@node Formula syntax for Calc
+@node Formula syntax for Calc, Formula syntax for Lisp, References, The spreadsheet
 @subsection Formula syntax for Calc
 @cindex formula syntax, Calc
 @cindex syntax, of formulas
@@ -2772,7 +2772,7 @@ should be padded with 0 to the full size.
 You can add your own Calc functions defined in Emacs Lisp with @code{defmath}
 and use them in formula syntax for Calc.
 
-@node Formula syntax for Lisp
+@node Formula syntax for Lisp, Durations and time values, Formula syntax for Calc, The spreadsheet
 @subsection Emacs Lisp forms as formulas
 @cindex Lisp forms, as table formulas
 
@@ -2808,7 +2808,7 @@ Add columns 1 and 2, equivalent to Calc's @code{$1+$2}.
 Compute the sum of columns 1 to 4, like Calc's @code{vsum($1..$4)}.
 @end table
 
-@node Durations and time values
+@node Durations and time values, Field and range formulas, Formula syntax for Lisp, The spreadsheet
 @subsection Durations and time values
 @cindex Duration, computing
 @cindex Time, computing
@@ -2843,7 +2843,7 @@ third formula in the example above).
 Negative duration values can be manipulated as well, and integers will be
 considered as seconds in addition and subtraction.
 
-@node Field and range formulas
+@node Field and range formulas, Column formulas, Durations and time values, The spreadsheet
 @subsection Field and range formulas
 @cindex field formula
 @cindex range formula
@@ -2899,7 +2899,7 @@ can also be used to assign a formula to some but not all fields in a row.
 Named field, see @ref{Advanced features}.
 @end table
 
-@node Column formulas
+@node Column formulas, Lookup functions, Field and range formulas, The spreadsheet
 @subsection Column formulas
 @cindex column formula
 @cindex formula, for table column
@@ -2938,7 +2938,7 @@ stores it.  With a numeric prefix argument(e.g., @kbd{C-5 C-c =}) the command
 will apply it to that many consecutive fields in the current column.
 @end table
 
-@node Lookup functions
+@node Lookup functions, Editing and debugging formulas, Column formulas, The spreadsheet
 @subsection Lookup functions
 @cindex lookup functions in tables
 @cindex table lookup functions
@@ -2982,7 +2982,7 @@ matching cells, rank results, group data etc.  For practical examples
 see @uref{http://orgmode.org/worg/org-tutorials/org-lookups.html, this
 tutorial on Worg}.
 
-@node Editing and debugging formulas
+@node Editing and debugging formulas, Updating the table, Lookup functions, The spreadsheet
 @subsection Editing and debugging formulas
 @cindex formula editing
 @cindex editing, of table formulas
@@ -3135,7 +3135,7 @@ turn on formula debugging in the @code{Tbl} menu and repeat the
 calculation, for example by pressing @kbd{C-u C-u C-c = @key{RET}} in a
 field.  Detailed information will be displayed.
 
-@node Updating the table
+@node Updating the table, Advanced features, Editing and debugging formulas, The spreadsheet
 @subsection Updating the table
 @cindex recomputing table fields
 @cindex updating, table
@@ -3172,7 +3172,7 @@ Iterate all tables in the current buffer, in order to converge table-to-table
 dependencies.
 @end table
 
-@node Advanced features
+@node Advanced features,  , Updating the table, The spreadsheet
 @subsection Advanced features
 
 If you want the recalculation of fields to happen automatically, or if you
@@ -3277,7 +3277,7 @@ functions.
 @end group
 @end example
 
-@node Org-Plot
+@node Org-Plot,  , The spreadsheet, Tables
 @section Org-Plot
 @cindex graph, in tables
 @cindex plot tables using Gnuplot
@@ -3409,7 +3409,7 @@ The formula is an elisp call:
 
 @end table
 
-@node Hyperlinks
+@node Hyperlinks, TODO items, Tables, Top
 @chapter Hyperlinks
 @cindex hyperlinks
 
@@ -3427,7 +3427,7 @@ other files, Usenet articles, emails, and much more.
 * Custom searches::             When the default search is not enough
 @end menu
 
-@node Link format
+@node Link format, Internal links, Hyperlinks, Hyperlinks
 @section Link format
 @cindex link format
 @cindex format, of links
@@ -3458,7 +3458,7 @@ missing bracket hides the link internals again.  To show the
 internal structure of all links, use the menu entry
 @code{Org->Hyperlinks->Literal links}.
 
-@node Internal links
+@node Internal links, External links, Link format, Hyperlinks
 @section Internal links
 @cindex internal links
 @cindex links, internal
@@ -3529,7 +3529,7 @@ earlier.
 * Radio targets::               Make targets trigger links in plain text
 @end menu
 
-@node Radio targets
+@node Radio targets,  , Internal links, Internal links
 @subsection Radio targets
 @cindex radio targets
 @cindex targets, radio
@@ -3545,7 +3545,7 @@ for radio targets only when the file is first loaded into Emacs.  To
 update the target list during editing, press @kbd{C-c C-c} with the
 cursor on or at a target.
 
-@node External links
+@node External links, Handling links, Internal links, Hyperlinks
 @section External links
 @cindex links, external
 @cindex external links
@@ -3648,7 +3648,7 @@ as links.  If spaces must be part of the link (for example in
 @samp{bbdb:Richard Stallman}), or if you need to remove ambiguities
 about the end of the link, enclose them in square brackets.
 
-@node Handling links
+@node Handling links, Using links outside Org, External links, Hyperlinks
 @section Handling links
 @cindex links, handling
 
@@ -3846,7 +3846,7 @@ to @kbd{C-n} and @kbd{C-p}
 @end lisp
 @end table
 
-@node Using links outside Org
+@node Using links outside Org, Link abbreviations, Handling links, Hyperlinks
 @section Using links outside Org
 
 You can insert and follow links that have Org syntax not only in
@@ -3859,7 +3859,7 @@ yourself):
 (global-set-key "\C-c o" 'org-open-at-point-global)
 @end lisp
 
-@node Link abbreviations
+@node Link abbreviations, Search options, Using links outside Org, Hyperlinks
 @section Link abbreviations
 @cindex link abbreviations
 @cindex abbreviation, links
@@ -3933,7 +3933,7 @@ link with prefix.  You can add a completion function to a link like this:
 @end lisp
 
 
-@node Search options
+@node Search options, Custom searches, Link abbreviations, Hyperlinks
 @section Search options in file links
 @cindex search option in file links
 @cindex file links, searching
@@ -3985,7 +3985,7 @@ to search the current file.  For example, @code{[[file:::find me]]} does
 a search for @samp{find me} in the current file, just as
 @samp{[[find me]]} would.
 
-@node Custom searches
+@node Custom searches,  , Search options, Hyperlinks
 @section Custom Searches
 @cindex custom search strings
 @cindex search strings, custom
@@ -4009,7 +4009,7 @@ variables for more information.  Org actually uses this mechanism
 for Bib@TeX{} database files, and you can use the corresponding code as
 an implementation example.  See the file @file{org-bibtex.el}.
 
-@node TODO items
+@node TODO items, Tags, Hyperlinks, Top
 @chapter TODO items
 @cindex TODO items
 
@@ -4034,7 +4034,7 @@ methods to give you an overview of all the things that you have to do.
 * Checkboxes::                  Tick-off lists
 @end menu
 
-@node TODO basics
+@node TODO basics, TODO extensions, TODO items, TODO items
 @section Basic TODO functionality
 
 Any headline becomes a TODO item when it starts with the word
@@ -4108,7 +4108,7 @@ Insert a new TODO entry below the current one.
 Changing a TODO state can also trigger tag changes.  See the docstring of the
 option @code{org-todo-state-tags-triggers} for details.
 
-@node TODO extensions
+@node TODO extensions, Progress logging, TODO basics, TODO items
 @section Extended use of TODO keywords
 @cindex extended TODO keywords
 
@@ -4132,7 +4132,7 @@ TODO items in particular (@pxref{Tags}).
 * TODO dependencies::           When one task needs to wait for others
 @end menu
 
-@node Workflow states
+@node Workflow states, TODO types, TODO extensions, TODO extensions
 @subsection TODO keywords as workflow states
 @cindex TODO workflow
 @cindex workflow states as TODO keywords
@@ -4163,7 +4163,7 @@ define many keywords, you can use in-buffer completion
 buffer.  Changing a TODO state can be logged with a timestamp, see
 @ref{Tracking TODO state changes}, for more information.
 
-@node TODO types
+@node TODO types, Multiple sets in one file, Workflow states, TODO extensions
 @subsection TODO keywords as types
 @cindex TODO types
 @cindex names as TODO keywords
@@ -4195,7 +4195,7 @@ has to do, you would use @kbd{C-3 C-c / t}.  To collect Lucy's items from all
 agenda files into a single buffer, you would use the numeric prefix argument
 as well when creating the global TODO list: @kbd{C-3 C-c a t}.
 
-@node Multiple sets in one file
+@node Multiple sets in one file, Fast access to TODO states, TODO types, TODO extensions
 @subsection Multiple keyword sets in one file
 @cindex TODO keyword sets
 
@@ -4244,7 +4244,7 @@ from @code{DONE} to @code{REPORT} in the example above.  See also
 @code{shift-selection-mode}.
 @end table
 
-@node Fast access to TODO states
+@node Fast access to TODO states, Per-file keywords, Multiple sets in one file, TODO extensions
 @subsection Fast access to TODO states
 
 If you would like to quickly change an entry to an arbitrary TODO state
@@ -4269,7 +4269,7 @@ state through the tags interface (@pxref{Setting tags}), in case you like to
 mingle the two concepts.  Note that this means you need to come up with
 unique keys across both sets of keywords.}
 
-@node Per-file keywords
+@node Per-file keywords, Faces for TODO keywords, Fast access to TODO states, TODO extensions
 @subsection Setting up keywords for individual files
 @cindex keyword options
 @cindex per-file keywords
@@ -4315,7 +4315,7 @@ Org mode is activated after visiting a file.  @kbd{C-c C-c} with the
 cursor in a line starting with @samp{#+} is simply restarting Org mode
 for the current buffer.}.
 
-@node Faces for TODO keywords
+@node Faces for TODO keywords, TODO dependencies, Per-file keywords, TODO extensions
 @subsection Faces for TODO keywords
 @cindex faces, for TODO keywords
 
@@ -4343,7 +4343,7 @@ special face and use that.  A string is interpreted as a color.  The option
 @code{org-faces-easy-properties} determines if that color is interpreted as a
 foreground or a background color.
 
-@node TODO dependencies
+@node TODO dependencies,  , Faces for TODO keywords, TODO extensions
 @subsection TODO dependencies
 @cindex TODO dependencies
 @cindex dependencies, of TODO states
@@ -4416,7 +4416,7 @@ between entries in different trees or files, check out the contributed
 module @file{org-depend.el}.
 
 @page
-@node Progress logging
+@node Progress logging, Priorities, TODO extensions, TODO items
 @section Progress logging
 @cindex progress logging
 @cindex logging, of progress
@@ -4434,7 +4434,7 @@ work time}.
 * Tracking your habits::        How consistent have you been?
 @end menu
 
-@node Closing items
+@node Closing items, Tracking TODO state changes, Progress logging, Progress logging
 @subsection Closing items
 
 The most basic logging is to keep track of @emph{when} a certain TODO
@@ -4465,7 +4465,7 @@ lognotedone}.}
 You will then be prompted for a note, and that note will be stored below
 the entry with a @samp{Closing Note} heading.
 
-@node Tracking TODO state changes
+@node Tracking TODO state changes, Tracking your habits, Closing items, Progress logging
 @subsection Tracking TODO state changes
 @cindex drawer, for state change recording
 
@@ -4548,7 +4548,7 @@ settings like @code{TODO(!)}.  For example
   :END:
 @end example
 
-@node Tracking your habits
+@node Tracking your habits,  , Tracking TODO state changes, Progress logging
 @subsection Tracking your habits
 @cindex habits
 
@@ -4648,7 +4648,7 @@ temporarily be disabled and they won't appear at all.  Press @kbd{K} again to
 bring them back.  They are also subject to tag filtering, if you have habits
 which should only be done in certain contexts, for example.
 
-@node Priorities
+@node Priorities, Breaking down tasks, Progress logging, TODO items
 @section Priorities
 @cindex priorities
 
@@ -4706,7 +4706,7 @@ priority):
 #+PRIORITIES: A C B
 @end example
 
-@node Breaking down tasks
+@node Breaking down tasks, Checkboxes, Priorities, TODO items
 @section Breaking tasks down into subtasks
 @cindex tasks, breaking down
 @cindex statistics, for TODO items
@@ -4767,7 +4767,7 @@ Another possibility is the use of checkboxes to identify (a hierarchy of) a
 large number of subtasks (@pxref{Checkboxes}).
 
 
-@node Checkboxes
+@node Checkboxes,  , Breaking down tasks, TODO items
 @section Checkboxes
 @cindex checkboxes
 
@@ -4876,7 +4876,7 @@ changing TODO states.  If you delete boxes/entries or add/change them by
 hand, use this command to get things back into sync.
 @end table
 
-@node Tags
+@node Tags, Properties and columns, TODO items, Top
 @chapter Tags
 @cindex tags
 @cindex headline tagging
@@ -4904,7 +4904,7 @@ You may specify special faces for specific tags using the option
 * Tag searches::                Searching for combinations of tags
 @end menu
 
-@node Tag inheritance
+@node Tag inheritance, Setting tags, Tags, Tags
 @section Tag inheritance
 @cindex tag inheritance
 @cindex inheritance, of tags
@@ -4958,7 +4958,7 @@ with inherited tags.  Set @code{org-agenda-use-tag-inheritance} to control
 this: the default value includes all agenda types, but setting this to @code{nil}
 can really speed up agenda generation.
 
-@node Setting tags
+@node Setting tags, Tag hierarchy, Tag inheritance, Tags
 @section Setting tags
 @cindex setting tags
 @cindex tags, setting
@@ -5145,7 +5145,7 @@ instead of @kbd{C-c C-c}).  If you set the variable to the value
 @code{expert}, the special window is not even shown for single-key tag
 selection, it comes up only when you press an extra @kbd{C-c}.
 
-@node Tag hierarchy
+@node Tag hierarchy, Tag searches, Setting tags, Tags
 @section Tag hierarchy
 
 @cindex group tags
@@ -5250,7 +5250,7 @@ If you want to ignore group tags temporarily, toggle group tags support
 with @command{org-toggle-tags-groups}, bound to @kbd{C-c C-x q}.  If you
 want to disable tag groups completely, set @code{org-group-tags} to @code{nil}.
 
-@node Tag searches
+@node Tag searches,  , Tag hierarchy, Tags
 @section Tag searches
 @cindex tag searches
 @cindex searching for tags
@@ -5282,7 +5282,7 @@ properties.  For a complete description with many examples, see @ref{Matching
 tags and properties}.
 
 
-@node Properties and columns
+@node Properties and columns, Dates and times, Tags, Top
 @chapter Properties and columns
 @cindex properties
 
@@ -5312,7 +5312,7 @@ Properties can be conveniently edited and viewed in column view
 * Property API::                Properties for Lisp programmers
 @end menu
 
-@node Property syntax
+@node Property syntax, Special properties, Properties and columns, Properties and columns
 @section Property syntax
 @cindex property syntax
 @cindex drawer, for properties
@@ -5436,7 +5436,7 @@ Compute the property at point, using the operator and scope from the
 nearest column format definition.
 @end table
 
-@node Special properties
+@node Special properties, Property searches, Property syntax, Properties and columns
 @section Special properties
 @cindex properties, special
 
@@ -5481,7 +5481,7 @@ TIMESTAMP_IA @r{The first inactive timestamp in the entry.}
 TODO         @r{The TODO keyword of the entry.}
 @end example
 
-@node Property searches
+@node Property searches, Property inheritance, Special properties, Properties and columns
 @section Property searches
 @cindex properties, searching
 @cindex searching, of properties
@@ -5518,7 +5518,7 @@ value.  If you enclose the value in curly braces, it is interpreted as
 a regular expression and matched against the property values.
 @end table
 
-@node Property inheritance
+@node Property inheritance, Column view, Property searches, Properties and columns
 @section Property Inheritance
 @cindex properties, inheritance
 @cindex inheritance, of properties
@@ -5562,7 +5562,7 @@ The LOGGING property may define logging settings for an entry or a
 subtree (@pxref{Tracking TODO state changes}).
 @end table
 
-@node Column view
+@node Column view, Property API, Property inheritance, Properties and columns
 @section Column view
 
 A great way to view and edit properties in an outline tree is
@@ -5585,7 +5585,7 @@ queries have collected selected items, possibly from a number of files.
 * Capturing column view::       A dynamic block for column view
 @end menu
 
-@node Defining columns
+@node Defining columns, Using column view, Column view, Column view
 @subsection Defining columns
 @cindex column view, for properties
 @cindex properties, column view
@@ -5598,7 +5598,7 @@ done by defining a column format line.
 * Column attributes::           Appearance and content of a column
 @end menu
 
-@node Scope of column definitions
+@node Scope of column definitions, Column attributes, Defining columns, Defining columns
 @subsubsection Scope of column definitions
 
 To define a column format for an entire file, use a line like
@@ -5625,7 +5625,7 @@ you can define columns on level 1 that are general enough for all
 sublevels, and more specific columns further down, when you edit a
 deeper part of the tree.
 
-@node Column attributes
+@node Column attributes,  , Scope of column definitions, Defining columns
 @subsubsection Column attributes
 A column definition sets the attributes of a column.  The general
 definition looks like this:
@@ -5731,7 +5731,7 @@ an @samp{[X]} status if all children have been checked.  The
 sums of CLOCK intervals in the subtree, either for all clocks or just for
 today.
 
-@node Using column view
+@node Using column view, Capturing column view, Defining columns, Column view
 @subsection Using column view
 
 @table @kbd
@@ -5790,7 +5790,7 @@ Insert a new column, to the left of the current column.
 Delete the current column.
 @end table
 
-@node Capturing column view
+@node Capturing column view,  , Using column view, Column view
 @subsection Capturing column view
 
 Since column view is just an overlay over a buffer, it cannot be
@@ -5869,7 +5869,7 @@ distributed with the main distribution of Org (visit
 properties from entries in a certain scope, and arbitrary Lisp expressions to
 process these values before inserting them into a table or a dynamic block.
 
-@node Property API
+@node Property API,  , Column view, Properties and columns
 @section The Property API
 @cindex properties, API
 @cindex API, for properties
@@ -5879,7 +5879,7 @@ be used by Emacs Lisp programs to work with properties and to implement
 features based on them.  For more information see @ref{Using the
 property API}.
 
-@node Dates and times
+@node Dates and times, Capture - Refile - Archive, Properties and columns, Top
 @chapter Dates and times
 @cindex dates
 @cindex times
@@ -5903,7 +5903,7 @@ is used in a much wider sense.
 @end menu
 
 
-@node Timestamps
+@node Timestamps, Creating timestamps, Dates and times, Dates and times
 @section Timestamps, deadlines, and scheduling
 @cindex timestamps
 @cindex ranges, time
@@ -5997,7 +5997,7 @@ angular ones.  These timestamps are inactive in the sense that they do
 
 @end table
 
-@node Creating timestamps
+@node Creating timestamps, Deadlines and scheduling, Timestamps, Dates and times
 @section Creating timestamps
 @cindex creating timestamps
 @cindex timestamps, creating
@@ -6068,7 +6068,7 @@ the following column).
 * Custom time format::          Making dates look different
 @end menu
 
-@node The date/time prompt
+@node The date/time prompt, Custom time format, Creating timestamps, Creating timestamps
 @subsection The date/time prompt
 @cindex date, reading in minibuffer
 @cindex time, reading in minibuffer
@@ -6198,7 +6198,7 @@ on, the current interpretation of your input will be displayed live in the
 minibuffer@footnote{If you find this distracting, turn the display off with
 @code{org-read-date-display-live}.}.
 
-@node Custom time format
+@node Custom time format,  , The date/time prompt, Creating timestamps
 @subsection Custom time format
 @cindex custom date/time format
 @cindex time format, custom
@@ -6246,7 +6246,7 @@ format is shorter, things do work as expected.
 @end itemize
 
 
-@node Deadlines and scheduling
+@node Deadlines and scheduling, Clocking work time, Creating timestamps, Dates and times
 @section Deadlines and scheduling
 
 A timestamp may be preceded by special keywords to facilitate planning.  Both
@@ -6337,7 +6337,7 @@ sexp entry matches.
 * Repeated tasks::              Items that show up again and again
 @end menu
 
-@node Inserting deadline/schedule
+@node Inserting deadline/schedule, Repeated tasks, Deadlines and scheduling, Deadlines and scheduling
 @subsection Inserting deadlines or schedules
 
 The following commands allow you to quickly insert a deadline or to schedule
@@ -6384,7 +6384,7 @@ setting the date by indicating a relative time: e.g., +1d will set
 the date to the next day after today, and --1w will set the date
 to the previous week before any current timestamp.
 
-@node Repeated tasks
+@node Repeated tasks,  , Inserting deadline/schedule, Deadlines and scheduling
 @subsection Repeated tasks
 @cindex tasks, repeated
 @cindex repeated tasks
@@ -6485,7 +6485,7 @@ subtree, with dates shifted in each copy.  The command @kbd{C-c C-x c} was
 created for this purpose, it is described in @ref{Structure editing}.
 
 
-@node Clocking work time
+@node Clocking work time, Effort estimates, Deadlines and scheduling, Dates and times
 @section Clocking work time
 @cindex clocking time
 @cindex time clocking
@@ -6517,7 +6517,7 @@ what to do with it.
 * Resolving idle time::         Resolving time when you've been idle
 @end menu
 
-@node Clocking commands
+@node Clocking commands, The clock table, Clocking work time, Clocking work time
 @subsection Clocking commands
 
 @table @kbd
@@ -6616,7 +6616,7 @@ which tasks have been worked on or closed during a day.
 @code{org-clock-in-last} can have a global key binding and will not
 modify the window disposition.
 
-@node The clock table
+@node The clock table, Resolving idle time, Clocking commands, Clocking work time
 @subsection The clock table
 @cindex clocktable, dynamic block
 @cindex report, of clocked time
@@ -6768,7 +6768,7 @@ would be
 #+END: clocktable
 @end example
 
-@node Resolving idle time
+@node Resolving idle time,  , The clock table, Clocking work time
 @subsection Resolving idle time and continuous clocking
 
 @subsubheading Resolving idle time
@@ -6853,7 +6853,7 @@ last clocked entry for this session, and start the new clock from there.
 If you only want this from time to time, use three universal prefix arguments
 with @code{org-clock-in} and two @kbd{C-u C-u} with @code{org-clock-in-last}.
 
-@node Effort estimates
+@node Effort estimates, Timers, Clocking work time, Dates and times
 @section Effort estimates
 @cindex effort estimates
 
@@ -6914,7 +6914,7 @@ with the @kbd{/} key in the agenda (@pxref{Agenda commands}).  If you have
 these estimates defined consistently, two or three key presses will narrow
 down the list to stuff that fits into an available time slot.
 
-@node Timers
+@node Timers,  , Effort estimates, Dates and times
 @section Taking notes with a timer
 @cindex relative timer
 @cindex countdown timer
@@ -6964,7 +6964,7 @@ Stop the timer.  After this, you can only start a new timer, not continue the
 old one.  This command also removes the timer from the mode line.
 @end table
 
-@node Capture - Refile - Archive
+@node Capture - Refile - Archive, Agenda views, Dates and times, Top
 @chapter Capture - Refile - Archive
 @cindex capture
 
@@ -6984,7 +6984,7 @@ trees to an archive file keeps the system compact and fast.
 * Archiving::                   What to do with finished projects
 @end menu
 
-@node Capture
+@node Capture, Attachments, Capture - Refile - Archive, Capture - Refile - Archive
 @section Capture
 @cindex capture
 
@@ -7011,7 +7011,7 @@ customization.
 * Capture templates::           Define the outline of different note types
 @end menu
 
-@node Setting up capture
+@node Setting up capture, Using capture, Capture, Capture
 @subsection Setting up capture
 
 The following customization sets a default target file for notes, and defines
@@ -7026,7 +7026,7 @@ suggestion.}  for capturing new material.
 @end group
 @end smalllisp
 
-@node Using capture
+@node Using capture, Capture templates, Setting up capture, Capture
 @subsection Using capture
 
 @table @kbd
@@ -7083,7 +7083,7 @@ automatically be created unless you set @code{org-capture-bookmark} to
 To insert the capture at point in an Org buffer, call @code{org-capture} with
 a @code{C-0} prefix argument.
 
-@node Capture templates
+@node Capture templates,  , Using capture, Capture
 @subsection Capture templates
 @cindex templates, for Capture
 
@@ -7142,7 +7142,7 @@ like this:
 * Templates in contexts::       Only show a template in a specific context
 @end menu
 
-@node Template elements
+@node Template elements, Template expansion, Capture templates, Capture templates
 @subsubsection Template elements
 
 Now lets look at the elements of a template definition.  Each entry in
@@ -7307,7 +7307,7 @@ buffer again after capture is completed.
 @end table
 @end table
 
-@node Template expansion
+@node Template expansion, Templates in contexts, Template elements, Capture templates
 @subsubsection Template expansion
 
 In the template itself, special @kbd{%}-escapes@footnote{If you need one of
@@ -7392,7 +7392,7 @@ To place the cursor after template expansion use:
 %?          @r{After completing the template, position cursor here.}
 @end smallexample
 
-@node Templates in contexts
+@node Templates in contexts,  , Template expansion, Capture templates
 @subsubsection Templates in contexts
 
 @vindex org-capture-templates-contexts
@@ -7416,7 +7416,7 @@ template.  In that case, add this command key like this:
 
 See the docstring of the variable for more information.
 
-@node Attachments
+@node Attachments, RSS feeds, Capture, Capture - Refile - Archive
 @section Attachments
 @cindex attachments
 
@@ -7507,7 +7507,7 @@ same directory for attachments as the parent does.
 @end table
 @end table
 
-@node RSS feeds
+@node RSS feeds, Protocols, Attachments, Capture - Refile - Archive
 @section RSS feeds
 @cindex RSS feeds
 @cindex Atom feeds
@@ -7550,7 +7550,7 @@ adding the same item several times.
 For more information, including how to read atom feeds, see
 @file{org-feed.el} and the docstring of @code{org-feed-alist}.
 
-@node Protocols
+@node Protocols, Refile and copy, RSS feeds, Capture - Refile - Archive
 @section Protocols for external access
 @cindex protocols, for external access
 
@@ -7588,7 +7588,7 @@ sections.  Configure @code{org-protocol-protocol-alist} to define your own.
 * @code{open-source} protocol::  Edit published contents.
 @end menu
 
-@node @code{store-link} protocol
+@node @code{store-link} protocol, @code{capture} protocol, Protocols, Protocols
 @subsection @code{store-link} protocol
 @cindex store-link protocol
 @cindex protocol, store-link
@@ -7619,7 +7619,7 @@ javascript:location.href='org-protocol://store-link?url='+
       encodeURIComponent(location.href);
 @end example
 
-@node @code{capture} protocol
+@node @code{capture} protocol, @code{open-source} protocol, @code{store-link} protocol, Protocols
 @subsection @code{capture} protocol
 @cindex capture protocol
 @cindex protocol, capture
@@ -7661,7 +7661,7 @@ The following template placeholders are available:
 %i              The selected text
 @end example
 
-@node @code{open-source} protocol
+@node @code{open-source} protocol,  , @code{capture} protocol, Protocols
 @subsection @code{open-source} protocol
 @cindex open-source protocol
 @cindex protocol, open-source
@@ -7758,7 +7758,7 @@ valid contents: @code{org-protocol-create} and
 @code{org-protocol-create-for-org}.  The latter is of use if you're editing
 an Org file that is part of a publishing project.
 
-@node Refile and copy
+@node Refile and copy, Archiving, Protocols, Capture - Refile - Archive
 @section Refile and copy
 @cindex refiling notes
 @cindex copying notes
@@ -7815,7 +7815,7 @@ setting @code{org-refile-use-cache}.  To make the command see new possible
 targets, you have to clear the cache with this command.
 @end table
 
-@node Archiving
+@node Archiving,  , Refile and copy, Capture - Refile - Archive
 @section Archiving
 @cindex archiving
 
@@ -7836,7 +7836,7 @@ Archive the current entry using the command specified in the variable
 * Internal archiving::          Switch off a tree but keep it in the file
 @end menu
 
-@node Moving subtrees
+@node Moving subtrees, Internal archiving, Archiving, Archiving
 @subsection Moving a tree to the archive file
 @cindex external archiving
 
@@ -7890,7 +7890,7 @@ outline path the archiving time etc.  Configure the variable
 added.
 
 
-@node Internal archiving
+@node Internal archiving,  , Moving subtrees, Archiving
 @subsection Internal archiving
 
 @cindex archive tag
@@ -7954,7 +7954,7 @@ outline.
 @end table
 
 
-@node Agenda views
+@node Agenda views, Markup, Capture - Refile - Archive, Top
 @chapter Agenda views
 @cindex agenda views
 
@@ -8021,7 +8021,7 @@ window configuration is restored when the agenda exits:
 * Agenda column view::          Using column view for collected entries
 @end menu
 
-@node Agenda files
+@node Agenda files, Agenda dispatcher, Agenda views, Agenda views
 @section Agenda files
 @cindex agenda files
 @cindex files for agenda
@@ -8098,7 +8098,7 @@ effect immediately.
 Lift the restriction.
 @end table
 
-@node Agenda dispatcher
+@node Agenda dispatcher, Built-in agenda views, Agenda files, Agenda views
 @section The agenda dispatcher
 @cindex agenda dispatcher
 @cindex dispatching agenda commands
@@ -8161,7 +8161,7 @@ possibility to create extended agenda buffers that contain several
 blocks together, for example the weekly agenda, the global TODO list and
 a number of special tags matches.  @xref{Custom agenda views}.
 
-@node Built-in agenda views
+@node Built-in agenda views, Presentation and sorting, Agenda dispatcher, Agenda views
 @section The built-in agenda views
 
 In this section we describe the built-in views.
@@ -8174,7 +8174,7 @@ In this section we describe the built-in views.
 * Stuck projects::              Find projects you need to review
 @end menu
 
-@node Weekly/daily agenda
+@node Weekly/daily agenda, Global TODO list, Built-in agenda views, Built-in agenda views
 @subsection The weekly/daily agenda
 @cindex agenda
 @cindex weekly agenda
@@ -8333,7 +8333,7 @@ It also reads a @code{APPT_WARNTIME} property which will then override the
 value of @code{appt-message-warning-time} for this appointment.  See the
 docstring for details.
 
-@node Global TODO list
+@node Global TODO list, Matching tags and properties, Weekly/daily agenda, Built-in agenda views
 @subsection The global TODO list
 @cindex global TODO list
 @cindex TODO list, global
@@ -8394,7 +8394,7 @@ and omit the sublevels from the global list.  Configure the variable
 @code{org-agenda-todo-list-sublevels} to get this behavior.
 @end itemize
 
-@node Matching tags and properties
+@node Matching tags and properties, Search view, Global TODO list, Built-in agenda views
 @subsection Matching tags and properties
 @cindex matching, of tags
 @cindex matching, of properties
@@ -8567,7 +8567,7 @@ Select @samp{:work:}-tagged TODO lines that are either @samp{WAITING} or
 @samp{NEXT}.
 @end table
 
-@node Search view
+@node Search view, Stuck projects, Matching tags and properties, Built-in agenda views
 @subsection Search view
 @cindex search view
 @cindex text search
@@ -8597,7 +8597,7 @@ the docstring of the command @code{org-search-view}.
 Note that in addition to the agenda files, this command will also search
 the files listed in @code{org-agenda-text-search-extra-files}.
 
-@node Stuck projects
+@node Stuck projects,  , Search view, Built-in agenda views
 @subsection Stuck projects
 @pindex GTD, Getting Things Done
 
@@ -8645,7 +8645,7 @@ correct customization for this is
 Note that if a project is identified as non-stuck, the subtree of this entry
 will still be searched for stuck projects.
 
-@node Presentation and sorting
+@node Presentation and sorting, Agenda commands, Built-in agenda views, Agenda views
 @section Presentation and sorting
 @cindex presentation, of agenda items
 
@@ -8667,7 +8667,7 @@ associated with the item.
 * Filtering/limiting agenda items::  Dynamically narrow the agenda
 @end menu
 
-@node Categories
+@node Categories, Time-of-day specifications, Presentation and sorting, Presentation and sorting
 @subsection Categories
 
 @cindex category
@@ -8694,7 +8694,7 @@ longer than 10 characters.
 You can set up icons for category by customizing the
 @code{org-agenda-category-icon-alist} variable.
 
-@node Time-of-day specifications
+@node Time-of-day specifications, Sorting agenda items, Categories, Presentation and sorting
 @subsection Time-of-day specifications
 @cindex time-of-day specification
 
@@ -8745,7 +8745,7 @@ The time grid can be turned on and off with the variable
 @code{org-agenda-use-time-grid}, and can be configured with
 @code{org-agenda-time-grid}.
 
-@node Sorting agenda items
+@node Sorting agenda items, Filtering/limiting agenda items, Time-of-day specifications, Presentation and sorting
 @subsection Sorting agenda items
 @cindex sorting, of agenda items
 @cindex priorities, of agenda items
@@ -8779,7 +8779,7 @@ Sorting can be customized using the variable
 @code{org-agenda-sorting-strategy}, and may also include criteria based on
 the estimated effort of an entry (@pxref{Effort estimates}).
 
-@node Filtering/limiting agenda items
+@node Filtering/limiting agenda items,  , Sorting agenda items, Presentation and sorting
 @subsection Filtering/limiting agenda items
 
 Agenda built-in or customized commands are statically defined.  Agenda
@@ -8965,7 +8965,7 @@ rebuilding the agenda:
 This prompts for the type of limit to apply and its value.
 @end table
 
-@node Agenda commands
+@node Agenda commands, Custom agenda views, Presentation and sorting, Agenda views
 @section Commands in the agenda buffer
 @cindex commands, in agenda buffer
 
@@ -9488,7 +9488,7 @@ visit Org files will not be removed.
 @end table
 
 
-@node Custom agenda views
+@node Custom agenda views, Exporting agenda views, Agenda commands, Agenda views
 @section Custom agenda views
 @cindex custom agenda views
 @cindex agenda views, custom
@@ -9504,7 +9504,7 @@ dispatcher (@pxref{Agenda dispatcher}), just like the default commands.
 * Setting options::             Changing the rules
 @end menu
 
-@node Storing searches
+@node Storing searches, Block agenda, Custom agenda views, Custom agenda views
 @subsection Storing searches
 
 The first application of custom searches is the definition of keyboard
@@ -9596,7 +9596,7 @@ Peter, or Kim) as additional tag to match.
 Note that the @code{*-tree} agenda views need to be called from an
 Org buffer as they operate on the current buffer only.
 
-@node Block agenda
+@node Block agenda, Setting options, Storing searches, Custom agenda views
 @subsection Block agenda
 @cindex block agenda
 @cindex agenda, with block views
@@ -9630,7 +9630,7 @@ your agenda for the current week, all TODO items that carry the tag
 @samp{home}, and also all lines tagged with @samp{garden}.  Finally the
 command @kbd{C-c a o} provides a similar view for office tasks.
 
-@node Setting options
+@node Setting options,  , Block agenda, Custom agenda views
 @subsection Setting options for custom commands
 @cindex options, for custom agenda views
 
@@ -9722,7 +9722,7 @@ command key @code{"r"}.  In that case, add this command key like this:
 
 See the docstring of the variable for more information.
 
-@node Exporting agenda views
+@node Exporting agenda views, Agenda column view, Custom agenda views, Agenda views
 @section Exporting agenda views
 @cindex agenda views, exporting
 
@@ -9862,7 +9862,7 @@ processing by other programs.  See @ref{Extracting agenda information}, for
 more information.
 
 
-@node Agenda column view
+@node Agenda column view,  , Exporting agenda views, Agenda views
 @section Using column view in the agenda
 @cindex column view, in agenda
 @cindex agenda, column view
@@ -9928,7 +9928,7 @@ spent ---via @code{CLOCKSUM}---and with the planned total effort for it.
 @end enumerate
 
 
-@node Markup
+@node Markup, Exporting, Agenda views, Top
 @chapter Markup for rich export
 
 When exporting Org mode documents, the exporter tries to reflect the
@@ -9948,7 +9948,7 @@ markup rules used in an Org mode buffer.
 * Embedded @LaTeX{}::           LaTeX can be freely used inside Org documents
 @end menu
 
-@node Paragraphs
+@node Paragraphs, Emphasis and monospace, Markup, Markup
 @section Paragraphs, line breaks, and quoting
 @cindex paragraphs, markup rules
 
@@ -9994,7 +9994,7 @@ but not any simpler
 #+END_CENTER
 @end example
 
-@node Emphasis and monospace
+@node Emphasis and monospace, Horizontal rules, Paragraphs, Markup
 @section Emphasis and monospace
 
 @cindex underlined text, markup rules
@@ -10019,13 +10019,13 @@ can tweak @code{org-emphasis-regexp-components}.  Beware that changing one of
 the above variables will no take effect until you reload Org, for which you
 may need to restart Emacs.
 
-@node Horizontal rules
+@node Horizontal rules, Images and tables, Emphasis and monospace, Markup
 @section Horizontal rules
 @cindex horizontal rules, markup rules
 A line consisting of only dashes, and at least 5 of them, will be exported as
 a horizontal line.
 
-@node Images and tables
+@node Images and tables, Literal examples, Horizontal rules, Markup
 @section Images and Tables
 
 @cindex tables, markup rules
@@ -10073,7 +10073,7 @@ the same caption mechanism can apply to many others (e.g., @LaTeX{}
 equations, source code blocks).  Depending on the export back-end, those may
 or may not be handled.
 
-@node Literal examples
+@node Literal examples, Special symbols, Images and tables, Markup
 @section Literal examples
 @cindex literal examples, markup rules
 @cindex code line references, markup rules
@@ -10213,7 +10213,7 @@ formatting like @samp{(ref:label)} at the end of the current line.  Then the
 label is stored as a link @samp{(label)}, for retrieval with @kbd{C-c C-l}.
 @end table
 
-@node Special symbols
+@node Special symbols, Subscripts and superscripts, Literal examples, Markup
 @section Special symbols
 @cindex Org entities
 @cindex math symbols
@@ -10274,7 +10274,7 @@ way@footnote{This behaviour can be disabled with @code{-} export setting
 combinations: @samp{\-} is treated as a shy hyphen, @samp{--} and @samp{---}
 are converted into dashes, and @samp{...} becomes a compact set of dots.
 
-@node Subscripts and superscripts
+@node Subscripts and superscripts, Embedded @LaTeX{}, Special symbols, Markup
 @section Subscripts and superscripts
 @cindex subscript
 @cindex superscript
@@ -10303,7 +10303,7 @@ In addition to showing entities as UTF-8 characters, this command will also
 format sub- and superscripts in a WYSIWYM way.
 @end table
 
-@node Embedded @LaTeX{}
+@node Embedded @LaTeX{},  , Subscripts and superscripts, Markup
 @section Embedded @LaTeX{}
 @cindex @TeX{} interpretation
 @cindex @LaTeX{} interpretation
@@ -10324,7 +10324,7 @@ readily processed to produce pretty output for a number of export back-ends.
 * CDLaTeX mode::                Speed up entering of formulas
 @end menu
 
-@node @LaTeX{} fragments
+@node @LaTeX{} fragments, Previewing @LaTeX{} fragments, Embedded @LaTeX{}, Embedded @LaTeX{}
 @subsection @LaTeX{} fragments
 @cindex @LaTeX{} fragments
 
@@ -10388,7 +10388,7 @@ lines:
 #+OPTIONS: tex:verbatim   @r{Verbatim export, for jsMath or so}
 @end example
 
-@node Previewing @LaTeX{} fragments
+@node Previewing @LaTeX{} fragments, CDLaTeX mode, @LaTeX{} fragments, Embedded @LaTeX{}
 @subsection Previewing @LaTeX{} fragments
 @cindex @LaTeX{} fragments, preview
 
@@ -10436,7 +10436,7 @@ To disable it, simply use
 #+STARTUP: nolatexpreview
 @end example
 
-@node CDLaTeX mode
+@node CDLaTeX mode,  , Previewing @LaTeX{} fragments, Embedded @LaTeX{}
 @subsection Using CD@LaTeX{} to enter math
 @cindex CD@LaTeX{}
 
@@ -10497,7 +10497,7 @@ modification will work only inside @LaTeX{} fragments; outside the quote
 is normal.
 @end itemize
 
-@node Exporting
+@node Exporting, Publishing, Markup, Top
 @chapter Exporting
 @cindex exporting
 
@@ -10564,7 +10564,7 @@ library in the Emacs init file like this:
 * Export in foreign buffers::   Author tables and lists in Org syntax
 @end menu
 
-@node The export dispatcher
+@node The export dispatcher, Export settings, Exporting, Exporting
 @section The export dispatcher
 @vindex org-export-dispatch-use-expert-ui
 @cindex Export, dispatcher
@@ -10631,7 +10631,7 @@ Toggle visible-only export.  Useful for exporting only visible parts of an
 Org document by adjusting outline visibility settings.
 @end table
 
-@node Export settings
+@node Export settings, Table of contents, The export dispatcher, Exporting
 @section Export settings
 @cindex Export, settings
 
@@ -10903,7 +10903,7 @@ can become buffer-local during export by using the BIND keyword.  Its syntax
 is @samp{#+BIND: variable value}.  This is particularly useful for in-buffer
 settings that cannot be changed using keywords.
 
-@node Table of contents
+@node Table of contents, Include files, Export settings, Exporting
 @section Table of contents
 @cindex table of contents
 @cindex list of tables
@@ -10980,7 +10980,7 @@ Normally Org uses the headline for its entry in the table of contents.  But
 with @code{ALT_TITLE} property, a different entry can be specified for the
 table of contents.
 
-@node Include files
+@node Include files, Macro replacement, Table of contents, Exporting
 @section Include files
 @cindex include files, during export
 Include other files during export.  For example, to include your @file{.emacs}
@@ -11054,7 +11054,7 @@ element.  Some examples:
 Visit the include file at point.
 @end table
 
-@node Macro replacement
+@node Macro replacement, Comment lines, Include files, Exporting
 @section Macro replacement
 @cindex macro replacement, during export
 @cindex #+MACRO
@@ -11140,7 +11140,7 @@ The surrounding brackets can be made invisible by setting
 
 Org expands macros at the very beginning of the export process.
 
-@node Comment lines
+@node Comment lines, ASCII/Latin-1/UTF-8 export, Macro replacement, Exporting
 @section Comment lines
 @cindex exporting, not
 
@@ -11167,7 +11167,7 @@ comment status of a headline.
 Toggle the @samp{COMMENT} keyword at the beginning of an entry.
 @end table
 
-@node ASCII/Latin-1/UTF-8 export
+@node ASCII/Latin-1/UTF-8 export, Beamer export, Comment lines, Exporting
 @section ASCII/Latin-1/UTF-8 export
 @cindex ASCII export
 @cindex Latin-1 export
@@ -11267,7 +11267,7 @@ It's just a jump to the left...
 #+END_JUSTIFYRIGHT
 @end example
 
-@node Beamer export
+@node Beamer export, HTML export, ASCII/Latin-1/UTF-8 export, Exporting
 @section Beamer export
 @cindex Beamer export
 
@@ -11285,7 +11285,7 @@ popular display formats.
 * A Beamer example::            A complete presentation.
 @end menu
 
-@node Beamer export commands
+@node Beamer export commands, Beamer specific export settings, Beamer export, Beamer export
 @subsection Beamer export commands
 
 @table @kbd
@@ -11301,7 +11301,7 @@ Export as @LaTeX{} file, convert it to PDF format, and then open the PDF
 file.
 @end table
 
-@node Beamer specific export settings
+@node Beamer specific export settings, Sectioning Frames and Blocks in Beamer, Beamer export commands, Beamer export
 @subsection Beamer specific export settings
 
 Beamer export back-end has several additional keywords for customizing Beamer
@@ -11360,7 +11360,7 @@ metadata.  Use @code{org-latex-title-command} to configure typesetting of
 subtitle as part of front matter.
 @end table
 
-@node Sectioning Frames and Blocks in Beamer
+@node Sectioning Frames and Blocks in Beamer, Beamer specific syntax, Beamer specific export settings, Beamer export
 @subsection Sectioning, Frames and Blocks in Beamer
 
 Org transforms heading levels into Beamer's sectioning elements, frames and
@@ -11429,7 +11429,7 @@ Beamer export automatically handles @LaTeX{} column separations for
 contiguous headlines.  To manually adjust them for any unique configurations
 needs, use the @code{BEAMER_ENV} property.
 
-@node Beamer specific syntax
+@node Beamer specific syntax, Editing support, Sectioning Frames and Blocks in Beamer, Beamer export
 @subsection Beamer specific syntax
 Since Org's Beamer export back-end is an extension of the @LaTeX{} back-end,
 it recognizes other @LaTeX{} specific syntax---for example, @samp{#+LATEX:}
@@ -11493,7 +11493,7 @@ Let $G$ be a finite group, and let $H$ be
 a subgroup of $G$.  Then the order of $H$ divides the order of $G$.
 @end example
 
-@node Editing support
+@node Editing support, A Beamer example, Beamer specific syntax, Beamer export
 @subsection Editing support
 
 
@@ -11510,7 +11510,7 @@ The @code{org-beamer-mode} provides this key for quicker selections in Beamer
 normal environments, and for selecting the @code{BEAMER_COL} property.
 @end table
 
-@node A Beamer example
+@node A Beamer example,  , Editing support, Beamer export
 @subsection A Beamer example
 
 Here is an example of an Org document ready for Beamer export.
@@ -11549,7 +11549,7 @@ Here is an example of an Org document ready for Beamer export.
     Please test this stuff!
 @end example
 
-@node HTML export
+@node HTML export, @LaTeX{} export, Beamer export, Exporting
 @section HTML export
 @cindex HTML export
 
@@ -11572,7 +11572,7 @@ with XHTML 1.0 strict standard.
 @end menu
 
 
-@node HTML Export commands
+@node HTML Export commands, HTML Specific export settings, HTML export, HTML export
 @subsection HTML export commands
 
 @table @kbd
@@ -11585,7 +11585,7 @@ h o} Exports to HTML and opens it in a web browser.
 Exports to a temporary buffer.  Does not create a file.
 @end table
 
-@node HTML Specific export settings
+@node HTML Specific export settings, HTML doctypes, HTML Export commands, HTML export
 @subsection HTML Specific export settings
 HTML export has a number of keywords, similar to the general options settings
 described in @ref{Export settings}.
@@ -11659,7 +11659,7 @@ The document's subtitle.  HTML exporter formats subtitle if document type is
 Some of these keywords are explained in more detail in the following sections
 of the manual.
 
-@node HTML doctypes
+@node HTML doctypes, HTML preamble and postamble, HTML Specific export settings, HTML export
 @subsection HTML doctypes
 
 Org can export to various (X)HTML flavors.
@@ -11747,7 +11747,7 @@ Special blocks cannot have headlines.  For the HTML exporter to wrap the
 headline and its contents in @samp{<section>} or @samp{<article>} tags, set
 the @code{HTML_CONTAINER} property for the headline.
 
-@node HTML preamble and postamble
+@node HTML preamble and postamble, Quoting HTML tags, HTML doctypes, HTML export
 @subsection HTML preamble and postamble
 @vindex org-html-preamble
 @vindex org-html-postamble
@@ -11775,7 +11775,7 @@ to insert the postamble in the format specified in the
 @code{org-html-postamble-format} variable.  The HTML exporter will not insert
 a postamble if @code{org-html-postamble} is set to @code{nil}.
 
-@node Quoting HTML tags
+@node Quoting HTML tags, Links in HTML export, HTML preamble and postamble, HTML export
 @subsection Quoting HTML tags
 
 The HTML export back-end transforms @samp{<} and @samp{>} to @samp{&lt;} and
@@ -11801,7 +11801,7 @@ All lines between these markers are exported literally
 @end example
 
 
-@node Links in HTML export
+@node Links in HTML export, Tables in HTML export, Quoting HTML tags, HTML export
 @subsection Links in HTML export
 
 @cindex links, in HTML export
@@ -11835,7 +11835,7 @@ to @code{<a>} or @code{<img>} tags.  This example shows changing the link's
 [[http://orgmode.org]]
 @end example
 
-@node Tables in HTML export
+@node Tables in HTML export, Images in HTML export, Links in HTML export, HTML export
 @subsection Tables in HTML export
 @cindex tables, in HTML
 @vindex org-html-table-default-attributes
@@ -11887,7 +11887,7 @@ Opening and ending tags for table rows.
 Non-@code{nil} formats column one in tables with header tags.
 @end table
 
-@node Images in HTML export
+@node Images in HTML export, Math formatting in HTML export, Tables in HTML export, HTML export
 @subsection Images in HTML export
 
 @cindex images, inline in HTML
@@ -11931,7 +11931,7 @@ standards.
 The HTML export back-end copies the @code{http} links from the Org file as
 is.
 
-@node Math formatting in HTML export
+@node Math formatting in HTML export, Text areas in HTML export, Images in HTML export, HTML export
 @subsection Math formatting in HTML export
 @cindex MathJax
 @cindex dvipng
@@ -11976,7 +11976,7 @@ or:
 #+OPTIONS: tex:imagemagick
 @end example
 
-@node Text areas in HTML export
+@node Text areas in HTML export, CSS support, Math formatting in HTML export, HTML export
 @subsection Text areas in HTML export
 
 @cindex text areas, in HTML
@@ -12005,7 +12005,7 @@ and height just enough to fit the content.  Override these defaults with
 @end example
 
 
-@node CSS support
+@node CSS support, JavaScript support, Text areas in HTML export, HTML export
 @subsection CSS support
 @cindex CSS, for HTML export
 @cindex HTML export, CSS
@@ -12096,7 +12096,7 @@ simpler ways of customizing as described above.
 @c FIXME: More about header and footer styles
 @c FIXME: Talk about links and targets.
 
-@node JavaScript support
+@node JavaScript support,  , CSS support, HTML export
 @subsection JavaScript supported display of web pages
 
 @cindex Rose, Sebastian
@@ -12158,7 +12158,7 @@ You can choose default values for these options by customizing the variable
 @code{org-html-infojs-options}.  If you want the script to always apply to
 your pages, configure the variable @code{org-html-use-infojs}.
 
-@node @LaTeX{} export
+@node @LaTeX{} export, Markdown export, HTML export, Exporting
 @section @LaTeX{} export
 @cindex @LaTeX{} export
 @cindex PDF export
@@ -12193,7 +12193,7 @@ blank lines to tell apart syntactical elements, such as paragraphs.
 * Horizontal rules in @LaTeX{} export::  Attributes specific to horizontal rules.
 @end menu
 
-@node @LaTeX{} export commands
+@node @LaTeX{} export commands, @LaTeX{} specific export settings, @LaTeX{} export, @LaTeX{} export
 @subsection @LaTeX{} export commands
 
 @table @kbd
@@ -12226,7 +12226,7 @@ compilers for different files.  However, ``smart'' @LaTeX{} compilation
 systems, such as @samp{latexmk}, can select the correct bibliography
 compiler.}.
 
-@node @LaTeX{} specific export settings
+@node @LaTeX{} specific export settings, @LaTeX{} header and sectioning, @LaTeX{} export commands, @LaTeX{} export
 @subsection @LaTeX{} specific export settings
 
 The @LaTeX{} export back-end has several additional keywords for customizing
@@ -12302,7 +12302,7 @@ document's front matter.
 
 The following sections have further details.
 
-@node @LaTeX{} header and sectioning
+@node @LaTeX{} header and sectioning, Quoting @LaTeX{} code, @LaTeX{} specific export settings, @LaTeX{} export
 @subsection @LaTeX{} header and sectioning structure
 @cindex @LaTeX{} class
 @cindex @LaTeX{} sectioning structure
@@ -12365,7 +12365,7 @@ A sample Org file with the above headers:
   some more text
 @end example
 
-@node Quoting @LaTeX{} code
+@node Quoting @LaTeX{} code, Tables in @LaTeX{} export, @LaTeX{} header and sectioning, @LaTeX{} export
 @subsection Quoting @LaTeX{} code
 
 The @LaTeX{} export back-end can insert any arbitrary @LaTeX{} code,
@@ -12393,7 +12393,7 @@ any arbitrary LaTeX code
 #+END_EXPORT
 @end example
 
-@node Tables in @LaTeX{} export
+@node Tables in @LaTeX{} export, Images in @LaTeX{} export, Quoting @LaTeX{} code, @LaTeX{} export
 @subsection Tables in @LaTeX{} export
 @cindex tables, in @LaTeX{} export
 @cindex #+ATTR_LATEX, in tables
@@ -12496,7 +12496,7 @@ Set the caption with the @LaTeX{} command
 @end example
 
 
-@node Images in @LaTeX{} export
+@node Images in @LaTeX{} export, Plain lists in @LaTeX{} export, Tables in @LaTeX{} export, @LaTeX{} export
 @subsection Images in @LaTeX{} export
 @cindex images, inline in @LaTeX{}
 @cindex inlining images in @LaTeX{}
@@ -12567,7 +12567,7 @@ centering globally, set @code{org-latex-images-centered} to @code{t}.
 Set the @code{:comment-include} attribute to non-@code{nil} value for the
 @LaTeX{} export back-end to comment out the @code{\includegraphics} macro.
 
-@node Plain lists in @LaTeX{} export
+@node Plain lists in @LaTeX{} export, Source blocks in @LaTeX{} export, Images in @LaTeX{} export, @LaTeX{} export
 @subsection Plain lists in @LaTeX{} export
 @cindex plain lists, in @LaTeX{} export
 @cindex #+ATTR_LATEX, in plain lists
@@ -12601,7 +12601,7 @@ four:
         - Five
 @end example
 
-@node Source blocks in @LaTeX{} export
+@node Source blocks in @LaTeX{} export, Example blocks in @LaTeX{} export, Plain lists in @LaTeX{} export, @LaTeX{} export
 @subsection Source blocks in @LaTeX{} export
 @cindex source blocks, in @LaTeX{} export
 @cindex #+ATTR_LATEX, in source blocks
@@ -12647,7 +12647,7 @@ To apply similar configuration options for all source blocks in a file, use
 the @code{org-latex-listings-options} and @code{org-latex-minted-options}
 variables.
 
-@node Example blocks in @LaTeX{} export
+@node Example blocks in @LaTeX{} export, Special blocks in @LaTeX{} export, Source blocks in @LaTeX{} export, @LaTeX{} export
 @subsection Example blocks in @LaTeX{} export
 @cindex example blocks, in @LaTeX{} export
 @cindex verbatim blocks, in @LaTeX{} export
@@ -12666,7 +12666,7 @@ This sentence is false.
 #+END_EXAMPLE
 @end example
 
-@node Special blocks in @LaTeX{} export
+@node Special blocks in @LaTeX{} export, Horizontal rules in @LaTeX{} export, Example blocks in @LaTeX{} export, @LaTeX{} export
 @subsection Special blocks in @LaTeX{} export
 @cindex special blocks, in @LaTeX{} export
 @cindex abstract, in @LaTeX{} export
@@ -12716,7 +12716,7 @@ example:
 #+END_proof
 @end example
 
-@node Horizontal rules in @LaTeX{} export
+@node Horizontal rules in @LaTeX{} export,  , Special blocks in @LaTeX{} export, @LaTeX{} export
 @subsection Horizontal rules in @LaTeX{} export
 @cindex horizontal rules, in @LaTeX{} export
 @cindex #+ATTR_LATEX, in horizontal rules
@@ -12729,7 +12729,7 @@ The @LaTeX{} export back-end converts horizontal rules by the specified
 -----
 @end example
 
-@node Markdown export
+@node Markdown export, OpenDocument Text export, @LaTeX{} export, Exporting
 @section Markdown export
 @cindex Markdown export
 
@@ -12763,7 +12763,7 @@ level before the absolute limit (@pxref{Export settings}).
 
 @c begin opendocument
 
-@node OpenDocument Text export
+@node OpenDocument Text export, Org export, Markdown export, Exporting
 @section OpenDocument Text export
 @cindex ODT
 @cindex OpenDocument
@@ -12791,14 +12791,14 @@ is compatible with LibreOffice 3.4.
 * Advanced topics in ODT export::  For power users.
 @end menu
 
-@node Pre-requisites for ODT export
+@node Pre-requisites for ODT export, ODT export commands, OpenDocument Text export, OpenDocument Text export
 @subsection Pre-requisites for ODT export
 @cindex zip
 The ODT export back-end relies on the @file{zip} program to create the final
 compressed ODT output.  Check if @file{zip} is locally available and
 executable.  Without @file{zip}, export cannot finish.
 
-@node ODT export commands
+@node ODT export commands, ODT specific export settings, Pre-requisites for ODT export, OpenDocument Text export
 @subsection ODT export commands
 @anchor{x-export-to-odt}
 @cindex region, active
@@ -12835,7 +12835,7 @@ file instead.  @xref{x-export-to-other-formats, , Automatically exporting to
 other formats}.
 @end table
 
-@node ODT specific export settings
+@node ODT specific export settings, Extending ODT export, ODT export commands, OpenDocument Text export
 @subsection ODT specific export settings
 The ODT export back-end has several additional keywords for customizing ODT
 output.  Setting these keywords works similar to the general options
@@ -12866,7 +12866,7 @@ The ODT export back-end uses the @code{org-odt-styles-file} by default.  See
 The document subtitle.
 @end table
 
-@node Extending ODT export
+@node Extending ODT export, Applying custom styles, ODT specific export settings, OpenDocument Text export
 @subsection Extending ODT export
 
 The ODT export back-end can produce documents in other formats besides ODT
@@ -12909,7 +12909,7 @@ Convert an existing document from one format to another.  With a prefix
 argument, opens the newly produced file.
 @end table
 
-@node Applying custom styles
+@node Applying custom styles, Links in ODT export, Extending ODT export, OpenDocument Text export
 @subsection Applying custom styles
 @cindex styles, custom
 @cindex template, custom
@@ -12965,7 +12965,7 @@ The ODT export back-end relies on many templates and style names.  Using
 third-party styles and templates can lead to mismatches.  Templates derived
 from built in ODT templates and styles seem to have fewer problems.
 
-@node Links in ODT export
+@node Links in ODT export, Tables in ODT export, Applying custom styles, OpenDocument Text export
 @subsection Links in ODT export
 @cindex links, in ODT export
 
@@ -12979,7 +12979,7 @@ A @samp{\ref@{label@}}-style reference to an image, table etc.@: is replaced
 with a cross-reference and sequence number of the labeled entity.
 @xref{Labels and captions in ODT export}.
 
-@node Tables in ODT export
+@node Tables in ODT export, Images in ODT export, Links in ODT export, OpenDocument Text export
 @subsection Tables in ODT export
 @cindex tables, in ODT export
 
@@ -13024,7 +13024,7 @@ For even more customization, create custom table styles and associate them
 with a table using the @code{#+ATTR_ODT} line.  @xref{Customizing tables in
 ODT export}.
 
-@node Images in ODT export
+@node Images in ODT export, Math formatting in ODT export, Tables in ODT export, OpenDocument Text export
 @subsection Images in ODT export
 @cindex images, embedding in ODT
 @cindex embedding images in ODT
@@ -13121,7 +13121,7 @@ To create an image that is anchored to a page:
 [[./img.png]]
 @end example
 
-@node Math formatting in ODT export
+@node Math formatting in ODT export, Labels and captions in ODT export, Images in ODT export, OpenDocument Text export
 @subsection Math formatting in ODT export
 
 The ODT export back-end has special support built-in for handling math.
@@ -13131,7 +13131,7 @@ The ODT export back-end has special support built-in for handling math.
 * Working with MathML or OpenDocument formula files::  Embedding in native format.
 @end menu
 
-@node Working with @LaTeX{} math snippets
+@node Working with @LaTeX{} math snippets, Working with MathML or OpenDocument formula files, Math formatting in ODT export, Math formatting in ODT export
 @subsubheading Working with @LaTeX{} math snippets
 
 @LaTeX{} math snippets (@pxref{@LaTeX{} fragments}) can be embedded in an ODT
@@ -13214,7 +13214,7 @@ requires @file{dvipng} program, @file{dvisvgm} or @file{imagemagick}
 programs.
 @end enumerate
 
-@node Working with MathML or OpenDocument formula files
+@node Working with MathML or OpenDocument formula files,  , Working with @LaTeX{} math snippets, Math formatting in ODT export
 @subsubheading Working with MathML or OpenDocument formula files
 
 When embedding @LaTeX{} math snippets in ODT documents is not reliable, there
@@ -13232,7 +13232,7 @@ or
 [[./equation.odf]]
 @end example
 
-@node Labels and captions in ODT export
+@node Labels and captions in ODT export, Literal examples in ODT export, Math formatting in ODT export, OpenDocument Text export
 @subsection Labels and captions in ODT export
 
 ODT format handles labeling and captioning of objects based on their
@@ -13270,7 +13270,7 @@ With the above modification, the previous example changes to:
 Illustration 2: Bell curve
 @end example
 
-@node Literal examples in ODT export
+@node Literal examples in ODT export, Advanced topics in ODT export, Labels and captions in ODT export, OpenDocument Text export
 @subsection Literal examples in ODT export
 
 The ODT export back-end supports literal examples (@pxref{Literal examples})
@@ -13288,7 +13288,7 @@ For custom fontification styles, customize the
 To turn off fontification of literal examples, customize the
 @code{org-odt-fontify-srcblocks} option.
 
-@node Advanced topics in ODT export
+@node Advanced topics in ODT export,  , Literal examples in ODT export, OpenDocument Text export
 @subsection Advanced topics in ODT export
 
 The ODT export back-end has extensive features useful for power users and
@@ -13302,7 +13302,7 @@ frequent uses of ODT formats.
 * Validating OpenDocument XML::  Debugging corrupted OpenDocument files.
 @end menu
 
-@node Configuring a document converter
+@node Configuring a document converter, Working with OpenDocument style files, Advanced topics in ODT export, Advanced topics in ODT export
 @subsubheading Configuring a document converter
 @cindex convert
 @cindex doc, docx, rtf
@@ -13335,7 +13335,7 @@ Select the newly added converter as the preferred one by customizing the
 option @code{org-odt-convert-process}.
 @end enumerate
 
-@node Working with OpenDocument style files
+@node Working with OpenDocument style files, Creating one-off styles, Configuring a document converter, Advanced topics in ODT export
 @subsubheading Working with OpenDocument style files
 @cindex styles, custom
 @cindex template, custom
@@ -13438,7 +13438,7 @@ Use this variable to specify the blank @file{content.xml} that will be used
 in the final output.
 @end itemize
 
-@node Creating one-off styles
+@node Creating one-off styles, Customizing tables in ODT export, Working with OpenDocument style files, Advanced topics in ODT export
 @subsubheading Creating one-off styles
 
 The ODT export back-end can read embedded raw OpenDocument XML from the Org
@@ -13504,7 +13504,7 @@ This paragraph is specially formatted and uses bold text.
 
 @end enumerate
 
-@node Customizing tables in ODT export
+@node Customizing tables in ODT export, Validating OpenDocument XML, Creating one-off styles, Advanced topics in ODT export
 @subsubheading Customizing tables in ODT export
 @cindex tables, in ODT export
 
@@ -13666,7 +13666,7 @@ the @code{ATTR_ODT} line as shown below.
 @end example
 @end enumerate
 
-@node Validating OpenDocument XML
+@node Validating OpenDocument XML,  , Customizing tables in ODT export, Advanced topics in ODT export
 @subsubheading Validating OpenDocument XML
 
 Sometimes ODT format files may not open due to @file{.odt} file corruption.
@@ -13685,7 +13685,7 @@ back-end takes care of updating the @code{rng-schema-locating-files}.
 
 @c end opendocument
 
-@node Org export
+@node Org export, Texinfo export, OpenDocument Text export, Exporting
 @section Org export
 @cindex Org export
 
@@ -13706,7 +13706,7 @@ Export to a temporary buffer.  Does not create a file.
 Export to an Org file, then open it.
 @end table
 
-@node Texinfo export
+@node Texinfo export, iCalendar export, Org export, Exporting
 @section Texinfo export
 @cindex Texinfo export
 
@@ -13718,7 +13718,7 @@ can compile to Info format.
 * Texinfo specific export settings::  Setting the environment.
 * Texinfo file header::         Generating the header.
 * Texinfo title and copyright page::  Creating preamble pages.
-* Info directory file::     Installing a manual in Info file hierarchy.
+* Info directory file::         Installing a manual in Info file hierarchy.
 * Headings and sectioning structure::  Building document structure.
 * Indices::                     Creating indices.
 * Quoting Texinfo code::        Incorporating literal Texinfo code.
@@ -13729,7 +13729,7 @@ can compile to Info format.
 * A Texinfo example::           Processing Org to Texinfo.
 @end menu
 
-@node Texinfo export commands
+@node Texinfo export commands, Texinfo specific export settings, Texinfo export, Texinfo export
 @subsection Texinfo export commands
 
 @vindex org-texinfo-info-process
@@ -13743,7 +13743,7 @@ generate other formats, such as DocBook, customize the
 @code{org-texinfo-info-process} variable.
 @end table
 
-@node Texinfo specific export settings
+@node Texinfo specific export settings, Texinfo file header, Texinfo export commands, Texinfo export
 @subsection Texinfo specific export settings
 The Texinfo export back-end has several additional keywords for customizing
 Texinfo output.  Setting these keywords works similar to the general options
@@ -13794,7 +13794,7 @@ The directory description of the document.
 The printed title of the document.
 @end table
 
-@node Texinfo file header
+@node Texinfo file header, Texinfo title and copyright page, Texinfo specific export settings, Texinfo export
 @subsection Texinfo file header
 
 @cindex #+TEXINFO_FILENAME
@@ -13817,7 +13817,7 @@ Instead of repeatedly installing the same set of commands, define a class in
 @code{org-texinfo-classes} once, and then activate it in the document by
 setting the @code{#+TEXINFO_CLASS} keyword to that class.
 
-@node Texinfo title and copyright page
+@node Texinfo title and copyright page, Info directory file, Texinfo file header, Texinfo export
 @subsection Texinfo title and copyright page
 
 @cindex #+TEXINFO_PRINTED_TITLE
@@ -13856,7 +13856,7 @@ Copyright information is printed on the back of the title page.
   Copyright \copy 2016 Free Software Foundation, Inc.
 @end example
 
-@node Info directory file
+@node Info directory file, Headings and sectioning structure, Texinfo title and copyright page, Texinfo export
 @subsection Info directory file
 @cindex @samp{dir} file, in Texinfo export
 @cindex Texinfo export, @samp{dir} file
@@ -13882,7 +13882,7 @@ Here is an example that writes to the Info directory file:
 #+TEXINFO_DIR_DESC: Outline-based notes management and organizer
 @end example
 
-@node Headings and sectioning structure
+@node Headings and sectioning structure, Indices, Info directory file, Texinfo export
 @subsection Headings and sectioning structure
 
 @vindex org-texinfo-classes
@@ -13930,7 +13930,7 @@ node in which a reader enters an Info manual.  As such, it is expected not to
 appear in printed output generated from the @file{.texi} file.  @inforef{The
 Top Node,,texinfo}, for more information.
 
-@node Indices
+@node Indices, Quoting Texinfo code, Headings and sectioning structure, Texinfo export
 @subsection Indices
 
 @cindex #+CINDEX
@@ -13976,7 +13976,7 @@ inserts the index after its contents.
   :END:
 @end example
 
-@node Quoting Texinfo code
+@node Quoting Texinfo code, Plain lists in Texinfo export, Indices, Texinfo export
 @subsection Quoting Texinfo code
 
 Use any of the following three methods to insert or escape raw Texinfo code:
@@ -13995,7 +13995,7 @@ This paragraph is preceded by...
 #+END_EXPORT
 @end example
 
-@node Plain lists in Texinfo export
+@node Plain lists in Texinfo export, Tables in Texinfo export, Quoting Texinfo code, Texinfo export
 @subsection Plain lists in Texinfo export
 @cindex #+ATTR_TEXINFO, in plain lists
 @cindex Two-column tables, in Texinfo export
@@ -14039,7 +14039,7 @@ This is the common text for variables foo and bar.
 @@end table
 @end example
 
-@node Tables in Texinfo export
+@node Tables in Texinfo export, Images in Texinfo export, Plain lists in Texinfo export, Texinfo export
 @subsection Tables in Texinfo export
 @cindex #+ATTR_TEXINFO, in tables
 
@@ -14052,7 +14052,7 @@ length, use the @code{:columns} attribute.  See example below.
 | a cell | another cell |
 @end example
 
-@node Images in Texinfo export
+@node Images in Texinfo export, Special blocks in Texinfo export, Tables in Texinfo export, Texinfo export
 @subsection Images in Texinfo export
 @cindex #+ATTR_TEXINFO, in images
 
@@ -14067,7 +14067,7 @@ the text using Texinfo code, as shown in the example:
 [[ridt.pdf]]
 @end example
 
-@node Special blocks in Texinfo export
+@node Special blocks in Texinfo export, A Texinfo example, Images in Texinfo export, Texinfo export
 @subsection Special blocks
 @cindex #+ATTR_TEXINFO, in special blocks
 
@@ -14091,7 +14091,7 @@ A somewhat obsessive function.
 @@end defun
 @end example
 
-@node A Texinfo example
+@node A Texinfo example,  , Special blocks in Texinfo export, Texinfo export
 @subsection A Texinfo example
 
 Here is a more detailed example Org file.  See @ref{GNU Sample
@@ -14163,7 +14163,7 @@ This manual is for GNU Sample (version @{@{@{version@}@}@},
   :END:
 @end example
 
-@node iCalendar export
+@node iCalendar export, Other built-in back-ends, Texinfo export, Exporting
 @section iCalendar export
 @cindex iCalendar export
 
@@ -14246,7 +14246,7 @@ Exporting to iCalendar format depends in large part on the capabilities of
 the destination application.  Some are more lenient than others.  Consult the
 Org mode FAQ for advice on specific applications.
 
-@node Other built-in back-ends
+@node Other built-in back-ends, Advanced configuration, iCalendar export, Exporting
 @section Other built-in back-ends
 @cindex export back-ends, built-in
 @vindex org-export-backends
@@ -14265,7 +14265,7 @@ dispatcher}).
 Follow the comment section of such files, for example, @file{ox-man.el}, for
 usage and configuration details.
 
-@node Advanced configuration
+@node Advanced configuration, Export in foreign buffers, Other built-in back-ends, Exporting
 @section Advanced configuration
 
 @subheading Hooks
@@ -14463,7 +14463,7 @@ To use the newly defined back-end, call the following from an Org buffer:
 Further steps to consider would be an interactive function, self-installing
 an item in the export dispatcher menu, and other user-friendly improvements.
 
-@node Export in foreign buffers
+@node Export in foreign buffers,  , Advanced configuration, Exporting
 @section Export in foreign buffers
 
 The export back-ends in Org often include commands to convert selected
@@ -14488,7 +14488,7 @@ commands to create a list, select it, and covert it to HTML with @code{M-x
 org-html-convert-region-to-html RET}.
 
 
-@node Publishing
+@node Publishing, Working with source code, Exporting, Top
 @chapter Publishing
 @cindex publishing
 
@@ -14510,7 +14510,7 @@ Publishing has been contributed to Org by David O'Toole.
 * Triggering publication::      Publication commands
 @end menu
 
-@node Configuration
+@node Configuration, Uploading files, Publishing, Publishing
 @section Configuration
 
 Publishing needs significant configuration to specify files, destination
@@ -14527,7 +14527,7 @@ and many other properties of a project.
 * Generating an index::         An index that reaches across pages
 @end menu
 
-@node Project alist
+@node Project alist, Sources and destinations, Configuration, Configuration
 @subsection The variable @code{org-publish-project-alist}
 @cindex org-publish-project-alist
 @cindex projects, for publishing
@@ -14554,7 +14554,7 @@ together files requiring different publishing options.  When you publish such
 a ``meta-project'', all the components will also be published, in the
 sequence given.
 
-@node Sources and destinations
+@node Sources and destinations, Selecting files, Project alist, Configuration
 @subsection Sources and destinations for files
 @cindex directories, for publishing
 
@@ -14583,7 +14583,7 @@ list.
 @end multitable
 @noindent
 
-@node Selecting files
+@node Selecting files, Publishing action, Sources and destinations, Configuration
 @subsection Selecting files
 @cindex files, selecting for publishing
 
@@ -14609,7 +14609,7 @@ and @code{:exclude}.
 @tab non-@code{nil} means, check base-directory recursively for files to publish.
 @end multitable
 
-@node Publishing action
+@node Publishing action, Publishing options, Selecting files, Configuration
 @subsection Publishing action
 @cindex action, for publishing
 
@@ -14648,7 +14648,7 @@ and the path to the publishing directory of the output file.  It should take
 the specified file, make the necessary transformation (if any) and place the
 result into the destination folder.
 
-@node Publishing options
+@node Publishing options, Publishing links, Publishing action, Configuration
 @subsection Options for the exporters
 @cindex options, for publishing
 
@@ -14877,7 +14877,7 @@ however, override everything.
 @item @code{:texinfo-text-markup-alist}          @tab @code{org-texinfo-text-markup-alist}
 @end multitable
 
-@node Publishing links
+@node Publishing links, Sitemap, Publishing options, Configuration
 @subsection Links between published files
 @cindex links, publishing
 
@@ -14906,7 +14906,7 @@ all point to a dedicated anchor in @file{foo.html}.
 [[file:foo.org::target]]
 @end example
 
-@node Sitemap
+@node Sitemap, Generating an index, Publishing links, Configuration
 @subsection Generating a sitemap
 @cindex sitemap, of published pages
 
@@ -14968,7 +14968,7 @@ a sitemap entry's date is to be formatted.  This property bypasses
 
 @end multitable
 
-@node Generating an index
+@node Generating an index,  , Sitemap, Configuration
 @subsection Generating an index
 @cindex index, in a publishing project
 
@@ -14995,7 +14995,7 @@ contains an exclamation mark will create a sub item.
 #+INDEX: Application!CV
 @end example
 
-@node Uploading files
+@node Uploading files, Sample configuration, Configuration, Publishing
 @section Uploading files
 @cindex rsync
 @cindex unison
@@ -15028,7 +15028,7 @@ benefit of re-including any changed external files such as source example
 files you might include with @code{#+INCLUDE:}.  The timestamp mechanism in
 Org is not smart enough to detect if included files have been modified.
 
-@node Sample configuration
+@node Sample configuration, Triggering publication, Uploading files, Publishing
 @section Sample configuration
 
 Below we provide two example configurations.  The first one is a simple
@@ -15040,7 +15040,7 @@ more complex, with a multi-component project.
 * Complex example::             A multi-component publishing example
 @end menu
 
-@node Simple example
+@node Simple example, Complex example, Sample configuration, Sample configuration
 @subsection Example: simple publishing configuration
 
 This example publishes a set of Org files to the @file{public_html}
@@ -15059,7 +15059,7 @@ directory on the local machine.
                     type=\"text/css\"/>")))
 @end lisp
 
-@node Complex example
+@node Complex example,  , Simple example, Sample configuration
 @subsection Example: complex publishing configuration
 
 This more complicated example publishes an entire website, including
@@ -15109,7 +15109,7 @@ right place on the web server, and publishing images to it.
          ("website" :components ("orgfiles" "images" "other"))))
 @end lisp
 
-@node Triggering publication
+@node Triggering publication,  , Sample configuration, Publishing
 @section Triggering publication
 
 Once properly configured, Org can publish with the following commands:
@@ -15134,7 +15134,7 @@ This may be necessary in particular if files include other files via
 @code{#+SETUPFILE:} or @code{#+INCLUDE:}.
 
 
-@node Working with source code
+@node Working with source code, Miscellaneous, Publishing, Top
 @chapter Working with source code
 @cindex Schulte, Eric
 @cindex Davison, Dan
@@ -15224,7 +15224,7 @@ Details of Org's facilities for working with source code are shown next.
 @end menu
 
 
-@node Structure of code blocks
+@node Structure of code blocks, Editing source code, Working with source code, Working with source code
 @section Structure of code blocks
 @cindex code block, structure
 @cindex source code, block structure
@@ -15243,12 +15243,12 @@ A @samp{src} block conforms to this structure:
 #+END_SRC
 @end example
 
-Org mode's templates system (@pxref{Easy templates}) speeds up creating
-@samp{src} 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 a command for wrapping existing text in a block (@pxref{Inserting
+structure 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:
@@ -15296,7 +15296,7 @@ specific sub-trees of the Org document.
 Source code in the dialect of the specified language identifier.
 @end table
 
-@node Editing source code
+@node Editing source code, Exporting code blocks, Structure of code blocks, Working with source code
 @section Editing source code
 @cindex code block, editing
 @cindex source code, editing
@@ -15360,7 +15360,7 @@ Emacs-Lisp languages.
                             ("python" (:background "#E5FFB8"))))
 @end lisp
 
-@node Exporting code blocks
+@node Exporting code blocks, Extracting source code, Editing source code, Working with source code
 @section Exporting code blocks
 @cindex code block, exporting
 @cindex source code, exporting
@@ -15413,7 +15413,7 @@ Org never evaluates code blocks in commented sub-trees when exporting
 (@pxref{Comment lines}).  On the other hand, Org does evaluate code blocks in
 sub-trees excluded from export (@pxref{Export settings}).
 
-@node Extracting source code
+@node Extracting source code, Evaluating code blocks, Exporting code blocks, Working with source code
 @section Extracting source code
 @cindex tangling
 @cindex source code, extracting
@@ -15478,7 +15478,7 @@ block header arguments: One, set @code{padline} (@pxref{padline}) to true
 (the default setting).  Two, set @code{comments} (@pxref{comments}) to
 @code{link}, which makes Org insert links to the Org file.
 
-@node Evaluating code blocks
+@node Evaluating code blocks, Library of Babel, Extracting source code, Working with source code
 @section Evaluating code blocks
 @cindex code block, evaluating
 @cindex source code, evaluating
@@ -15555,7 +15555,7 @@ For more examples of header arguments for @code{#+CALL:} lines,
 @pxref{Arguments in function calls}.
 @end table
 
-@node Library of Babel
+@node Library of Babel, Languages, Evaluating code blocks, Working with source code
 @section Library of Babel
 @cindex babel, library of
 @cindex source code, library
@@ -15572,7 +15572,7 @@ For any user to add code to the library, first save the code in regular
 @samp{src} code blocks of an Org file, and then load the Org file with
 @code{org-babel-lob-ingest}, which is bound to @kbd{C-c C-v i}.
 
-@node Languages
+@node Languages, Header arguments, Library of Babel, Working with source code
 @section Languages
 @cindex babel, languages
 @cindex source code, languages
@@ -15632,7 +15632,7 @@ following enables execution of @code{clojure} code blocks:
 (require 'ob-clojure)
 @end lisp
 
-@node Header arguments
+@node Header arguments, Results of evaluation, Languages, Working with source code
 @section Header arguments
 @cindex code block, header arguments
 @cindex source code, block header arguments
@@ -15644,7 +15644,7 @@ Details of configuring header arguments are shown here.
 * Specific header arguments::   List of header arguments
 @end menu
 
-@node Using header arguments
+@node Using header arguments, Specific header arguments, Header arguments, Header arguments
 @subsection Using header arguments
 
 Since header arguments can be set in several ways, Org prioritizes them in
@@ -15661,7 +15661,7 @@ global defaults.
 @end menu
 
 
-@node System-wide header arguments
+@node System-wide header arguments, Language-specific header arguments, Using header arguments, Using header arguments
 @subsubheading System-wide header arguments
 @vindex org-babel-default-header-args
 System-wide values of header arguments can be specified by adapting the
@@ -15689,14 +15689,14 @@ Org expand @code{:noweb} references by default.
             (assq-delete-all :noweb org-babel-default-header-args)))
 @end lisp
 
-@node Language-specific header arguments
+@node Language-specific header arguments, Header arguments in Org mode properties, System-wide header arguments, Using header arguments
 @subsubheading Language-specific header arguments
 Each language can have separate default header arguments by customizing the
 variable @code{org-babel-default-header-args:<lang>}, where @code{<lang>} is
 the name of the language.  For details, see the language-specific online
 documentation at @uref{http://orgmode.org/worg/org-contrib/babel}.
 
-@node Header arguments in Org mode properties
+@node Header arguments in Org mode properties, Language-specific mode properties, Language-specific header arguments, Using header arguments
 @subsubheading Header arguments in Org mode properties
 
 For header arguments applicable to the buffer, use @code{#+PROPERTY:} lines
@@ -15734,7 +15734,7 @@ Properties defined through @code{org-set-property} function, bound to
 @kbd{C-c C-x p}, apply to all active languages.  They override properties set
 in @code{org-babel-default-header-args}.
 
-@node Language-specific mode properties
+@node Language-specific mode properties, Code block specific header arguments, Header arguments in Org mode properties, Using header arguments
 @subsubheading Language-specific mode properties
 
 Language-specific header arguments are also read from properties
@@ -15757,7 +15757,7 @@ would force separate sessions for clojure blocks in Heading and Subheading,
 but use the same session for all @samp{R} blocks.  Blocks in Subheading
 inherit settings from Heading.
 
-@node Code block specific header arguments
+@node Code block specific header arguments, Arguments in function calls, Language-specific mode properties, Using header arguments
 @subsubheading Code block specific header arguments
 
 Header arguments are most commonly set at the @samp{src} code block level, on
@@ -15815,7 +15815,7 @@ Multi-line header arguments on a named @samp{src} code block:
   : data:2
 @end example
 
-@node Arguments in function calls
+@node Arguments in function calls,  , Code block specific header arguments, Using header arguments
 @subsubheading Arguments in function calls
 
 Header arguments in function calls are the most specific and override all
@@ -15837,7 +15837,7 @@ evaluation of @code{factorial} code block.
 #+CALL: factorial[:session special](n=5)
 @end example
 
-@node Specific header arguments
+@node Specific header arguments,  , Using header arguments, Header arguments
 @subsection Specific header arguments
 Org comes with many header arguments common to all languages.  New header
 arguments are added for specific languages as they become available for use
@@ -15879,7 +15879,7 @@ are:
 
 For language-specific header arguments, see @ref{Languages}.
 
-@node var
+@node var, results, Specific header arguments, Specific header arguments
 @subsubsection @code{:var}
 @cindex @code{:var}, src header argument
 Use @code{:var} for passing arguments to @samp{src} code blocks.  The
@@ -16133,7 +16133,7 @@ as Emacs Lisp code, as illustrated in the following example.
 : (a b c)
 @end example
 
-@node results
+@node results, file, var, Specific header arguments
 @subsubsection @code{:results}
 @cindex @code{:results}, src header argument
 
@@ -16241,7 +16241,7 @@ Prepend results to the Org buffer.  Latest results are at the top.  Does not
 remove previous results.  Usage example: @code{:results output prepend}.
 @end itemize
 
-@node file
+@node file, file-desc, results, Specific header arguments
 @subsubsection @code{:file}
 @cindex @code{:file}, src header argument
 
@@ -16254,7 +16254,7 @@ format}).  Some languages, such as @samp{R}, @samp{dot}, @samp{ditaa}, and
 code.  Such code wrapping helps recreate the output, especially graphics
 output, by executing just the @code{:file} contents.
 
-@node file-desc
+@node file-desc, file-ext, file, Specific header arguments
 @subsubsection @code{:file-desc}
 
 A description of the results file.  Org uses this description for the link
@@ -16262,7 +16262,7 @@ A description of the results file.  Org uses this description for the link
 has no value, Org will use file name for both the ``link'' and the
 ``description'' portion of the Org mode link.
 
-@node file-ext
+@node file-ext, output-dir, file-desc, Specific header arguments
 @subsubsection @code{:file-ext}
 @cindex @code{:file-ext}, src header argument
 
@@ -16271,7 +16271,7 @@ name, and extension by combining @code{:file-ext}, @code{#+NAME:} of the
 source block, and the @ref{output-dir} header argument.  To override this
 auto generated file name, use the @code{:file} header argument.
 
-@node output-dir
+@node output-dir, dir, file-ext, Specific header arguments
 @subsubsection @code{:output-dir}
 @cindex @code{:output-dir}, src header argument
 
@@ -16280,7 +16280,7 @@ absolute path (beginning with @code{/}) or a relative directory (without
 @code{/}).  The value can be combined with @code{#+NAME:} of the source block
 and @ref{file} or @ref{file-ext} header arguments.
 
-@node dir
+@node dir, exports, output-dir, Specific header arguments
 @subsubsection @code{:dir} and remote execution
 @cindex @code{:dir}, src header argument
 
@@ -16339,7 +16339,7 @@ Org does not expand @code{default directory} to avoid some underlying
 portability issues.
 @end itemize
 
-@node exports
+@node exports, tangle, dir, Specific header arguments
 @subsubsection @code{:exports}
 @cindex @code{:exports}, src header argument
 
@@ -16363,7 +16363,7 @@ file.  Whether the code is evaluated at all depends on other
 options.  Example: @code{:exports none}.
 @end itemize
 
-@node tangle
+@node tangle, mkdirp, exports, Specific header arguments
 @subsubsection @code{:tangle}
 @cindex @code{:tangle}, src header argument
 
@@ -16386,7 +16386,7 @@ the file name as being relative to the directory of the Org file's location.
 Example: @code{:tangle path}.
 @end itemize
 
-@node mkdirp
+@node mkdirp, comments, tangle, Specific header arguments
 @subsubsection @code{:mkdirp}
 @cindex @code{:mkdirp}, src header argument
 
@@ -16394,7 +16394,7 @@ The @code{:mkdirp} header argument creates parent directories for tangled
 files if the directory does not exist.  @code{yes} enables directory creation
 and @code{no} inhibits directory creation.
 
-@node comments
+@node comments, padline, mkdirp, Specific header arguments
 @subsubsection @code{:comments}
 @cindex @code{:comments}, src header argument
 Controls inserting comments into tangled files.  These are above and beyond
@@ -16418,7 +16418,7 @@ Includes ``link'' comment option, expands noweb references, and wraps them in
 link comments inside the body of the @samp{src} code block.
 @end itemize
 
-@node padline
+@node padline, no-expand, comments, Specific header arguments
 @subsubsection @code{:padline}
 @cindex @code{:padline}, src header argument
 Control insertion of newlines to pad @samp{src} code blocks in the tangled
@@ -16431,7 +16431,7 @@ tangled file.
 Do not insert newlines to pad the tangled @samp{src} code blocks.
 @end itemize
 
-@node no-expand
+@node no-expand, session, padline, Specific header arguments
 @subsubsection @code{:no-expand}
 @cindex @code{:no-expand}, src header argument
 
@@ -16444,7 +16444,7 @@ these expansions may cause premature assignment, hence this option.  This
 option makes a difference only for tangling.  It has no effect when exporting
 since @samp{src} code blocks for execution have to be expanded anyway.
 
-@node session
+@node session, noweb, no-expand, Specific header arguments
 @subsubsection @code{:session}
 @cindex @code{:session}, src header argument
 
@@ -16467,7 +16467,7 @@ shared.  Some interpreted languages support concurrent sessions when
 subsequent source code language blocks change session names.
 @end itemize
 
-@node noweb
+@node noweb, noweb-ref, session, Specific header arguments
 @subsubsection @code{:noweb}
 @cindex @code{:noweb}, src header argument
 
@@ -16575,7 +16575,7 @@ and evaluates to:
 Do things when True
 @end example
 
-@node noweb-ref
+@node noweb-ref, noweb-sep, noweb, Specific header arguments
 @subsubsection @code{:noweb-ref}
 @cindex @code{:noweb-ref}, src header argument
 
@@ -16613,7 +16613,7 @@ when tangled.
  #+END_SRC
 @end example
 
-@node noweb-sep
+@node noweb-sep, cache, noweb-ref, Specific header arguments
 @subsubsection @code{:noweb-sep}
 @cindex @code{:noweb-sep}, src header argument
 
@@ -16621,7 +16621,7 @@ By default a newline separates each noweb reference concatenation.  To change
 this newline separator, edit the @code{:noweb-sep} (@pxref{noweb-sep}) header
 argument.
 
-@node cache
+@node cache, sep, noweb-sep, Specific header arguments
 @subsubsection @code{:cache}
 @cindex @code{:cache}, src header argument
 
@@ -16686,7 +16686,7 @@ the result from @code{random} has changed since the last run.
  0.254227238707244
 @end example
 
-@node sep
+@node sep, hlines, cache, Specific header arguments
 @subsubsection @code{:sep}
 @cindex @code{:sep}, src header argument
 
@@ -16695,7 +16695,7 @@ to files (@pxref{file}) external to Org mode.  Org defaults to tab delimited
 output.  The function, @code{org-open-at-point}, which is bound to @kbd{C-c
 C-o}, also uses @code{:sep} for opening tabular results.
 
-@node hlines
+@node hlines, colnames, sep, Specific header arguments
 @subsubsection @code{:hlines}
 @cindex @code{:hlines}, src header argument
 
@@ -16756,7 +16756,7 @@ For @code{:hlines yes}, the example shows hlines unchanged.
 @end example
 @end itemize
 
-@node colnames
+@node colnames, rownames, hlines, Specific header arguments
 @subsubsection @code{:colnames}
 @cindex @code{:colnames}, src header argument
 
@@ -16803,7 +16803,7 @@ value.  That is, Org removes the column names, processes the table, puts back
 the column names, and then writes the table to the results block.
 @end itemize
 
-@node rownames
+@node rownames, shebang, colnames, Specific header arguments
 @subsubsection @code{:rownames}
 @cindex @code{:rownames}, src header argument
 
@@ -16842,7 +16842,7 @@ for indexing.
 
 @end itemize
 
-@node shebang
+@node shebang, tangle-mode, rownames, Specific header arguments
 @subsubsection @code{:shebang}
 @cindex @code{:shebang}, src header argument
 
@@ -16852,7 +16852,7 @@ setting the @code{:shebang} header argument to a string value (for example,
 the tangled file that the @samp{src} code block is extracted to.  Org then
 turns on the tangled file's executable permission.
 
-@node tangle-mode
+@node tangle-mode, eval, shebang, Specific header arguments
 @subsubsection @code{:tangle-mode}
 @cindex @code{:tangle-mode}, src header argument
 
@@ -16870,7 +16870,7 @@ When multiple @samp{src} code blocks tangle to a single file with different
 and conflicting @code{tangle-mode} header arguments, Org's behavior is
 undefined.
 
-@node eval
+@node eval, wrap, tangle-mode, Specific header arguments
 @subsubsection @code{:eval}
 @cindex @code{:eval}, src header argument
 The @code{:eval} header argument can limit evaluation of specific code
@@ -16894,14 +16894,14 @@ If @code{:eval} header argument is not set for a source block, then Org
 determines whether to evaluate from the @code{org-confirm-babel-evaluate}
 variable (@pxref{Code evaluation security}).
 
-@node wrap
+@node wrap, post, eval, Specific header arguments
 @subsubsection @code{:wrap}
 @cindex @code{:wrap}, src header argument
 The @code{:wrap} header argument marks the results block by appending strings
 to @code{#+BEGIN_} and @code{#+END_}.  If no string is specified, Org wraps
 the results in a @code{#+BEGIN/END_RESULTS} block.
 
-@node post
+@node post, prologue, wrap, Specific header arguments
 @subsubsection @code{:post}
 @cindex @code{:post}, src header argument
 The @code{:post} header argument is for post-processing results from
@@ -16963,7 +16963,7 @@ data.frame(foo=rnorm(1))
 | 1.371 |
 @end example
 
-@node prologue
+@node prologue, epilogue, post, Specific header arguments
 @subsubsection @code{:prologue}
 @cindex @code{:prologue}, src header argument
 The @code{prologue} header argument is for appending to the top of the code
@@ -16976,13 +16976,13 @@ execution of a @samp{src} code block.  A @code{reset} for @samp{gnuplot}:
              '((:prologue . "reset")))
 @end lisp
 
-@node epilogue
+@node epilogue,  , prologue, Specific header arguments
 @subsubsection @code{:epilogue}
 @cindex @code{:epilogue}, src header argument
 The value of the @code{epilogue} header argument is for appending to the end
 of the code block for execution.  See also @ref{prologue}.
 
-@node Results of evaluation
+@node Results of evaluation, Noweb reference syntax, Header arguments, Working with source code
 @section Results of evaluation
 @cindex code block, results of evaluation
 @cindex source code, results of evaluation
@@ -17083,7 +17083,7 @@ in results.
 In the above @code{:session} mode, the interactive interpreter receives and
 prints ``2''.  Results show that.
 
-@node Noweb reference syntax
+@node Noweb reference syntax, Key bindings and useful functions, Results of evaluation, Working with source code
 @section Noweb reference syntax
 @cindex code block, noweb reference
 @cindex syntax, noweb
@@ -17165,7 +17165,7 @@ Note that now the expansion contains the @emph{results} of the code block
 @end example
 
 
-@node Key bindings and useful functions
+@node Key bindings and useful functions, Batch execution, Noweb reference syntax, Working with source code
 @section Key bindings and useful functions
 @cindex code block, key bindings
 
@@ -17268,7 +17268,7 @@ Active key bindings in Org mode buffer:
 @c @item @kbd{C-c C-v C-z} @tab @code{org-babel-switch-to-session}
 @c @end multitable
 
-@node Batch execution
+@node Batch execution,  , Key bindings and useful functions, Working with source code
 @section Batch execution
 @cindex code block, batch execution
 @cindex source code, batch execution
@@ -17294,12 +17294,12 @@ emacs -Q --batch --eval "
   " "$@@"
 @end example
 
-@node Miscellaneous
+@node Miscellaneous, Hacking, Working with source code, Top
 @chapter Miscellaneous
 
 @menu
 * Completion::                  M-TAB guesses completions
-* Easy templates::              Quick insertion of structural elements
+* Inserting structure templates::  Wrapping text in code blocks
 * Speed keys::                  Electric commands at the beginning of a headline
 * Code evaluation security::    Org mode files evaluate inline code
 * Customization::               Adapting Org to changing tastes
@@ -17312,7 +17312,7 @@ emacs -Q --batch --eval "
 @end menu
 
 
-@node Completion
+@node Completion, Inserting structure templates, Miscellaneous, Miscellaneous
 @section Completion
 @cindex completion, of @TeX{} symbols
 @cindex completion, of TODO keywords
@@ -17374,47 +17374,42 @@ If your desktop intercepts the combo @kbd{M-@key{TAB}} to switch windows, use
 environment.
 @end table
 
-@node Easy templates
-@section Easy templates
+@node Inserting structure templates, Speed keys, Completion, Miscellaneous
+@section Inserting structure templates
 @cindex template insertion
 @cindex insertion, of templates
 
-With just a few keystrokes, Org's easy templates inserts empty pairs of
-structural elements, such as @code{#+BEGIN_SRC} and @code{#+END_SRC}.  Easy
-templates use an expansion mechanism, which is native to Org, in a process
-similar to @file{yasnippet} and other Emacs template expansion packages.
-
-@kbd{<} @kbd{s} @kbd{@key{TAB}} expands to a @samp{src} code block.
-
-@kbd{<} @kbd{l} @kbd{@key{TAB}} expands to:
-
-#+BEGIN_EXPORT latex
-
-#+END_EXPORT
+With just a few keystrokes, it's possible to insert empty structural blocks,
+such as @code{#+begin_src} and @code{#+end_src}, or to wrap existing text in
+such a block.
+
+@defun org-insert-structure-template
+@kindex C-c C-x w
+Prompt for a type of block structure, and insert the block at point.  If the
+region is active, it will be wrapped in the block.  First prompts the user
+for a key, which is used to look up a structure type from the values below.
+If the key is @key{TAB}, the user is prompted to enter a type.  Bound to
+@kbd{C-c C-x w}.
+@end defun
 
-Org comes with these pre-defined easy templates:
-
-@multitable @columnfractions 0.1 0.9
-@item @kbd{s} @tab @code{#+BEGIN_SRC ... #+END_SRC}
-@item @kbd{e} @tab @code{#+BEGIN_EXAMPLE ... #+END_EXAMPLE}
-@item @kbd{q} @tab @code{#+BEGIN_QUOTE ... #+END_QUOTE}
-@item @kbd{v} @tab @code{#+BEGIN_VERSE ... #+END_VERSE}
-@item @kbd{c} @tab @code{#+BEGIN_CENTER ... #+END_CENTER}
-@item @kbd{C} @tab @code{#+BEGIN_COMMENT ... #+END_COMMENT}
-@item @kbd{l} @tab @code{#+BEGIN_EXPORT latex ... #+END_EXPORT}
-@item @kbd{L} @tab @code{#+LATEX:}
-@item @kbd{h} @tab @code{#+BEGIN_EXPORT html ... #+END_EXPORT}
-@item @kbd{H} @tab @code{#+HTML:}
-@item @kbd{a} @tab @code{#+BEGIN_EXPORT ascii ... #+END_EXPORT}
-@item @kbd{A} @tab @code{#+ASCII:}
-@item @kbd{i} @tab @code{#+INDEX:} line
-@item @kbd{I} @tab @code{#+INCLUDE:} line
+@vindex org-structure-template-alist
+Available structure types are defined in @code{org-structure-template-alist},
+see the docstring for adding or changing values.
+
+@multitable @columnfractions 0.2 0.8
+@item @kbd{s} @tab @code{src}
+@item @kbd{e} @tab @code{example}
+@item @kbd{E} @tab @code{export}
+@item @kbd{q} @tab @code{quote}
+@item @kbd{v} @tab @code{verse}
+@item @kbd{c} @tab @code{center}
+@item @kbd{C} @tab @code{comment}
+@item @kbd{l} @tab @code{export latex}
+@item @kbd{h} @tab @code{export html}
+@item @kbd{a} @tab @code{export ascii}
 @end multitable
 
-More templates can added by customizing the variable
-@code{org-structure-template-alist}, whose docstring has additional details.
-
-@node Speed keys
+@node Speed keys, Code evaluation security, Inserting structure templates, Miscellaneous
 @section Speed keys
 @cindex speed keys
 
@@ -17440,7 +17435,7 @@ org-speed-command-help}, or @kbd{?} when cursor is at the beginning of an Org
 headline, shows currently active Speed Keys, including the user-defined ones.
 
 
-@node Code evaluation security
+@node Code evaluation security, Customization, Speed keys, Miscellaneous
 @section Code evaluation and security issues
 
 Unlike plain text, running code comes with risk.  Each @samp{src} code block,
@@ -17501,7 +17496,7 @@ Org executes formulas in tables (@pxref{The spreadsheet}) either through the
 @emph{calc} or the @emph{Emacs Lisp} interpreters.
 @end table
 
-@node Customization
+@node Customization, In-buffer settings, Code evaluation security, Miscellaneous
 @section Customization
 @cindex customization
 @cindex options, for customization
@@ -17512,7 +17507,7 @@ through the usual @kbd{M-x org-customize RET} command.  Or through the Org
 menu, @code{Org->Customization->Browse Org Group}.  Org also has per-file
 settings for some variables (@pxref{In-buffer settings}).
 
-@node In-buffer settings
+@node In-buffer settings, The very busy C-c C-c key, Customization, Miscellaneous
 @section Summary of in-buffer settings
 @cindex in-buffer settings
 @cindex special keywords
@@ -17799,7 +17794,7 @@ These lines set the TODO keywords and their significance to the current file.
 The corresponding variable is @code{org-todo-keywords}.
 @end table
 
-@node The very busy C-c C-c key
+@node The very busy C-c C-c key, Clean view, In-buffer settings, Miscellaneous
 @section The very busy C-c C-c key
 @kindex C-c C-c
 @cindex C-c C-c, overview
@@ -17851,7 +17846,7 @@ block is updated.
 If the cursor is at a timestamp, fix the day name in the timestamp.
 @end itemize
 
-@node Clean view
+@node Clean view, TTY keys, The very busy C-c C-c key, Miscellaneous
 @section A cleaner outline view
 @cindex hiding leading stars
 @cindex dynamic indentation
@@ -17969,7 +17964,7 @@ To switch between single and double stars layouts, use @kbd{M-x
 org-convert-to-odd-levels RET} and @kbd{M-x org-convert-to-oddeven-levels}.
 @end enumerate
 
-@node TTY keys
+@node TTY keys, Interaction, Clean view, Miscellaneous
 @section Using Org on a tty
 @cindex tty key bindings
 
@@ -18003,7 +17998,7 @@ normal @kbd{S-@key{cursor}} for editing timestamp might be better with
 @end multitable
 
 
-@node Interaction
+@node Interaction, org-crypt, TTY keys, Miscellaneous
 @section Interaction with other packages
 @cindex packages, interaction with other
 Org's compatibility and the level of interaction with other Emacs packages
@@ -18015,7 +18010,7 @@ are documented here.
 * Conflicts::                   Packages that lead to conflicts
 @end menu
 
-@node Cooperation
+@node Cooperation, Conflicts, Interaction, Interaction
 @subsection Packages that Org cooperates with
 
 @table @asis
@@ -18084,7 +18079,7 @@ for details.
 @end table
 @end table
 
-@node Conflicts
+@node Conflicts,  , Cooperation, Interaction
 @subsection Packages that conflict with Org mode
 
 @table @asis
@@ -18208,7 +18203,7 @@ another key for this command, or override the key in
 
 @end table
 
-@node org-crypt
+@node org-crypt,  , Interaction, Miscellaneous
 @section org-crypt.el
 @cindex @file{org-crypt.el}
 @cindex @code{org-decrypt-entry}
@@ -18245,7 +18240,7 @@ Suggested Org crypt settings in Emacs init file:
 Excluding the crypt tag from inheritance prevents encrypting previously
 encrypted text.
 
-@node Hacking
+@node Hacking, MobileOrg, Miscellaneous, Top
 @appendix Hacking
 @cindex hacking
 
@@ -18267,7 +18262,7 @@ Org.
 * Using the mapping API::       Mapping over all or selected entries
 @end menu
 
-@node Hooks
+@node Hooks, Add-on packages, Hacking, Hacking
 @section Hooks
 @cindex hooks
 
@@ -18276,7 +18271,7 @@ appendix illustrates using a few.  A complete list of hooks with
 documentation is maintained by the Worg project at
 @uref{http://orgmode.org/worg/doc.html#hooks}.
 
-@node Add-on packages
+@node Add-on packages, Adding hyperlink types, Hooks, Hacking
 @section Add-on packages
 @cindex add-on packages
 
@@ -18288,7 +18283,7 @@ See the @file{contrib/README} file in the source code directory for a list of
 contributed files.  Worg page with more information is at:
 @uref{http://orgmode.org/worg/org-contrib/}.
 
-@node Adding hyperlink types
+@node Adding hyperlink types, Adding export back-ends, Add-on packages, Hacking
 @section Adding hyperlink types
 @cindex hyperlinks, adding new types
 
@@ -18383,7 +18378,7 @@ To define new link types, define a function that implements completion
 support with @kbd{C-c C-l}.  This function should not accept any arguments
 but return the appropriate prefix and complete link string.
 
-@node Adding export back-ends
+@node Adding export back-ends, Context-sensitive commands, Adding hyperlink types, Hacking
 @section Adding export back-ends
 @cindex Export, writing back-ends
 
@@ -18410,7 +18405,7 @@ For complete documentation, see
 @url{http://orgmode.org/worg/dev/org-export-reference.html, the Org Export
 Reference on Worg}.
 
-@node Context-sensitive commands
+@node Context-sensitive commands, Tables in arbitrary syntax, Adding export back-ends, Hacking
 @section Context-sensitive commands
 @cindex context-sensitive commands, hooks
 @cindex add-ons, context-sensitive commands
@@ -18427,7 +18422,7 @@ These context sensitive commands work by providing a function that detects
 special context for that add-on and executes functionality appropriate for
 that context.
 
-@node Tables in arbitrary syntax
+@node Tables in arbitrary syntax, Dynamic blocks, Context-sensitive commands, Hacking
 @section Tables and lists in arbitrary syntax
 @cindex tables, in other modes
 @cindex lists, in other modes
@@ -18460,7 +18455,7 @@ list locally to another format, such as HTML, @LaTeX{} or Texinfo.
 * Radio lists::                 Sending and receiving lists
 @end menu
 
-@node Radio tables
+@node Radio tables, A @LaTeX{} example, Tables in arbitrary syntax, Tables in arbitrary syntax
 @subsection Radio tables
 @cindex radio tables
 
@@ -18522,7 +18517,7 @@ Comment and uncomment each line of the table during edits.  The @kbd{M-x
 orgtbl-toggle-comment RET} command makes toggling easy.
 @end itemize
 
-@node A @LaTeX{} example
+@node A @LaTeX{} example, Translator functions, Radio tables, Tables in arbitrary syntax
 @subsection A @LaTeX{} example of radio tables
 @cindex @LaTeX{}, and Orgtbl mode
 
@@ -18628,7 +18623,7 @@ Functions with two arguments can be supplied instead of strings.  By default,
 no special formatting is applied.
 @end table
 
-@node Translator functions
+@node Translator functions, Radio lists, A @LaTeX{} example, Tables in arbitrary syntax
 @subsection Translator functions
 @cindex HTML, and Orgtbl mode
 @cindex translator function
@@ -18679,7 +18674,7 @@ parameters specified in the @samp{#+ORGTBL: SEND} line.  Please share your
 translator functions by posting them to the Org users mailing list,
 @email{emacs-orgmode@@gnu.org}.
 
-@node Radio lists
+@node Radio lists,  , Translator functions, Tables in arbitrary syntax
 @subsection Radio lists
 @cindex radio lists
 @cindex org-list-insert-radio-list
@@ -18720,7 +18715,7 @@ parameters for accurate customizations of lists.  Here is a @LaTeX{} example:
 @kbd{C-c C-c} on @samp{a new house} inserts the translated @LaTeX{} list
 in-between the BEGIN and END marker lines.
 
-@node Dynamic blocks
+@node Dynamic blocks, Special agenda views, Tables in arbitrary syntax, Hacking
 @section Dynamic blocks
 @cindex dynamic blocks
 
@@ -18784,7 +18779,7 @@ Org mode.
 Dynamic blocks, like any other block, can be narrowed with
 @code{org-narrow-to-block}.
 
-@node Special agenda views
+@node Special agenda views, Speeding up your agendas, Dynamic blocks, Hacking
 @section Special agenda views
 @cindex agenda views, user-defined
 
@@ -18880,7 +18875,7 @@ special function:
     (org-agenda-overriding-header "Projects waiting for something: "))))
 @end lisp
 
-@node Speeding up your agendas
+@node Speeding up your agendas, Extracting agenda information, Special agenda views, Hacking
 @section Speeding up your agendas
 @cindex agenda views, optimization
 
@@ -18921,7 +18916,7 @@ about generation of agenda views, see the docstrings for the relevant
 variables, and this @uref{http://orgmode.org/worg/agenda-optimization.html,
 dedicated Worg page} for agenda optimization.
 
-@node Extracting agenda information
+@node Extracting agenda information, Using the property API, Speeding up your agendas, Hacking
 @section Extracting agenda information
 @cindex agenda, pipe
 @cindex Scripts, for agenda processing
@@ -19023,7 +19018,7 @@ foreach $line (split(/\n/,$agenda)) @{
 @}
 @end example
 
-@node Using the property API
+@node Using the property API, Using the mapping API, Extracting agenda information, Hacking
 @section Using the property API
 @cindex API, for properties
 @cindex properties, API
@@ -19103,7 +19098,7 @@ to be entered.  The functions must return @code{nil} if they are not
 responsible for this property.
 @end defopt
 
-@node Using the mapping API
+@node Using the mapping API,  , Using the property API, Hacking
 @section Using the mapping API
 @cindex API, for mapping
 @cindex mapping entries, API
@@ -19209,7 +19204,7 @@ The following example counts the number of entries with TODO keyword
 (length (org-map-entries t "/+WAITING" 'agenda))
 @end lisp
 
-@node MobileOrg
+@node MobileOrg, History and acknowledgments, Hacking, Top
 @appendix MobileOrg
 @cindex iPhone
 @cindex MobileOrg
@@ -19243,7 +19238,7 @@ them.  Though MobileOrg has in-buffer settings, it understands TODO states
 * Pulling from MobileOrg::      Integrating captured and flagged items
 @end menu
 
-@node Setting up the staging area
+@node Setting up the staging area, Pushing to MobileOrg, MobileOrg, MobileOrg
 @section Setting up the staging area
 
 MobileOrg needs access to a file directory on a server to interact with
@@ -19274,7 +19269,7 @@ follows:
 Org copies files to the above directory for MobileOrg.  Org also uses the
 same directory for sharing notes between Org and MobileOrg.
 
-@node Pushing to MobileOrg
+@node Pushing to MobileOrg, Pulling from MobileOrg, Setting up the staging area, MobileOrg
 @section Pushing to MobileOrg
 
 Org pushes files listed in @code{org-mobile-files} to
@@ -19299,7 +19294,7 @@ to download for agendas.  For faster downloads, MobileOrg will read only
 those files whose checksums@footnote{Checksums are stored automatically in
 the file @file{checksums.dat}.} have changed.
 
-@node Pulling from MobileOrg
+@node Pulling from MobileOrg,  , Pushing to MobileOrg, MobileOrg
 @section Pulling from MobileOrg
 
 When MobileOrg synchronizes with the server, it pulls the Org files for
@@ -19343,7 +19338,7 @@ entries.  Note that these entries may not be the most recent since MobileOrg
 searches files that were last pulled.  To get an updated agenda view with
 changes since the last pull, pull again.
 
-@node History and acknowledgments
+@node History and acknowledgments, GNU Free Documentation License, MobileOrg, Top
 @appendix History and acknowledgments
 @cindex acknowledgments
 @cindex history
@@ -19720,27 +19715,27 @@ and contributed various ideas and code snippets.
 @end itemize
 
 
-@node GNU Free Documentation License
+@node GNU Free Documentation License, Main Index, History and acknowledgments, Top
 @appendix GNU Free Documentation License
 @include doclicense.texi
 
 
-@node Main Index
+@node Main Index, Key Index, GNU Free Documentation License, Top
 @unnumbered Concept index
 
 @printindex cp
 
-@node Key Index
+@node Key Index, Command and Function Index, Main Index, Top
 @unnumbered Key index
 
 @printindex ky
 
-@node Command and Function Index
+@node Command and Function Index, Variable Index, Key Index, Top
 @unnumbered Command and function index
 
 @printindex fn
 
-@node Variable Index
+@node Variable Index,  , Command and Function Index, Top
 @unnumbered Variable index
 
 This is not a complete index of variables and faces, only the ones that are
diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 391ef94ac..97ccf884b 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -149,6 +149,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 w by default.
 
 *** ~org-export-excluded-from-toc-p~
 
diff --git a/lisp/org.el b/lisp/org.el
index 3b26bfd3d..9ad06ac3b 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -6740,8 +6740,6 @@ Use `\\[org-edit-special]' to edit table.el tables"))
        ((run-hook-with-args-until-success
 	 'org-tab-after-check-for-cycling-hook))
 
-       ((org-try-structure-completion))
-
        ((run-hook-with-args-until-success
 	 'org-tab-before-tab-emulation-hook))
 
@@ -11859,76 +11857,77 @@ keywords relative to each registered export back-end."
     "TITLE:" "TODO:" "TYP_TODO:" "SELECT_TAGS:" "EXCLUDE_TAGS:"))
 
 (defcustom org-structure-template-alist
-  '(("s" "#+BEGIN_SRC ?\n\n#+END_SRC")
-    ("e" "#+BEGIN_EXAMPLE\n?\n#+END_EXAMPLE")
-    ("q" "#+BEGIN_QUOTE\n?\n#+END_QUOTE")
-    ("v" "#+BEGIN_VERSE\n?\n#+END_VERSE")
-    ("V" "#+BEGIN_VERBATIM\n?\n#+END_VERBATIM")
-    ("c" "#+BEGIN_CENTER\n?\n#+END_CENTER")
-    ("C" "#+BEGIN_COMMENT\n?\n#+END_COMMENT")
-    ("l" "#+BEGIN_EXPORT latex\n?\n#+END_EXPORT")
-    ("L" "#+LaTeX: ")
-    ("h" "#+BEGIN_EXPORT html\n?\n#+END_EXPORT")
-    ("H" "#+HTML: ")
-    ("a" "#+BEGIN_EXPORT ascii\n?\n#+END_EXPORT")
-    ("A" "#+ASCII: ")
-    ("i" "#+INDEX: ?")
-    ("I" "#+INCLUDE: %file ?"))
+  '((?s . "src")
+    (?e . "example")
+    (?E . "export")
+    (?q . "quote")
+    (?v . "verse")
+    (?c . "center")
+    (?C . "comment")
+    (?l . "export latex")
+    (?h . "export html")
+    (?a . "export ascii"))
   "Structure completion elements.
-This is a list of abbreviation keys and values.  The value gets inserted
-if you type `<' followed by the key and then press the completion key,
-usually `TAB'.  %file will be replaced by a file name after prompting
-for the file using completion.  The cursor will be placed at the position
-of the `?' in the template.
-There are two templates for each key, the first uses the original Org syntax,
-the second uses Emacs Muse-like syntax tags.  These Muse-like tags become
-the default when the /org-mtags.el/ module has been loaded.  See also the
-variable `org-mtags-prefer-muse-templates'."
+This is an alist of characters and values.  When
+`org-insert-structure-template' is called, an additional key is
+read.  The key is first looked up in this alist, and the
+corresponding structure is inserted, with \"#+begin\" and
+\"#+end\" added automatically."
   :group 'org-completion
   :type '(repeat
-	  (list
-	   (string :tag "Key")
+	  (cons
+	   (character :tag "Key")
 	   (string :tag "Template")))
-  :version "26.1"
   :package-version '(Org . "8.3"))
 
-(defun org-try-structure-completion ()
-  "Try to complete a structure template before point.
-This looks for strings like \"<e\" on an otherwise empty line and
-expands them."
-  (let ((l (buffer-substring (point-at-bol) (point)))
-	a)
-    (when (and (looking-at "[ \t]*$")
-	       (string-match "^[ \t]*<\\([a-zA-Z]+\\)$" l)
-	       (setq a (assoc (match-string 1 l) org-structure-template-alist)))
-      (org-complete-expand-structure-template (+ -1 (point-at-bol)
-						 (match-beginning 1)) a)
-      t)))
-
-(defun org-complete-expand-structure-template (start cell)
-  "Expand a structure template."
-  (let ((rpl (nth 1 cell))
-	(ind ""))
-    (delete-region start (point))
-    (when (string-match "\\`[ \t]*#\\+" rpl)
-      (cond
-       ((bolp))
-       ((not (string-match "\\S-" (buffer-substring (point-at-bol) (point))))
-	(setq ind (buffer-substring (point-at-bol) (point))))
-       (t (newline))))
-    (setq start (point))
-    (when (string-match "%file" rpl)
-      (setq rpl (replace-match
-		 (concat
-		  "\""
-		  (save-match-data
-		    (abbreviate-file-name (read-file-name "Include file: ")))
-		  "\"")
-		 t t rpl)))
-    (setq rpl (mapconcat 'identity (split-string rpl "\n")
-			 (concat "\n" ind)))
-    (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.
+First read a character, which can be one of the keys in
+`org-structure-template-alist'.  When it is <TAB>, prompt the
+user for a string to use.  With an active region, wrap the region
+in the block.  Otherwise, insert an empty block."
+  (interactive
+   (list
+    (let* ((key (read-key "Key: "))
+	   (struct-string
+	    (or (cdr (assq key org-structure-template-alist))
+		(and (= key ?\t)
+		     (read-string "Structure type: "))
+		(error "'%c' has no structure definition" key))))
+      struct-string)))
+  (let ((s (if (use-region-p)
+	       (region-beginning)
+	     (point)))
+	(e (copy-marker (if (use-region-p)
+			    (region-end)
+			  (point))
+			t))
+	column)
+    (when (string-match-p
+	   (concat "\\`"
+		   (regexp-opt '("example" "export" "src")))
+	   type)
+      (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"
+		    (car (split-string type))))
+    (when (or (string-match-p "src\\|\\`export\\'" type)
+	      (null (use-region-p)))
+      (goto-char s)
+      (end-of-line))
+    (set-marker e nil)))
 
 ;;;; TODO, DEADLINE, Comments
 
@@ -19393,6 +19392,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-xw"    '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 379ded672..ca1b7f463 100644
--- a/testing/lisp/test-org.el
+++ b/testing/lisp/test-org.el
@@ -4000,6 +4000,52 @@ 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 multiple lines in buffer.
+  (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-mark-element)
+	      (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-mark-element)
+	      (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-mark-element)
+	      (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-mark-element)
+	      (org-insert-structure-template "foo")
+	      (buffer-string)))))
+
 (ert-deftest test-org/previous-block ()
   "Test `org-previous-block' specifications."
   ;; Regular test.
-- 
2.14.3

Re: function for inserting a block

[Eric Abrahamsen]

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

Sorry, last patch had some documentation errors.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Replace-easy-templates-with-org-insert-structure-tem.patch --]
[-- Type: text/x-diff, Size: 131042 bytes --]

From 055af9e9545947b9aeccc3370c8b67a237eea5d8 Mon Sep 17 00:00:00 2001
From: Eric Abrahamsen <eric@ericabrahamsen.net>
Date: Mon, 30 Oct 2017 10:55:29 -0700
Subject: [PATCH] Replace easy templates with 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.
  (org-structure-predefined-blocks): New option holding predefined
  blocks, for completion.
  (org-try-structure-completion,
  org-complete-expand-structure-template): Remove functions.
* doc/org.texi (Inserting structure templates): Document.
* testing/lisp/test-org.el (test-org/insert-template): New test.
---
 doc/org.texi             | 756 +++++++++++++++++++++++------------------------
 etc/ORG-NEWS             |   4 +
 lisp/org.el              | 132 ++++-----
 testing/lisp/test-org.el |  46 +++
 4 files changed, 491 insertions(+), 447 deletions(-)

diff --git a/doc/org.texi b/doc/org.texi
index 77da6d335..486fe88fe 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -652,7 +652,7 @@ Texinfo export
 * Texinfo specific export settings::  Setting the environment.
 * Texinfo file header::         Generating the header.
 * Texinfo title and copyright page::  Creating preamble pages.
-* Info directory file::     Installing a manual in Info file hierarchy.
+* Info directory file::         Installing a manual in Info file hierarchy.
 * Headings and sectioning structure::  Building document structure.
 * Indices::                     Creating indices.
 * Quoting Texinfo code::        Incorporating literal Texinfo code.
@@ -749,7 +749,7 @@ Specific header arguments
 Miscellaneous
 
 * Completion::                  M-TAB guesses completions
-* Easy templates::              Quick insertion of structural elements
+* Inserting structure templates::  Wrapping text in code blocks
 * Speed keys::                  Electric commands at the beginning of a headline
 * Code evaluation security::    Org mode files evaluate inline code
 * Customization::               Adapting Org to changing tastes
@@ -796,7 +796,7 @@ MobileOrg
 @end detailmenu
 @end menu
 
-@node Introduction
+@node Introduction, Document structure, Top, Top
 @chapter Introduction
 @cindex introduction
 
@@ -808,7 +808,7 @@ MobileOrg
 * Conventions::                 Typesetting conventions in the manual
 @end menu
 
-@node Summary
+@node Summary, Installation, Introduction, Introduction
 @section Summary
 @cindex summary
 
@@ -864,7 +864,7 @@ Network Theory Ltd.}
 
 @page
 
-@node Installation
+@node Installation, Activation, Summary, Introduction
 @section Installation
 @cindex installation
 
@@ -940,7 +940,7 @@ For more detailed explanations on Org's build system, please check the Org
 Build System page on @uref{http://orgmode.org/worg/dev/org-build-system.html,
 Worg}.
 
-@node Activation
+@node Activation, Feedback, Installation, Introduction
 @section Activation
 @cindex activation
 @cindex autoload
@@ -991,7 +991,7 @@ the default.  If you do not like @code{transient-mark-mode}, you can create
 an active region by using the mouse to select a region, or pressing
 @kbd{C-@key{SPC}} twice before moving the cursor.
 
-@node Feedback
+@node Feedback, Conventions, Activation, Introduction
 @section Feedback
 @cindex feedback
 @cindex bug reports
@@ -1091,7 +1091,7 @@ screen.  Save this buffer to a file (for example using @kbd{C-x C-w}) and
 attach it to your bug report.
 @end enumerate
 
-@node Conventions
+@node Conventions,  , Feedback, Introduction
 @section Typesetting conventions used in this manual
 
 @subsubheading TODO keywords, tags, properties, etc.
@@ -1141,7 +1141,7 @@ will be listed to call @code{org-table-move-column-right}.  If you prefer,
 you can compile the manual without the command names by unsetting the flag
 @code{cmdnames} in @file{org.texi}.
 
-@node Document structure
+@node Document structure, Tables, Introduction, Top
 @chapter Document structure
 @cindex document structure
 @cindex structure of document
@@ -1164,7 +1164,7 @@ edit the structure of the document.
 * Org syntax::                  Formal description of Org's syntax
 @end menu
 
-@node Outlines
+@node Outlines, Headlines, Document structure, Document structure
 @section Outlines
 @cindex outlines
 @cindex Outline mode
@@ -1178,7 +1178,7 @@ currently being worked on.  Org greatly simplifies the use of
 outlines by compressing the entire show/hide functionality into a single
 command, @command{org-cycle}, which is bound to the @key{TAB} key.
 
-@node Headlines
+@node Headlines, Visibility cycling, Outlines, Document structure
 @section Headlines
 @cindex headlines
 @cindex outline tree
@@ -1220,7 +1220,7 @@ least two empty lines, one empty line will remain visible after folding
 the subtree, in order to structure the collapsed view.  See the
 variable @code{org-cycle-separator-lines} to modify this behavior.
 
-@node Visibility cycling
+@node Visibility cycling, Motion, Headlines, Document structure
 @section Visibility cycling
 @cindex cycling, visibility
 @cindex visibility cycling
@@ -1234,7 +1234,7 @@ variable @code{org-cycle-separator-lines} to modify this behavior.
 * Catching invisible edits::    Preventing mistakes when editing invisible parts
 @end menu
 
-@node Global and local cycling
+@node Global and local cycling, Initial visibility, Visibility cycling, Visibility cycling
 @subsection Global and local cycling
 
 Outlines make it possible to hide parts of the text in the buffer.
@@ -1315,7 +1315,7 @@ a @kbd{C-u} prefix, do not remove the previously used indirect buffer.
 Copy the @i{visible} text in the region into the kill ring.
 @end table
 
-@node Initial visibility
+@node Initial visibility, Catching invisible edits, Global and local cycling, Visibility cycling
 @subsection Initial visibility
 
 @cindex visibility, initialize
@@ -1355,7 +1355,7 @@ requested by startup options and @samp{VISIBILITY} properties in individual
 entries.
 @end table
 
-@node Catching invisible edits
+@node Catching invisible edits,  , Initial visibility, Visibility cycling
 @subsection Catching invisible edits
 
 @vindex org-catch-invisible-edits
@@ -1366,7 +1366,7 @@ confused on what has been edited and how to undo the mistake.  Setting
 docstring of this option on how Org should catch invisible edits and process
 them.
 
-@node Motion
+@node Motion, Structure editing, Visibility cycling, Document structure
 @section Motion
 @cindex motion, between headlines
 @cindex jumping, to headlines
@@ -1406,7 +1406,7 @@ q            @r{Quit}
 See also the option @code{org-goto-interface}.
 @end table
 
-@node Structure editing
+@node Structure editing, Sparse trees, Motion, Document structure
 @section Structure editing
 @cindex structure editing
 @cindex headline, promotion and demotion
@@ -1542,7 +1542,7 @@ inside a table (@pxref{Tables}), the Meta-Cursor keys have different
 functionality.
 
 
-@node Sparse trees
+@node Sparse trees, Plain lists, Structure editing, Document structure
 @section Sparse trees
 @cindex sparse trees
 @cindex trees, sparse
@@ -1609,7 +1609,7 @@ To print a sparse tree, you can use the Emacs command
 document.  Or you can use @kbd{C-c C-e C-v} to export only the visible part
 of the document and print the resulting file.
 
-@node Plain lists
+@node Plain lists, Drawers, Sparse trees, Document structure
 @section Plain lists
 @cindex plain lists
 @cindex lists, plain
@@ -1813,7 +1813,7 @@ numerically, alphabetically, by time, by checked status for check lists,
 or by a custom function.
 @end table
 
-@node Drawers
+@node Drawers, Blocks, Plain lists, Document structure
 @section Drawers
 @cindex drawers
 @cindex visibility cycling, drawers
@@ -1866,7 +1866,7 @@ You can select the name of the drawers which should be exported with
 export output.  Property drawers are not affected by this variable: configure
 @code{org-export-with-properties} instead.
 
-@node Blocks
+@node Blocks, Footnotes, Drawers, Document structure
 @section Blocks
 
 @vindex org-hide-block-startup
@@ -1885,7 +1885,7 @@ or on a per-file basis by using
 #+STARTUP: nohideblocks
 @end example
 
-@node Footnotes
+@node Footnotes, Orgstruct mode, Blocks, Document structure
 @section Footnotes
 @cindex footnotes
 
@@ -1990,7 +1990,7 @@ a separate window.  The window can be closed by pressing @kbd{C-c '}.
 
 @end table
 
-@node Orgstruct mode
+@node Orgstruct mode, Org syntax, Footnotes, Document structure
 @section The Orgstruct minor mode
 @cindex Orgstruct mode
 @cindex minor mode for structure editing
@@ -2025,7 +2025,7 @@ Lisp files, you will be able to fold and unfold headlines in Emacs Lisp
 commented lines.  Some commands like @code{org-demote} are disabled when the
 prefix is set, but folding/unfolding will work correctly.
 
-@node Org syntax
+@node Org syntax,  , Orgstruct mode, Document structure
 @section Org syntax
 @cindex Org syntax
 
@@ -2051,7 +2051,7 @@ rely on the syntactic meaning of the surrounding context.
 @cindex linter
 You can check syntax in your documents using @code{org-lint} command.
 
-@node Tables
+@node Tables, Hyperlinks, Document structure, Top
 @chapter Tables
 @cindex tables
 @cindex editing tables
@@ -2069,7 +2069,7 @@ calculations are supported using the Emacs @file{calc} package
 * Org-Plot::                    Plotting from org tables
 @end menu
 
-@node Built-in table editor
+@node Built-in table editor, Column width and alignment, Tables, Tables
 @section The built-in table editor
 @cindex table editor, built-in
 
@@ -2289,7 +2289,7 @@ it off with
 @noindent Then the only table command that still works is
 @kbd{C-c C-c} to do a manual re-align.
 
-@node Column width and alignment
+@node Column width and alignment, Column groups, Built-in table editor, Tables
 @section Column width and alignment
 @cindex narrow columns in tables
 @cindex alignment in tables
@@ -2380,7 +2380,7 @@ alignment and field width like this: @samp{<r10>}.
 Lines which only contain these formatting cookies are removed automatically
 upon exporting the document.
 
-@node Column groups
+@node Column groups, Orgtbl mode, Column width and alignment, Tables
 @section Column groups
 @cindex grouping columns in tables
 
@@ -2415,7 +2415,7 @@ every vertical line you would like to have:
 | /  | <   |     |     | <       |            |
 @end example
 
-@node Orgtbl mode
+@node Orgtbl mode, The spreadsheet, Column groups, Tables
 @section The Orgtbl minor mode
 @cindex Orgtbl mode
 @cindex minor mode for tables
@@ -2436,7 +2436,7 @@ construct @LaTeX{} tables with the underlying ease and power of
 Orgtbl mode, including spreadsheet capabilities.  For details, see
 @ref{Tables in arbitrary syntax}.
 
-@node The spreadsheet
+@node The spreadsheet, Org-Plot, Orgtbl mode, Tables
 @section The spreadsheet
 @cindex calculations, in tables
 @cindex spreadsheet capabilities
@@ -2465,7 +2465,7 @@ formula, moving these references by arrow keys
 * Advanced features::           Field and column names, parameters and automatic recalc
 @end menu
 
-@node References
+@node References, Formula syntax for Calc, The spreadsheet, The spreadsheet
 @subsection References
 @cindex references
 
@@ -2657,7 +2657,7 @@ table.  For example @code{remote($1, @@>$2)} => @code{remote(year_2013,
 @@>$1)}.  The format @code{B3} is not supported because it can not be
 distinguished from a plain table name or ID.
 
-@node Formula syntax for Calc
+@node Formula syntax for Calc, Formula syntax for Lisp, References, The spreadsheet
 @subsection Formula syntax for Calc
 @cindex formula syntax, Calc
 @cindex syntax, of formulas
@@ -2772,7 +2772,7 @@ should be padded with 0 to the full size.
 You can add your own Calc functions defined in Emacs Lisp with @code{defmath}
 and use them in formula syntax for Calc.
 
-@node Formula syntax for Lisp
+@node Formula syntax for Lisp, Durations and time values, Formula syntax for Calc, The spreadsheet
 @subsection Emacs Lisp forms as formulas
 @cindex Lisp forms, as table formulas
 
@@ -2808,7 +2808,7 @@ Add columns 1 and 2, equivalent to Calc's @code{$1+$2}.
 Compute the sum of columns 1 to 4, like Calc's @code{vsum($1..$4)}.
 @end table
 
-@node Durations and time values
+@node Durations and time values, Field and range formulas, Formula syntax for Lisp, The spreadsheet
 @subsection Durations and time values
 @cindex Duration, computing
 @cindex Time, computing
@@ -2843,7 +2843,7 @@ third formula in the example above).
 Negative duration values can be manipulated as well, and integers will be
 considered as seconds in addition and subtraction.
 
-@node Field and range formulas
+@node Field and range formulas, Column formulas, Durations and time values, The spreadsheet
 @subsection Field and range formulas
 @cindex field formula
 @cindex range formula
@@ -2899,7 +2899,7 @@ can also be used to assign a formula to some but not all fields in a row.
 Named field, see @ref{Advanced features}.
 @end table
 
-@node Column formulas
+@node Column formulas, Lookup functions, Field and range formulas, The spreadsheet
 @subsection Column formulas
 @cindex column formula
 @cindex formula, for table column
@@ -2938,7 +2938,7 @@ stores it.  With a numeric prefix argument(e.g., @kbd{C-5 C-c =}) the command
 will apply it to that many consecutive fields in the current column.
 @end table
 
-@node Lookup functions
+@node Lookup functions, Editing and debugging formulas, Column formulas, The spreadsheet
 @subsection Lookup functions
 @cindex lookup functions in tables
 @cindex table lookup functions
@@ -2982,7 +2982,7 @@ matching cells, rank results, group data etc.  For practical examples
 see @uref{http://orgmode.org/worg/org-tutorials/org-lookups.html, this
 tutorial on Worg}.
 
-@node Editing and debugging formulas
+@node Editing and debugging formulas, Updating the table, Lookup functions, The spreadsheet
 @subsection Editing and debugging formulas
 @cindex formula editing
 @cindex editing, of table formulas
@@ -3135,7 +3135,7 @@ turn on formula debugging in the @code{Tbl} menu and repeat the
 calculation, for example by pressing @kbd{C-u C-u C-c = @key{RET}} in a
 field.  Detailed information will be displayed.
 
-@node Updating the table
+@node Updating the table, Advanced features, Editing and debugging formulas, The spreadsheet
 @subsection Updating the table
 @cindex recomputing table fields
 @cindex updating, table
@@ -3172,7 +3172,7 @@ Iterate all tables in the current buffer, in order to converge table-to-table
 dependencies.
 @end table
 
-@node Advanced features
+@node Advanced features,  , Updating the table, The spreadsheet
 @subsection Advanced features
 
 If you want the recalculation of fields to happen automatically, or if you
@@ -3277,7 +3277,7 @@ functions.
 @end group
 @end example
 
-@node Org-Plot
+@node Org-Plot,  , The spreadsheet, Tables
 @section Org-Plot
 @cindex graph, in tables
 @cindex plot tables using Gnuplot
@@ -3409,7 +3409,7 @@ The formula is an elisp call:
 
 @end table
 
-@node Hyperlinks
+@node Hyperlinks, TODO items, Tables, Top
 @chapter Hyperlinks
 @cindex hyperlinks
 
@@ -3427,7 +3427,7 @@ other files, Usenet articles, emails, and much more.
 * Custom searches::             When the default search is not enough
 @end menu
 
-@node Link format
+@node Link format, Internal links, Hyperlinks, Hyperlinks
 @section Link format
 @cindex link format
 @cindex format, of links
@@ -3458,7 +3458,7 @@ missing bracket hides the link internals again.  To show the
 internal structure of all links, use the menu entry
 @code{Org->Hyperlinks->Literal links}.
 
-@node Internal links
+@node Internal links, External links, Link format, Hyperlinks
 @section Internal links
 @cindex internal links
 @cindex links, internal
@@ -3529,7 +3529,7 @@ earlier.
 * Radio targets::               Make targets trigger links in plain text
 @end menu
 
-@node Radio targets
+@node Radio targets,  , Internal links, Internal links
 @subsection Radio targets
 @cindex radio targets
 @cindex targets, radio
@@ -3545,7 +3545,7 @@ for radio targets only when the file is first loaded into Emacs.  To
 update the target list during editing, press @kbd{C-c C-c} with the
 cursor on or at a target.
 
-@node External links
+@node External links, Handling links, Internal links, Hyperlinks
 @section External links
 @cindex links, external
 @cindex external links
@@ -3648,7 +3648,7 @@ as links.  If spaces must be part of the link (for example in
 @samp{bbdb:Richard Stallman}), or if you need to remove ambiguities
 about the end of the link, enclose them in square brackets.
 
-@node Handling links
+@node Handling links, Using links outside Org, External links, Hyperlinks
 @section Handling links
 @cindex links, handling
 
@@ -3846,7 +3846,7 @@ to @kbd{C-n} and @kbd{C-p}
 @end lisp
 @end table
 
-@node Using links outside Org
+@node Using links outside Org, Link abbreviations, Handling links, Hyperlinks
 @section Using links outside Org
 
 You can insert and follow links that have Org syntax not only in
@@ -3859,7 +3859,7 @@ yourself):
 (global-set-key "\C-c o" 'org-open-at-point-global)
 @end lisp
 
-@node Link abbreviations
+@node Link abbreviations, Search options, Using links outside Org, Hyperlinks
 @section Link abbreviations
 @cindex link abbreviations
 @cindex abbreviation, links
@@ -3933,7 +3933,7 @@ link with prefix.  You can add a completion function to a link like this:
 @end lisp
 
 
-@node Search options
+@node Search options, Custom searches, Link abbreviations, Hyperlinks
 @section Search options in file links
 @cindex search option in file links
 @cindex file links, searching
@@ -3985,7 +3985,7 @@ to search the current file.  For example, @code{[[file:::find me]]} does
 a search for @samp{find me} in the current file, just as
 @samp{[[find me]]} would.
 
-@node Custom searches
+@node Custom searches,  , Search options, Hyperlinks
 @section Custom Searches
 @cindex custom search strings
 @cindex search strings, custom
@@ -4009,7 +4009,7 @@ variables for more information.  Org actually uses this mechanism
 for Bib@TeX{} database files, and you can use the corresponding code as
 an implementation example.  See the file @file{org-bibtex.el}.
 
-@node TODO items
+@node TODO items, Tags, Hyperlinks, Top
 @chapter TODO items
 @cindex TODO items
 
@@ -4034,7 +4034,7 @@ methods to give you an overview of all the things that you have to do.
 * Checkboxes::                  Tick-off lists
 @end menu
 
-@node TODO basics
+@node TODO basics, TODO extensions, TODO items, TODO items
 @section Basic TODO functionality
 
 Any headline becomes a TODO item when it starts with the word
@@ -4108,7 +4108,7 @@ Insert a new TODO entry below the current one.
 Changing a TODO state can also trigger tag changes.  See the docstring of the
 option @code{org-todo-state-tags-triggers} for details.
 
-@node TODO extensions
+@node TODO extensions, Progress logging, TODO basics, TODO items
 @section Extended use of TODO keywords
 @cindex extended TODO keywords
 
@@ -4132,7 +4132,7 @@ TODO items in particular (@pxref{Tags}).
 * TODO dependencies::           When one task needs to wait for others
 @end menu
 
-@node Workflow states
+@node Workflow states, TODO types, TODO extensions, TODO extensions
 @subsection TODO keywords as workflow states
 @cindex TODO workflow
 @cindex workflow states as TODO keywords
@@ -4163,7 +4163,7 @@ define many keywords, you can use in-buffer completion
 buffer.  Changing a TODO state can be logged with a timestamp, see
 @ref{Tracking TODO state changes}, for more information.
 
-@node TODO types
+@node TODO types, Multiple sets in one file, Workflow states, TODO extensions
 @subsection TODO keywords as types
 @cindex TODO types
 @cindex names as TODO keywords
@@ -4195,7 +4195,7 @@ has to do, you would use @kbd{C-3 C-c / t}.  To collect Lucy's items from all
 agenda files into a single buffer, you would use the numeric prefix argument
 as well when creating the global TODO list: @kbd{C-3 C-c a t}.
 
-@node Multiple sets in one file
+@node Multiple sets in one file, Fast access to TODO states, TODO types, TODO extensions
 @subsection Multiple keyword sets in one file
 @cindex TODO keyword sets
 
@@ -4244,7 +4244,7 @@ from @code{DONE} to @code{REPORT} in the example above.  See also
 @code{shift-selection-mode}.
 @end table
 
-@node Fast access to TODO states
+@node Fast access to TODO states, Per-file keywords, Multiple sets in one file, TODO extensions
 @subsection Fast access to TODO states
 
 If you would like to quickly change an entry to an arbitrary TODO state
@@ -4269,7 +4269,7 @@ state through the tags interface (@pxref{Setting tags}), in case you like to
 mingle the two concepts.  Note that this means you need to come up with
 unique keys across both sets of keywords.}
 
-@node Per-file keywords
+@node Per-file keywords, Faces for TODO keywords, Fast access to TODO states, TODO extensions
 @subsection Setting up keywords for individual files
 @cindex keyword options
 @cindex per-file keywords
@@ -4315,7 +4315,7 @@ Org mode is activated after visiting a file.  @kbd{C-c C-c} with the
 cursor in a line starting with @samp{#+} is simply restarting Org mode
 for the current buffer.}.
 
-@node Faces for TODO keywords
+@node Faces for TODO keywords, TODO dependencies, Per-file keywords, TODO extensions
 @subsection Faces for TODO keywords
 @cindex faces, for TODO keywords
 
@@ -4343,7 +4343,7 @@ special face and use that.  A string is interpreted as a color.  The option
 @code{org-faces-easy-properties} determines if that color is interpreted as a
 foreground or a background color.
 
-@node TODO dependencies
+@node TODO dependencies,  , Faces for TODO keywords, TODO extensions
 @subsection TODO dependencies
 @cindex TODO dependencies
 @cindex dependencies, of TODO states
@@ -4416,7 +4416,7 @@ between entries in different trees or files, check out the contributed
 module @file{org-depend.el}.
 
 @page
-@node Progress logging
+@node Progress logging, Priorities, TODO extensions, TODO items
 @section Progress logging
 @cindex progress logging
 @cindex logging, of progress
@@ -4434,7 +4434,7 @@ work time}.
 * Tracking your habits::        How consistent have you been?
 @end menu
 
-@node Closing items
+@node Closing items, Tracking TODO state changes, Progress logging, Progress logging
 @subsection Closing items
 
 The most basic logging is to keep track of @emph{when} a certain TODO
@@ -4465,7 +4465,7 @@ lognotedone}.}
 You will then be prompted for a note, and that note will be stored below
 the entry with a @samp{Closing Note} heading.
 
-@node Tracking TODO state changes
+@node Tracking TODO state changes, Tracking your habits, Closing items, Progress logging
 @subsection Tracking TODO state changes
 @cindex drawer, for state change recording
 
@@ -4548,7 +4548,7 @@ settings like @code{TODO(!)}.  For example
   :END:
 @end example
 
-@node Tracking your habits
+@node Tracking your habits,  , Tracking TODO state changes, Progress logging
 @subsection Tracking your habits
 @cindex habits
 
@@ -4648,7 +4648,7 @@ temporarily be disabled and they won't appear at all.  Press @kbd{K} again to
 bring them back.  They are also subject to tag filtering, if you have habits
 which should only be done in certain contexts, for example.
 
-@node Priorities
+@node Priorities, Breaking down tasks, Progress logging, TODO items
 @section Priorities
 @cindex priorities
 
@@ -4706,7 +4706,7 @@ priority):
 #+PRIORITIES: A C B
 @end example
 
-@node Breaking down tasks
+@node Breaking down tasks, Checkboxes, Priorities, TODO items
 @section Breaking tasks down into subtasks
 @cindex tasks, breaking down
 @cindex statistics, for TODO items
@@ -4767,7 +4767,7 @@ Another possibility is the use of checkboxes to identify (a hierarchy of) a
 large number of subtasks (@pxref{Checkboxes}).
 
 
-@node Checkboxes
+@node Checkboxes,  , Breaking down tasks, TODO items
 @section Checkboxes
 @cindex checkboxes
 
@@ -4876,7 +4876,7 @@ changing TODO states.  If you delete boxes/entries or add/change them by
 hand, use this command to get things back into sync.
 @end table
 
-@node Tags
+@node Tags, Properties and columns, TODO items, Top
 @chapter Tags
 @cindex tags
 @cindex headline tagging
@@ -4904,7 +4904,7 @@ You may specify special faces for specific tags using the option
 * Tag searches::                Searching for combinations of tags
 @end menu
 
-@node Tag inheritance
+@node Tag inheritance, Setting tags, Tags, Tags
 @section Tag inheritance
 @cindex tag inheritance
 @cindex inheritance, of tags
@@ -4958,7 +4958,7 @@ with inherited tags.  Set @code{org-agenda-use-tag-inheritance} to control
 this: the default value includes all agenda types, but setting this to @code{nil}
 can really speed up agenda generation.
 
-@node Setting tags
+@node Setting tags, Tag hierarchy, Tag inheritance, Tags
 @section Setting tags
 @cindex setting tags
 @cindex tags, setting
@@ -5145,7 +5145,7 @@ instead of @kbd{C-c C-c}).  If you set the variable to the value
 @code{expert}, the special window is not even shown for single-key tag
 selection, it comes up only when you press an extra @kbd{C-c}.
 
-@node Tag hierarchy
+@node Tag hierarchy, Tag searches, Setting tags, Tags
 @section Tag hierarchy
 
 @cindex group tags
@@ -5250,7 +5250,7 @@ If you want to ignore group tags temporarily, toggle group tags support
 with @command{org-toggle-tags-groups}, bound to @kbd{C-c C-x q}.  If you
 want to disable tag groups completely, set @code{org-group-tags} to @code{nil}.
 
-@node Tag searches
+@node Tag searches,  , Tag hierarchy, Tags
 @section Tag searches
 @cindex tag searches
 @cindex searching for tags
@@ -5282,7 +5282,7 @@ properties.  For a complete description with many examples, see @ref{Matching
 tags and properties}.
 
 
-@node Properties and columns
+@node Properties and columns, Dates and times, Tags, Top
 @chapter Properties and columns
 @cindex properties
 
@@ -5312,7 +5312,7 @@ Properties can be conveniently edited and viewed in column view
 * Property API::                Properties for Lisp programmers
 @end menu
 
-@node Property syntax
+@node Property syntax, Special properties, Properties and columns, Properties and columns
 @section Property syntax
 @cindex property syntax
 @cindex drawer, for properties
@@ -5436,7 +5436,7 @@ Compute the property at point, using the operator and scope from the
 nearest column format definition.
 @end table
 
-@node Special properties
+@node Special properties, Property searches, Property syntax, Properties and columns
 @section Special properties
 @cindex properties, special
 
@@ -5481,7 +5481,7 @@ TIMESTAMP_IA @r{The first inactive timestamp in the entry.}
 TODO         @r{The TODO keyword of the entry.}
 @end example
 
-@node Property searches
+@node Property searches, Property inheritance, Special properties, Properties and columns
 @section Property searches
 @cindex properties, searching
 @cindex searching, of properties
@@ -5518,7 +5518,7 @@ value.  If you enclose the value in curly braces, it is interpreted as
 a regular expression and matched against the property values.
 @end table
 
-@node Property inheritance
+@node Property inheritance, Column view, Property searches, Properties and columns
 @section Property Inheritance
 @cindex properties, inheritance
 @cindex inheritance, of properties
@@ -5562,7 +5562,7 @@ The LOGGING property may define logging settings for an entry or a
 subtree (@pxref{Tracking TODO state changes}).
 @end table
 
-@node Column view
+@node Column view, Property API, Property inheritance, Properties and columns
 @section Column view
 
 A great way to view and edit properties in an outline tree is
@@ -5585,7 +5585,7 @@ queries have collected selected items, possibly from a number of files.
 * Capturing column view::       A dynamic block for column view
 @end menu
 
-@node Defining columns
+@node Defining columns, Using column view, Column view, Column view
 @subsection Defining columns
 @cindex column view, for properties
 @cindex properties, column view
@@ -5598,7 +5598,7 @@ done by defining a column format line.
 * Column attributes::           Appearance and content of a column
 @end menu
 
-@node Scope of column definitions
+@node Scope of column definitions, Column attributes, Defining columns, Defining columns
 @subsubsection Scope of column definitions
 
 To define a column format for an entire file, use a line like
@@ -5625,7 +5625,7 @@ you can define columns on level 1 that are general enough for all
 sublevels, and more specific columns further down, when you edit a
 deeper part of the tree.
 
-@node Column attributes
+@node Column attributes,  , Scope of column definitions, Defining columns
 @subsubsection Column attributes
 A column definition sets the attributes of a column.  The general
 definition looks like this:
@@ -5731,7 +5731,7 @@ an @samp{[X]} status if all children have been checked.  The
 sums of CLOCK intervals in the subtree, either for all clocks or just for
 today.
 
-@node Using column view
+@node Using column view, Capturing column view, Defining columns, Column view
 @subsection Using column view
 
 @table @kbd
@@ -5790,7 +5790,7 @@ Insert a new column, to the left of the current column.
 Delete the current column.
 @end table
 
-@node Capturing column view
+@node Capturing column view,  , Using column view, Column view
 @subsection Capturing column view
 
 Since column view is just an overlay over a buffer, it cannot be
@@ -5869,7 +5869,7 @@ distributed with the main distribution of Org (visit
 properties from entries in a certain scope, and arbitrary Lisp expressions to
 process these values before inserting them into a table or a dynamic block.
 
-@node Property API
+@node Property API,  , Column view, Properties and columns
 @section The Property API
 @cindex properties, API
 @cindex API, for properties
@@ -5879,7 +5879,7 @@ be used by Emacs Lisp programs to work with properties and to implement
 features based on them.  For more information see @ref{Using the
 property API}.
 
-@node Dates and times
+@node Dates and times, Capture - Refile - Archive, Properties and columns, Top
 @chapter Dates and times
 @cindex dates
 @cindex times
@@ -5903,7 +5903,7 @@ is used in a much wider sense.
 @end menu
 
 
-@node Timestamps
+@node Timestamps, Creating timestamps, Dates and times, Dates and times
 @section Timestamps, deadlines, and scheduling
 @cindex timestamps
 @cindex ranges, time
@@ -5997,7 +5997,7 @@ angular ones.  These timestamps are inactive in the sense that they do
 
 @end table
 
-@node Creating timestamps
+@node Creating timestamps, Deadlines and scheduling, Timestamps, Dates and times
 @section Creating timestamps
 @cindex creating timestamps
 @cindex timestamps, creating
@@ -6068,7 +6068,7 @@ the following column).
 * Custom time format::          Making dates look different
 @end menu
 
-@node The date/time prompt
+@node The date/time prompt, Custom time format, Creating timestamps, Creating timestamps
 @subsection The date/time prompt
 @cindex date, reading in minibuffer
 @cindex time, reading in minibuffer
@@ -6198,7 +6198,7 @@ on, the current interpretation of your input will be displayed live in the
 minibuffer@footnote{If you find this distracting, turn the display off with
 @code{org-read-date-display-live}.}.
 
-@node Custom time format
+@node Custom time format,  , The date/time prompt, Creating timestamps
 @subsection Custom time format
 @cindex custom date/time format
 @cindex time format, custom
@@ -6246,7 +6246,7 @@ format is shorter, things do work as expected.
 @end itemize
 
 
-@node Deadlines and scheduling
+@node Deadlines and scheduling, Clocking work time, Creating timestamps, Dates and times
 @section Deadlines and scheduling
 
 A timestamp may be preceded by special keywords to facilitate planning.  Both
@@ -6337,7 +6337,7 @@ sexp entry matches.
 * Repeated tasks::              Items that show up again and again
 @end menu
 
-@node Inserting deadline/schedule
+@node Inserting deadline/schedule, Repeated tasks, Deadlines and scheduling, Deadlines and scheduling
 @subsection Inserting deadlines or schedules
 
 The following commands allow you to quickly insert a deadline or to schedule
@@ -6384,7 +6384,7 @@ setting the date by indicating a relative time: e.g., +1d will set
 the date to the next day after today, and --1w will set the date
 to the previous week before any current timestamp.
 
-@node Repeated tasks
+@node Repeated tasks,  , Inserting deadline/schedule, Deadlines and scheduling
 @subsection Repeated tasks
 @cindex tasks, repeated
 @cindex repeated tasks
@@ -6485,7 +6485,7 @@ subtree, with dates shifted in each copy.  The command @kbd{C-c C-x c} was
 created for this purpose, it is described in @ref{Structure editing}.
 
 
-@node Clocking work time
+@node Clocking work time, Effort estimates, Deadlines and scheduling, Dates and times
 @section Clocking work time
 @cindex clocking time
 @cindex time clocking
@@ -6517,7 +6517,7 @@ what to do with it.
 * Resolving idle time::         Resolving time when you've been idle
 @end menu
 
-@node Clocking commands
+@node Clocking commands, The clock table, Clocking work time, Clocking work time
 @subsection Clocking commands
 
 @table @kbd
@@ -6616,7 +6616,7 @@ which tasks have been worked on or closed during a day.
 @code{org-clock-in-last} can have a global key binding and will not
 modify the window disposition.
 
-@node The clock table
+@node The clock table, Resolving idle time, Clocking commands, Clocking work time
 @subsection The clock table
 @cindex clocktable, dynamic block
 @cindex report, of clocked time
@@ -6768,7 +6768,7 @@ would be
 #+END: clocktable
 @end example
 
-@node Resolving idle time
+@node Resolving idle time,  , The clock table, Clocking work time
 @subsection Resolving idle time and continuous clocking
 
 @subsubheading Resolving idle time
@@ -6853,7 +6853,7 @@ last clocked entry for this session, and start the new clock from there.
 If you only want this from time to time, use three universal prefix arguments
 with @code{org-clock-in} and two @kbd{C-u C-u} with @code{org-clock-in-last}.
 
-@node Effort estimates
+@node Effort estimates, Timers, Clocking work time, Dates and times
 @section Effort estimates
 @cindex effort estimates
 
@@ -6914,7 +6914,7 @@ with the @kbd{/} key in the agenda (@pxref{Agenda commands}).  If you have
 these estimates defined consistently, two or three key presses will narrow
 down the list to stuff that fits into an available time slot.
 
-@node Timers
+@node Timers,  , Effort estimates, Dates and times
 @section Taking notes with a timer
 @cindex relative timer
 @cindex countdown timer
@@ -6964,7 +6964,7 @@ Stop the timer.  After this, you can only start a new timer, not continue the
 old one.  This command also removes the timer from the mode line.
 @end table
 
-@node Capture - Refile - Archive
+@node Capture - Refile - Archive, Agenda views, Dates and times, Top
 @chapter Capture - Refile - Archive
 @cindex capture
 
@@ -6984,7 +6984,7 @@ trees to an archive file keeps the system compact and fast.
 * Archiving::                   What to do with finished projects
 @end menu
 
-@node Capture
+@node Capture, Attachments, Capture - Refile - Archive, Capture - Refile - Archive
 @section Capture
 @cindex capture
 
@@ -7011,7 +7011,7 @@ customization.
 * Capture templates::           Define the outline of different note types
 @end menu
 
-@node Setting up capture
+@node Setting up capture, Using capture, Capture, Capture
 @subsection Setting up capture
 
 The following customization sets a default target file for notes, and defines
@@ -7026,7 +7026,7 @@ suggestion.}  for capturing new material.
 @end group
 @end smalllisp
 
-@node Using capture
+@node Using capture, Capture templates, Setting up capture, Capture
 @subsection Using capture
 
 @table @kbd
@@ -7083,7 +7083,7 @@ automatically be created unless you set @code{org-capture-bookmark} to
 To insert the capture at point in an Org buffer, call @code{org-capture} with
 a @code{C-0} prefix argument.
 
-@node Capture templates
+@node Capture templates,  , Using capture, Capture
 @subsection Capture templates
 @cindex templates, for Capture
 
@@ -7142,7 +7142,7 @@ like this:
 * Templates in contexts::       Only show a template in a specific context
 @end menu
 
-@node Template elements
+@node Template elements, Template expansion, Capture templates, Capture templates
 @subsubsection Template elements
 
 Now lets look at the elements of a template definition.  Each entry in
@@ -7307,7 +7307,7 @@ buffer again after capture is completed.
 @end table
 @end table
 
-@node Template expansion
+@node Template expansion, Templates in contexts, Template elements, Capture templates
 @subsubsection Template expansion
 
 In the template itself, special @kbd{%}-escapes@footnote{If you need one of
@@ -7392,7 +7392,7 @@ To place the cursor after template expansion use:
 %?          @r{After completing the template, position cursor here.}
 @end smallexample
 
-@node Templates in contexts
+@node Templates in contexts,  , Template expansion, Capture templates
 @subsubsection Templates in contexts
 
 @vindex org-capture-templates-contexts
@@ -7416,7 +7416,7 @@ template.  In that case, add this command key like this:
 
 See the docstring of the variable for more information.
 
-@node Attachments
+@node Attachments, RSS feeds, Capture, Capture - Refile - Archive
 @section Attachments
 @cindex attachments
 
@@ -7507,7 +7507,7 @@ same directory for attachments as the parent does.
 @end table
 @end table
 
-@node RSS feeds
+@node RSS feeds, Protocols, Attachments, Capture - Refile - Archive
 @section RSS feeds
 @cindex RSS feeds
 @cindex Atom feeds
@@ -7550,7 +7550,7 @@ adding the same item several times.
 For more information, including how to read atom feeds, see
 @file{org-feed.el} and the docstring of @code{org-feed-alist}.
 
-@node Protocols
+@node Protocols, Refile and copy, RSS feeds, Capture - Refile - Archive
 @section Protocols for external access
 @cindex protocols, for external access
 
@@ -7588,7 +7588,7 @@ sections.  Configure @code{org-protocol-protocol-alist} to define your own.
 * @code{open-source} protocol::  Edit published contents.
 @end menu
 
-@node @code{store-link} protocol
+@node @code{store-link} protocol, @code{capture} protocol, Protocols, Protocols
 @subsection @code{store-link} protocol
 @cindex store-link protocol
 @cindex protocol, store-link
@@ -7619,7 +7619,7 @@ javascript:location.href='org-protocol://store-link?url='+
       encodeURIComponent(location.href);
 @end example
 
-@node @code{capture} protocol
+@node @code{capture} protocol, @code{open-source} protocol, @code{store-link} protocol, Protocols
 @subsection @code{capture} protocol
 @cindex capture protocol
 @cindex protocol, capture
@@ -7661,7 +7661,7 @@ The following template placeholders are available:
 %i              The selected text
 @end example
 
-@node @code{open-source} protocol
+@node @code{open-source} protocol,  , @code{capture} protocol, Protocols
 @subsection @code{open-source} protocol
 @cindex open-source protocol
 @cindex protocol, open-source
@@ -7758,7 +7758,7 @@ valid contents: @code{org-protocol-create} and
 @code{org-protocol-create-for-org}.  The latter is of use if you're editing
 an Org file that is part of a publishing project.
 
-@node Refile and copy
+@node Refile and copy, Archiving, Protocols, Capture - Refile - Archive
 @section Refile and copy
 @cindex refiling notes
 @cindex copying notes
@@ -7815,7 +7815,7 @@ setting @code{org-refile-use-cache}.  To make the command see new possible
 targets, you have to clear the cache with this command.
 @end table
 
-@node Archiving
+@node Archiving,  , Refile and copy, Capture - Refile - Archive
 @section Archiving
 @cindex archiving
 
@@ -7836,7 +7836,7 @@ Archive the current entry using the command specified in the variable
 * Internal archiving::          Switch off a tree but keep it in the file
 @end menu
 
-@node Moving subtrees
+@node Moving subtrees, Internal archiving, Archiving, Archiving
 @subsection Moving a tree to the archive file
 @cindex external archiving
 
@@ -7890,7 +7890,7 @@ outline path the archiving time etc.  Configure the variable
 added.
 
 
-@node Internal archiving
+@node Internal archiving,  , Moving subtrees, Archiving
 @subsection Internal archiving
 
 @cindex archive tag
@@ -7954,7 +7954,7 @@ outline.
 @end table
 
 
-@node Agenda views
+@node Agenda views, Markup, Capture - Refile - Archive, Top
 @chapter Agenda views
 @cindex agenda views
 
@@ -8021,7 +8021,7 @@ window configuration is restored when the agenda exits:
 * Agenda column view::          Using column view for collected entries
 @end menu
 
-@node Agenda files
+@node Agenda files, Agenda dispatcher, Agenda views, Agenda views
 @section Agenda files
 @cindex agenda files
 @cindex files for agenda
@@ -8098,7 +8098,7 @@ effect immediately.
 Lift the restriction.
 @end table
 
-@node Agenda dispatcher
+@node Agenda dispatcher, Built-in agenda views, Agenda files, Agenda views
 @section The agenda dispatcher
 @cindex agenda dispatcher
 @cindex dispatching agenda commands
@@ -8161,7 +8161,7 @@ possibility to create extended agenda buffers that contain several
 blocks together, for example the weekly agenda, the global TODO list and
 a number of special tags matches.  @xref{Custom agenda views}.
 
-@node Built-in agenda views
+@node Built-in agenda views, Presentation and sorting, Agenda dispatcher, Agenda views
 @section The built-in agenda views
 
 In this section we describe the built-in views.
@@ -8174,7 +8174,7 @@ In this section we describe the built-in views.
 * Stuck projects::              Find projects you need to review
 @end menu
 
-@node Weekly/daily agenda
+@node Weekly/daily agenda, Global TODO list, Built-in agenda views, Built-in agenda views
 @subsection The weekly/daily agenda
 @cindex agenda
 @cindex weekly agenda
@@ -8333,7 +8333,7 @@ It also reads a @code{APPT_WARNTIME} property which will then override the
 value of @code{appt-message-warning-time} for this appointment.  See the
 docstring for details.
 
-@node Global TODO list
+@node Global TODO list, Matching tags and properties, Weekly/daily agenda, Built-in agenda views
 @subsection The global TODO list
 @cindex global TODO list
 @cindex TODO list, global
@@ -8394,7 +8394,7 @@ and omit the sublevels from the global list.  Configure the variable
 @code{org-agenda-todo-list-sublevels} to get this behavior.
 @end itemize
 
-@node Matching tags and properties
+@node Matching tags and properties, Search view, Global TODO list, Built-in agenda views
 @subsection Matching tags and properties
 @cindex matching, of tags
 @cindex matching, of properties
@@ -8567,7 +8567,7 @@ Select @samp{:work:}-tagged TODO lines that are either @samp{WAITING} or
 @samp{NEXT}.
 @end table
 
-@node Search view
+@node Search view, Stuck projects, Matching tags and properties, Built-in agenda views
 @subsection Search view
 @cindex search view
 @cindex text search
@@ -8597,7 +8597,7 @@ the docstring of the command @code{org-search-view}.
 Note that in addition to the agenda files, this command will also search
 the files listed in @code{org-agenda-text-search-extra-files}.
 
-@node Stuck projects
+@node Stuck projects,  , Search view, Built-in agenda views
 @subsection Stuck projects
 @pindex GTD, Getting Things Done
 
@@ -8645,7 +8645,7 @@ correct customization for this is
 Note that if a project is identified as non-stuck, the subtree of this entry
 will still be searched for stuck projects.
 
-@node Presentation and sorting
+@node Presentation and sorting, Agenda commands, Built-in agenda views, Agenda views
 @section Presentation and sorting
 @cindex presentation, of agenda items
 
@@ -8667,7 +8667,7 @@ associated with the item.
 * Filtering/limiting agenda items::  Dynamically narrow the agenda
 @end menu
 
-@node Categories
+@node Categories, Time-of-day specifications, Presentation and sorting, Presentation and sorting
 @subsection Categories
 
 @cindex category
@@ -8694,7 +8694,7 @@ longer than 10 characters.
 You can set up icons for category by customizing the
 @code{org-agenda-category-icon-alist} variable.
 
-@node Time-of-day specifications
+@node Time-of-day specifications, Sorting agenda items, Categories, Presentation and sorting
 @subsection Time-of-day specifications
 @cindex time-of-day specification
 
@@ -8745,7 +8745,7 @@ The time grid can be turned on and off with the variable
 @code{org-agenda-use-time-grid}, and can be configured with
 @code{org-agenda-time-grid}.
 
-@node Sorting agenda items
+@node Sorting agenda items, Filtering/limiting agenda items, Time-of-day specifications, Presentation and sorting
 @subsection Sorting agenda items
 @cindex sorting, of agenda items
 @cindex priorities, of agenda items
@@ -8779,7 +8779,7 @@ Sorting can be customized using the variable
 @code{org-agenda-sorting-strategy}, and may also include criteria based on
 the estimated effort of an entry (@pxref{Effort estimates}).
 
-@node Filtering/limiting agenda items
+@node Filtering/limiting agenda items,  , Sorting agenda items, Presentation and sorting
 @subsection Filtering/limiting agenda items
 
 Agenda built-in or customized commands are statically defined.  Agenda
@@ -8965,7 +8965,7 @@ rebuilding the agenda:
 This prompts for the type of limit to apply and its value.
 @end table
 
-@node Agenda commands
+@node Agenda commands, Custom agenda views, Presentation and sorting, Agenda views
 @section Commands in the agenda buffer
 @cindex commands, in agenda buffer
 
@@ -9488,7 +9488,7 @@ visit Org files will not be removed.
 @end table
 
 
-@node Custom agenda views
+@node Custom agenda views, Exporting agenda views, Agenda commands, Agenda views
 @section Custom agenda views
 @cindex custom agenda views
 @cindex agenda views, custom
@@ -9504,7 +9504,7 @@ dispatcher (@pxref{Agenda dispatcher}), just like the default commands.
 * Setting options::             Changing the rules
 @end menu
 
-@node Storing searches
+@node Storing searches, Block agenda, Custom agenda views, Custom agenda views
 @subsection Storing searches
 
 The first application of custom searches is the definition of keyboard
@@ -9596,7 +9596,7 @@ Peter, or Kim) as additional tag to match.
 Note that the @code{*-tree} agenda views need to be called from an
 Org buffer as they operate on the current buffer only.
 
-@node Block agenda
+@node Block agenda, Setting options, Storing searches, Custom agenda views
 @subsection Block agenda
 @cindex block agenda
 @cindex agenda, with block views
@@ -9630,7 +9630,7 @@ your agenda for the current week, all TODO items that carry the tag
 @samp{home}, and also all lines tagged with @samp{garden}.  Finally the
 command @kbd{C-c a o} provides a similar view for office tasks.
 
-@node Setting options
+@node Setting options,  , Block agenda, Custom agenda views
 @subsection Setting options for custom commands
 @cindex options, for custom agenda views
 
@@ -9722,7 +9722,7 @@ command key @code{"r"}.  In that case, add this command key like this:
 
 See the docstring of the variable for more information.
 
-@node Exporting agenda views
+@node Exporting agenda views, Agenda column view, Custom agenda views, Agenda views
 @section Exporting agenda views
 @cindex agenda views, exporting
 
@@ -9862,7 +9862,7 @@ processing by other programs.  See @ref{Extracting agenda information}, for
 more information.
 
 
-@node Agenda column view
+@node Agenda column view,  , Exporting agenda views, Agenda views
 @section Using column view in the agenda
 @cindex column view, in agenda
 @cindex agenda, column view
@@ -9928,7 +9928,7 @@ spent ---via @code{CLOCKSUM}---and with the planned total effort for it.
 @end enumerate
 
 
-@node Markup
+@node Markup, Exporting, Agenda views, Top
 @chapter Markup for rich export
 
 When exporting Org mode documents, the exporter tries to reflect the
@@ -9948,7 +9948,7 @@ markup rules used in an Org mode buffer.
 * Embedded @LaTeX{}::           LaTeX can be freely used inside Org documents
 @end menu
 
-@node Paragraphs
+@node Paragraphs, Emphasis and monospace, Markup, Markup
 @section Paragraphs, line breaks, and quoting
 @cindex paragraphs, markup rules
 
@@ -9994,7 +9994,7 @@ but not any simpler
 #+END_CENTER
 @end example
 
-@node Emphasis and monospace
+@node Emphasis and monospace, Horizontal rules, Paragraphs, Markup
 @section Emphasis and monospace
 
 @cindex underlined text, markup rules
@@ -10019,13 +10019,13 @@ can tweak @code{org-emphasis-regexp-components}.  Beware that changing one of
 the above variables will no take effect until you reload Org, for which you
 may need to restart Emacs.
 
-@node Horizontal rules
+@node Horizontal rules, Images and tables, Emphasis and monospace, Markup
 @section Horizontal rules
 @cindex horizontal rules, markup rules
 A line consisting of only dashes, and at least 5 of them, will be exported as
 a horizontal line.
 
-@node Images and tables
+@node Images and tables, Literal examples, Horizontal rules, Markup
 @section Images and Tables
 
 @cindex tables, markup rules
@@ -10073,7 +10073,7 @@ the same caption mechanism can apply to many others (e.g., @LaTeX{}
 equations, source code blocks).  Depending on the export back-end, those may
 or may not be handled.
 
-@node Literal examples
+@node Literal examples, Special symbols, Images and tables, Markup
 @section Literal examples
 @cindex literal examples, markup rules
 @cindex code line references, markup rules
@@ -10118,8 +10118,8 @@ for details.}.  This is done with the @samp{src} block, where you also need
 to specify the name of the major mode that should be used to fontify the
 example@footnote{Code in @samp{src} blocks may also be evaluated either
 interactively or on export.  @xref{Working with source code}, for more
-information on evaluating code blocks.}, see @ref{Easy templates} for
-shortcuts to easily insert code blocks.
+information on evaluating code blocks.}, see @ref{Inserting structure
+templates} for shortcuts to easily insert code blocks.
 @cindex #+BEGIN_SRC
 
 @example
@@ -10186,8 +10186,7 @@ HTML export also allows examples to be published as text areas (@pxref{Text
 areas in HTML export}).
 
 Because the @code{#+BEGIN_...} and @code{#+END_...} patterns need to be added
-so often, shortcuts are provided using the Easy templates facility
-(@pxref{Easy templates}).
+so often, a shortcut is provided (@pxref{Inserting structure templates}).
 
 @table @kbd
 @kindex C-c '
@@ -10213,7 +10212,7 @@ formatting like @samp{(ref:label)} at the end of the current line.  Then the
 label is stored as a link @samp{(label)}, for retrieval with @kbd{C-c C-l}.
 @end table
 
-@node Special symbols
+@node Special symbols, Subscripts and superscripts, Literal examples, Markup
 @section Special symbols
 @cindex Org entities
 @cindex math symbols
@@ -10274,7 +10273,7 @@ way@footnote{This behaviour can be disabled with @code{-} export setting
 combinations: @samp{\-} is treated as a shy hyphen, @samp{--} and @samp{---}
 are converted into dashes, and @samp{...} becomes a compact set of dots.
 
-@node Subscripts and superscripts
+@node Subscripts and superscripts, Embedded @LaTeX{}, Special symbols, Markup
 @section Subscripts and superscripts
 @cindex subscript
 @cindex superscript
@@ -10303,7 +10302,7 @@ In addition to showing entities as UTF-8 characters, this command will also
 format sub- and superscripts in a WYSIWYM way.
 @end table
 
-@node Embedded @LaTeX{}
+@node Embedded @LaTeX{},  , Subscripts and superscripts, Markup
 @section Embedded @LaTeX{}
 @cindex @TeX{} interpretation
 @cindex @LaTeX{} interpretation
@@ -10324,7 +10323,7 @@ readily processed to produce pretty output for a number of export back-ends.
 * CDLaTeX mode::                Speed up entering of formulas
 @end menu
 
-@node @LaTeX{} fragments
+@node @LaTeX{} fragments, Previewing @LaTeX{} fragments, Embedded @LaTeX{}, Embedded @LaTeX{}
 @subsection @LaTeX{} fragments
 @cindex @LaTeX{} fragments
 
@@ -10388,7 +10387,7 @@ lines:
 #+OPTIONS: tex:verbatim   @r{Verbatim export, for jsMath or so}
 @end example
 
-@node Previewing @LaTeX{} fragments
+@node Previewing @LaTeX{} fragments, CDLaTeX mode, @LaTeX{} fragments, Embedded @LaTeX{}
 @subsection Previewing @LaTeX{} fragments
 @cindex @LaTeX{} fragments, preview
 
@@ -10436,7 +10435,7 @@ To disable it, simply use
 #+STARTUP: nolatexpreview
 @end example
 
-@node CDLaTeX mode
+@node CDLaTeX mode,  , Previewing @LaTeX{} fragments, Embedded @LaTeX{}
 @subsection Using CD@LaTeX{} to enter math
 @cindex CD@LaTeX{}
 
@@ -10497,7 +10496,7 @@ modification will work only inside @LaTeX{} fragments; outside the quote
 is normal.
 @end itemize
 
-@node Exporting
+@node Exporting, Publishing, Markup, Top
 @chapter Exporting
 @cindex exporting
 
@@ -10564,7 +10563,7 @@ library in the Emacs init file like this:
 * Export in foreign buffers::   Author tables and lists in Org syntax
 @end menu
 
-@node The export dispatcher
+@node The export dispatcher, Export settings, Exporting, Exporting
 @section The export dispatcher
 @vindex org-export-dispatch-use-expert-ui
 @cindex Export, dispatcher
@@ -10631,7 +10630,7 @@ Toggle visible-only export.  Useful for exporting only visible parts of an
 Org document by adjusting outline visibility settings.
 @end table
 
-@node Export settings
+@node Export settings, Table of contents, The export dispatcher, Exporting
 @section Export settings
 @cindex Export, settings
 
@@ -10903,7 +10902,7 @@ can become buffer-local during export by using the BIND keyword.  Its syntax
 is @samp{#+BIND: variable value}.  This is particularly useful for in-buffer
 settings that cannot be changed using keywords.
 
-@node Table of contents
+@node Table of contents, Include files, Export settings, Exporting
 @section Table of contents
 @cindex table of contents
 @cindex list of tables
@@ -10980,7 +10979,7 @@ Normally Org uses the headline for its entry in the table of contents.  But
 with @code{ALT_TITLE} property, a different entry can be specified for the
 table of contents.
 
-@node Include files
+@node Include files, Macro replacement, Table of contents, Exporting
 @section Include files
 @cindex include files, during export
 Include other files during export.  For example, to include your @file{.emacs}
@@ -11054,7 +11053,7 @@ element.  Some examples:
 Visit the include file at point.
 @end table
 
-@node Macro replacement
+@node Macro replacement, Comment lines, Include files, Exporting
 @section Macro replacement
 @cindex macro replacement, during export
 @cindex #+MACRO
@@ -11140,7 +11139,7 @@ The surrounding brackets can be made invisible by setting
 
 Org expands macros at the very beginning of the export process.
 
-@node Comment lines
+@node Comment lines, ASCII/Latin-1/UTF-8 export, Macro replacement, Exporting
 @section Comment lines
 @cindex exporting, not
 
@@ -11167,7 +11166,7 @@ comment status of a headline.
 Toggle the @samp{COMMENT} keyword at the beginning of an entry.
 @end table
 
-@node ASCII/Latin-1/UTF-8 export
+@node ASCII/Latin-1/UTF-8 export, Beamer export, Comment lines, Exporting
 @section ASCII/Latin-1/UTF-8 export
 @cindex ASCII export
 @cindex Latin-1 export
@@ -11267,7 +11266,7 @@ It's just a jump to the left...
 #+END_JUSTIFYRIGHT
 @end example
 
-@node Beamer export
+@node Beamer export, HTML export, ASCII/Latin-1/UTF-8 export, Exporting
 @section Beamer export
 @cindex Beamer export
 
@@ -11285,7 +11284,7 @@ popular display formats.
 * A Beamer example::            A complete presentation.
 @end menu
 
-@node Beamer export commands
+@node Beamer export commands, Beamer specific export settings, Beamer export, Beamer export
 @subsection Beamer export commands
 
 @table @kbd
@@ -11301,7 +11300,7 @@ Export as @LaTeX{} file, convert it to PDF format, and then open the PDF
 file.
 @end table
 
-@node Beamer specific export settings
+@node Beamer specific export settings, Sectioning Frames and Blocks in Beamer, Beamer export commands, Beamer export
 @subsection Beamer specific export settings
 
 Beamer export back-end has several additional keywords for customizing Beamer
@@ -11360,7 +11359,7 @@ metadata.  Use @code{org-latex-title-command} to configure typesetting of
 subtitle as part of front matter.
 @end table
 
-@node Sectioning Frames and Blocks in Beamer
+@node Sectioning Frames and Blocks in Beamer, Beamer specific syntax, Beamer specific export settings, Beamer export
 @subsection Sectioning, Frames and Blocks in Beamer
 
 Org transforms heading levels into Beamer's sectioning elements, frames and
@@ -11429,7 +11428,7 @@ Beamer export automatically handles @LaTeX{} column separations for
 contiguous headlines.  To manually adjust them for any unique configurations
 needs, use the @code{BEAMER_ENV} property.
 
-@node Beamer specific syntax
+@node Beamer specific syntax, Editing support, Sectioning Frames and Blocks in Beamer, Beamer export
 @subsection Beamer specific syntax
 Since Org's Beamer export back-end is an extension of the @LaTeX{} back-end,
 it recognizes other @LaTeX{} specific syntax---for example, @samp{#+LATEX:}
@@ -11493,7 +11492,7 @@ Let $G$ be a finite group, and let $H$ be
 a subgroup of $G$.  Then the order of $H$ divides the order of $G$.
 @end example
 
-@node Editing support
+@node Editing support, A Beamer example, Beamer specific syntax, Beamer export
 @subsection Editing support
 
 
@@ -11510,7 +11509,7 @@ The @code{org-beamer-mode} provides this key for quicker selections in Beamer
 normal environments, and for selecting the @code{BEAMER_COL} property.
 @end table
 
-@node A Beamer example
+@node A Beamer example,  , Editing support, Beamer export
 @subsection A Beamer example
 
 Here is an example of an Org document ready for Beamer export.
@@ -11549,7 +11548,7 @@ Here is an example of an Org document ready for Beamer export.
     Please test this stuff!
 @end example
 
-@node HTML export
+@node HTML export, @LaTeX{} export, Beamer export, Exporting
 @section HTML export
 @cindex HTML export
 
@@ -11572,7 +11571,7 @@ with XHTML 1.0 strict standard.
 @end menu
 
 
-@node HTML Export commands
+@node HTML Export commands, HTML Specific export settings, HTML export, HTML export
 @subsection HTML export commands
 
 @table @kbd
@@ -11585,7 +11584,7 @@ h o} Exports to HTML and opens it in a web browser.
 Exports to a temporary buffer.  Does not create a file.
 @end table
 
-@node HTML Specific export settings
+@node HTML Specific export settings, HTML doctypes, HTML Export commands, HTML export
 @subsection HTML Specific export settings
 HTML export has a number of keywords, similar to the general options settings
 described in @ref{Export settings}.
@@ -11659,7 +11658,7 @@ The document's subtitle.  HTML exporter formats subtitle if document type is
 Some of these keywords are explained in more detail in the following sections
 of the manual.
 
-@node HTML doctypes
+@node HTML doctypes, HTML preamble and postamble, HTML Specific export settings, HTML export
 @subsection HTML doctypes
 
 Org can export to various (X)HTML flavors.
@@ -11747,7 +11746,7 @@ Special blocks cannot have headlines.  For the HTML exporter to wrap the
 headline and its contents in @samp{<section>} or @samp{<article>} tags, set
 the @code{HTML_CONTAINER} property for the headline.
 
-@node HTML preamble and postamble
+@node HTML preamble and postamble, Quoting HTML tags, HTML doctypes, HTML export
 @subsection HTML preamble and postamble
 @vindex org-html-preamble
 @vindex org-html-postamble
@@ -11775,7 +11774,7 @@ to insert the postamble in the format specified in the
 @code{org-html-postamble-format} variable.  The HTML exporter will not insert
 a postamble if @code{org-html-postamble} is set to @code{nil}.
 
-@node Quoting HTML tags
+@node Quoting HTML tags, Links in HTML export, HTML preamble and postamble, HTML export
 @subsection Quoting HTML tags
 
 The HTML export back-end transforms @samp{<} and @samp{>} to @samp{&lt;} and
@@ -11801,7 +11800,7 @@ All lines between these markers are exported literally
 @end example
 
 
-@node Links in HTML export
+@node Links in HTML export, Tables in HTML export, Quoting HTML tags, HTML export
 @subsection Links in HTML export
 
 @cindex links, in HTML export
@@ -11835,7 +11834,7 @@ to @code{<a>} or @code{<img>} tags.  This example shows changing the link's
 [[http://orgmode.org]]
 @end example
 
-@node Tables in HTML export
+@node Tables in HTML export, Images in HTML export, Links in HTML export, HTML export
 @subsection Tables in HTML export
 @cindex tables, in HTML
 @vindex org-html-table-default-attributes
@@ -11887,7 +11886,7 @@ Opening and ending tags for table rows.
 Non-@code{nil} formats column one in tables with header tags.
 @end table
 
-@node Images in HTML export
+@node Images in HTML export, Math formatting in HTML export, Tables in HTML export, HTML export
 @subsection Images in HTML export
 
 @cindex images, inline in HTML
@@ -11931,7 +11930,7 @@ standards.
 The HTML export back-end copies the @code{http} links from the Org file as
 is.
 
-@node Math formatting in HTML export
+@node Math formatting in HTML export, Text areas in HTML export, Images in HTML export, HTML export
 @subsection Math formatting in HTML export
 @cindex MathJax
 @cindex dvipng
@@ -11976,7 +11975,7 @@ or:
 #+OPTIONS: tex:imagemagick
 @end example
 
-@node Text areas in HTML export
+@node Text areas in HTML export, CSS support, Math formatting in HTML export, HTML export
 @subsection Text areas in HTML export
 
 @cindex text areas, in HTML
@@ -12005,7 +12004,7 @@ and height just enough to fit the content.  Override these defaults with
 @end example
 
 
-@node CSS support
+@node CSS support, JavaScript support, Text areas in HTML export, HTML export
 @subsection CSS support
 @cindex CSS, for HTML export
 @cindex HTML export, CSS
@@ -12096,7 +12095,7 @@ simpler ways of customizing as described above.
 @c FIXME: More about header and footer styles
 @c FIXME: Talk about links and targets.
 
-@node JavaScript support
+@node JavaScript support,  , CSS support, HTML export
 @subsection JavaScript supported display of web pages
 
 @cindex Rose, Sebastian
@@ -12158,7 +12157,7 @@ You can choose default values for these options by customizing the variable
 @code{org-html-infojs-options}.  If you want the script to always apply to
 your pages, configure the variable @code{org-html-use-infojs}.
 
-@node @LaTeX{} export
+@node @LaTeX{} export, Markdown export, HTML export, Exporting
 @section @LaTeX{} export
 @cindex @LaTeX{} export
 @cindex PDF export
@@ -12193,7 +12192,7 @@ blank lines to tell apart syntactical elements, such as paragraphs.
 * Horizontal rules in @LaTeX{} export::  Attributes specific to horizontal rules.
 @end menu
 
-@node @LaTeX{} export commands
+@node @LaTeX{} export commands, @LaTeX{} specific export settings, @LaTeX{} export, @LaTeX{} export
 @subsection @LaTeX{} export commands
 
 @table @kbd
@@ -12226,7 +12225,7 @@ compilers for different files.  However, ``smart'' @LaTeX{} compilation
 systems, such as @samp{latexmk}, can select the correct bibliography
 compiler.}.
 
-@node @LaTeX{} specific export settings
+@node @LaTeX{} specific export settings, @LaTeX{} header and sectioning, @LaTeX{} export commands, @LaTeX{} export
 @subsection @LaTeX{} specific export settings
 
 The @LaTeX{} export back-end has several additional keywords for customizing
@@ -12302,7 +12301,7 @@ document's front matter.
 
 The following sections have further details.
 
-@node @LaTeX{} header and sectioning
+@node @LaTeX{} header and sectioning, Quoting @LaTeX{} code, @LaTeX{} specific export settings, @LaTeX{} export
 @subsection @LaTeX{} header and sectioning structure
 @cindex @LaTeX{} class
 @cindex @LaTeX{} sectioning structure
@@ -12365,7 +12364,7 @@ A sample Org file with the above headers:
   some more text
 @end example
 
-@node Quoting @LaTeX{} code
+@node Quoting @LaTeX{} code, Tables in @LaTeX{} export, @LaTeX{} header and sectioning, @LaTeX{} export
 @subsection Quoting @LaTeX{} code
 
 The @LaTeX{} export back-end can insert any arbitrary @LaTeX{} code,
@@ -12393,7 +12392,7 @@ any arbitrary LaTeX code
 #+END_EXPORT
 @end example
 
-@node Tables in @LaTeX{} export
+@node Tables in @LaTeX{} export, Images in @LaTeX{} export, Quoting @LaTeX{} code, @LaTeX{} export
 @subsection Tables in @LaTeX{} export
 @cindex tables, in @LaTeX{} export
 @cindex #+ATTR_LATEX, in tables
@@ -12496,7 +12495,7 @@ Set the caption with the @LaTeX{} command
 @end example
 
 
-@node Images in @LaTeX{} export
+@node Images in @LaTeX{} export, Plain lists in @LaTeX{} export, Tables in @LaTeX{} export, @LaTeX{} export
 @subsection Images in @LaTeX{} export
 @cindex images, inline in @LaTeX{}
 @cindex inlining images in @LaTeX{}
@@ -12567,7 +12566,7 @@ centering globally, set @code{org-latex-images-centered} to @code{t}.
 Set the @code{:comment-include} attribute to non-@code{nil} value for the
 @LaTeX{} export back-end to comment out the @code{\includegraphics} macro.
 
-@node Plain lists in @LaTeX{} export
+@node Plain lists in @LaTeX{} export, Source blocks in @LaTeX{} export, Images in @LaTeX{} export, @LaTeX{} export
 @subsection Plain lists in @LaTeX{} export
 @cindex plain lists, in @LaTeX{} export
 @cindex #+ATTR_LATEX, in plain lists
@@ -12601,7 +12600,7 @@ four:
         - Five
 @end example
 
-@node Source blocks in @LaTeX{} export
+@node Source blocks in @LaTeX{} export, Example blocks in @LaTeX{} export, Plain lists in @LaTeX{} export, @LaTeX{} export
 @subsection Source blocks in @LaTeX{} export
 @cindex source blocks, in @LaTeX{} export
 @cindex #+ATTR_LATEX, in source blocks
@@ -12647,7 +12646,7 @@ To apply similar configuration options for all source blocks in a file, use
 the @code{org-latex-listings-options} and @code{org-latex-minted-options}
 variables.
 
-@node Example blocks in @LaTeX{} export
+@node Example blocks in @LaTeX{} export, Special blocks in @LaTeX{} export, Source blocks in @LaTeX{} export, @LaTeX{} export
 @subsection Example blocks in @LaTeX{} export
 @cindex example blocks, in @LaTeX{} export
 @cindex verbatim blocks, in @LaTeX{} export
@@ -12666,7 +12665,7 @@ This sentence is false.
 #+END_EXAMPLE
 @end example
 
-@node Special blocks in @LaTeX{} export
+@node Special blocks in @LaTeX{} export, Horizontal rules in @LaTeX{} export, Example blocks in @LaTeX{} export, @LaTeX{} export
 @subsection Special blocks in @LaTeX{} export
 @cindex special blocks, in @LaTeX{} export
 @cindex abstract, in @LaTeX{} export
@@ -12716,7 +12715,7 @@ example:
 #+END_proof
 @end example
 
-@node Horizontal rules in @LaTeX{} export
+@node Horizontal rules in @LaTeX{} export,  , Special blocks in @LaTeX{} export, @LaTeX{} export
 @subsection Horizontal rules in @LaTeX{} export
 @cindex horizontal rules, in @LaTeX{} export
 @cindex #+ATTR_LATEX, in horizontal rules
@@ -12729,7 +12728,7 @@ The @LaTeX{} export back-end converts horizontal rules by the specified
 -----
 @end example
 
-@node Markdown export
+@node Markdown export, OpenDocument Text export, @LaTeX{} export, Exporting
 @section Markdown export
 @cindex Markdown export
 
@@ -12763,7 +12762,7 @@ level before the absolute limit (@pxref{Export settings}).
 
 @c begin opendocument
 
-@node OpenDocument Text export
+@node OpenDocument Text export, Org export, Markdown export, Exporting
 @section OpenDocument Text export
 @cindex ODT
 @cindex OpenDocument
@@ -12791,14 +12790,14 @@ is compatible with LibreOffice 3.4.
 * Advanced topics in ODT export::  For power users.
 @end menu
 
-@node Pre-requisites for ODT export
+@node Pre-requisites for ODT export, ODT export commands, OpenDocument Text export, OpenDocument Text export
 @subsection Pre-requisites for ODT export
 @cindex zip
 The ODT export back-end relies on the @file{zip} program to create the final
 compressed ODT output.  Check if @file{zip} is locally available and
 executable.  Without @file{zip}, export cannot finish.
 
-@node ODT export commands
+@node ODT export commands, ODT specific export settings, Pre-requisites for ODT export, OpenDocument Text export
 @subsection ODT export commands
 @anchor{x-export-to-odt}
 @cindex region, active
@@ -12835,7 +12834,7 @@ file instead.  @xref{x-export-to-other-formats, , Automatically exporting to
 other formats}.
 @end table
 
-@node ODT specific export settings
+@node ODT specific export settings, Extending ODT export, ODT export commands, OpenDocument Text export
 @subsection ODT specific export settings
 The ODT export back-end has several additional keywords for customizing ODT
 output.  Setting these keywords works similar to the general options
@@ -12866,7 +12865,7 @@ The ODT export back-end uses the @code{org-odt-styles-file} by default.  See
 The document subtitle.
 @end table
 
-@node Extending ODT export
+@node Extending ODT export, Applying custom styles, ODT specific export settings, OpenDocument Text export
 @subsection Extending ODT export
 
 The ODT export back-end can produce documents in other formats besides ODT
@@ -12909,7 +12908,7 @@ Convert an existing document from one format to another.  With a prefix
 argument, opens the newly produced file.
 @end table
 
-@node Applying custom styles
+@node Applying custom styles, Links in ODT export, Extending ODT export, OpenDocument Text export
 @subsection Applying custom styles
 @cindex styles, custom
 @cindex template, custom
@@ -12965,7 +12964,7 @@ The ODT export back-end relies on many templates and style names.  Using
 third-party styles and templates can lead to mismatches.  Templates derived
 from built in ODT templates and styles seem to have fewer problems.
 
-@node Links in ODT export
+@node Links in ODT export, Tables in ODT export, Applying custom styles, OpenDocument Text export
 @subsection Links in ODT export
 @cindex links, in ODT export
 
@@ -12979,7 +12978,7 @@ A @samp{\ref@{label@}}-style reference to an image, table etc.@: is replaced
 with a cross-reference and sequence number of the labeled entity.
 @xref{Labels and captions in ODT export}.
 
-@node Tables in ODT export
+@node Tables in ODT export, Images in ODT export, Links in ODT export, OpenDocument Text export
 @subsection Tables in ODT export
 @cindex tables, in ODT export
 
@@ -13024,7 +13023,7 @@ For even more customization, create custom table styles and associate them
 with a table using the @code{#+ATTR_ODT} line.  @xref{Customizing tables in
 ODT export}.
 
-@node Images in ODT export
+@node Images in ODT export, Math formatting in ODT export, Tables in ODT export, OpenDocument Text export
 @subsection Images in ODT export
 @cindex images, embedding in ODT
 @cindex embedding images in ODT
@@ -13121,7 +13120,7 @@ To create an image that is anchored to a page:
 [[./img.png]]
 @end example
 
-@node Math formatting in ODT export
+@node Math formatting in ODT export, Labels and captions in ODT export, Images in ODT export, OpenDocument Text export
 @subsection Math formatting in ODT export
 
 The ODT export back-end has special support built-in for handling math.
@@ -13131,7 +13130,7 @@ The ODT export back-end has special support built-in for handling math.
 * Working with MathML or OpenDocument formula files::  Embedding in native format.
 @end menu
 
-@node Working with @LaTeX{} math snippets
+@node Working with @LaTeX{} math snippets, Working with MathML or OpenDocument formula files, Math formatting in ODT export, Math formatting in ODT export
 @subsubheading Working with @LaTeX{} math snippets
 
 @LaTeX{} math snippets (@pxref{@LaTeX{} fragments}) can be embedded in an ODT
@@ -13214,7 +13213,7 @@ requires @file{dvipng} program, @file{dvisvgm} or @file{imagemagick}
 programs.
 @end enumerate
 
-@node Working with MathML or OpenDocument formula files
+@node Working with MathML or OpenDocument formula files,  , Working with @LaTeX{} math snippets, Math formatting in ODT export
 @subsubheading Working with MathML or OpenDocument formula files
 
 When embedding @LaTeX{} math snippets in ODT documents is not reliable, there
@@ -13232,7 +13231,7 @@ or
 [[./equation.odf]]
 @end example
 
-@node Labels and captions in ODT export
+@node Labels and captions in ODT export, Literal examples in ODT export, Math formatting in ODT export, OpenDocument Text export
 @subsection Labels and captions in ODT export
 
 ODT format handles labeling and captioning of objects based on their
@@ -13270,7 +13269,7 @@ With the above modification, the previous example changes to:
 Illustration 2: Bell curve
 @end example
 
-@node Literal examples in ODT export
+@node Literal examples in ODT export, Advanced topics in ODT export, Labels and captions in ODT export, OpenDocument Text export
 @subsection Literal examples in ODT export
 
 The ODT export back-end supports literal examples (@pxref{Literal examples})
@@ -13288,7 +13287,7 @@ For custom fontification styles, customize the
 To turn off fontification of literal examples, customize the
 @code{org-odt-fontify-srcblocks} option.
 
-@node Advanced topics in ODT export
+@node Advanced topics in ODT export,  , Literal examples in ODT export, OpenDocument Text export
 @subsection Advanced topics in ODT export
 
 The ODT export back-end has extensive features useful for power users and
@@ -13302,7 +13301,7 @@ frequent uses of ODT formats.
 * Validating OpenDocument XML::  Debugging corrupted OpenDocument files.
 @end menu
 
-@node Configuring a document converter
+@node Configuring a document converter, Working with OpenDocument style files, Advanced topics in ODT export, Advanced topics in ODT export
 @subsubheading Configuring a document converter
 @cindex convert
 @cindex doc, docx, rtf
@@ -13335,7 +13334,7 @@ Select the newly added converter as the preferred one by customizing the
 option @code{org-odt-convert-process}.
 @end enumerate
 
-@node Working with OpenDocument style files
+@node Working with OpenDocument style files, Creating one-off styles, Configuring a document converter, Advanced topics in ODT export
 @subsubheading Working with OpenDocument style files
 @cindex styles, custom
 @cindex template, custom
@@ -13438,7 +13437,7 @@ Use this variable to specify the blank @file{content.xml} that will be used
 in the final output.
 @end itemize
 
-@node Creating one-off styles
+@node Creating one-off styles, Customizing tables in ODT export, Working with OpenDocument style files, Advanced topics in ODT export
 @subsubheading Creating one-off styles
 
 The ODT export back-end can read embedded raw OpenDocument XML from the Org
@@ -13504,7 +13503,7 @@ This paragraph is specially formatted and uses bold text.
 
 @end enumerate
 
-@node Customizing tables in ODT export
+@node Customizing tables in ODT export, Validating OpenDocument XML, Creating one-off styles, Advanced topics in ODT export
 @subsubheading Customizing tables in ODT export
 @cindex tables, in ODT export
 
@@ -13666,7 +13665,7 @@ the @code{ATTR_ODT} line as shown below.
 @end example
 @end enumerate
 
-@node Validating OpenDocument XML
+@node Validating OpenDocument XML,  , Customizing tables in ODT export, Advanced topics in ODT export
 @subsubheading Validating OpenDocument XML
 
 Sometimes ODT format files may not open due to @file{.odt} file corruption.
@@ -13685,7 +13684,7 @@ back-end takes care of updating the @code{rng-schema-locating-files}.
 
 @c end opendocument
 
-@node Org export
+@node Org export, Texinfo export, OpenDocument Text export, Exporting
 @section Org export
 @cindex Org export
 
@@ -13706,7 +13705,7 @@ Export to a temporary buffer.  Does not create a file.
 Export to an Org file, then open it.
 @end table
 
-@node Texinfo export
+@node Texinfo export, iCalendar export, Org export, Exporting
 @section Texinfo export
 @cindex Texinfo export
 
@@ -13718,7 +13717,7 @@ can compile to Info format.
 * Texinfo specific export settings::  Setting the environment.
 * Texinfo file header::         Generating the header.
 * Texinfo title and copyright page::  Creating preamble pages.
-* Info directory file::     Installing a manual in Info file hierarchy.
+* Info directory file::         Installing a manual in Info file hierarchy.
 * Headings and sectioning structure::  Building document structure.
 * Indices::                     Creating indices.
 * Quoting Texinfo code::        Incorporating literal Texinfo code.
@@ -13729,7 +13728,7 @@ can compile to Info format.
 * A Texinfo example::           Processing Org to Texinfo.
 @end menu
 
-@node Texinfo export commands
+@node Texinfo export commands, Texinfo specific export settings, Texinfo export, Texinfo export
 @subsection Texinfo export commands
 
 @vindex org-texinfo-info-process
@@ -13743,7 +13742,7 @@ generate other formats, such as DocBook, customize the
 @code{org-texinfo-info-process} variable.
 @end table
 
-@node Texinfo specific export settings
+@node Texinfo specific export settings, Texinfo file header, Texinfo export commands, Texinfo export
 @subsection Texinfo specific export settings
 The Texinfo export back-end has several additional keywords for customizing
 Texinfo output.  Setting these keywords works similar to the general options
@@ -13794,7 +13793,7 @@ The directory description of the document.
 The printed title of the document.
 @end table
 
-@node Texinfo file header
+@node Texinfo file header, Texinfo title and copyright page, Texinfo specific export settings, Texinfo export
 @subsection Texinfo file header
 
 @cindex #+TEXINFO_FILENAME
@@ -13817,7 +13816,7 @@ Instead of repeatedly installing the same set of commands, define a class in
 @code{org-texinfo-classes} once, and then activate it in the document by
 setting the @code{#+TEXINFO_CLASS} keyword to that class.
 
-@node Texinfo title and copyright page
+@node Texinfo title and copyright page, Info directory file, Texinfo file header, Texinfo export
 @subsection Texinfo title and copyright page
 
 @cindex #+TEXINFO_PRINTED_TITLE
@@ -13856,7 +13855,7 @@ Copyright information is printed on the back of the title page.
   Copyright \copy 2016 Free Software Foundation, Inc.
 @end example
 
-@node Info directory file
+@node Info directory file, Headings and sectioning structure, Texinfo title and copyright page, Texinfo export
 @subsection Info directory file
 @cindex @samp{dir} file, in Texinfo export
 @cindex Texinfo export, @samp{dir} file
@@ -13882,7 +13881,7 @@ Here is an example that writes to the Info directory file:
 #+TEXINFO_DIR_DESC: Outline-based notes management and organizer
 @end example
 
-@node Headings and sectioning structure
+@node Headings and sectioning structure, Indices, Info directory file, Texinfo export
 @subsection Headings and sectioning structure
 
 @vindex org-texinfo-classes
@@ -13930,7 +13929,7 @@ node in which a reader enters an Info manual.  As such, it is expected not to
 appear in printed output generated from the @file{.texi} file.  @inforef{The
 Top Node,,texinfo}, for more information.
 
-@node Indices
+@node Indices, Quoting Texinfo code, Headings and sectioning structure, Texinfo export
 @subsection Indices
 
 @cindex #+CINDEX
@@ -13976,7 +13975,7 @@ inserts the index after its contents.
   :END:
 @end example
 
-@node Quoting Texinfo code
+@node Quoting Texinfo code, Plain lists in Texinfo export, Indices, Texinfo export
 @subsection Quoting Texinfo code
 
 Use any of the following three methods to insert or escape raw Texinfo code:
@@ -13995,7 +13994,7 @@ This paragraph is preceded by...
 #+END_EXPORT
 @end example
 
-@node Plain lists in Texinfo export
+@node Plain lists in Texinfo export, Tables in Texinfo export, Quoting Texinfo code, Texinfo export
 @subsection Plain lists in Texinfo export
 @cindex #+ATTR_TEXINFO, in plain lists
 @cindex Two-column tables, in Texinfo export
@@ -14039,7 +14038,7 @@ This is the common text for variables foo and bar.
 @@end table
 @end example
 
-@node Tables in Texinfo export
+@node Tables in Texinfo export, Images in Texinfo export, Plain lists in Texinfo export, Texinfo export
 @subsection Tables in Texinfo export
 @cindex #+ATTR_TEXINFO, in tables
 
@@ -14052,7 +14051,7 @@ length, use the @code{:columns} attribute.  See example below.
 | a cell | another cell |
 @end example
 
-@node Images in Texinfo export
+@node Images in Texinfo export, Special blocks in Texinfo export, Tables in Texinfo export, Texinfo export
 @subsection Images in Texinfo export
 @cindex #+ATTR_TEXINFO, in images
 
@@ -14067,7 +14066,7 @@ the text using Texinfo code, as shown in the example:
 [[ridt.pdf]]
 @end example
 
-@node Special blocks in Texinfo export
+@node Special blocks in Texinfo export, A Texinfo example, Images in Texinfo export, Texinfo export
 @subsection Special blocks
 @cindex #+ATTR_TEXINFO, in special blocks
 
@@ -14091,7 +14090,7 @@ A somewhat obsessive function.
 @@end defun
 @end example
 
-@node A Texinfo example
+@node A Texinfo example,  , Special blocks in Texinfo export, Texinfo export
 @subsection A Texinfo example
 
 Here is a more detailed example Org file.  See @ref{GNU Sample
@@ -14163,7 +14162,7 @@ This manual is for GNU Sample (version @{@{@{version@}@}@},
   :END:
 @end example
 
-@node iCalendar export
+@node iCalendar export, Other built-in back-ends, Texinfo export, Exporting
 @section iCalendar export
 @cindex iCalendar export
 
@@ -14246,7 +14245,7 @@ Exporting to iCalendar format depends in large part on the capabilities of
 the destination application.  Some are more lenient than others.  Consult the
 Org mode FAQ for advice on specific applications.
 
-@node Other built-in back-ends
+@node Other built-in back-ends, Advanced configuration, iCalendar export, Exporting
 @section Other built-in back-ends
 @cindex export back-ends, built-in
 @vindex org-export-backends
@@ -14265,7 +14264,7 @@ dispatcher}).
 Follow the comment section of such files, for example, @file{ox-man.el}, for
 usage and configuration details.
 
-@node Advanced configuration
+@node Advanced configuration, Export in foreign buffers, Other built-in back-ends, Exporting
 @section Advanced configuration
 
 @subheading Hooks
@@ -14463,7 +14462,7 @@ To use the newly defined back-end, call the following from an Org buffer:
 Further steps to consider would be an interactive function, self-installing
 an item in the export dispatcher menu, and other user-friendly improvements.
 
-@node Export in foreign buffers
+@node Export in foreign buffers,  , Advanced configuration, Exporting
 @section Export in foreign buffers
 
 The export back-ends in Org often include commands to convert selected
@@ -14488,7 +14487,7 @@ commands to create a list, select it, and covert it to HTML with @code{M-x
 org-html-convert-region-to-html RET}.
 
 
-@node Publishing
+@node Publishing, Working with source code, Exporting, Top
 @chapter Publishing
 @cindex publishing
 
@@ -14510,7 +14509,7 @@ Publishing has been contributed to Org by David O'Toole.
 * Triggering publication::      Publication commands
 @end menu
 
-@node Configuration
+@node Configuration, Uploading files, Publishing, Publishing
 @section Configuration
 
 Publishing needs significant configuration to specify files, destination
@@ -14527,7 +14526,7 @@ and many other properties of a project.
 * Generating an index::         An index that reaches across pages
 @end menu
 
-@node Project alist
+@node Project alist, Sources and destinations, Configuration, Configuration
 @subsection The variable @code{org-publish-project-alist}
 @cindex org-publish-project-alist
 @cindex projects, for publishing
@@ -14554,7 +14553,7 @@ together files requiring different publishing options.  When you publish such
 a ``meta-project'', all the components will also be published, in the
 sequence given.
 
-@node Sources and destinations
+@node Sources and destinations, Selecting files, Project alist, Configuration
 @subsection Sources and destinations for files
 @cindex directories, for publishing
 
@@ -14583,7 +14582,7 @@ list.
 @end multitable
 @noindent
 
-@node Selecting files
+@node Selecting files, Publishing action, Sources and destinations, Configuration
 @subsection Selecting files
 @cindex files, selecting for publishing
 
@@ -14609,7 +14608,7 @@ and @code{:exclude}.
 @tab non-@code{nil} means, check base-directory recursively for files to publish.
 @end multitable
 
-@node Publishing action
+@node Publishing action, Publishing options, Selecting files, Configuration
 @subsection Publishing action
 @cindex action, for publishing
 
@@ -14648,7 +14647,7 @@ and the path to the publishing directory of the output file.  It should take
 the specified file, make the necessary transformation (if any) and place the
 result into the destination folder.
 
-@node Publishing options
+@node Publishing options, Publishing links, Publishing action, Configuration
 @subsection Options for the exporters
 @cindex options, for publishing
 
@@ -14877,7 +14876,7 @@ however, override everything.
 @item @code{:texinfo-text-markup-alist}          @tab @code{org-texinfo-text-markup-alist}
 @end multitable
 
-@node Publishing links
+@node Publishing links, Sitemap, Publishing options, Configuration
 @subsection Links between published files
 @cindex links, publishing
 
@@ -14906,7 +14905,7 @@ all point to a dedicated anchor in @file{foo.html}.
 [[file:foo.org::target]]
 @end example
 
-@node Sitemap
+@node Sitemap, Generating an index, Publishing links, Configuration
 @subsection Generating a sitemap
 @cindex sitemap, of published pages
 
@@ -14968,7 +14967,7 @@ a sitemap entry's date is to be formatted.  This property bypasses
 
 @end multitable
 
-@node Generating an index
+@node Generating an index,  , Sitemap, Configuration
 @subsection Generating an index
 @cindex index, in a publishing project
 
@@ -14995,7 +14994,7 @@ contains an exclamation mark will create a sub item.
 #+INDEX: Application!CV
 @end example
 
-@node Uploading files
+@node Uploading files, Sample configuration, Configuration, Publishing
 @section Uploading files
 @cindex rsync
 @cindex unison
@@ -15028,7 +15027,7 @@ benefit of re-including any changed external files such as source example
 files you might include with @code{#+INCLUDE:}.  The timestamp mechanism in
 Org is not smart enough to detect if included files have been modified.
 
-@node Sample configuration
+@node Sample configuration, Triggering publication, Uploading files, Publishing
 @section Sample configuration
 
 Below we provide two example configurations.  The first one is a simple
@@ -15040,7 +15039,7 @@ more complex, with a multi-component project.
 * Complex example::             A multi-component publishing example
 @end menu
 
-@node Simple example
+@node Simple example, Complex example, Sample configuration, Sample configuration
 @subsection Example: simple publishing configuration
 
 This example publishes a set of Org files to the @file{public_html}
@@ -15059,7 +15058,7 @@ directory on the local machine.
                     type=\"text/css\"/>")))
 @end lisp
 
-@node Complex example
+@node Complex example,  , Simple example, Sample configuration
 @subsection Example: complex publishing configuration
 
 This more complicated example publishes an entire website, including
@@ -15109,7 +15108,7 @@ right place on the web server, and publishing images to it.
          ("website" :components ("orgfiles" "images" "other"))))
 @end lisp
 
-@node Triggering publication
+@node Triggering publication,  , Sample configuration, Publishing
 @section Triggering publication
 
 Once properly configured, Org can publish with the following commands:
@@ -15134,7 +15133,7 @@ This may be necessary in particular if files include other files via
 @code{#+SETUPFILE:} or @code{#+INCLUDE:}.
 
 
-@node Working with source code
+@node Working with source code, Miscellaneous, Publishing, Top
 @chapter Working with source code
 @cindex Schulte, Eric
 @cindex Davison, Dan
@@ -15224,7 +15223,7 @@ Details of Org's facilities for working with source code are shown next.
 @end menu
 
 
-@node Structure of code blocks
+@node Structure of code blocks, Editing source code, Working with source code, Working with source code
 @section Structure of code blocks
 @cindex code block, structure
 @cindex source code, block structure
@@ -15243,12 +15242,12 @@ A @samp{src} block conforms to this structure:
 #+END_SRC
 @end example
 
-Org mode's templates system (@pxref{Easy templates}) speeds up creating
-@samp{src} 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 a command for wrapping existing text in a block (@pxref{Inserting
+structure 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:
@@ -15296,7 +15295,7 @@ specific sub-trees of the Org document.
 Source code in the dialect of the specified language identifier.
 @end table
 
-@node Editing source code
+@node Editing source code, Exporting code blocks, Structure of code blocks, Working with source code
 @section Editing source code
 @cindex code block, editing
 @cindex source code, editing
@@ -15360,7 +15359,7 @@ Emacs-Lisp languages.
                             ("python" (:background "#E5FFB8"))))
 @end lisp
 
-@node Exporting code blocks
+@node Exporting code blocks, Extracting source code, Editing source code, Working with source code
 @section Exporting code blocks
 @cindex code block, exporting
 @cindex source code, exporting
@@ -15413,7 +15412,7 @@ Org never evaluates code blocks in commented sub-trees when exporting
 (@pxref{Comment lines}).  On the other hand, Org does evaluate code blocks in
 sub-trees excluded from export (@pxref{Export settings}).
 
-@node Extracting source code
+@node Extracting source code, Evaluating code blocks, Exporting code blocks, Working with source code
 @section Extracting source code
 @cindex tangling
 @cindex source code, extracting
@@ -15478,7 +15477,7 @@ block header arguments: One, set @code{padline} (@pxref{padline}) to true
 (the default setting).  Two, set @code{comments} (@pxref{comments}) to
 @code{link}, which makes Org insert links to the Org file.
 
-@node Evaluating code blocks
+@node Evaluating code blocks, Library of Babel, Extracting source code, Working with source code
 @section Evaluating code blocks
 @cindex code block, evaluating
 @cindex source code, evaluating
@@ -15555,7 +15554,7 @@ For more examples of header arguments for @code{#+CALL:} lines,
 @pxref{Arguments in function calls}.
 @end table
 
-@node Library of Babel
+@node Library of Babel, Languages, Evaluating code blocks, Working with source code
 @section Library of Babel
 @cindex babel, library of
 @cindex source code, library
@@ -15572,7 +15571,7 @@ For any user to add code to the library, first save the code in regular
 @samp{src} code blocks of an Org file, and then load the Org file with
 @code{org-babel-lob-ingest}, which is bound to @kbd{C-c C-v i}.
 
-@node Languages
+@node Languages, Header arguments, Library of Babel, Working with source code
 @section Languages
 @cindex babel, languages
 @cindex source code, languages
@@ -15632,7 +15631,7 @@ following enables execution of @code{clojure} code blocks:
 (require 'ob-clojure)
 @end lisp
 
-@node Header arguments
+@node Header arguments, Results of evaluation, Languages, Working with source code
 @section Header arguments
 @cindex code block, header arguments
 @cindex source code, block header arguments
@@ -15644,7 +15643,7 @@ Details of configuring header arguments are shown here.
 * Specific header arguments::   List of header arguments
 @end menu
 
-@node Using header arguments
+@node Using header arguments, Specific header arguments, Header arguments, Header arguments
 @subsection Using header arguments
 
 Since header arguments can be set in several ways, Org prioritizes them in
@@ -15661,7 +15660,7 @@ global defaults.
 @end menu
 
 
-@node System-wide header arguments
+@node System-wide header arguments, Language-specific header arguments, Using header arguments, Using header arguments
 @subsubheading System-wide header arguments
 @vindex org-babel-default-header-args
 System-wide values of header arguments can be specified by adapting the
@@ -15689,14 +15688,14 @@ Org expand @code{:noweb} references by default.
             (assq-delete-all :noweb org-babel-default-header-args)))
 @end lisp
 
-@node Language-specific header arguments
+@node Language-specific header arguments, Header arguments in Org mode properties, System-wide header arguments, Using header arguments
 @subsubheading Language-specific header arguments
 Each language can have separate default header arguments by customizing the
 variable @code{org-babel-default-header-args:<lang>}, where @code{<lang>} is
 the name of the language.  For details, see the language-specific online
 documentation at @uref{http://orgmode.org/worg/org-contrib/babel}.
 
-@node Header arguments in Org mode properties
+@node Header arguments in Org mode properties, Language-specific mode properties, Language-specific header arguments, Using header arguments
 @subsubheading Header arguments in Org mode properties
 
 For header arguments applicable to the buffer, use @code{#+PROPERTY:} lines
@@ -15734,7 +15733,7 @@ Properties defined through @code{org-set-property} function, bound to
 @kbd{C-c C-x p}, apply to all active languages.  They override properties set
 in @code{org-babel-default-header-args}.
 
-@node Language-specific mode properties
+@node Language-specific mode properties, Code block specific header arguments, Header arguments in Org mode properties, Using header arguments
 @subsubheading Language-specific mode properties
 
 Language-specific header arguments are also read from properties
@@ -15757,7 +15756,7 @@ would force separate sessions for clojure blocks in Heading and Subheading,
 but use the same session for all @samp{R} blocks.  Blocks in Subheading
 inherit settings from Heading.
 
-@node Code block specific header arguments
+@node Code block specific header arguments, Arguments in function calls, Language-specific mode properties, Using header arguments
 @subsubheading Code block specific header arguments
 
 Header arguments are most commonly set at the @samp{src} code block level, on
@@ -15815,7 +15814,7 @@ Multi-line header arguments on a named @samp{src} code block:
   : data:2
 @end example
 
-@node Arguments in function calls
+@node Arguments in function calls,  , Code block specific header arguments, Using header arguments
 @subsubheading Arguments in function calls
 
 Header arguments in function calls are the most specific and override all
@@ -15837,7 +15836,7 @@ evaluation of @code{factorial} code block.
 #+CALL: factorial[:session special](n=5)
 @end example
 
-@node Specific header arguments
+@node Specific header arguments,  , Using header arguments, Header arguments
 @subsection Specific header arguments
 Org comes with many header arguments common to all languages.  New header
 arguments are added for specific languages as they become available for use
@@ -15879,7 +15878,7 @@ are:
 
 For language-specific header arguments, see @ref{Languages}.
 
-@node var
+@node var, results, Specific header arguments, Specific header arguments
 @subsubsection @code{:var}
 @cindex @code{:var}, src header argument
 Use @code{:var} for passing arguments to @samp{src} code blocks.  The
@@ -16133,7 +16132,7 @@ as Emacs Lisp code, as illustrated in the following example.
 : (a b c)
 @end example
 
-@node results
+@node results, file, var, Specific header arguments
 @subsubsection @code{:results}
 @cindex @code{:results}, src header argument
 
@@ -16241,7 +16240,7 @@ Prepend results to the Org buffer.  Latest results are at the top.  Does not
 remove previous results.  Usage example: @code{:results output prepend}.
 @end itemize
 
-@node file
+@node file, file-desc, results, Specific header arguments
 @subsubsection @code{:file}
 @cindex @code{:file}, src header argument
 
@@ -16254,7 +16253,7 @@ format}).  Some languages, such as @samp{R}, @samp{dot}, @samp{ditaa}, and
 code.  Such code wrapping helps recreate the output, especially graphics
 output, by executing just the @code{:file} contents.
 
-@node file-desc
+@node file-desc, file-ext, file, Specific header arguments
 @subsubsection @code{:file-desc}
 
 A description of the results file.  Org uses this description for the link
@@ -16262,7 +16261,7 @@ A description of the results file.  Org uses this description for the link
 has no value, Org will use file name for both the ``link'' and the
 ``description'' portion of the Org mode link.
 
-@node file-ext
+@node file-ext, output-dir, file-desc, Specific header arguments
 @subsubsection @code{:file-ext}
 @cindex @code{:file-ext}, src header argument
 
@@ -16271,7 +16270,7 @@ name, and extension by combining @code{:file-ext}, @code{#+NAME:} of the
 source block, and the @ref{output-dir} header argument.  To override this
 auto generated file name, use the @code{:file} header argument.
 
-@node output-dir
+@node output-dir, dir, file-ext, Specific header arguments
 @subsubsection @code{:output-dir}
 @cindex @code{:output-dir}, src header argument
 
@@ -16280,7 +16279,7 @@ absolute path (beginning with @code{/}) or a relative directory (without
 @code{/}).  The value can be combined with @code{#+NAME:} of the source block
 and @ref{file} or @ref{file-ext} header arguments.
 
-@node dir
+@node dir, exports, output-dir, Specific header arguments
 @subsubsection @code{:dir} and remote execution
 @cindex @code{:dir}, src header argument
 
@@ -16339,7 +16338,7 @@ Org does not expand @code{default directory} to avoid some underlying
 portability issues.
 @end itemize
 
-@node exports
+@node exports, tangle, dir, Specific header arguments
 @subsubsection @code{:exports}
 @cindex @code{:exports}, src header argument
 
@@ -16363,7 +16362,7 @@ file.  Whether the code is evaluated at all depends on other
 options.  Example: @code{:exports none}.
 @end itemize
 
-@node tangle
+@node tangle, mkdirp, exports, Specific header arguments
 @subsubsection @code{:tangle}
 @cindex @code{:tangle}, src header argument
 
@@ -16386,7 +16385,7 @@ the file name as being relative to the directory of the Org file's location.
 Example: @code{:tangle path}.
 @end itemize
 
-@node mkdirp
+@node mkdirp, comments, tangle, Specific header arguments
 @subsubsection @code{:mkdirp}
 @cindex @code{:mkdirp}, src header argument
 
@@ -16394,7 +16393,7 @@ The @code{:mkdirp} header argument creates parent directories for tangled
 files if the directory does not exist.  @code{yes} enables directory creation
 and @code{no} inhibits directory creation.
 
-@node comments
+@node comments, padline, mkdirp, Specific header arguments
 @subsubsection @code{:comments}
 @cindex @code{:comments}, src header argument
 Controls inserting comments into tangled files.  These are above and beyond
@@ -16418,7 +16417,7 @@ Includes ``link'' comment option, expands noweb references, and wraps them in
 link comments inside the body of the @samp{src} code block.
 @end itemize
 
-@node padline
+@node padline, no-expand, comments, Specific header arguments
 @subsubsection @code{:padline}
 @cindex @code{:padline}, src header argument
 Control insertion of newlines to pad @samp{src} code blocks in the tangled
@@ -16431,7 +16430,7 @@ tangled file.
 Do not insert newlines to pad the tangled @samp{src} code blocks.
 @end itemize
 
-@node no-expand
+@node no-expand, session, padline, Specific header arguments
 @subsubsection @code{:no-expand}
 @cindex @code{:no-expand}, src header argument
 
@@ -16444,7 +16443,7 @@ these expansions may cause premature assignment, hence this option.  This
 option makes a difference only for tangling.  It has no effect when exporting
 since @samp{src} code blocks for execution have to be expanded anyway.
 
-@node session
+@node session, noweb, no-expand, Specific header arguments
 @subsubsection @code{:session}
 @cindex @code{:session}, src header argument
 
@@ -16467,7 +16466,7 @@ shared.  Some interpreted languages support concurrent sessions when
 subsequent source code language blocks change session names.
 @end itemize
 
-@node noweb
+@node noweb, noweb-ref, session, Specific header arguments
 @subsubsection @code{:noweb}
 @cindex @code{:noweb}, src header argument
 
@@ -16575,7 +16574,7 @@ and evaluates to:
 Do things when True
 @end example
 
-@node noweb-ref
+@node noweb-ref, noweb-sep, noweb, Specific header arguments
 @subsubsection @code{:noweb-ref}
 @cindex @code{:noweb-ref}, src header argument
 
@@ -16613,7 +16612,7 @@ when tangled.
  #+END_SRC
 @end example
 
-@node noweb-sep
+@node noweb-sep, cache, noweb-ref, Specific header arguments
 @subsubsection @code{:noweb-sep}
 @cindex @code{:noweb-sep}, src header argument
 
@@ -16621,7 +16620,7 @@ By default a newline separates each noweb reference concatenation.  To change
 this newline separator, edit the @code{:noweb-sep} (@pxref{noweb-sep}) header
 argument.
 
-@node cache
+@node cache, sep, noweb-sep, Specific header arguments
 @subsubsection @code{:cache}
 @cindex @code{:cache}, src header argument
 
@@ -16686,7 +16685,7 @@ the result from @code{random} has changed since the last run.
  0.254227238707244
 @end example
 
-@node sep
+@node sep, hlines, cache, Specific header arguments
 @subsubsection @code{:sep}
 @cindex @code{:sep}, src header argument
 
@@ -16695,7 +16694,7 @@ to files (@pxref{file}) external to Org mode.  Org defaults to tab delimited
 output.  The function, @code{org-open-at-point}, which is bound to @kbd{C-c
 C-o}, also uses @code{:sep} for opening tabular results.
 
-@node hlines
+@node hlines, colnames, sep, Specific header arguments
 @subsubsection @code{:hlines}
 @cindex @code{:hlines}, src header argument
 
@@ -16756,7 +16755,7 @@ For @code{:hlines yes}, the example shows hlines unchanged.
 @end example
 @end itemize
 
-@node colnames
+@node colnames, rownames, hlines, Specific header arguments
 @subsubsection @code{:colnames}
 @cindex @code{:colnames}, src header argument
 
@@ -16803,7 +16802,7 @@ value.  That is, Org removes the column names, processes the table, puts back
 the column names, and then writes the table to the results block.
 @end itemize
 
-@node rownames
+@node rownames, shebang, colnames, Specific header arguments
 @subsubsection @code{:rownames}
 @cindex @code{:rownames}, src header argument
 
@@ -16842,7 +16841,7 @@ for indexing.
 
 @end itemize
 
-@node shebang
+@node shebang, tangle-mode, rownames, Specific header arguments
 @subsubsection @code{:shebang}
 @cindex @code{:shebang}, src header argument
 
@@ -16852,7 +16851,7 @@ setting the @code{:shebang} header argument to a string value (for example,
 the tangled file that the @samp{src} code block is extracted to.  Org then
 turns on the tangled file's executable permission.
 
-@node tangle-mode
+@node tangle-mode, eval, shebang, Specific header arguments
 @subsubsection @code{:tangle-mode}
 @cindex @code{:tangle-mode}, src header argument
 
@@ -16870,7 +16869,7 @@ When multiple @samp{src} code blocks tangle to a single file with different
 and conflicting @code{tangle-mode} header arguments, Org's behavior is
 undefined.
 
-@node eval
+@node eval, wrap, tangle-mode, Specific header arguments
 @subsubsection @code{:eval}
 @cindex @code{:eval}, src header argument
 The @code{:eval} header argument can limit evaluation of specific code
@@ -16894,14 +16893,14 @@ If @code{:eval} header argument is not set for a source block, then Org
 determines whether to evaluate from the @code{org-confirm-babel-evaluate}
 variable (@pxref{Code evaluation security}).
 
-@node wrap
+@node wrap, post, eval, Specific header arguments
 @subsubsection @code{:wrap}
 @cindex @code{:wrap}, src header argument
 The @code{:wrap} header argument marks the results block by appending strings
 to @code{#+BEGIN_} and @code{#+END_}.  If no string is specified, Org wraps
 the results in a @code{#+BEGIN/END_RESULTS} block.
 
-@node post
+@node post, prologue, wrap, Specific header arguments
 @subsubsection @code{:post}
 @cindex @code{:post}, src header argument
 The @code{:post} header argument is for post-processing results from
@@ -16963,7 +16962,7 @@ data.frame(foo=rnorm(1))
 | 1.371 |
 @end example
 
-@node prologue
+@node prologue, epilogue, post, Specific header arguments
 @subsubsection @code{:prologue}
 @cindex @code{:prologue}, src header argument
 The @code{prologue} header argument is for appending to the top of the code
@@ -16976,13 +16975,13 @@ execution of a @samp{src} code block.  A @code{reset} for @samp{gnuplot}:
              '((:prologue . "reset")))
 @end lisp
 
-@node epilogue
+@node epilogue,  , prologue, Specific header arguments
 @subsubsection @code{:epilogue}
 @cindex @code{:epilogue}, src header argument
 The value of the @code{epilogue} header argument is for appending to the end
 of the code block for execution.  See also @ref{prologue}.
 
-@node Results of evaluation
+@node Results of evaluation, Noweb reference syntax, Header arguments, Working with source code
 @section Results of evaluation
 @cindex code block, results of evaluation
 @cindex source code, results of evaluation
@@ -17083,7 +17082,7 @@ in results.
 In the above @code{:session} mode, the interactive interpreter receives and
 prints ``2''.  Results show that.
 
-@node Noweb reference syntax
+@node Noweb reference syntax, Key bindings and useful functions, Results of evaluation, Working with source code
 @section Noweb reference syntax
 @cindex code block, noweb reference
 @cindex syntax, noweb
@@ -17165,7 +17164,7 @@ Note that now the expansion contains the @emph{results} of the code block
 @end example
 
 
-@node Key bindings and useful functions
+@node Key bindings and useful functions, Batch execution, Noweb reference syntax, Working with source code
 @section Key bindings and useful functions
 @cindex code block, key bindings
 
@@ -17268,7 +17267,7 @@ Active key bindings in Org mode buffer:
 @c @item @kbd{C-c C-v C-z} @tab @code{org-babel-switch-to-session}
 @c @end multitable
 
-@node Batch execution
+@node Batch execution,  , Key bindings and useful functions, Working with source code
 @section Batch execution
 @cindex code block, batch execution
 @cindex source code, batch execution
@@ -17294,12 +17293,12 @@ emacs -Q --batch --eval "
   " "$@@"
 @end example
 
-@node Miscellaneous
+@node Miscellaneous, Hacking, Working with source code, Top
 @chapter Miscellaneous
 
 @menu
 * Completion::                  M-TAB guesses completions
-* Easy templates::              Quick insertion of structural elements
+* Inserting structure templates::  Wrapping text in code blocks
 * Speed keys::                  Electric commands at the beginning of a headline
 * Code evaluation security::    Org mode files evaluate inline code
 * Customization::               Adapting Org to changing tastes
@@ -17312,7 +17311,7 @@ emacs -Q --batch --eval "
 @end menu
 
 
-@node Completion
+@node Completion, Inserting structure templates, Miscellaneous, Miscellaneous
 @section Completion
 @cindex completion, of @TeX{} symbols
 @cindex completion, of TODO keywords
@@ -17374,47 +17373,42 @@ If your desktop intercepts the combo @kbd{M-@key{TAB}} to switch windows, use
 environment.
 @end table
 
-@node Easy templates
-@section Easy templates
+@node Inserting structure templates, Speed keys, Completion, Miscellaneous
+@section Inserting structure templates
 @cindex template insertion
 @cindex insertion, of templates
 
-With just a few keystrokes, Org's easy templates inserts empty pairs of
-structural elements, such as @code{#+BEGIN_SRC} and @code{#+END_SRC}.  Easy
-templates use an expansion mechanism, which is native to Org, in a process
-similar to @file{yasnippet} and other Emacs template expansion packages.
-
-@kbd{<} @kbd{s} @kbd{@key{TAB}} expands to a @samp{src} code block.
-
-@kbd{<} @kbd{l} @kbd{@key{TAB}} expands to:
-
-#+BEGIN_EXPORT latex
-
-#+END_EXPORT
+With just a few keystrokes, it's possible to insert empty structural blocks,
+such as @code{#+begin_src} and @code{#+end_src}, or to wrap existing text in
+such a block.
+
+@defun org-insert-structure-template
+@kindex C-c C-x w
+Prompt for a type of block structure, and insert the block at point.  If the
+region is active, it will be wrapped in the block.  First prompts the user
+for a key, which is used to look up a structure type from the values below.
+If the key is @key{TAB}, the user is prompted to enter a type.  Bound to
+@kbd{C-c C-x w}.
+@end defun
 
-Org comes with these pre-defined easy templates:
-
-@multitable @columnfractions 0.1 0.9
-@item @kbd{s} @tab @code{#+BEGIN_SRC ... #+END_SRC}
-@item @kbd{e} @tab @code{#+BEGIN_EXAMPLE ... #+END_EXAMPLE}
-@item @kbd{q} @tab @code{#+BEGIN_QUOTE ... #+END_QUOTE}
-@item @kbd{v} @tab @code{#+BEGIN_VERSE ... #+END_VERSE}
-@item @kbd{c} @tab @code{#+BEGIN_CENTER ... #+END_CENTER}
-@item @kbd{C} @tab @code{#+BEGIN_COMMENT ... #+END_COMMENT}
-@item @kbd{l} @tab @code{#+BEGIN_EXPORT latex ... #+END_EXPORT}
-@item @kbd{L} @tab @code{#+LATEX:}
-@item @kbd{h} @tab @code{#+BEGIN_EXPORT html ... #+END_EXPORT}
-@item @kbd{H} @tab @code{#+HTML:}
-@item @kbd{a} @tab @code{#+BEGIN_EXPORT ascii ... #+END_EXPORT}
-@item @kbd{A} @tab @code{#+ASCII:}
-@item @kbd{i} @tab @code{#+INDEX:} line
-@item @kbd{I} @tab @code{#+INCLUDE:} line
+@vindex org-structure-template-alist
+Available structure types are defined in @code{org-structure-template-alist},
+see the docstring for adding or changing values.
+
+@multitable @columnfractions 0.2 0.8
+@item @kbd{s} @tab @code{src}
+@item @kbd{e} @tab @code{example}
+@item @kbd{E} @tab @code{export}
+@item @kbd{q} @tab @code{quote}
+@item @kbd{v} @tab @code{verse}
+@item @kbd{c} @tab @code{center}
+@item @kbd{C} @tab @code{comment}
+@item @kbd{l} @tab @code{export latex}
+@item @kbd{h} @tab @code{export html}
+@item @kbd{a} @tab @code{export ascii}
 @end multitable
 
-More templates can added by customizing the variable
-@code{org-structure-template-alist}, whose docstring has additional details.
-
-@node Speed keys
+@node Speed keys, Code evaluation security, Inserting structure templates, Miscellaneous
 @section Speed keys
 @cindex speed keys
 
@@ -17440,7 +17434,7 @@ org-speed-command-help}, or @kbd{?} when cursor is at the beginning of an Org
 headline, shows currently active Speed Keys, including the user-defined ones.
 
 
-@node Code evaluation security
+@node Code evaluation security, Customization, Speed keys, Miscellaneous
 @section Code evaluation and security issues
 
 Unlike plain text, running code comes with risk.  Each @samp{src} code block,
@@ -17501,7 +17495,7 @@ Org executes formulas in tables (@pxref{The spreadsheet}) either through the
 @emph{calc} or the @emph{Emacs Lisp} interpreters.
 @end table
 
-@node Customization
+@node Customization, In-buffer settings, Code evaluation security, Miscellaneous
 @section Customization
 @cindex customization
 @cindex options, for customization
@@ -17512,7 +17506,7 @@ through the usual @kbd{M-x org-customize RET} command.  Or through the Org
 menu, @code{Org->Customization->Browse Org Group}.  Org also has per-file
 settings for some variables (@pxref{In-buffer settings}).
 
-@node In-buffer settings
+@node In-buffer settings, The very busy C-c C-c key, Customization, Miscellaneous
 @section Summary of in-buffer settings
 @cindex in-buffer settings
 @cindex special keywords
@@ -17799,7 +17793,7 @@ These lines set the TODO keywords and their significance to the current file.
 The corresponding variable is @code{org-todo-keywords}.
 @end table
 
-@node The very busy C-c C-c key
+@node The very busy C-c C-c key, Clean view, In-buffer settings, Miscellaneous
 @section The very busy C-c C-c key
 @kindex C-c C-c
 @cindex C-c C-c, overview
@@ -17851,7 +17845,7 @@ block is updated.
 If the cursor is at a timestamp, fix the day name in the timestamp.
 @end itemize
 
-@node Clean view
+@node Clean view, TTY keys, The very busy C-c C-c key, Miscellaneous
 @section A cleaner outline view
 @cindex hiding leading stars
 @cindex dynamic indentation
@@ -17969,7 +17963,7 @@ To switch between single and double stars layouts, use @kbd{M-x
 org-convert-to-odd-levels RET} and @kbd{M-x org-convert-to-oddeven-levels}.
 @end enumerate
 
-@node TTY keys
+@node TTY keys, Interaction, Clean view, Miscellaneous
 @section Using Org on a tty
 @cindex tty key bindings
 
@@ -18003,7 +17997,7 @@ normal @kbd{S-@key{cursor}} for editing timestamp might be better with
 @end multitable
 
 
-@node Interaction
+@node Interaction, org-crypt, TTY keys, Miscellaneous
 @section Interaction with other packages
 @cindex packages, interaction with other
 Org's compatibility and the level of interaction with other Emacs packages
@@ -18015,7 +18009,7 @@ are documented here.
 * Conflicts::                   Packages that lead to conflicts
 @end menu
 
-@node Cooperation
+@node Cooperation, Conflicts, Interaction, Interaction
 @subsection Packages that Org cooperates with
 
 @table @asis
@@ -18084,7 +18078,7 @@ for details.
 @end table
 @end table
 
-@node Conflicts
+@node Conflicts,  , Cooperation, Interaction
 @subsection Packages that conflict with Org mode
 
 @table @asis
@@ -18208,7 +18202,7 @@ another key for this command, or override the key in
 
 @end table
 
-@node org-crypt
+@node org-crypt,  , Interaction, Miscellaneous
 @section org-crypt.el
 @cindex @file{org-crypt.el}
 @cindex @code{org-decrypt-entry}
@@ -18245,7 +18239,7 @@ Suggested Org crypt settings in Emacs init file:
 Excluding the crypt tag from inheritance prevents encrypting previously
 encrypted text.
 
-@node Hacking
+@node Hacking, MobileOrg, Miscellaneous, Top
 @appendix Hacking
 @cindex hacking
 
@@ -18267,7 +18261,7 @@ Org.
 * Using the mapping API::       Mapping over all or selected entries
 @end menu
 
-@node Hooks
+@node Hooks, Add-on packages, Hacking, Hacking
 @section Hooks
 @cindex hooks
 
@@ -18276,7 +18270,7 @@ appendix illustrates using a few.  A complete list of hooks with
 documentation is maintained by the Worg project at
 @uref{http://orgmode.org/worg/doc.html#hooks}.
 
-@node Add-on packages
+@node Add-on packages, Adding hyperlink types, Hooks, Hacking
 @section Add-on packages
 @cindex add-on packages
 
@@ -18288,7 +18282,7 @@ See the @file{contrib/README} file in the source code directory for a list of
 contributed files.  Worg page with more information is at:
 @uref{http://orgmode.org/worg/org-contrib/}.
 
-@node Adding hyperlink types
+@node Adding hyperlink types, Adding export back-ends, Add-on packages, Hacking
 @section Adding hyperlink types
 @cindex hyperlinks, adding new types
 
@@ -18383,7 +18377,7 @@ To define new link types, define a function that implements completion
 support with @kbd{C-c C-l}.  This function should not accept any arguments
 but return the appropriate prefix and complete link string.
 
-@node Adding export back-ends
+@node Adding export back-ends, Context-sensitive commands, Adding hyperlink types, Hacking
 @section Adding export back-ends
 @cindex Export, writing back-ends
 
@@ -18410,7 +18404,7 @@ For complete documentation, see
 @url{http://orgmode.org/worg/dev/org-export-reference.html, the Org Export
 Reference on Worg}.
 
-@node Context-sensitive commands
+@node Context-sensitive commands, Tables in arbitrary syntax, Adding export back-ends, Hacking
 @section Context-sensitive commands
 @cindex context-sensitive commands, hooks
 @cindex add-ons, context-sensitive commands
@@ -18427,7 +18421,7 @@ These context sensitive commands work by providing a function that detects
 special context for that add-on and executes functionality appropriate for
 that context.
 
-@node Tables in arbitrary syntax
+@node Tables in arbitrary syntax, Dynamic blocks, Context-sensitive commands, Hacking
 @section Tables and lists in arbitrary syntax
 @cindex tables, in other modes
 @cindex lists, in other modes
@@ -18460,7 +18454,7 @@ list locally to another format, such as HTML, @LaTeX{} or Texinfo.
 * Radio lists::                 Sending and receiving lists
 @end menu
 
-@node Radio tables
+@node Radio tables, A @LaTeX{} example, Tables in arbitrary syntax, Tables in arbitrary syntax
 @subsection Radio tables
 @cindex radio tables
 
@@ -18522,7 +18516,7 @@ Comment and uncomment each line of the table during edits.  The @kbd{M-x
 orgtbl-toggle-comment RET} command makes toggling easy.
 @end itemize
 
-@node A @LaTeX{} example
+@node A @LaTeX{} example, Translator functions, Radio tables, Tables in arbitrary syntax
 @subsection A @LaTeX{} example of radio tables
 @cindex @LaTeX{}, and Orgtbl mode
 
@@ -18628,7 +18622,7 @@ Functions with two arguments can be supplied instead of strings.  By default,
 no special formatting is applied.
 @end table
 
-@node Translator functions
+@node Translator functions, Radio lists, A @LaTeX{} example, Tables in arbitrary syntax
 @subsection Translator functions
 @cindex HTML, and Orgtbl mode
 @cindex translator function
@@ -18679,7 +18673,7 @@ parameters specified in the @samp{#+ORGTBL: SEND} line.  Please share your
 translator functions by posting them to the Org users mailing list,
 @email{emacs-orgmode@@gnu.org}.
 
-@node Radio lists
+@node Radio lists,  , Translator functions, Tables in arbitrary syntax
 @subsection Radio lists
 @cindex radio lists
 @cindex org-list-insert-radio-list
@@ -18720,7 +18714,7 @@ parameters for accurate customizations of lists.  Here is a @LaTeX{} example:
 @kbd{C-c C-c} on @samp{a new house} inserts the translated @LaTeX{} list
 in-between the BEGIN and END marker lines.
 
-@node Dynamic blocks
+@node Dynamic blocks, Special agenda views, Tables in arbitrary syntax, Hacking
 @section Dynamic blocks
 @cindex dynamic blocks
 
@@ -18784,7 +18778,7 @@ Org mode.
 Dynamic blocks, like any other block, can be narrowed with
 @code{org-narrow-to-block}.
 
-@node Special agenda views
+@node Special agenda views, Speeding up your agendas, Dynamic blocks, Hacking
 @section Special agenda views
 @cindex agenda views, user-defined
 
@@ -18880,7 +18874,7 @@ special function:
     (org-agenda-overriding-header "Projects waiting for something: "))))
 @end lisp
 
-@node Speeding up your agendas
+@node Speeding up your agendas, Extracting agenda information, Special agenda views, Hacking
 @section Speeding up your agendas
 @cindex agenda views, optimization
 
@@ -18921,7 +18915,7 @@ about generation of agenda views, see the docstrings for the relevant
 variables, and this @uref{http://orgmode.org/worg/agenda-optimization.html,
 dedicated Worg page} for agenda optimization.
 
-@node Extracting agenda information
+@node Extracting agenda information, Using the property API, Speeding up your agendas, Hacking
 @section Extracting agenda information
 @cindex agenda, pipe
 @cindex Scripts, for agenda processing
@@ -19023,7 +19017,7 @@ foreach $line (split(/\n/,$agenda)) @{
 @}
 @end example
 
-@node Using the property API
+@node Using the property API, Using the mapping API, Extracting agenda information, Hacking
 @section Using the property API
 @cindex API, for properties
 @cindex properties, API
@@ -19103,7 +19097,7 @@ to be entered.  The functions must return @code{nil} if they are not
 responsible for this property.
 @end defopt
 
-@node Using the mapping API
+@node Using the mapping API,  , Using the property API, Hacking
 @section Using the mapping API
 @cindex API, for mapping
 @cindex mapping entries, API
@@ -19209,7 +19203,7 @@ The following example counts the number of entries with TODO keyword
 (length (org-map-entries t "/+WAITING" 'agenda))
 @end lisp
 
-@node MobileOrg
+@node MobileOrg, History and acknowledgments, Hacking, Top
 @appendix MobileOrg
 @cindex iPhone
 @cindex MobileOrg
@@ -19243,7 +19237,7 @@ them.  Though MobileOrg has in-buffer settings, it understands TODO states
 * Pulling from MobileOrg::      Integrating captured and flagged items
 @end menu
 
-@node Setting up the staging area
+@node Setting up the staging area, Pushing to MobileOrg, MobileOrg, MobileOrg
 @section Setting up the staging area
 
 MobileOrg needs access to a file directory on a server to interact with
@@ -19274,7 +19268,7 @@ follows:
 Org copies files to the above directory for MobileOrg.  Org also uses the
 same directory for sharing notes between Org and MobileOrg.
 
-@node Pushing to MobileOrg
+@node Pushing to MobileOrg, Pulling from MobileOrg, Setting up the staging area, MobileOrg
 @section Pushing to MobileOrg
 
 Org pushes files listed in @code{org-mobile-files} to
@@ -19299,7 +19293,7 @@ to download for agendas.  For faster downloads, MobileOrg will read only
 those files whose checksums@footnote{Checksums are stored automatically in
 the file @file{checksums.dat}.} have changed.
 
-@node Pulling from MobileOrg
+@node Pulling from MobileOrg,  , Pushing to MobileOrg, MobileOrg
 @section Pulling from MobileOrg
 
 When MobileOrg synchronizes with the server, it pulls the Org files for
@@ -19343,7 +19337,7 @@ entries.  Note that these entries may not be the most recent since MobileOrg
 searches files that were last pulled.  To get an updated agenda view with
 changes since the last pull, pull again.
 
-@node History and acknowledgments
+@node History and acknowledgments, GNU Free Documentation License, MobileOrg, Top
 @appendix History and acknowledgments
 @cindex acknowledgments
 @cindex history
@@ -19720,27 +19714,27 @@ and contributed various ideas and code snippets.
 @end itemize
 
 
-@node GNU Free Documentation License
+@node GNU Free Documentation License, Main Index, History and acknowledgments, Top
 @appendix GNU Free Documentation License
 @include doclicense.texi
 
 
-@node Main Index
+@node Main Index, Key Index, GNU Free Documentation License, Top
 @unnumbered Concept index
 
 @printindex cp
 
-@node Key Index
+@node Key Index, Command and Function Index, Main Index, Top
 @unnumbered Key index
 
 @printindex ky
 
-@node Command and Function Index
+@node Command and Function Index, Variable Index, Key Index, Top
 @unnumbered Command and function index
 
 @printindex fn
 
-@node Variable Index
+@node Variable Index,  , Command and Function Index, Top
 @unnumbered Variable index
 
 This is not a complete index of variables and faces, only the ones that are
diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 391ef94ac..97ccf884b 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -149,6 +149,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 w by default.
 
 *** ~org-export-excluded-from-toc-p~
 
diff --git a/lisp/org.el b/lisp/org.el
index 3b26bfd3d..9ad06ac3b 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -6740,8 +6740,6 @@ Use `\\[org-edit-special]' to edit table.el tables"))
        ((run-hook-with-args-until-success
 	 'org-tab-after-check-for-cycling-hook))
 
-       ((org-try-structure-completion))
-
        ((run-hook-with-args-until-success
 	 'org-tab-before-tab-emulation-hook))
 
@@ -11859,76 +11857,77 @@ keywords relative to each registered export back-end."
     "TITLE:" "TODO:" "TYP_TODO:" "SELECT_TAGS:" "EXCLUDE_TAGS:"))
 
 (defcustom org-structure-template-alist
-  '(("s" "#+BEGIN_SRC ?\n\n#+END_SRC")
-    ("e" "#+BEGIN_EXAMPLE\n?\n#+END_EXAMPLE")
-    ("q" "#+BEGIN_QUOTE\n?\n#+END_QUOTE")
-    ("v" "#+BEGIN_VERSE\n?\n#+END_VERSE")
-    ("V" "#+BEGIN_VERBATIM\n?\n#+END_VERBATIM")
-    ("c" "#+BEGIN_CENTER\n?\n#+END_CENTER")
-    ("C" "#+BEGIN_COMMENT\n?\n#+END_COMMENT")
-    ("l" "#+BEGIN_EXPORT latex\n?\n#+END_EXPORT")
-    ("L" "#+LaTeX: ")
-    ("h" "#+BEGIN_EXPORT html\n?\n#+END_EXPORT")
-    ("H" "#+HTML: ")
-    ("a" "#+BEGIN_EXPORT ascii\n?\n#+END_EXPORT")
-    ("A" "#+ASCII: ")
-    ("i" "#+INDEX: ?")
-    ("I" "#+INCLUDE: %file ?"))
+  '((?s . "src")
+    (?e . "example")
+    (?E . "export")
+    (?q . "quote")
+    (?v . "verse")
+    (?c . "center")
+    (?C . "comment")
+    (?l . "export latex")
+    (?h . "export html")
+    (?a . "export ascii"))
   "Structure completion elements.
-This is a list of abbreviation keys and values.  The value gets inserted
-if you type `<' followed by the key and then press the completion key,
-usually `TAB'.  %file will be replaced by a file name after prompting
-for the file using completion.  The cursor will be placed at the position
-of the `?' in the template.
-There are two templates for each key, the first uses the original Org syntax,
-the second uses Emacs Muse-like syntax tags.  These Muse-like tags become
-the default when the /org-mtags.el/ module has been loaded.  See also the
-variable `org-mtags-prefer-muse-templates'."
+This is an alist of characters and values.  When
+`org-insert-structure-template' is called, an additional key is
+read.  The key is first looked up in this alist, and the
+corresponding structure is inserted, with \"#+begin\" and
+\"#+end\" added automatically."
   :group 'org-completion
   :type '(repeat
-	  (list
-	   (string :tag "Key")
+	  (cons
+	   (character :tag "Key")
 	   (string :tag "Template")))
-  :version "26.1"
   :package-version '(Org . "8.3"))
 
-(defun org-try-structure-completion ()
-  "Try to complete a structure template before point.
-This looks for strings like \"<e\" on an otherwise empty line and
-expands them."
-  (let ((l (buffer-substring (point-at-bol) (point)))
-	a)
-    (when (and (looking-at "[ \t]*$")
-	       (string-match "^[ \t]*<\\([a-zA-Z]+\\)$" l)
-	       (setq a (assoc (match-string 1 l) org-structure-template-alist)))
-      (org-complete-expand-structure-template (+ -1 (point-at-bol)
-						 (match-beginning 1)) a)
-      t)))
-
-(defun org-complete-expand-structure-template (start cell)
-  "Expand a structure template."
-  (let ((rpl (nth 1 cell))
-	(ind ""))
-    (delete-region start (point))
-    (when (string-match "\\`[ \t]*#\\+" rpl)
-      (cond
-       ((bolp))
-       ((not (string-match "\\S-" (buffer-substring (point-at-bol) (point))))
-	(setq ind (buffer-substring (point-at-bol) (point))))
-       (t (newline))))
-    (setq start (point))
-    (when (string-match "%file" rpl)
-      (setq rpl (replace-match
-		 (concat
-		  "\""
-		  (save-match-data
-		    (abbreviate-file-name (read-file-name "Include file: ")))
-		  "\"")
-		 t t rpl)))
-    (setq rpl (mapconcat 'identity (split-string rpl "\n")
-			 (concat "\n" ind)))
-    (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.
+First read a character, which can be one of the keys in
+`org-structure-template-alist'.  When it is <TAB>, prompt the
+user for a string to use.  With an active region, wrap the region
+in the block.  Otherwise, insert an empty block."
+  (interactive
+   (list
+    (let* ((key (read-key "Key: "))
+	   (struct-string
+	    (or (cdr (assq key org-structure-template-alist))
+		(and (= key ?\t)
+		     (read-string "Structure type: "))
+		(error "'%c' has no structure definition" key))))
+      struct-string)))
+  (let ((s (if (use-region-p)
+	       (region-beginning)
+	     (point)))
+	(e (copy-marker (if (use-region-p)
+			    (region-end)
+			  (point))
+			t))
+	column)
+    (when (string-match-p
+	   (concat "\\`"
+		   (regexp-opt '("example" "export" "src")))
+	   type)
+      (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"
+		    (car (split-string type))))
+    (when (or (string-match-p "src\\|\\`export\\'" type)
+	      (null (use-region-p)))
+      (goto-char s)
+      (end-of-line))
+    (set-marker e nil)))
 
 ;;;; TODO, DEADLINE, Comments
 
@@ -19393,6 +19392,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-xw"    '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 379ded672..ca1b7f463 100644
--- a/testing/lisp/test-org.el
+++ b/testing/lisp/test-org.el
@@ -4000,6 +4000,52 @@ 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 multiple lines in buffer.
+  (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-mark-element)
+	      (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-mark-element)
+	      (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-mark-element)
+	      (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-mark-element)
+	      (org-insert-structure-template "foo")
+	      (buffer-string)))))
+
 (ert-deftest test-org/previous-block ()
   "Test `org-previous-block' specifications."
   ;; Regular test.
-- 
2.14.3

Re: function for inserting a block

[Nicolas Goaziou]

Hello,

Eric Abrahamsen <eric@ericabrahamsen.net> writes:

> From 055af9e9545947b9aeccc3370c8b67a237eea5d8 Mon Sep 17 00:00:00 2001
> From: Eric Abrahamsen <eric@ericabrahamsen.net>
> Date: Mon, 30 Oct 2017 10:55:29 -0700
> Subject: [PATCH] Replace easy templates with 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.
>   (org-structure-predefined-blocks): New option holding predefined
>   blocks, for completion.
>   (org-try-structure-completion,
>   org-complete-expand-structure-template): Remove functions.
> * doc/org.texi (Inserting structure templates): Document.
> * testing/lisp/test-org.el (test-org/insert-template): New test.

Thank you. I applied your patch with the changes below.

> -* Info directory file::     Installing a manual in Info file hierarchy.
> +* Info directory file::         Installing a manual in Info file hierarchy.

Ignored.

> -* Easy templates::              Quick insertion of structural elements
> +* Inserting structure templates::  Wrapping text in code blocks

I used "Structure templates" instead of "Inserting structure templates"
and updated the rest of the "org.texi" accordingly.

> -@node Introduction
> +@node Introduction, Document structure, Top, Top

There is a lot of noise like this in your patch. I removed it.

> +With just a few keystrokes, it's possible to insert empty structural blocks,
> +such as @code{#+begin_src} and @code{#+end_src}, or to wrap existing text in
> +such a block.

Manual's conventions require to use uppercase keywords: #+BEGIN_SRC,
even though the function inserts them in lowercase.

> +@defun org-insert-structure-template
> +@kindex C-c C-x w

Manual uses

  @table @kbd
  @orgcmd(C-c C-x w, org-insert-structure-template)
  @end table

instead.

> +Prompt for a type of block structure, and insert the block at point.  If the
> +region is active, it will be wrapped in the block.  First prompts the user

"it is wrapped in the block"

GNU Manuals's convention is to favor present tense over future one.

> +@vindex org-structure-template-alist
> +Available structure types are defined in @code{org-structure-template-alist},
> +see the docstring for adding or changing values.
> +
> +@multitable @columnfractions 0.2 0.8
> +@item @kbd{s} @tab @code{src}
> +@item @kbd{e} @tab @code{example}
> +@item @kbd{E} @tab @code{export}
> +@item @kbd{q} @tab @code{quote}
> +@item @kbd{v} @tab @code{verse}
> +@item @kbd{c} @tab @code{center}
> +@item @kbd{C} @tab @code{comment}
> +@item @kbd{l} @tab @code{export latex}
> +@item @kbd{h} @tab @code{export html}
> +@item @kbd{a} @tab @code{export ascii}

@code{src} -> @samp{#+BEGIN_SRC}
...

I also re-ordered the entries.

> +  '((?s . "src")
> +    (?e . "example")
> +    (?E . "export")
> +    (?q . "quote")
> +    (?v . "verse")
> +    (?c . "center")
> +    (?C . "comment")
> +    (?l . "export latex")
> +    (?h . "export html")
> +    (?a . "export ascii"))
>    "Structure completion elements.

I re-ordered the entries.

> -This is a list of abbreviation keys and values.  The value gets inserted
> -if you type `<' followed by the key and then press the completion key,
> -usually `TAB'.  %file will be replaced by a file name after prompting
> -for the file using completion.  The cursor will be placed at the position
> -of the `?' in the template.
> -There are two templates for each key, the first uses the original Org syntax,
> -the second uses Emacs Muse-like syntax tags.  These Muse-like tags become
> -the default when the /org-mtags.el/ module has been loaded.  See also the
> -variable `org-mtags-prefer-muse-templates'."
> +This is an alist of characters and values.  When
> +`org-insert-structure-template' is called, an additional key is
> +read.  The key is first looked up in this alist, and the
> +corresponding structure is inserted, with \"#+begin\" and
> +\"#+end\" added automatically."

"#+BEGIN_" and "#+END_".

>    :group 'org-completion
>    :type '(repeat
> -	  (list
> -	   (string :tag "Key")
> +	  (cons
> +	   (character :tag "Key")
>  	   (string :tag "Template")))
> -  :version "26.1"
>    :package-version '(Org . "8.3"))

"8.3" -> "9.2"

> +(defun org-insert-structure-template (type)
> +  "Insert a block structure of the type #+begin_foo/#+end_foo.
> +First read a character, which can be one of the keys in
> +`org-structure-template-alist'.  When it is <TAB>, prompt the
> +user for a string to use.  With an active region, wrap the region
> +in the block.  Otherwise, insert an empty block."
> +  (interactive
> +   (list
> +    (let* ((key (read-key "Key: "))
> +	   (struct-string
> +	    (or (cdr (assq key org-structure-template-alist))
> +		(and (= key ?\t)
> +		     (read-string "Structure type: "))
> +		(error "'%c' has no structure definition" key))))

(user-error "`%c' ...")

> +      struct-string)))
> +  (let ((s (if (use-region-p)
> +	       (region-beginning)
> +	     (point)))
> +	(e (copy-marker (if (use-region-p)
> +			    (region-end)
> +			  (point))
> +			t))

I also bound (use-region-p) to `region?'.

> +  (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))

The line above is not necessary, I removed it.

Regards,

-- 
Nicolas Goaziou

Re: function for inserting a block

[Kaushal Modi]

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

On Sun, Nov 5, 2017 at 4:07 AM Nicolas Goaziou <mail@nicolasgoaziou.fr>
wrote:

> Hello,
>
> Eric Abrahamsen <eric@ericabrahamsen.net> writes:
>
> > From 055af9e9545947b9aeccc3370c8b67a237eea5d8 Mon Sep 17 00:00:00 2001
> > From: Eric Abrahamsen <eric@ericabrahamsen.net>
> > Date: Mon, 30 Oct 2017 10:55:29 -0700
> > Subject: [PATCH] Replace easy templates with
> 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.
> >   (org-structure-predefined-blocks): New option holding predefined
> >   blocks, for completion.
> >   (org-try-structure-completion,
> >   org-complete-expand-structure-template): Remove functions.
> > * doc/org.texi (Inserting structure templates): Document.
> > * testing/lisp/test-org.el (test-org/insert-template): New test.
>
> Thank you. I applied your patch with the changes below.
>

I'll try this out soon. This is a breaking change though
(org-try-structure-completion doesn't exist any more.. it breaks at least
my config.. could be breaking more). Can you please also mention this
breakage in the ORG-NEWS?
-- 

Kaushal Modi

[-- Attachment #2: Type: text/html, Size: 1797 bytes --]

Re: function for inserting a block

[Kaushal Modi]

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

On Sun, Nov 5, 2017 at 9:24 AM Kaushal Modi <kaushal.modi@gmail.com> wrote:

>  This is a breaking change though (org-try-structure-completion doesn't
> exist any more.. it breaks at least my config.. could be breaking more).
>

It could actually be a wider breakage as it changes the structure of
org-structure-template-alist
-- 

Kaushal Modi

[-- Attachment #2: Type: text/html, Size: 895 bytes --]

Re: function for inserting a block

[Nicolas Goaziou]

Hello,

Kaushal Modi <kaushal.modi@gmail.com> writes:

> On Sun, Nov 5, 2017 at 9:24 AM Kaushal Modi <kaushal.modi@gmail.com> wrote:
>
>>  This is a breaking change though (org-try-structure-completion doesn't
>> exist any more.. it breaks at least my config.. could be breaking more).
>>
>
> It could actually be a wider breakage as it changes the structure of
> org-structure-template-alist

I documented the two changes above in ORG-NEWS.

Regards,

-- 
Nicolas Goaziou

Re: function for inserting a block

[Kaushal Modi]

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

On Mon, Nov 6, 2017 at 8:48 AM Nicolas Goaziou <mail@nicolasgoaziou.fr>
wrote:

> I documented the two changes above in ORG-NEWS.
>

Thanks!
-- 

Kaushal Modi

[-- Attachment #2: Type: text/html, Size: 537 bytes --]

Re: function for inserting a block

[Eric Abrahamsen]

On 11/05/17 10:06 AM, Nicolas Goaziou wrote:
> Hello,
>
> Eric Abrahamsen <eric@ericabrahamsen.net> writes:
>
>> From 055af9e9545947b9aeccc3370c8b67a237eea5d8 Mon Sep 17 00:00:00 2001
>> From: Eric Abrahamsen <eric@ericabrahamsen.net>
>> Date: Mon, 30 Oct 2017 10:55:29 -0700
>> Subject: [PATCH] Replace easy templates with 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.
>>   (org-structure-predefined-blocks): New option holding predefined
>>   blocks, for completion.
>>   (org-try-structure-completion,
>>   org-complete-expand-structure-template): Remove functions.
>> * doc/org.texi (Inserting structure templates): Document.
>> * testing/lisp/test-org.el (test-org/insert-template): New test.
>
> Thank you. I applied your patch with the changes below.

Great!

>> -* Info directory file::     Installing a manual in Info file hierarchy.
>> +* Info directory file::         Installing a manual in Info file hierarchy.
>
> Ignored.
>
>> -* Easy templates::              Quick insertion of structural elements
>> +* Inserting structure templates::  Wrapping text in code blocks
>
> I used "Structure templates" instead of "Inserting structure templates"
> and updated the rest of the "org.texi" accordingly.
>
>> -@node Introduction
>> +@node Introduction, Document structure, Top, Top
>
> There is a lot of noise like this in your patch. I removed it.

I don't know why that happened, I ran the update-menus and update-nodes
menu commands, I figured that was necessary after the section renaming.
I have noticed a bit of churn when producing other info manuals, though.

Thanks a lot for the rest of your edits!

Eric

Re: function for inserting a block

[Thorsten Jolitz]

Hello,
this is a long thread so I did not read everything, just want to mention
that in org-dp.el I did something similar using

- tempo templates (for a programmer who wants to insert an
org-dp-create call in his emacs-lisp program) and 

- a universal (org) prompt function for a user who wants to insert a
src-block in his org file.

This one for productive use in emacs-lisp programs (note that there is
tab completion for values):

,----[ C-h f tempo-template-org-dp-create RET ]
| tempo-template-org-dp-create is an interactive Lisp function.
| 
| (tempo-template-org-dp-create &optional ARG)
| 
| Insert org-dp-create template.
| 
| [back]
`----

This one with comments to give a bit more explanation to the programmer:

,----[ C-h f tempo-template-org-dp-create-with-comments RET ]
| tempo-template-org-dp-create-with-comments is an interactive Lisp
| function.
| 
| (tempo-template-org-dp-create-with-comments &optional ARG)
| 
| Insert org-dp-create template.
| 
| [back]
`----

This one is on the user level (in org files), C-c w w ist just my
personnal key binding from my .emacs:

,----[ C-h f org-dp-wrap-in-block RET ]
| org-dp-wrap-in-block is an interactive Lisp function in
| ‘org-dp-lib.el’.
| 
| It is bound to C-c w w.
| 
| (org-dp-wrap-in-block &optional LINES USER-INFO &rest PROMPT-SPEC)
| 
| Wrap sexp-at-point or region in Org block.
| 
| A region instead of the sexp-at-point is wrapped if either
| 
|    - optional arg LINES is an (positive or negative) integer or
| 
|    - the region is active
| 
| In the first case the region is determined by moving LINES lines
| up (LINES is positive) or down (LINES is negative) from point
| using ‘forward-line’, in the second case the active region is
| used.
| 
| If point is already inside of a block, modify it or unwrap its
| content/value instead of wrapping it in another block, except if
| explicitly asked for by user.
| 
| If USER-INFO is given, it should be a list in the format returned
| by ‘org-dp-prompt-all’, i.e.
| 
|  (elem-type contents replace affiliated args)
| 
| Look up that function’s docstring for more information about the
| list’s elements. A non-nil USER-INFO suppresses calls to
| ‘org-dp-prompt-all’ and is used instead of its return value.
| 
| Possible &rest PROMPT-SPEC should be keyword/value pairs used for
| restricting user-prompting via ‘org-dp-prompt-all’, e.g.
| 
|   :noprompt-affiliated t :noprompt-replace t
| 
| see the docstring of that function for more info.
| 
| [back]
`----

org-dp-prompt-all is the universal function, with &rest argument
PROMPT-SPEC you can reduce the prompting and such easily create your own
specific 'wrap in block' utility commands without much programming.

Hope this is not off-topic.

-- 
cheers,
Thorsten

Re: function for inserting a block

[Nicolas Goaziou]

Hello,

Eric Abrahamsen <eric@ericabrahamsen.net> writes:

> Kaushal Modi <kaushal.modi@gmail.com> writes:

>> I just tried it out, and it works great!
>>
>> I have a comment about
>>
>> (when (string-equal (downcase type) "example")
>>       (org-escape-code-in-region s e)) 
>>
>> I have never needed to escape org in example, blocks, but I *have* needed to do that in org src blocks. 
>>
>> Should type string be also matched with "src org"?
>>
>> Actually should the type string be matched only with "src org"? Because I see the Org example blocks as <pre> <code> blocks in HTML with no syntax highlighting.. so
>> those can contain code from any language.
>>
>> Also as this is part of org and emacs, org-structure-predefined-blocks deserves "SRC org" and "SRC emacs-lisp" too? :)
>
> The template really only inserts the block type, not anything specific
> like the source language or export backend. I think prompting for
> "second-level" information like that might be a little overkill.
>
> As for what should be escaped and what shouldn't, I defer to Nicolas,
> let's see what he says.

"src" (not only with "org" language), "example" and "export", i.e.,
verbatim, blocks need to be escaped.

You should probably use something like

  (when (string-prefix-p (regexp-opt '("example" "export" "src")) type t)
   ...)

Regards,

-- 
Nicolas Goaziou

Re: function for inserting a block

[Eric Abrahamsen]

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

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Hello,
>
> Eric Abrahamsen <eric@ericabrahamsen.net> writes:
>
>> Kaushal Modi <kaushal.modi@gmail.com> writes:
>
>>> I just tried it out, and it works great!
>>>
>>> I have a comment about
>>>
>>> (when (string-equal (downcase type) "example")
>>>       (org-escape-code-in-region s e)) 
>>>
>>> I have never needed to escape org in example, blocks, but I *have* needed to do that in org src blocks. 
>>>
>>> Should type string be also matched with "src org"?
>>>
>>> Actually should the type string be matched only with "src org"? Because I see the Org example blocks as <pre> <code> blocks in HTML with no syntax highlighting.. so
>>> those can contain code from any language.
>>>
>>> Also as this is part of org and emacs, org-structure-predefined-blocks deserves "SRC org" and "SRC emacs-lisp" too? :)
>>
>> The template really only inserts the block type, not anything specific
>> like the source language or export backend. I think prompting for
>> "second-level" information like that might be a little overkill.
>>
>> As for what should be escaped and what shouldn't, I defer to Nicolas,
>> let's see what he says.
>
> "src" (not only with "org" language), "example" and "export", i.e.,
> verbatim, blocks need to be escaped.
>
> You should probably use something like
>
>   (when (string-prefix-p (regexp-opt '("example" "export" "src")) type t)
>    ...)

string-prefix-p doesn't appear to work with regular expressions, so I
used string-match-p.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-New-function-org-insert-structure-template.patch --]
[-- Type: text/x-diff, Size: 7944 bytes --]

From 1ef3404310f516d1f762501b2bb974220a61da1d Mon Sep 17 00:00:00 2001
From: Eric Abrahamsen <eric@ericabrahamsen.net>
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.
  (org-structure-predefined-blocks): New option holding predefined
  blocks, for completion.
* 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              | 49 ++++++++++++++++++++++++++++++++++++++++++++++++
 testing/lisp/test-org.el | 42 +++++++++++++++++++++++++++++++++++++++++
 4 files changed, 110 insertions(+), 6 deletions(-)

diff --git a/doc/org.texi b/doc/org.texi
index c54f2615a..6ad9d1c15 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -15242,12 +15242,13 @@ A @samp{src} block conforms to this structure:
 #+END_SRC
 @end example
 
-Org mode's templates system (@pxref{Easy templates}) speeds up creating
-@samp{src} 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:
@@ -17418,6 +17419,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.
 
+@findex org-insert-structure-template
+@kindex C-c C-x w
+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 w} by default.
+
 @node Speed keys
 @section Speed keys
 @cindex speed keys
diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 1076dd970..190a6b8bc 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 w by default.
 
 *** ~org-export-excluded-from-toc-p~
 
diff --git a/lisp/org.el b/lisp/org.el
index 54687abc7..552dd7ec4 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -12117,6 +12117,13 @@ keywords relative to each registered export back-end."
     "PRIORITIES:" "SELECT_TAGS:" "SEQ_TODO:" "SETUPFILE:" "STARTUP:" "TAGS:"
     "TITLE:" "TODO:" "TYP_TODO:" "SELECT_TAGS:" "EXCLUDE_TAGS:"))
 
+(defcustom org-structure-predefined-blocks
+  '("SRC" "EXAMPLE" "QUOTE" "VERSE" "VERBATIM" "CENTER" "COMMENT" "EXPORT")
+  "Block structure completion names."
+  :group 'org-completion
+  :type '(repeat string)
+  :package-version '(Org . "9.1.3"))
+
 (defcustom org-structure-template-alist
   '(("s" "#+BEGIN_SRC ?\n\n#+END_SRC")
     ("e" "#+BEGIN_EXAMPLE\n?\n#+END_EXAMPLE")
@@ -12189,6 +12196,47 @@ expands them."
     (insert rpl)
     (when (re-search-backward "\\?" start t) (delete-char 1))))
 
+(defun org-insert-structure-template (&optional 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)
+  (setq type (or type (completing-read "Block type: "
+				       org-structure-predefined-blocks)))
+  (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-match-p (concat "\\`"
+				  (regexp-opt '("example" "export" "src")))
+			  type)
+      (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 ()
@@ -19652,6 +19700,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-xw"    '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 f94079b7e..84924eb23 100644
--- a/testing/lisp/test-org.el
+++ b/testing/lisp/test-org.el
@@ -4033,6 +4033,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

Re: function for inserting a block

[Bastien]

Hi Eric,

thanks *a lot* for implementing this change!

Maybe I missed something in this thread, but what about making
the change backward-compatible by allowing "<s" (or variants) to
be expanded?  For me, I'd rather type <s TAB than `C-c C-x w s'.

Thanks for your time & answer!

-- 
 Bastien

Re: function for inserting a block

[Nicolas Goaziou]

Hello,

Bastien <bzg@gnu.org> writes:

> Maybe I missed something in this thread, but what about making
> the change backward-compatible by allowing "<s" (or variants) to
> be expanded?  For me, I'd rather type <s TAB than `C-c C-x w s'.

I suggested the idea to remove "<s". The idea behind this remove is that
many other template systems, e.g., YASnippet, already provides this.
I didn't want to re-implement the wheel and let, instead, various parts
of Emacs cooperate.

Regards,

-- 
Nicolas Goaziou

Re: function for inserting a block

[Bastien]

Hi Nicolas,

> I suggested the idea to remove "<s". The idea behind this remove is that
> many other template systems, e.g., YASnippet, already provides this.
> I didn't want to re-implement the wheel and let, instead, various parts
> of Emacs cooperate.

is there a simple mechanism in Emacs core to restore the same
functionnality?

I'm aware of Yasnippet, but it is not in Emacs core and it can
be daunting for newcomers to install, customize and use.

The previous function was very straightforward and simple, the
cost for losing it seems to high to me.  I'd rather have 10 lines
in Org (and in Emacs core) for it, than to ask users to install
something that does a lot more that they don't need.

Let me know what you think.

-- 
 Bastien

Restore old easy template feature (Re: function for inserting a block)

[Kaushal Modi]

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

On Wed, Nov 8, 2017, 7:16 AM Bastien <bzg@gnu.org> wrote:

>
> is there a simple mechanism in Emacs core to restore the same
> functionnality?
>

+1

I'm aware of Yasnippet, but it is not in Emacs core and it can
> be daunting for newcomers to install, customize and use.
>

I am aware of Yasnippet, have it installed, but haven't used for a long
time. The old easy template system just worked and I used it dozens of
times a day.

The previous function was very straightforward and simple, the
> cost for losing it seems to high to me.  I'd rather have 10 lines
> in Org (and in Emacs core) for it, than to ask users to install
> something that does a lot more that they don't need.
>

I agree with that sentiment. In parallel to removing that feature, it would
be needed to add details in the manual on how to restore that functionality
using other means.

Given the lack of time, I just restored for works for me in my personal
config:
https://github.com/kaushalmodi/.emacs.d/commit/9aa3be89a2f8dce3f2aa57f98e0a2f38fdca4c6b

I just like the convenience of hitting "<s" and let the template insertion
logic do its thing.

Let me know what you think.
>
-- 

Kaushal Modi

[-- Attachment #2: Type: text/html, Size: 2261 bytes --]

Re: Restore old easy template feature (Re: function for inserting a block)

[Kaushal Modi]

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

On Wed, Nov 8, 2017, 7:27 AM Kaushal Modi <kaushal.modi@gmail.com> wrote:

> On Wed, Nov 8, 2017, 7:16 AM Bastien <bzg@gnu.org> wrote:
>
>>
>> is there a simple mechanism in Emacs core to restore the same
>> functionnality?
>>
>
> +1
>

To clarify, I am not suggesting to blindly restore the old easy template
system, and then have 2 sets of code doing similar things.

I am suggesting to have a minor mode that simply binds "<" to do the
template insertion (only when that is typed at BOL with optional leading
whitespace, or if a region is selected). If they want to literally type "<"
in those cases, they can either type "<<" or the old "C-q <".

That minor mode will reuse the code that Eric added, so that typing "<s"
will insert the BEGIN_SRC block, etc.

I can work on getting a patch ready if people are fine with this idea (I
effectively do the same in my config, but with the old template system. So
while the heuristics work great, I'll need to adjust that code to fit the
easy template replacement.)

> --

Kaushal Modi

[-- Attachment #2: Type: text/html, Size: 1927 bytes --]

Re: Restore old easy template feature (Re: function for inserting a block)

[Bastien Guerry]

Hi Kaushal,

Kaushal Modi <kaushal.modi@gmail.com> writes:

> I am suggesting to have a minor mode that simply binds "<" to do the
> template insertion (only when that is typed at BOL with optional
> leading whitespace, or if a region is selected).

I think this is a great suggestion and brings the best of both the new
and the old system.

I cannot test this myself until this week-end, but I'd happy too then.

Thanks!

-- 
 Bastien

Re: Restore old easy template feature (Re: function for inserting a block)

[Matt Price]

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

On Wed, Nov 8, 2017 at 9:08 AM, Bastien Guerry <bzg@gnu.org> wrote:

> Hi Kaushal,
>
> Kaushal Modi <kaushal.modi@gmail.com> writes:
>
> > I am suggesting to have a minor mode that simply binds "<" to do the
> > template insertion (only when that is typed at BOL with optional
> > leading whitespace, or if a region is selected).
>
> I think this is a great suggestion and brings the best of both the new
> and the old system.
>
> I cannot test this myself until this week-end, but I'd happy too then.
>

I guess I missed this ocnversation while I was busy wiht other stuff  --
the old easy templating has been removed? I am certainly very sorry to see
it go, esp. as I have found yasnippet to work only intermittently in
org-mode buffers (at least for me).   I see Kaushal has added it back in
his config files, but if someone has a slightly less specialized solution
for restoring it I would love to see it.

I see Nicolas's point that this functionality exists elsewhere, but maybe
someone can point to a ready-made replacement for those of us who rely on
<s, etc., as part of our daily workflow?

Thanks everyone!

[-- Attachment #2: Type: text/html, Size: 1628 bytes --]

Re: Restore old easy template feature (Re: function for inserting a block)

[Eric Abrahamsen]

Matt Price <moptop99@gmail.com> writes:

> On Wed, Nov 8, 2017 at 9:08 AM, Bastien Guerry <bzg@gnu.org> wrote:
>
>  Hi Kaushal,
>
>  Kaushal Modi <kaushal.modi@gmail.com> writes:
>
>  > I am suggesting to have a minor mode that simply binds "<" to do the
>  > template insertion (only when that is typed at BOL with optional
>  > leading whitespace, or if a region is selected).
>
>  I think this is a great suggestion and brings the best of both the new
>  and the old system.
>
>  I cannot test this myself until this week-end, but I'd happy too then.
>
> I guess I missed this ocnversation while I was busy wiht other stuff  -- the old easy templating has been removed? I am certainly very sorry to see it go, esp. as I have
> found yasnippet to work only intermittently in org-mode buffers (at least for me).   I see Kaushal has added it back in his config files, but if someone has a slightly less
> specialized solution for restoring it I would love to see it. 

It's on its way back! Just slowly. Rasmus has added org-tempo.el, which
you can require to pretty much restore the old functionality. Just don't
customize anything yet, as some of the options are likely to change.

Eric

Re: Restore old easy template feature (Re: function for inserting a block)

[Rasmus]

Matt Price <moptop99@gmail.com> writes:

> On Wed, Nov 8, 2017 at 9:08 AM, Bastien Guerry <bzg@gnu.org> wrote:
>
>> Hi Kaushal,
>>
>> Kaushal Modi <kaushal.modi@gmail.com> writes:
>>
>> > I am suggesting to have a minor mode that simply binds "<" to do the
>> > template insertion (only when that is typed at BOL with optional
>> > leading whitespace, or if a region is selected).
>>
>> I think this is a great suggestion and brings the best of both the new
>> and the old system.
>>
>> I cannot test this myself until this week-end, but I'd happy too then.
>>
>
> I guess I missed this ocnversation while I was busy wiht other stuff  --
> the old easy templating has been removed? I am certainly very sorry to see
> it go, esp. as I have found yasnippet to work only intermittently in
> org-mode buffers (at least for me).   I see Kaushal has added it back in
> his config files, but if someone has a slightly less specialized solution
> for restoring it I would love to see it.
>
> I see Nicolas's point that this functionality exists elsewhere, but maybe
> someone can point to a ready-made replacement for those of us who rely on
> <s, etc., as part of our daily workflow?

(require ’org-tempo)

At the moment you can only use one character after the "<"
cf. ‘org-structure-template-alist’.  Perhaps this will change in the
future.

Rasmus

-- 
History is what should never happen again

Re: Restore old easy template feature (Re: function for inserting a block)

[Matt Price]

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

On Tue, Dec 19, 2017 at 5:04 AM, Rasmus <rasmus@gmx.us> wrote:

> Matt Price <moptop99@gmail.com> writes:
>
> > On Wed, Nov 8, 2017 at 9:08 AM, Bastien Guerry <bzg@gnu.org> wrote:
> >
> >> Hi Kaushal,
> >>
> >> Kaushal Modi <kaushal.modi@gmail.com> writes:
> >>
> >> > I am suggesting to have a minor mode that simply binds "<" to do the
> >> > template insertion (only when that is typed at BOL with optional
> >> > leading whitespace, or if a region is selected).
> >>
> >> I think this is a great suggestion and brings the best of both the new
> >> and the old system.
> >>
> >> I cannot test this myself until this week-end, but I'd happy too then.
> >>
> >
> > I guess I missed this ocnversation while I was busy wiht other stuff  --
> > the old easy templating has been removed? I am certainly very sorry to
> see
> > it go, esp. as I have found yasnippet to work only intermittently in
> > org-mode buffers (at least for me).   I see Kaushal has added it back in
> > his config files, but if someone has a slightly less specialized solution
> > for restoring it I would love to see it.
> >
> > I see Nicolas's point that this functionality exists elsewhere, but maybe
> > someone can point to a ready-made replacement for those of us who rely on
> > <s, etc., as part of our daily workflow?
>
> (require ’org-tempo)
>
> At the moment you can only use one character after the "<"
> cf. ‘org-structure-template-alist’.  Perhaps this will change in the
> future.
>
> ah ok, thank you both for the clarification, this helps a lot.

m

[-- Attachment #2: Type: text/html, Size: 2367 bytes --]

Re: Restore old easy template feature (Re: function for inserting a block)

[Nicolas Goaziou]

Hello,

Kaushal Modi <kaushal.modi@gmail.com> writes:

> I just like the convenience of hitting "<s" and let the template insertion
> logic do its thing.
>
> Let me know what you think.

There are many ways to get dumb template insertion. Org doesn't need to
implement yet another one.

Regards,

-- 
Nicolas Goaziou                                                0x80A93738

Re: function for inserting a block

[Nicolas Goaziou]

Bastien <bzg@gnu.org> writes:

> is there a simple mechanism in Emacs core to restore the same
> functionnality?

Of course, it is called Abbrev mode: (info "(emacs)Abbrev Concepts").

You may also use (info "(autotype)Using Skeletons") for more advanced
uses.

Regards,

Re: function for inserting a block

[Bastien Guerry]

Hi Nicolas,

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Bastien <bzg@gnu.org> writes:
>
>> is there a simple mechanism in Emacs core to restore the same
>> functionnality?
>
> Of course, it is called Abbrev mode: (info "(emacs)Abbrev
> Concepts").

Abbrev only expands on words constituents, so "<s" would not work.

> You may also use (info "(autotype)Using Skeletons") for more advanced
> uses.

I see.  So combining the two, we would have something like this:

(define-skeleton org-skeleton-src-block
     "" nil
     >
     "#+begin_src" \n
     _ \n
     "#+end_src")

(define-abbrev org-mode-abbrev-table "<s"
      "" 'org-skeleton-src-block)

... modulo the restriction on "<s" mentioned above.

I need to think about this and Kaushal proposal to see if we can
come up with a simple and backward-compatible solution.

Already thanks for the pointers.

-- 
 Bastien

Re: function for inserting a block

[Eric Abrahamsen]

Bastien Guerry <bzg@gnu.org> writes:

> Hi Nicolas,
>
> Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:
>
>> Bastien <bzg@gnu.org> writes:
>>
>>> is there a simple mechanism in Emacs core to restore the same
>>> functionnality?
>>
>> Of course, it is called Abbrev mode: (info "(emacs)Abbrev
>> Concepts").
>
> Abbrev only expands on words constituents, so "<s" would not work.
>
>> You may also use (info "(autotype)Using Skeletons") for more advanced
>> uses.
>
> I see.  So combining the two, we would have something like this:
>
> (define-skeleton org-skeleton-src-block
>      "" nil
>      >
>      "#+begin_src" \n
>      _ \n
>      "#+end_src")
>
> (define-abbrev org-mode-abbrev-table "<s"
>       "" 'org-skeleton-src-block)
>
> ... modulo the restriction on "<s" mentioned above.
>
> I need to think about this and Kaushal proposal to see if we can
> come up with a simple and backward-compatible solution.
>
> Already thanks for the pointers.

I'd be happy to add something to the manual, once we've got a clear way
of replicating the old system.

Re: function for inserting a block

[William Denton]

On 8 November 2017, Bastien wrote:

> I'm aware of Yasnippet, but it is not in Emacs core and it can
> be daunting for newcomers to install, customize and use.
>
> The previous function was very straightforward and simple, the
> cost for losing it seems to high to me.  I'd rather have 10 lines
> in Org (and in Emacs core) for it, than to ask users to install
> something that does a lot more that they don't need.

I just realized that <s had stopped working, and I miss it.  That's a great 
feature.  I hope it comes back so that a little bit of the helpful Org magic is 
built right in.

Bill
--
William Denton :: Toronto, Canada   ---   Listening to Art: https://listeningtoart.org/
https://www.miskatonic.org/         ---   GHG.EARTH: http://ghg.earth/
Caveat lector.                      ---   STAPLR: http://staplr.org/

Re: function for inserting a block

[Rasmus]

Hi,

Thanks you, Eric, for providing this new functionality.

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Bastien <bzg@gnu.org> writes:
>
>> Maybe I missed something in this thread, but what about making
>> the change backward-compatible by allowing "<s" (or variants) to
>> be expanded?  For me, I'd rather type <s TAB than `C-c C-x w s'.
>
> I suggested the idea to remove "<s". The idea behind this remove is that
> many other template systems, e.g., YASnippet, already provides this.
> I didn't want to re-implement the wheel and let, instead, various parts
> of Emacs cooperate.

I am only reading the thread now; my apology for coming late to the "party".

I think the template expansion a la "<s" is brilliant.  I used to have
YASnippet installed for many years, and I never figured out how to use it
properly.  To me, it is a bit too complex a replacement.

I wonder if skeleton.el or abbrev could be used?  Perhaps it is sufficient
(for me) to bind the new function to "<".

Thanks,
Rasmus

PS: Thanks for remembering and advocating my distaste for the FORTRAN-ORG
style!

-- 
⠠⠵

Re: function for inserting a block

[Berry, Charles]

> On Nov 8, 2017, at 6:07 AM, Rasmus <rasmus@gmx.us> wrote:
> 
> I think the template expansion a la "<s" is brilliant.  I used to have
> YASnippet installed for many years, and I never figured out how to use it
> properly.  To me, it is a bit too complex a replacement.


Me too.  "<s" just works. And it is brutally easy to extend.

I suspect that there will be cries of pain and anger from others who have not tuned in to this thread if it is removed.

Chuck

Re: function for inserting a block

[Nicolas Goaziou]

Hello,

"Berry, Charles" <ccberry@ucsd.edu> writes:

>> On Nov 8, 2017, at 6:07 AM, Rasmus <rasmus@gmx.us> wrote:
>> 
>> I think the template expansion a la "<s" is brilliant.  I used to have
>> YASnippet installed for many years, and I never figured out how to use it
>> properly.  To me, it is a bit too complex a replacement.
>
>
> Me too.  "<s" just works. And it is brutally easy to extend.
>
> I suspect that there will be cries of pain and anger from others who
> have not tuned in to this thread if it is removed.

Emacs provides already a lot of function for that. I don't think "<s"
was superior to them.

Regards,

-- 
Nicolas Goaziou

Re: function for inserting a block

[Thomas S. Dye]

Berry, Charles writes:

>> On Nov 8, 2017, at 6:07 AM, Rasmus <rasmus@gmx.us> wrote:
>>
>> I think the template expansion a la "<s" is brilliant.  I used to have
>> YASnippet installed for many years, and I never figured out how to use it
>> properly.  To me, it is a bit too complex a replacement.
>
>
> Me too.  "<s" just works. And it is brutally easy to extend.
>
> I suspect that there will be cries of pain and anger from others who have not tuned in to this thread if it is removed.
>
> Chuck

Agreed.  It would be great if backward compatibility could be
maintained.  I use (org-try-structure-completion) all the time.

All the best,
Tom

--
Thomas S. Dye
http://www.tsdye.com

Re: function for inserting a block

[Takaaki Ishikawa]

I also support the idea of keeping "<s" as it was.
Please give importance to the backward compatibility in this case.

Best regards,
Takaaki Ishikawa

2017-11-09 3:24 GMT+09:00 Thomas S. Dye <tsd@tsdye.com>:
>
> Berry, Charles writes:
>
>>> On Nov 8, 2017, at 6:07 AM, Rasmus <rasmus@gmx.us> wrote:
>>>
>>> I think the template expansion a la "<s" is brilliant.  I used to have
>>> YASnippet installed for many years, and I never figured out how to use it
>>> properly.  To me, it is a bit too complex a replacement.
>>
>>
>> Me too.  "<s" just works. And it is brutally easy to extend.
>>
>> I suspect that there will be cries of pain and anger from others who have not tuned in to this thread if it is removed.
>>
>> Chuck
>
> Agreed.  It would be great if backward compatibility could be
> maintained.  I use (org-try-structure-completion) all the time.
>
> All the best,
> Tom
>
> --
> Thomas S. Dye
> http://www.tsdye.com
>

Re: function for inserting a block

[Eric Abrahamsen]

Perhaps what we can do is re-instate this functionality using the
built-in Emacs mechanisms?

Re: function for inserting a block

[Nicolas Goaziou]

Hello,

Takaaki Ishikawa <takaxp@ieee.org> writes:

> I also support the idea of keeping "<s" as it was.
> Please give importance to the backward compatibility in this case.

I explained why I thought it could be removed. I also suggested
solutions to get an equivalent feature without implementing it in Org.

What is wrong with Abbrev mode, skeletons, tempo.el, expand.el, all
bundled with Emacs, or YASnippet, in the Emacs ecosystem? It sounds like
NIH. Or, to put it differently: why in the world would Org implement its
own template system?

The only argument so far is "<" cannot be expanded since it not word
constituent. Seriously. "<" has no meaning anyway. You can use "@",
which is word constituent and just as meaningless. So, you can define,
e.g., a skeleton, that will expand "@s" to "#+begin_src\n#+end_src".

We can even document how to do it in the manual.

Regards,

-- 
Nicolas Goaziou

Re: function for inserting a block

[Thomas S. Dye]

Aloha Nicolas,

Nicolas Goaziou writes:

> Hello,
>
> Takaaki Ishikawa <takaxp@ieee.org> writes:
>
>> I also support the idea of keeping "<s" as it was.
>> Please give importance to the backward compatibility in this case.
>
> I explained why I thought it could be removed. I also suggested
> solutions to get an equivalent feature without implementing it in Org.
>
> What is wrong with Abbrev mode, skeletons, tempo.el, expand.el, all
> bundled with Emacs, or YASnippet, in the Emacs ecosystem? It sounds like
> NIH. Or, to put it differently: why in the world would Org implement its
> own template system?

The "why in the world" question is likely one that can be answered by
the author of the Org template system.

> The only argument so far is "<" cannot be expanded since it not word
> constituent. Seriously. "<" has no meaning anyway. You can use "@",
> which is word constituent and just as meaningless. So, you can define,
> e.g., a skeleton, that will expand "@s" to "#+begin_src\n#+end_src".
>
> We can even document how to do it in the manual.

For me, the issue isn't about how the template system is implemented, it
is about backwards compatibility of (org-try-structure-completion).

All the best,
Tom

--
Thomas S. Dye
http://www.tsdye.com

Re: function for inserting a block

[Carsten Dominik]

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

On Thu, Nov 9, 2017 at 5:31 AM, Thomas S. Dye <tsd@tsdye.com> wrote:

> Aloha Nicolas,
>
> Nicolas Goaziou writes:
>
> > Hello,
> >
> > Takaaki Ishikawa <takaxp@ieee.org> writes:
> >
> >> I also support the idea of keeping "<s" as it was.
> >> Please give importance to the backward compatibility in this case.
> >
> > I explained why I thought it could be removed. I also suggested
> > solutions to get an equivalent feature without implementing it in Org.
> >
> > What is wrong with Abbrev mode, skeletons, tempo.el, expand.el, all
> > bundled with Emacs, or YASnippet, in the Emacs ecosystem? It sounds like
> > NIH. Or, to put it differently: why in the world would Org implement its
> > own template system?
>
> The "why in the world" question is likely one that can be answered by
> the author of the Org template system.
>

I guess that would be me.

The reason why I implemented it was the same reason why I implemented
org-mode.  It scratched an itch that I was having, and so I implemented it
to solve this issue, without much regard for existing expansion systems -
back then, I am not sure which of them did even exist and how easy it would
have been to deal with dependencies.

The reason why the leading character is "<" lies in the fact that, at the
time, I was experimenting with HTML tags, mainly because this was how emacs
MUSE was handling markup.  I left it at that because it led to very few
conflicts and because "<" is a character that is easily typed.

I have always come down on the side of NOT breaking backward compatibility
unless we really HAVE TO in order to make progress.  The reason for this
bias is because most Org users are not reading this maling list and just
want the system to function and to continue to function the way they are
used to, while it is hopefully improving.  It will stop them from upgrading
if such breakage happens too often.

So I would support reimplement the expansion (including
org-try-structure-completion
for people who use that in custom code), if possible of course on the back
of one of the built-in expansion systems in Emacs, before pushing this
change out in a release.  I would certainly reimplement this in some way
for myself, because using these abbreviations is already hardcoded in my
spine, I think.

That does not take away from that fact that I am really happy we now can
wrap existing text into a block structure.  Very useful indeed.

Carsten


>
> > The only argument so far is "<" cannot be expanded since it not word
> > constituent. Seriously. "<" has no meaning anyway. You can use "@",
> > which is word constituent and just as meaningless. So, you can define,
> > e.g., a skeleton, that will expand "@s" to "#+begin_src\n#+end_src".
> >
> > We can even document how to do it in the manual.
>
> For me, the issue isn't about how the template system is implemented, it
> is about backwards compatibility of (org-try-structure-completion).
>
> All the best,
> Tom
>
> --
> Thomas S. Dye
> http://www.tsdye.com
>
>

[-- Attachment #2: Type: text/html, Size: 4199 bytes --]

Re: function for inserting a block

[Matt Lundin]

Carsten Dominik <dominik@uva.nl> writes:

> I have always come down on the side of NOT breaking backward
> compatibility unless we really HAVE TO in order to make progress. The
> reason for this bias is because most Org users are not reading this
> maling list and just want the system to function and to continue to
> function the way they are used to, while it is hopefully improving. It
> will stop them from upgrading if such breakage happens too often.
>
> So I would support reimplement the expansion (including
> org-try-structure-completion for people who use that in custom code),
> if possible of course on the back of one of the built-in expansion
> systems in Emacs, before pushing this change out in a release. I would
> certainly reimplement this in some way for myself, because using these
> abbreviations is already hardcoded in my spine, I think.

I agree. I support removing redundant code behind the scenes, but I also
think we should preserve backwards compatibility in the user interface.
A fair number of people around here have been using Org Mode for more
than a decade, and, for better or for worse, everything about the user
interface is now hardwired in their brains. 

In short, we have a time-saving expansion system that works well for
lots of people. I support re-implementing it on top of another snippet
engine but also leaving it in place until a suitable replacement is
ready.

Matt

Re: function for inserting a block

[numbchild]

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

+1 I added a snippet for `<s` in yasnippet temporaryly.

[stardiviner]           <Hack this world!>      GPG key ID: 47C32433
IRC(freeenode): stardiviner                     Twitter:  @numbchild
Key fingerprint = 9BAA 92BC CDDD B9EF 3B36  CB99 B8C4 B8E5 47C3 2433
Blog: http://stardiviner.github.io/

On Sun, Nov 12, 2017 at 12:35 PM, Matt Lundin <mdl@imapmail.org> wrote:

> Carsten Dominik <dominik@uva.nl> writes:
>
> > I have always come down on the side of NOT breaking backward
> > compatibility unless we really HAVE TO in order to make progress. The
> > reason for this bias is because most Org users are not reading this
> > maling list and just want the system to function and to continue to
> > function the way they are used to, while it is hopefully improving. It
> > will stop them from upgrading if such breakage happens too often.
> >
> > So I would support reimplement the expansion (including
> > org-try-structure-completion for people who use that in custom code),
> > if possible of course on the back of one of the built-in expansion
> > systems in Emacs, before pushing this change out in a release. I would
> > certainly reimplement this in some way for myself, because using these
> > abbreviations is already hardcoded in my spine, I think.
>
> I agree. I support removing redundant code behind the scenes, but I also
> think we should preserve backwards compatibility in the user interface.
> A fair number of people around here have been using Org Mode for more
> than a decade, and, for better or for worse, everything about the user
> interface is now hardwired in their brains.
>
> In short, we have a time-saving expansion system that works well for
> lots of people. I support re-implementing it on top of another snippet
> engine but also leaving it in place until a suitable replacement is
> ready.
>
> Matt
>
>
>

[-- Attachment #2: Type: text/html, Size: 2741 bytes --]

Re: function for inserting a block

[Rasmus]

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

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Takaaki Ishikawa <takaxp@ieee.org> writes:
>
>> I also support the idea of keeping "<s" as it was.
>> Please give importance to the backward compatibility in this case.
>
> I explained why I thought it could be removed. I also suggested
> solutions to get an equivalent feature without implementing it in Org.

Which sounds fair.

> What is wrong with Abbrev mode, skeletons, tempo.el, expand.el, all
> bundled with Emacs, or YASnippet, in the Emacs ecosystem? It sounds like
> NIH. Or, to put it differently: why in the world would Org implement its
> own template system?

tempo.el, which I was unaware of, will be able to do this.  Thanks for the
pointer.

I have started to write a replacement.  It seems to work fairly OK so far.
Not all keywords have been added, and no mechanism for adding additional
keywords is there yet.

Nicolas, what would be the best way to hook ‘tempo-complete-tag’ into
"space"?  Should I add support directly in org-self-insert-command or add
it to post-command-hook?

> The onbly argument so far is "<" cannot be expanded since it not word
> constituent. Seriously. "<" has no meaning anyway. You can use "@",
> which is word constituent and just as meaningless. So, you can define,
> e.g., a skeleton, that will expand "@s" to "#+begin_src\n#+end_src".

A small aside: on my keyboard layout < is easy to type.  I don’t like
typing @.

> We can even document how to do it in the manual.

Of course.

Thanks,
Rasmus

-- 
I feel emotional landscapes they puzzle me

[-- Attachment #2: org-tempo.el --]
[-- Type: application/emacs-lisp, Size: 2347 bytes --]

Re: function for inserting a block

[Rasmus]

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

Rasmus <rasmus@gmx.us> writes:

> Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:
>
>> Takaaki Ishikawa <takaxp@ieee.org> writes:
>>
>>> I also support the idea of keeping "<s" as it was.
>>> Please give importance to the backward compatibility in this case.
>>
>> I explained why I thought it could be removed. I also suggested
>> solutions to get an equivalent feature without implementing it in Org.
>
> Which sounds fair.
>
>> What is wrong with Abbrev mode, skeletons, tempo.el, expand.el, all
>> bundled with Emacs, or YASnippet, in the Emacs ecosystem? It sounds like
>> NIH. Or, to put it differently: why in the world would Org implement its
>> own template system?
>
> tempo.el, which I was unaware of, will be able to do this.  Thanks for the
> pointer.
>
> I have started to write a replacement.  It seems to work fairly OK so far.
> Not all keywords have been added, and no mechanism for adding additional
> keywords is there yet.
>
> Nicolas, what would be the best way to hook ‘tempo-complete-tag’ into
> "space"?  Should I add support directly in org-self-insert-command or add
> it to post-command-hook?

Actually, it should just hook into TAB (doh).

The attached version seems to replicate the old behavior more or less.  I
had to add a new custom variable to store keywords.

Also, Eric, it seems that org-structure-template-alist only supports a
single letter for short-hands (the car of an entry in
org-structure-template-alist is a char).  I used to have blocks like "<ab"
expanding to an "abstract" special-block, which I guess isn’t possible
anymore?

Should I add this file to Org?

Rasmus

-- 
Got mashed potatoes. Ain't got no T-Bone. No T-Bone

[-- Attachment #2: org-tempo.el --]
[-- Type: application/emacs-lisp, Size: 3851 bytes --]

Re: function for inserting a block

[Eric Abrahamsen]

Rasmus <rasmus@gmx.us> writes:

> Rasmus <rasmus@gmx.us> writes:
>
>> Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:
>>
>>> Takaaki Ishikawa <takaxp@ieee.org> writes:
>>>
>>>> I also support the idea of keeping "<s" as it was.
>>>> Please give importance to the backward compatibility in this case.
>>>
>>> I explained why I thought it could be removed. I also suggested
>>> solutions to get an equivalent feature without implementing it in Org.
>>
>> Which sounds fair.
>>
>>> What is wrong with Abbrev mode, skeletons, tempo.el, expand.el, all
>>> bundled with Emacs, or YASnippet, in the Emacs ecosystem? It sounds like
>>> NIH. Or, to put it differently: why in the world would Org implement its
>>> own template system?
>>
>> tempo.el, which I was unaware of, will be able to do this.  Thanks for the
>> pointer.
>>
>> I have started to write a replacement.  It seems to work fairly OK so far.
>> Not all keywords have been added, and no mechanism for adding additional
>> keywords is there yet.
>>
>> Nicolas, what would be the best way to hook ‘tempo-complete-tag’ into
>> "space"?  Should I add support directly in org-self-insert-command or add
>> it to post-command-hook?
>
> Actually, it should just hook into TAB (doh).
>
> The attached version seems to replicate the old behavior more or less.  I
> had to add a new custom variable to store keywords.
>
> Also, Eric, it seems that org-structure-template-alist only supports a
> single letter for short-hands (the car of an entry in
> org-structure-template-alist is a char).  I used to have blocks like "<ab"
> expanding to an "abstract" special-block, which I guess isn’t possible
> anymore?

I hadn't thought of that. Really, all I ever wanted was to wrap things
in blocks...

I don't see any reason why org-structure-template-alist couldn't go back
to using string keys. Then we could use read-string, and wouldn't have
to have special <TAB> behavior -- a string that didn't exist in the
alist could just be used literally to make a block.

Eric

Re: function for inserting a block

[Rasmus]

Hi Eric,

Eric Abrahamsen <eric@ericabrahamsen.net> writes:

>> Also, Eric, it seems that org-structure-template-alist only supports a
>> single letter for short-hands (the car of an entry in
>> org-structure-template-alist is a char).  I used to have blocks like "<ab"
>> expanding to an "abstract" special-block, which I guess isn’t possible
>> anymore?
>
> I hadn't thought of that. Really, all I ever wanted was to wrap things
> in blocks...
>
> I don't see any reason why org-structure-template-alist couldn't go back
> to using string keys. Then we could use read-string, and wouldn't have
> to have special <TAB> behavior -- a string that didn't exist in the
> alist could just be used literally to make a block.

I’d prefer that.  For some special blocks, a few characters might makes it
more intuitive, e.g. "def" → "definition", "hyp" → "hypothesis" etc.

Thanks,
Rasmus

-- 
Warning: Everything saved will be lost

Re: function for inserting a block

[Eric Abrahamsen]

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

Rasmus <rasmus@gmx.us> writes:

> Hi Eric,
>
> Eric Abrahamsen <eric@ericabrahamsen.net> writes:
>
>>> Also, Eric, it seems that org-structure-template-alist only supports a
>>> single letter for short-hands (the car of an entry in
>>> org-structure-template-alist is a char).  I used to have blocks like "<ab"
>>> expanding to an "abstract" special-block, which I guess isn’t possible
>>> anymore?
>>
>> I hadn't thought of that. Really, all I ever wanted was to wrap things
>> in blocks...
>>
>> I don't see any reason why org-structure-template-alist couldn't go back
>> to using string keys. Then we could use read-string, and wouldn't have
>> to have special <TAB> behavior -- a string that didn't exist in the
>> alist could just be used literally to make a block.
>
> I’d prefer that.  For some special blocks, a few characters might makes it
> more intuitive, e.g. "def" → "definition", "hyp" → "hypothesis" etc.

Here's the simplest solution. 

There still remains the fact that `org-structure-template-alist' has
changed format, and `org-try-structure-completion' no longer exists.
That may still annoy some people who were using the internals of the
process, but...


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: stringkeys.diff --]
[-- Type: text/x-diff, Size: 2486 bytes --]

diff --git a/lisp/org.el b/lisp/org.el
index f873f1021..7c451d525 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -11857,42 +11857,40 @@ keywords relative to each registered export back-end."
     "TITLE:" "TODO:" "TYP_TODO:" "SELECT_TAGS:" "EXCLUDE_TAGS:"))
 
 (defcustom org-structure-template-alist
-  '((?a . "export ascii")
-    (?c . "center")
-    (?C . "comment")
-    (?e . "example")
-    (?E . "export")
-    (?h . "export html")
-    (?l . "export latex")
-    (?q . "quote")
-    (?s . "src")
-    (?v . "verse"))
+  '(("a" . "export ascii")
+    ("c" . "center")
+    ("C" . "comment")
+    ("e" . "example")
+    ("E" . "export")
+    ("h" . "export html")
+    ("l" . "export latex")
+    ("q" . "quote")
+    ("s" . "src")
+    ("v" . "verse"))
   "Structure completion elements.
 This is an alist of characters and values.  When
-`org-insert-structure-template' is called, an additional key is
-read.  The key is first looked up in this alist, and the
-corresponding structure is inserted, with \"#+BEGIN_\" and
-\"#+END_\" added automatically."
+`org-insert-structure-template' is called, a string key is read.
+The key is first looked up in this alist, and the corresponding
+structure is inserted, with \"#+BEGIN_\" and \"#+END_\" added
+automatically."
   :group 'org-completion
   :type '(repeat
-	  (cons (character :tag "Key")
+	  (cons (string :tag "Key")
 		(string :tag "Template")))
   :package-version '(Org . "9.2"))
 
 (defun org-insert-structure-template (type)
   "Insert a block structure of the type #+begin_foo/#+end_foo.
-First read a character, which can be one of the keys in
-`org-structure-template-alist'.  When it is <TAB>, prompt the
-user for a string to use.  With an active region, wrap the region
-in the block.  Otherwise, insert an empty block."
+First read a string, which is used as a lookup key in
+`org-structure-template-alist' or, failing that, used literally.
+With an active region, wrap the region in the block.  Otherwise,
+insert an empty block."
   (interactive
    (list
-    (let* ((key (read-key "Key: "))
+    (let* ((key (read-string "Key: "))
 	   (struct-string
-	    (or (cdr (assq key org-structure-template-alist))
-		(and (= key ?\t)
-		     (read-string "Structure type: "))
-		(user-error "`%c' has no structure definition" key))))
+	    (or (cdr (assoc-string key org-structure-template-alist))
+		key)))
       struct-string)))
   (let* ((region? (use-region-p))
 	 (s (if region? (region-beginning) (point)))

Re: function for inserting a block

[Thomas S. Dye]

Eric Abrahamsen writes:

> Rasmus <rasmus@gmx.us> writes:
>
>> Hi Eric,
>>
>> Eric Abrahamsen <eric@ericabrahamsen.net> writes:
>>
>>>> Also, Eric, it seems that org-structure-template-alist only supports a
>>>> single letter for short-hands (the car of an entry in
>>>> org-structure-template-alist is a char).  I used to have blocks like "<ab"
>>>> expanding to an "abstract" special-block, which I guess isn’t possible
>>>> anymore?
>>>
>>> I hadn't thought of that. Really, all I ever wanted was to wrap things
>>> in blocks...
>>>
>>> I don't see any reason why org-structure-template-alist couldn't go back
>>> to using string keys. Then we could use read-string, and wouldn't have
>>> to have special <TAB> behavior -- a string that didn't exist in the
>>> alist could just be used literally to make a block.
>>
>> I’d prefer that.  For some special blocks, a few characters might makes it
>> more intuitive, e.g. "def" → "definition", "hyp" → "hypothesis" etc.
>
> Here's the simplest solution.
>
> There still remains the fact that `org-structure-template-alist' has
> changed format, and `org-try-structure-completion' no longer exists.
> That may still annoy some people who were using the internals of the
> process, but...

Would something like this work?

(defun org-try-structure-completion ()
  (tempo-complete-tag))

All the best,
Tom

--
Thomas S. Dye
http://www.tsdye.com

Re: function for inserting a block

[Eric Abrahamsen]

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

"Thomas S. Dye" <tsd@tsdye.com> writes:

> Eric Abrahamsen writes:
>
>> Rasmus <rasmus@gmx.us> writes:
>>
>>> Hi Eric,
>>>
>>> Eric Abrahamsen <eric@ericabrahamsen.net> writes:
>>>
>>>>> Also, Eric, it seems that org-structure-template-alist only supports a
>>>>> single letter for short-hands (the car of an entry in
>>>>> org-structure-template-alist is a char).  I used to have blocks like "<ab"
>>>>> expanding to an "abstract" special-block, which I guess isn’t possible
>>>>> anymore?
>>>>
>>>> I hadn't thought of that. Really, all I ever wanted was to wrap things
>>>> in blocks...
>>>>
>>>> I don't see any reason why org-structure-template-alist couldn't go back
>>>> to using string keys. Then we could use read-string, and wouldn't have
>>>> to have special <TAB> behavior -- a string that didn't exist in the
>>>> alist could just be used literally to make a block.
>>>
>>> I’d prefer that.  For some special blocks, a few characters might makes it
>>> more intuitive, e.g. "def" → "definition", "hyp" → "hypothesis" etc.
>>
>> Here's the simplest solution.
>>
>> There still remains the fact that `org-structure-template-alist' has
>> changed format, and `org-try-structure-completion' no longer exists.
>> That may still annoy some people who were using the internals of the
>> process, but...
>
> Would something like this work?
>
> (defun org-try-structure-completion ()
>   (tempo-complete-tag))

Here's the newest version!

It incorporates Rasmus' org-tempo.el file, with modifications, and
Thomas' suggestion to re-instate `org-try-structure-completion', and,
erm, stardiviner's request to honor
`org-babel-uppercase-example-markers'.

Remaining issues:

1. The "org-include" tempo template doesn't work, for reasons I don't
   understand (I've never used tempo before). Nothing happens when I hit
   <TAB>.
2. Now it seems like there should be completion when prompting for a
   string key. Feature creep! But likely worthwhile feature creep.
3. I've rather rashly renamed the relevant customization options
   `org-structure-block-alist' (for blocks added via
   `org-insert-structure-template') and `org-structure-keyword-alist'
   (for keywords insertable via the tempo system). Perhaps this was a
   bad idea. If it's not a bad idea, maybe
   `org-insert-structure-template' should be renamed `org-insert-block'
   or something like that.
3. Docs need to be updated.

Comments welcome!

Eric


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: tempostructure.diff --]
[-- Type: text/x-diff, Size: 6945 bytes --]

diff --git a/lisp/org-tempo.el b/lisp/org-tempo.el
new file mode 100644
index 000000000..ebe5a26c2
--- /dev/null
+++ b/lisp/org-tempo.el
@@ -0,0 +1,118 @@
+;;; org-tempo.el --- Tempo-style templates for Org -*- lexical-binding: t; -*-
+
+;; Copyright (C) 2017 Free Software Foundation, Inc.
+;;
+;; Author: Rasmus Pank Roulund <emacs at pank dot eu>
+;; Keywords: outlines, hypermedia, calendar, wp
+;; Homepage: http://orgmode.org
+;;
+;; This file is part of GNU Emacs.
+;;
+;; GNU Emacs is free software: you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
+
+;; GNU Emacs is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;; GNU General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.
+;;
+;;; Commentary:
+
+;; Block and structure templates, to replace the previous Org-specific
+;; system.  The old function `org-try-structure-completion' is
+;; provided as a thin wrapper around `tempo-complete-tag', for
+;; backwards compatibility.
+
+;;; Code:
+
+(require 'tempo)
+(require 'cl-lib)
+
+(defvar org-tempo-tags nil
+  "Tempo tags for org-mode")
+
+(defcustom org-structure-keyword-alist
+  '(("L" . "latex")
+    ("H" . "html")
+    ("A" . "ascii")
+    ("i" . "index"))
+  "Keyword templates expanded using the tempo package."
+  :group 'org-tempo
+  :type '(repeat
+	  (cons (string :tag "Key")
+		(string :tag "Template")))
+  :package-version '(Org . "9.2"))
+
+(defun org-tempo-setup ()
+  (tempo-use-tag-list 'org-tempo-tags)
+  (setq tempo-match-finder "^ *\\(<[[:word:]]\\)\\="))
+
+(add-hook 'org-mode-hook 'org-tempo-setup)
+
+(defun org-tempo-add-templates ()
+  "Update all org-tempo templates.
+Goes through `org-structure-block-alist' and
+`org-structure-keyword-alist'."
+  (let ((keys (mapcar (apply-partially #'format "<%s")
+		      (mapcar #'car (append org-structure-block-alist
+					    org-structure-keyword-alist)))))
+    (if (> (length keys)
+           (length (delete-dups keys)))
+	(user-error "Duplicate keys in `org-structure-template-alist' and `org-structure-template-alist-keywords'"))
+    (dolist (key keys)
+      (if (assoc-string key org-tempo-tags)
+	  (setq org-tempo-tags
+		(delete (assoc-string key org-tempo-tags)
+			org-tempo-tags))))
+    (mapc #'org-tempo-add-block org-structure-block-alist)
+    (mapc #'org-tempo-add-keyword org-structure-keyword-alist))
+  (setq tempo-dirty-collection t))
+
+(defun org-tempo-add-block (entry)
+  "Add block entry from `org-structure-block-alist'."
+  (let* ((key (format "<%s" (car entry)))
+	 (name (cdr entry)))
+    (tempo-define-template
+     (format "org-%s" (replace-regexp-in-string " " "-" name))
+     `(,(format "#+begin_%s " name) p '> n n
+       ,(format "#+end_%s" (car (org-split-string name " ")))
+       >)
+     key
+     (format "Insert a %s block" name)
+     'org-tempo-tags)))
+
+(defun org-tempo-add-keyword (entry)
+  "Add keyword entry from `org-structure-keyword-alist'."
+  (let* ((key (format "<%s" (car entry)))
+	 (name (cdr entry)))
+    (tempo-define-template
+     (format "org-%s" (replace-regexp-in-string " " "-" name))
+     `(,(format "#+%s: " name) p '>)
+     key
+     (format "Insert a %s keyword" name)
+     'org-tempo-tags)))
+
+;; Additional keywords
+
+(tempo-define-template
+ "org-include"
+ '("#+include: "
+   (ignore-errors
+     (format "\"%s\" " (file-relative-name (read-file-name "Include file: "))))
+   p >)
+ "<I"
+ "Include keyword"
+ 'org-tempo-tags)
+
+(with-eval-after-load 'org
+  (org-tempo-add-templates)
+  (add-hook 'org-tab-before-tab-emulation-hook
+	    'tempo-complete-tag))
+
+(provide 'org-tempo)
+;;; org-tempo.el ends here
diff --git a/lisp/org.el b/lisp/org.el
index f873f1021..9ceaa2205 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -11856,43 +11856,41 @@ keywords relative to each registered export back-end."
     "PRIORITIES:" "SELECT_TAGS:" "SEQ_TODO:" "SETUPFILE:" "STARTUP:" "TAGS:"
     "TITLE:" "TODO:" "TYP_TODO:" "SELECT_TAGS:" "EXCLUDE_TAGS:"))
 
-(defcustom org-structure-template-alist
-  '((?a . "export ascii")
-    (?c . "center")
-    (?C . "comment")
-    (?e . "example")
-    (?E . "export")
-    (?h . "export html")
-    (?l . "export latex")
-    (?q . "quote")
-    (?s . "src")
-    (?v . "verse"))
+(defcustom org-structure-block-alist
+  '(("a" . "export ascii")
+    ("c" . "center")
+    ("C" . "comment")
+    ("e" . "example")
+    ("E" . "export")
+    ("h" . "export html")
+    ("l" . "export latex")
+    ("q" . "quote")
+    ("s" . "src")
+    ("v" . "verse"))
   "Structure completion elements.
 This is an alist of characters and values.  When
-`org-insert-structure-template' is called, an additional key is
-read.  The key is first looked up in this alist, and the
-corresponding structure is inserted, with \"#+BEGIN_\" and
-\"#+END_\" added automatically."
+`org-insert-structure-template' is called, a string key is read.
+The key is first looked up in this alist, and the corresponding
+structure is inserted, with \"#+BEGIN_\" and \"#+END_\" added
+automatically."
   :group 'org-completion
   :type '(repeat
-	  (cons (character :tag "Key")
+	  (cons (string :tag "Key")
 		(string :tag "Template")))
   :package-version '(Org . "9.2"))
 
 (defun org-insert-structure-template (type)
   "Insert a block structure of the type #+begin_foo/#+end_foo.
-First read a character, which can be one of the keys in
-`org-structure-template-alist'.  When it is <TAB>, prompt the
-user for a string to use.  With an active region, wrap the region
-in the block.  Otherwise, insert an empty block."
+First read a string, which is used as a lookup key in
+`org-structure-block-alist' or, failing that, used literally.
+With an active region, wrap the region in the block.  Otherwise,
+insert an empty block."
   (interactive
    (list
-    (let* ((key (read-key "Key: "))
+    (let* ((key (read-string "Block type: "))
 	   (struct-string
-	    (or (cdr (assq key org-structure-template-alist))
-		(and (= key ?\t)
-		     (read-string "Structure type: "))
-		(user-error "`%c' has no structure definition" key))))
+	    (or (cdr (assoc-string key org-structure-block-alist))
+		key)))
       struct-string)))
   (let* ((region? (use-region-p))
 	 (s (if region? (region-beginning) (point)))
@@ -11923,6 +11921,10 @@ in the block.  Otherwise, insert an empty block."
       (end-of-line))
     (set-marker e nil)))
 
+;; For backward compatibility with the previous system.
+(defun org-try-structure-completion ()
+  (tempo-complete-tag))
+
 ;;;; TODO, DEADLINE, Comments
 
 (defun org-toggle-comment ()

Re: function for inserting a block

[numbchild]

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

I think the function `org-insert-structure-template' also should respect
the `org-babel-uppercase-example-markers'.
Besides, your new diff does not have a condition on
`org-babel-uppercase-example-markers', you just use `upcase-initials` by
default. Then the new `tempo` snippets will be uppercase, but the
`org-insert-structure-template` inserted templates will be different.

[stardiviner]           <Hack this world!>      GPG key ID: 47C32433
IRC(freeenode): stardiviner                     Twitter:  @numbchild
Key fingerprint = 9BAA 92BC CDDD B9EF 3B36  CB99 B8C4 B8E5 47C3 2433
Blog: http://stardiviner.github.io/

On Wed, Nov 15, 2017 at 5:36 AM, Eric Abrahamsen <eric@ericabrahamsen.net>
wrote:

> "Thomas S. Dye" <tsd@tsdye.com> writes:
>
> > Eric Abrahamsen writes:
> >
> >> Rasmus <rasmus@gmx.us> writes:
> >>
> >>> Hi Eric,
> >>>
> >>> Eric Abrahamsen <eric@ericabrahamsen.net> writes:
> >>>
> >>>>> Also, Eric, it seems that org-structure-template-alist only supports
> a
> >>>>> single letter for short-hands (the car of an entry in
> >>>>> org-structure-template-alist is a char).  I used to have blocks like
> "<ab"
> >>>>> expanding to an "abstract" special-block, which I guess isn’t
> possible
> >>>>> anymore?
> >>>>
> >>>> I hadn't thought of that. Really, all I ever wanted was to wrap things
> >>>> in blocks...
> >>>>
> >>>> I don't see any reason why org-structure-template-alist couldn't go
> back
> >>>> to using string keys. Then we could use read-string, and wouldn't have
> >>>> to have special <TAB> behavior -- a string that didn't exist in the
> >>>> alist could just be used literally to make a block.
> >>>
> >>> I’d prefer that.  For some special blocks, a few characters might
> makes it
> >>> more intuitive, e.g. "def" → "definition", "hyp" → "hypothesis" etc.
> >>
> >> Here's the simplest solution.
> >>
> >> There still remains the fact that `org-structure-template-alist' has
> >> changed format, and `org-try-structure-completion' no longer exists.
> >> That may still annoy some people who were using the internals of the
> >> process, but...
> >
> > Would something like this work?
> >
> > (defun org-try-structure-completion ()
> >   (tempo-complete-tag))
>
> Here's the newest version!
>
> It incorporates Rasmus' org-tempo.el file, with modifications, and
> Thomas' suggestion to re-instate `org-try-structure-completion', and,
> erm, stardiviner's request to honor
> `org-babel-uppercase-example-markers'.
>
> Remaining issues:
>
> 1. The "org-include" tempo template doesn't work, for reasons I don't
>    understand (I've never used tempo before). Nothing happens when I hit
>    <TAB>.
> 2. Now it seems like there should be completion when prompting for a
>    string key. Feature creep! But likely worthwhile feature creep.
> 3. I've rather rashly renamed the relevant customization options
>    `org-structure-block-alist' (for blocks added via
>    `org-insert-structure-template') and `org-structure-keyword-alist'
>    (for keywords insertable via the tempo system). Perhaps this was a
>    bad idea. If it's not a bad idea, maybe
>    `org-insert-structure-template' should be renamed `org-insert-block'
>    or something like that.
> 3. Docs need to be updated.
>
> Comments welcome!
>
> Eric
>
>

[-- Attachment #2: Type: text/html, Size: 4971 bytes --]

Re: function for inserting a block

[Eric Abrahamsen]

"numbchild@gmail.com" <numbchild@gmail.com> writes:

> I think the function `org-insert-structure-template' also should respect the `org-babel-uppercase-example-markers'.
> Besides, your new diff does not have a condition on `org-babel-uppercase-example-markers', you just use `upcase-initials` by default. Then the new `tempo` snippets
> will be uppercase, but the `org-insert-structure-template` inserted templates will be different.

I'm not entirely understanding you here -- it is
`org-insert-structure-template' that respects
`org-babel-uppercase-example-markers', not the tempo snippet (which was
an omission). And none of the code is using `upcase-initials'.

As far as I can see, the bug is that EXAMPLE is uppercased but the
"begin" and "end" aren't, and also that the tempo snippet doesn't
capitalize at all...

Re: function for inserting a block

[numbchild]

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

Yeah, I misunderstand your code. Anyway, It should be like this:

#+BEGIN_SRC python
...
#+END_SRC

#+BEGIN_EXAMPLE
...
#+END_EXAMPLE

etc

[stardiviner]           <Hack this world!>      GPG key ID: 47C32433
IRC(freeenode): stardiviner                     Twitter:  @numbchild
Key fingerprint = 9BAA 92BC CDDD B9EF 3B36  CB99 B8C4 B8E5 47C3 2433
Blog: http://stardiviner.github.io/

On Thu, Nov 16, 2017 at 12:24 AM, Eric Abrahamsen <eric@ericabrahamsen.net>
wrote:

> "numbchild@gmail.com" <numbchild@gmail.com> writes:
>
> > I think the function `org-insert-structure-template' also should
> respect the `org-babel-uppercase-example-markers'.
> > Besides, your new diff does not have a condition on
> `org-babel-uppercase-example-markers', you just use `upcase-initials` by
> default. Then the new `tempo` snippets
> > will be uppercase, but the `org-insert-structure-template` inserted
> templates will be different.
>
> I'm not entirely understanding you here -- it is
> `org-insert-structure-template' that respects
> `org-babel-uppercase-example-markers', not the tempo snippet (which was
> an omission). And none of the code is using `upcase-initials'.
>
> As far as I can see, the bug is that EXAMPLE is uppercased but the
> "begin" and "end" aren't, and also that the tempo snippet doesn't
> capitalize at all...
>

[-- Attachment #2: Type: text/html, Size: 2989 bytes --]

Re: function for inserting a block

[Eric Abrahamsen]

"numbchild@gmail.com" <numbchild@gmail.com> writes:

> Yeah, I misunderstand your code. Anyway, It should be like this:
>
> #+BEGIN_SRC python
> ...
> #+END_SRC
>
> #+BEGIN_EXAMPLE
> ...
> #+END_EXAMPLE
>
> etc

If you look back up this (admittedly very long) thread, you'll see the
general consensus is to move to lower-case tags. I've intentionally left
things lowercase, and now will have to handle "example" specially, based
on the value of `org-babel-uppercase-example-markers'.

Re: function for inserting a block

[numbchild]

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

Ok, I see, Just I have to replace all uppercased babels and example blocks
to lowercase to keep same.
I have a lot of org files. Huge for me.
I can take with the lower-case tag.

[stardiviner]           <Hack this world!>      GPG key ID: 47C32433
IRC(freeenode): stardiviner                     Twitter:  @numbchild
Key fingerprint = 9BAA 92BC CDDD B9EF 3B36  CB99 B8C4 B8E5 47C3 2433
Blog: http://stardiviner.github.io/

On Sat, Nov 18, 2017 at 3:14 AM, Eric Abrahamsen <eric@ericabrahamsen.net>
wrote:

> "numbchild@gmail.com" <numbchild@gmail.com> writes:
>
> > Yeah, I misunderstand your code. Anyway, It should be like this:
> >
> > #+BEGIN_SRC python
> > ...
> > #+END_SRC
> >
> > #+BEGIN_EXAMPLE
> > ...
> > #+END_EXAMPLE
> >
> > etc
>
> If you look back up this (admittedly very long) thread, you'll see the
> general consensus is to move to lower-case tags. I've intentionally left
> things lowercase, and now will have to handle "example" specially, based
> on the value of `org-babel-uppercase-example-markers'.
>
>
>

[-- Attachment #2: Type: text/html, Size: 2066 bytes --]

Re: function for inserting a block

[Rasmus]

Hi Eric,


> It incorporates Rasmus' org-tempo.el file, with modifications, and
> Thomas' suggestion to re-instate `org-try-structure-completion', and,
> erm, stardiviner's request to honor
> `org-babel-uppercase-example-markers'.
>
> Remaining issues:
>
> 1. The "org-include" tempo template doesn't work, for reasons I don't
>    understand (I've never used tempo before). Nothing happens when I hit
>    <TAB>.
> 2. Now it seems like there should be completion when prompting for a
>    string key. Feature creep! But likely worthwhile feature creep.
> 3. I've rather rashly renamed the relevant customization options
>    `org-structure-block-alist' (for blocks added via
>    `org-insert-structure-template') and `org-structure-keyword-alist'
>    (for keywords insertable via the tempo system). Perhaps this was a
>    bad idea. If it's not a bad idea, maybe
>    `org-insert-structure-template' should be renamed `org-insert-block'
>    or something like that.
> 3. Docs need to be updated.

I will have a look at org-tempo and try to figure out why it isn’t
working.  As it would probably warrant changes to ORG-NEWS and maybe the
manual I will do it in a separate commit if people find it useful.

Rasmus
-- 
Hvor meget poesi tror De kommer ud af et glas isvand?

Re: function for inserting a block

[Eric Abrahamsen]

Rasmus <rasmus@gmx.us> writes:

> Hi Eric,
>
>
>> It incorporates Rasmus' org-tempo.el file, with modifications, and
>> Thomas' suggestion to re-instate `org-try-structure-completion', and,
>> erm, stardiviner's request to honor
>> `org-babel-uppercase-example-markers'.
>>
>> Remaining issues:
>>
>> 1. The "org-include" tempo template doesn't work, for reasons I don't
>>    understand (I've never used tempo before). Nothing happens when I hit
>>    <TAB>.
>> 2. Now it seems like there should be completion when prompting for a
>>    string key. Feature creep! But likely worthwhile feature creep.
>> 3. I've rather rashly renamed the relevant customization options
>>    `org-structure-block-alist' (for blocks added via
>>    `org-insert-structure-template') and `org-structure-keyword-alist'
>>    (for keywords insertable via the tempo system). Perhaps this was a
>>    bad idea. If it's not a bad idea, maybe
>>    `org-insert-structure-template' should be renamed `org-insert-block'
>>    or something like that.
>> 3. Docs need to be updated.
>
> I will have a look at org-tempo and try to figure out why it isn’t
> working.  As it would probably warrant changes to ORG-NEWS and maybe the
> manual I will do it in a separate commit if people find it useful.

Thanks! NEWS and the manual will have to be updated, yes. But I still
think this whole change should go in at once, because we'll need to
coordinate the shift from char keys to string keys in both
`org-structure-block-alist' and `org-structure-keyword-alist' (or
whatever those end up getting named).

Eric

Re: function for inserting a block

[stardiviner]

I agree. I hope this feature too.

+1


On 11/10/2017 05:31 PM, Rasmus wrote:
> Hi Eric,
>
> Eric Abrahamsen <eric@ericabrahamsen.net> writes:
>
>>> Also, Eric, it seems that org-structure-template-alist only supports a
>>> single letter for short-hands (the car of an entry in
>>> org-structure-template-alist is a char).  I used to have blocks like "<ab"
>>> expanding to an "abstract" special-block, which I guess isn’t possible
>>> anymore?
>> I hadn't thought of that. Really, all I ever wanted was to wrap things
>> in blocks...
>>
>> I don't see any reason why org-structure-template-alist couldn't go back
>> to using string keys. Then we could use read-string, and wouldn't have
>> to have special <TAB> behavior -- a string that didn't exist in the
>> alist could just be used literally to make a block.
> I’d prefer that.  For some special blocks, a few characters might makes it
> more intuitive, e.g. "def" → "definition", "hyp" → "hypothesis" etc.
>
> Thanks,
> Rasmus
>