; Improve documentation of 'treesit-language-source-alist'

* lisp/treesit.el (treesit--install-language-grammar-build-recipe)
(treesit-install-language-grammar):  Doc fixes.
(treesit-install-language-grammar): Autoload it.

* etc/NEWS: Improve wording of the
'treesit-install-language-grammar' documentation.

diff --git a/etc/NEWS b/etc/NEWS
index e679b904a65b8ac248953ad51a805eb85d2872c4..38a8798507a6de608cb3f321817ccf6ce252dedd 100644 (file)
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -63,18 +63,17 @@ the other shared libraries used by Emacs, or in the "tree-sitter"
 subdirectory of your 'user-emacs-directory', or in a directory
 mentioned in the variable 'treesit-extra-load-path'.
 
-Emacs provides a user command, 'treesit-install-language-grammar',
-that automates the building process.  A third-party major mode package
-could instruct its users to set 'treesit-language-source-alist'
-accordingly and use that command to download and compile the language
-grammar.  A user could also use that command directly and manually
-guide it through the process.
-
 You only need to install language grammar libraries required by the
 Emacs modes you will use, as Emacs loads these libraries only when the
 corresponding mode is turned on in some buffer for the first time in
 an Emacs session.
 
+Emacs provides a user command, 'treesit-install-language-grammar',
+that automates the download and build process of a grammar library.
+It prompts for the language, the URL of the language grammar's VCS
+repository, and then uses the installed C/C++ compiler to build the
+library and install it.
+
 +++
 ** Emacs can be built with built-in support for accessing SQLite databases.
 This uses the popular sqlite3 library, and can be disabled by using

diff --git a/lisp/treesit.el b/lisp/treesit.el
index 1ca72af5c2d9c9ad757bab598ee23dbc4b8c23d1..933d53082f951c6384dc3fff3439217ee286e3df 100644 (file)
--- a/lisp/treesit.el
+++ b/lisp/treesit.el
@@ -2633,7 +2633,7 @@ CC and C++ are C and C++ compilers, defaulting to \"cc\" and
 \"c++\", respectively.")
 
 (defun treesit--install-language-grammar-build-recipe (lang)
-  "Interactively build a recipe for LANG and return it.
+  "Interactively produce a download/build recipe for LANG and return it.
 See `treesit-language-source-alist' for details."
   (when (y-or-n-p (format "There is no recipe for %s, do you want to build it interactively?" lang))
     (cl-labels ((empty-string-to-nil (string)
@@ -2655,9 +2655,14 @@ See `treesit-language-source-alist' for details."
         (read-string
          "Enter the C++ compiler to use (default: auto-detect): "))))))
 
+;;;###autoload
 (defun treesit-install-language-grammar (lang)
   "Build and install the tree-sitter language grammar library for LANG.
 
+Interactively, if `treesit-language-source-alist' doesn't already
+have data for building the grammar for LANG, prompt for its
+repository URL and the C/C++ compiler to use.
+
 This command requires Git, a C compiler and (sometimes) a C++ compiler,
 and the linker to be installed and on PATH.  It also requires that the
 recipe for LANG exists in `treesit-language-source-alist'.