Re: function for inserting a block

[Nicolas Goaziou <mail@nicolasgoaziou.fr>]

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