Merge branch 'emacs-29' of git.savannah.gnu.org:/srv/git/emacs into emacs-29

This commit is contained in:
Eli Zaretskii 2023-03-19 07:57:40 +02:00
commit 6674c362ad
14 changed files with 121 additions and 121 deletions

View file

@ -17,6 +17,7 @@ TOC:
- More features?
- Common tasks (code snippets)
- Manual
- Appendix 1
* Building Emacs with tree-sitter
@ -42,11 +43,9 @@ You can use this script that I put together here:
https://github.com/casouri/tree-sitter-module
You can also find them under this directory in /build-modules.
This script automatically pulls and builds language definitions for C,
C++, Rust, JSON, Go, HTML, JavaScript, CSS, Python, Typescript,
and C#. Better yet, I pre-built these language definitions for
C#, etc. Better yet, I pre-built these language definitions for
GNU/Linux and macOS, they can be downloaded here:
https://github.com/casouri/tree-sitter-module/releases/tag/v2.1
@ -68,6 +67,10 @@ organization has all the "official" language definitions:
https://github.com/tree-sitter
Alternatively, you can use treesit-install-language-grammar command
and follow its instructions. If everything goes right, it should
automatically download and compile the language grammar for you.
* Setting up for adding major mode features
Start Emacs and load tree-sitter with
@ -78,6 +81,10 @@ Now check if Emacs is built with tree-sitter library
(treesit-available-p)
Make sure Emacs can find the language grammar you want to use
(treesit-language-available-p 'lang)
* Tree-sitter major modes
Tree-sitter modes should be separate major modes, so other modes
@ -89,12 +96,15 @@ modes.
If the tree-sitter variant and the "native" variant could share some
setup, you can create a "base mode", which only contains the common
setup. For example, there is python-base-mode (shared), python-mode
(native), and python-ts-mode (tree-sitter).
setup. For example, python.el defines python-base-mode (shared),
python-mode (native), and python-ts-mode (tree-sitter).
In the tree-sitter mode, check if we can use tree-sitter with
treesit-ready-p, it will error out if tree-sitter is not ready.
In Emacs 30 we'll introduce some mechanism to more gracefully inherit
modes and fallback to other modes.
* Naming convention
Use tree-sitter for text (documentation, comment), use treesit for
@ -180,18 +190,17 @@ mark the offending part in red.
To enable tree-sitter font-lock, set treesit-font-lock-settings and
treesit-font-lock-feature-list buffer-locally and call
treesit-major-mode-setup. For example, see
python--treesit-settings in python.el. Below I paste a snippet of
it.
python--treesit-settings in python.el. Below is a snippet of it.
Note that like the current font-lock, if the to-be-fontified region
already has a face (ie, an earlier match fontified part/all of the
region), the new face is discarded rather than applied. If you want
later matches always override earlier matches, use the :override
keyword.
Just like the current font-lock, if the to-be-fontified region already
has a face (ie, an earlier match fontified part/all of the region),
the new face is discarded rather than applied. If you want later
matches always override earlier matches, use the :override keyword.
Each rule should have a :feature, like function-name,
string-interpolation, builtin, etc. Users can then enable/disable each
feature individually.
feature individually. See Appendix 1 at the bottom for a set of common
features names.
#+begin_src elisp
(defvar python--treesit-settings
@ -247,8 +256,7 @@ Concretely, something like this:
(string-interpolation decorator)))
(treesit-major-mode-setup))
(t
;; No tree-sitter
(setq-local font-lock-defaults ...)
;; No tree-sitter, do nothing or fallback to another mode.
...)))
#+end_src
@ -289,6 +297,7 @@ For ANCHOR we have
first-sibling => start of the first sibling
parent => start of parent
parent-bol => BOL of the line parent is on.
standalone-parent => Like parent-bol but handles more edge cases
prev-sibling => start of previous sibling
no-indent => current position (dont indent)
prev-line => start of previous line
@ -329,7 +338,8 @@ tells you which rule is applied in the echo area.
...))))
#+end_src
Then you set treesit-simple-indent-rules to your rules, and call
To setup indentation for your major mode, set
treesit-simple-indent-rules to your rules, and call
treesit-major-mode-setup:
#+begin_src elisp
@ -339,36 +349,14 @@ Then you set treesit-simple-indent-rules to your rules, and call
* Imenu
Not much to say except for utilizing treesit-induce-sparse-tree (and
explicitly pass a LIMIT argument: most of the time you don't need more
than 10). See js--treesit-imenu-1 in js.el for an example.
Once you have the index builder, set imenu-create-index-function to
it.
Set treesit-simple-imenu-settings and call
treesit-major-mode-setup.
* Navigation
Mainly beginning-of-defun-function and end-of-defun-function.
You can find the end of a defun with something like
(treesit-search-forward-goto "function_definition" 'end)
where "function_definition" matches the node type of a function
definition node, and end means we want to go to the end of that node.
Tree-sitter has default implementations for
beginning-of-defun-function and end-of-defun-function. So for
ordinary languages, it is enough to set treesit-defun-type-regexp
to something that matches all the defun struct types in the language,
and call treesit-major-mode-setup. For example,
#+begin_src emacs-lisp
(setq-local treesit-defun-type-regexp (rx bol
(or "function" "class")
"_definition"
eol))
(treesit-major-mode-setup)
#+end_src>
Set treesit-defun-type-regexp and call
treesit-major-mode-setup. You can additionally set
treesit-defun-name-function.
* Which-func
@ -376,36 +364,7 @@ If you have an imenu implementation, set which-func-functions to
nil, and which-func will automatically use imenus data.
If you want an independent implementation for which-func, you can
find the current function by going up the tree and looking for the
function_definition node. See the function below for an example.
Since Python allows nested function definitions, that function keeps
going until it reaches the root node, and records all the function
names along the way.
#+begin_src elisp
(defun python-info-treesit-current-defun (&optional include-type)
"Identical to `python-info-current-defun' but use tree-sitter.
For INCLUDE-TYPE see `python-info-current-defun'."
(let ((node (treesit-node-at (point)))
(name-list ())
(type nil))
(cl-loop while node
if (pcase (treesit-node-type node)
("function_definition"
(setq type 'def))
("class_definition"
(setq type 'class))
(_ nil))
do (push (treesit-node-text
(treesit-node-child-by-field-name node "name")
t)
name-list)
do (setq node (treesit-node-parent node))
finally return (concat (if include-type
(format "%s " type)
"")
(string-join name-list ".")))))
#+end_src
find the current function by treesit-defun-at-point.
* More features?
@ -449,7 +408,51 @@ section is Parsing Program Source. Typing
C-h i d m elisp RET g Parsing Program Source RET
will bring you to that section. You can also read the HTML version
under /html-manual in this directory. I find the HTML version easier
to read. You dont need to read through every sentence, just read the
text paragraphs and glance over function names.
will bring you to that section. You dont need to read through every
sentence, just read the text paragraphs and glance over function
names.
* Appendix 1
Below is a set of common features used by built-in major mode.
Basic tokens:
delimiter ,.; (delimit things)
operator == != || (produces a value)
bracket []{}()
misc-punctuation (other punctuation that you want to highlight)
constant true, false, null
number
keyword
comment (includes doc-comments)
string (includes chars and docstrings)
string-interpolation f"text {variable}"
escape-sequence "\n\t\\"
function every function identifier
variable every variable identifier
type every type identifier
property a.b <--- highlight b
key { a: b, c: d } <--- highlight a, c
error highlight parse error
Abstract features:
assignment: the LHS of an assignment (thing being assigned to), eg:
a = b <--- highlight a
a.b = c <--- highlight b
a[1] = d <--- highlight a
definition: the thing being defined, eg:
int a(int b) { <--- highlight a
return 0
}
int a; <-- highlight a
struct a { <--- highlight a
int b; <--- highlight b
}

View file

@ -332,7 +332,7 @@ When the block type starts from the upper case, structure template
will now insert =#+BEGIN_TYPE=. Previously, lower-case =#+begin_type= was inserted unconditionally.
*** New ox-latex tabbing support for tables.
Latex tables can now be exported to the latex tabbing environment
LaTeX tables can now be exported to the latex tabbing environment
tabbing environment]].
This is done by adding =#+ATTR_LATEX: :mode tabbing= at the top
of the table.
@ -4284,7 +4284,7 @@ parameters specific to some pre-defined translators, e.g.,
~:environment~ and ~:booktabs~ for ~orgtbl-to-latex~. See translators
docstrings (including ~orgtbl-to-generic~) for details.
*** Non-floating minted listings in Latex export
*** Non-floating minted listings in LaTeX export
It is not possible to specify =#+attr_latex: :float nil= in conjunction
with source blocks exported by the minted package.
@ -6540,7 +6540,7 @@ that Calc formulas can operate on them.
*** Hyperlinks
**** Org-Bibtex -- major improvements
**** Org-BibTeX -- major improvements
Provides support for managing bibtex bibliographical references
data in headline properties. Each headline corresponds to a

View file

@ -141,7 +141,7 @@ exporting the literal LaTeX source."
(org-trim body))
(defun org-babel-execute:latex (body params)
"Execute a block of Latex code with Babel.
"Execute a block of LaTeX code with Babel.
This function is called by `org-babel-execute-src-block'."
(setq body (org-babel-expand-body:latex body params))
(if (cdr (assq :file params))
@ -180,7 +180,7 @@ This function is called by `org-babel-execute-src-block'."
tmp-pdf
(list org-babel-latex-pdf-svg-process)
extension err-msg log-buf)))
(shell-command (format "mv %s %s" img-out out-file)))))
(rename-file img-out out-file t))))
((string-suffix-p ".tikz" out-file)
(when (file-exists-p out-file) (delete-file out-file))
(with-temp-file out-file
@ -218,17 +218,14 @@ This function is called by `org-babel-execute-src-block'."
(if (string-suffix-p ".svg" out-file)
(progn
(shell-command "pwd")
(shell-command (format "mv %s %s"
(concat (file-name-sans-extension tex-file) "-1.svg")
out-file)))
(rename-file (concat (file-name-sans-extension tex-file) "-1.svg")
out-file t))
(error "SVG file produced but HTML file requested")))
((file-exists-p (concat (file-name-sans-extension tex-file) ".html"))
(if (string-suffix-p ".html" out-file)
(shell-command "mv %s %s"
(concat (file-name-sans-extension tex-file)
".html")
out-file)
(error "HTML file produced but SVG file requested")))))
(rename-file (concat (file-name-sans-extension tex-file) ".html")
out-file t)
(error "HTML file produced but SVG file requested")))))
((or (string= "pdf" extension) imagemagick)
(with-temp-file tex-file
(require 'ox-latex)

View file

@ -86,8 +86,8 @@
;; the active region, then call `org-bibtex-write' in a .org file to
;; insert a heading for the read bibtex entry
;;
;; - All Bibtex information is taken from the document compiled by
;; Andrew Roberts from the Bibtex manual, available at
;; - All BibTeX information is taken from the document compiled by
;; Andrew Roberts from the BibTeX manual, available at
;; https://www.andy-roberts.net/res/writing/latex/bibentries.pdf
;;
;;; History:
@ -99,7 +99,7 @@
;; and then implemented by Bastien Guerry.
;;
;; Eric Schulte eventually added the functions for translating between
;; Org headlines and Bibtex entries, and for fleshing out the Bibtex
;; Org headlines and BibTeX entries, and for fleshing out the BibTeX
;; fields of existing Org headlines.
;;
;; Org mode loads this module by default - if this is not what you want,
@ -144,7 +144,7 @@
(declare-function org-search-view "org-agenda" (&optional todo-only string edit-at))
;;; Bibtex data
;;; BibTeX data
(defvar org-bibtex-types
'((:article
(:description . "An article from a journal or magazine")
@ -202,7 +202,7 @@
(:description . "A document having an author and title, but not formally published.")
(:required :author :title :note)
(:optional :month :year :doi :url)))
"Bibtex entry types with required and optional parameters.")
"BibTeX entry types with required and optional parameters.")
(defvar org-bibtex-fields
'((:address . "Usually the address of the publisher or other type of institution. For major publishing houses, van Leunen recommends omitting the information entirely. For small publishers, on the other hand, you can help the reader by giving the complete address.")
@ -231,7 +231,7 @@
(:url . "Uniform resource locator.")
(:volume . "The volume of a journal or multi-volume book.")
(:year . "The year of publication or, for an unpublished work, the year it was written. Generally it should consist of four numerals, such as 1984, although the standard styles can handle any year whose last four nonpunctuation characters are numerals, such as '(about 1984)'"))
"Bibtex fields with descriptions.")
"BibTeX fields with descriptions.")
(defvar org-bibtex-entries nil
"List to hold parsed bibtex entries.")
@ -439,7 +439,7 @@ at point."
(error "Field:%s is not known" field))
(save-window-excursion
(let* ((name (substring (symbol-name field) 1))
(buf-name (format "*Bibtex Help %s*" name)))
(buf-name (format "*BibTeX Help %s*" name)))
(with-output-to-temp-buffer buf-name
(princ (cdr (assoc field org-bibtex-fields))))
(with-current-buffer buf-name (visual-line-mode 1))
@ -496,7 +496,7 @@ With optional argument OPTIONAL, also prompt for optional fields."
(org-bibtex-autokey)))
;;; Bibtex link functions
;;; BibTeX link functions
(org-link-set-parameters "bibtex"
:follow #'org-bibtex-open
:store #'org-bibtex-store-link)
@ -593,13 +593,13 @@ ARG, when non-nil, is a universal prefix argument. See
(add-hook 'org-execute-file-search-functions 'org-execute-file-search-in-bibtex)
;;; Bibtex <-> Org headline translation functions
;;; BibTeX <-> Org headline translation functions
(defun org-bibtex (filename)
"Export each headline in the current file to a bibtex entry.
Headlines are exported using `org-bibtex-headline'."
(interactive
(list (read-file-name
"Bibtex file: " nil nil nil
"BibTeX file: " nil nil nil
(let ((file (buffer-file-name (buffer-base-buffer))))
(and file
(file-name-nondirectory
@ -619,7 +619,7 @@ Headlines are exported using `org-bibtex-headline'."
nil))))
(when error-point
(goto-char error-point)
(message "Bibtex error at %S" (nth 4 (org-heading-components))))))
(message "BibTeX error at %S" (nth 4 (org-heading-components))))))
(defun org-bibtex-check (&optional optional)
"Check the current headline for required fields.

View file

@ -3348,7 +3348,7 @@ s Search for keywords M Like m, but only TODO entries
(`agenda
(call-interactively 'org-agenda-list))
(`agenda*
(funcall 'org-agenda-list nil nil t))
(funcall 'org-agenda-list nil nil nil t))
(`alltodo
(call-interactively 'org-todo-list))
(`search

View file

@ -2462,7 +2462,7 @@ CDR is a plist containing `:key', `:value', `:begin', `:end',
(org-element-property :value keyword)))
;;;; Latex Environment
;;;; LaTeX Environment
(defconst org-element--latex-begin-environment
"^[ \t]*\\\\begin{\\([A-Za-z0-9*]+\\)}"
@ -3412,7 +3412,7 @@ CONTENTS is the contents of the object."
(format "/%s/" contents))
;;;; Latex Fragment
;;;; LaTeX Fragment
(defun org-element-latex-fragment-parser ()
"Parse LaTeX fragment at point, if any.

View file

@ -540,13 +540,13 @@ COLLECTION is the plist holding data collection."
(defun org-persist-read:file (_ path __)
"Read file container from PATH."
(when (and path (file-exists-p (concat org-persist-directory path)))
(concat org-persist-directory path)))
(when (and path (file-exists-p (org-file-name-concat org-persist-directory path)))
(org-file-name-concat org-persist-directory path)))
(defun org-persist-read:url (_ path __)
"Read file container from PATH."
(when (and path (file-exists-p (concat org-persist-directory path)))
(concat org-persist-directory path)))
(when (and path (file-exists-p (org-file-name-concat org-persist-directory path)))
(org-file-name-concat org-persist-directory path)))
(defun org-persist-read:index (cont index-file _)
"Read index container CONT from INDEX-FILE."

View file

@ -315,7 +315,7 @@ is 0.")
(defun org-src--construct-edit-buffer-name (org-buffer-name lang)
"Construct the buffer name for a source editing buffer.
Format is \"*Org Src ORG-BUFFER-NAME [ LANG ]*\"."
Format is \"*Org Src ORG-BUFFER-NAME[ LANG ]*\"."
(concat "*Org Src " org-buffer-name "[ " lang " ]*"))
(defun org-src--edit-buffer (beg end)

View file

@ -11,7 +11,7 @@ Inserted by installing Org mode or when a release is made."
(defun org-git-version ()
"The Git version of Org mode.
Inserted by installing Org or when a release is made."
(let ((org-git-version "release_9.6.1-40-g3d817c"))
(let ((org-git-version "release_9.6.1-48-g92471e"))
org-git-version))
(provide 'org-version)

View file

@ -1549,7 +1549,7 @@ information."
keyword info)))))
;;;; Latex Environment
;;;; LaTeX Environment
(defun org-ascii-latex-environment (latex-environment _contents info)
"Transcode a LATEX-ENVIRONMENT element from Org to ASCII.
@ -1561,7 +1561,7 @@ information."
latex-environment info)))
;;;; Latex Fragment
;;;; LaTeX Fragment
(defun org-ascii-latex-fragment (latex-fragment _contents info)
"Transcode a LATEX-FRAGMENT object from Org to ASCII.

View file

@ -2969,7 +2969,7 @@ CONTENTS is nil. INFO is a plist holding contextual information."
((string= "listings" value) (org-html-list-of-listings info))
((string= "tables" value) (org-html-list-of-tables info))))))))
;;;; Latex Environment
;;;; LaTeX Environment
(defun org-html-format-latex (latex-frag processing-type info)
"Format a LaTeX fragment LATEX-FRAG into HTML.
@ -3086,7 +3086,7 @@ CONTENTS is nil. INFO is a plist holding contextual information."
info caption label)))))
(t (org-html--wrap-latex-environment latex-frag info caption label)))))
;;;; Latex Fragment
;;;; LaTeX Fragment
(defun org-html-latex-fragment (latex-fragment _contents info)
"Transcode a LATEX-FRAGMENT object from Org to HTML.

View file

@ -1272,7 +1272,7 @@ used. When nil, no theme is applied."
(defun org-latex-generate-engraved-preamble (info)
"Generate the preamble to setup engraved code.
The result is constructed from the :latex-engraved-preamble and
:latex-engraved-optionsn export options, the default values of
:latex-engraved-options export options, the default values of
which are given by `org-latex-engraved-preamble' and
`org-latex-engraved-options' respectively."
(let* ((engraved-options
@ -2600,7 +2600,7 @@ CONTENTS is nil. INFO is a plist holding contextual information."
(otherwise "\\lstlistoflistings")))))))))
;;;; Latex Environment
;;;; LaTeX Environment
(defun org-latex--environment-type (latex-environment)
"Return the TYPE of LATEX-ENVIRONMENT.
@ -2658,7 +2658,7 @@ CONTENTS is nil. INFO is a plist holding contextual information."
(insert caption)
(buffer-string))))))
;;;; Latex Fragment
;;;; LaTeX Fragment
(defun org-latex-latex-fragment (latex-fragment _contents _info)
"Transcode a LATEX-FRAGMENT object from Org to LaTeX.

View file

@ -486,7 +486,7 @@ channel."
(_ (org-export-with-backend 'html keyword contents info))))
;;;; Latex Environment
;;;; LaTeX Environment
(defun org-md-latex-environment (latex-environment _contents info)
"Transcode a LATEX-ENVIRONMENT object from Org to Markdown.
@ -501,7 +501,7 @@ CONTENTS is nil. INFO is a plist holding contextual information."
latex-frag)
latex-frag))))
;;;; Latex Fragment
;;;; LaTeX Fragment
(defun org-md-latex-fragment (latex-fragment _contents info)
"Transcode a LATEX-FRAGMENT object from Org to Markdown.

View file

@ -1986,7 +1986,7 @@ information."
(ignore))))))))
;;;; Latex Environment
;;;; LaTeX Environment
;; (eval-after-load 'ox-odt '(ad-deactivate 'org-format-latex-as-mathml))
;; (advice-add 'org-format-latex-as-mathml ; FIXME
@ -2007,7 +2007,7 @@ CONTENTS is nil. INFO is a plist holding contextual information."
(org-odt-do-format-code latex-frag info)))
;;;; Latex Fragment
;;;; LaTeX Fragment
;; (when latex-frag ; FIXME
;; (setq href (propertize href :title "LaTeX Fragment"