Re: function for inserting a block

[Nicolas Goaziou <mail@nicolasgoaziou.fr>]

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