* [NonGNU ELPA] Submitting treesit-fold to NonGNU ELPA
@ 2024-06-21 21:27 Elijah G.
2024-07-01 5:51 ` Yuan Fu
0 siblings, 1 reply; 8+ messages in thread
From: Elijah G. @ 2024-06-21 21:27 UTC (permalink / raw)
To: emacs-devel; +Cc: jcs090218
Good morning everyone,
I would like to know if it's possible to add treesit-fold
(https://github.com/emacs-tree-sitter/treesit-fold)
to NonGNU ELPA.
I'm not the author or the maintainer of that package, but I've talked
with one of them (CC'ed) and they agreed to make the package available
to NonGNU.
A brief description of what the package does:
treesit-fold builds on top of treesit.el to provide code folding based
on the tree-sitter syntax tree.
treesit-fold serves as an alternative to hideshow providing,
- code folding based in tree-sitter.
- interactive visual markers for toggle folding.
- extracts comment string for have a way to peek at what's inside the
folded range.
treesit-fold works for all the modes that have a tree-sitter parser
(including the non-ts modes) with `treesit-parser-create` and have
support out-the-box for all the languages available.
--
E.G. from Gnus The Newsreader and E-mail client
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [NonGNU ELPA] Submitting treesit-fold to NonGNU ELPA
2024-06-21 21:27 [NonGNU ELPA] Submitting treesit-fold to NonGNU ELPA Elijah G.
@ 2024-07-01 5:51 ` Yuan Fu
2024-07-01 14:05 ` Stefan Monnier
0 siblings, 1 reply; 8+ messages in thread
From: Yuan Fu @ 2024-07-01 5:51 UTC (permalink / raw)
To: Elijah G.
Cc: Emacs Devel, jcs090218, Philip Kaludercic, Stefan Kangas,
Stefan Monnier
> On Jun 21, 2024, at 2:27 PM, Elijah G. <eg642616@gmail.com> wrote:
>
> Good morning everyone,
> I would like to know if it's possible to add treesit-fold
> (https://github.com/emacs-tree-sitter/treesit-fold)
> to NonGNU ELPA.
>
> I'm not the author or the maintainer of that package, but I've talked
> with one of them (CC'ed) and they agreed to make the package available
> to NonGNU.
>
> A brief description of what the package does:
> treesit-fold builds on top of treesit.el to provide code folding based
> on the tree-sitter syntax tree.
>
> treesit-fold serves as an alternative to hideshow providing,
> - code folding based in tree-sitter.
> - interactive visual markers for toggle folding.
> - extracts comment string for have a way to peek at what's inside the
> folded range.
>
> treesit-fold works for all the modes that have a tree-sitter parser
> (including the non-ts modes) with `treesit-parser-create` and have
> support out-the-box for all the languages available.
>
> --
> E.G. from Gnus The Newsreader and E-mail client
>
Thanks for working on this! Treesit-fold is quite useful and through. It’ll be a great addition to NonGNU ELPA or ELPA!
I’d be curious to see what you can achieve with the addition of “things” support in Emacs 30 ;-)
I can’t help you directly for adding treesit-fold to NonGNU ELPA. Folks who usually help with ELPA will chime in in a few days, I’m sure. Though right now people are preoccupied with the emacs 30 release so it might take a bit longer than normal.
Yuan
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [NonGNU ELPA] Submitting treesit-fold to NonGNU ELPA
2024-07-01 5:51 ` Yuan Fu
@ 2024-07-01 14:05 ` Stefan Monnier
2024-07-02 3:24 ` Elijah G.
0 siblings, 1 reply; 8+ messages in thread
From: Stefan Monnier @ 2024-07-01 14:05 UTC (permalink / raw)
To: Yuan Fu; +Cc: Elijah G., Emacs Devel, jcs090218, Philip Kaludercic,
Stefan Kangas
> Thanks for working on this! Treesit-fold is quite useful and through.
> It’ll be a great addition to NonGNU ELPA or ELPA!
I just added it to `nongnu.git`. It should hopefully appear at NonGNU
later today.
I see that there are very few other contributors beside Jen-Chieh Shen
(the main author). Since he signed the copyright paperwork, it might
not be too hard to get this into GNU ELPA.
Another thing I noticed: just as for the EditorConfig thingy, this package
comes with a `<blabla>-alist` holding per-major-mode information which
should ideally be provided directly by the major modes rather than by
the package. But just as with the EditorConfig thingy, the package did
not come with a variable which the major mode can set buffer-locally for
that purpose. Not sure how we can encourage such a design, tho.
Stefan
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [NonGNU ELPA] Submitting treesit-fold to NonGNU ELPA
2024-07-01 14:05 ` Stefan Monnier
@ 2024-07-02 3:24 ` Elijah G.
2024-07-02 13:00 ` Stefan Monnier
2024-07-02 21:30 ` Jen-Chieh Shen
0 siblings, 2 replies; 8+ messages in thread
From: Elijah G. @ 2024-07-02 3:24 UTC (permalink / raw)
To: Stefan Monnier, jcs090218
Cc: Yuan Fu, Emacs Devel, jcs090218, Philip Kaludercic, Stefan Kangas
Stefan Monnier <monnier@iro.umontreal.ca> writes:
>> Thanks for working on this! Treesit-fold is quite useful and through.
>> It’ll be a great addition to NonGNU ELPA or ELPA!
>
> I just added it to `nongnu.git`. It should hopefully appear at NonGNU
> later today.
>
> I see that there are very few other contributors beside Jen-Chieh Shen
> (the main author). Since he signed the copyright paperwork, it might
> not be too hard to get this into GNU ELPA.
I'would also like that the pacakge can get into GNU ELPA, but IMO the
problem would be the contributions since i think it could limit it
(due paperwork), also since this package is a fork of another
one [ts-fold][https://github.com/emacs-tree-sitter/ts-fold] i don't know
if it could be a problem, Jen-Chieh what do you think about this?.
> Another thing I noticed: just as for the EditorConfig thingy, this package
> comes with a `<blabla>-alist` holding per-major-mode information which
> should ideally be provided directly by the major modes rather than by
> the package. But just as with the EditorConfig thingy, the package did
> not come with a variable which the major mode can set buffer-locally for
> that purpose. Not sure how we can encourage such a design, tho.
I'm not understanding this, but if the major mode (-ts-modes) comes with
a variable for the treesitter nodes folding (like something that maybe
hideshow can use) maybe it can be possible use the
variable instead define them, the problem that i see is the
compatibility with emacs-29.
something like this?:
```
(defvar c-ts-mode-nodes-alist '((compound_statement . treesit-fold-range-seq) (declaration_list . treesit-fold-range-seq) (enumerator_list . treesit-fold-range-seq) (field_declaration_list . treesit-fold-range-seq) (preproc_if . treesit-fold-range-c-preproc-if) (preproc_ifdef . treesit-fold-range-c-preproc-ifdef) (preproc_elif . treesit-fold-range-c-preproc-elif) (preproc_else . treesit-fold-range-c-preproc-else) (comment . treesit-fold-range-c-like-comment)))
```
--
E.G. from Gnus The Emacs Newsreader and E-mail client
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [NonGNU ELPA] Submitting treesit-fold to NonGNU ELPA
2024-07-02 3:24 ` Elijah G.
@ 2024-07-02 13:00 ` Stefan Monnier
2024-07-02 21:30 ` Jen-Chieh Shen
1 sibling, 0 replies; 8+ messages in thread
From: Stefan Monnier @ 2024-07-02 13:00 UTC (permalink / raw)
To: Elijah G.
Cc: jcs090218, Yuan Fu, Emacs Devel, Philip Kaludercic, Stefan Kangas
[-- Attachment #1: Type: text/plain, Size: 1313 bytes --]
> something like this?:
> ```
> (defvar c-ts-mode-nodes-alist '((compound_statement
> . treesit-fold-range-seq) (declaration_list . treesit-fold-range-seq)
> (enumerator_list . treesit-fold-range-seq) (field_declaration_list
> . treesit-fold-range-seq) (preproc_if . treesit-fold-range-c-preproc-if)
> (preproc_ifdef . treesit-fold-range-c-preproc-ifdef) (preproc_elif
> . treesit-fold-range-c-preproc-elif) (preproc_else
> . treesit-fold-range-c-preproc-else) (comment
> . treesit-fold-range-c-like-comment)))
> ```
I was thinking of something simple like:
(defvar-local treesit-fold-ranges nil
"List (FOLDABLE-NODE-TYPE . FUNCTION).
FUNCTION is used to determine where the beginning and end for FOLDABLE-NODE-TYPE
in MAJOR-MODE. It should take a single argument (the syntax node with type
FOLDABLE-NODE-TYPE) and return the buffer positions of the beginning and end of
the fold in a cons cell. See `treesit-fold-range-python-def' for an example.
If nil, the info is fetched from `treesit-fold-range-alist' instead.")
(defun treesit-fold--ranges ()
"Return the ranges alist for the current mode."
(or treesit-fold-ranges
(alist-get major-mode treesit-fold-range-alist)))
See patch below, which comes with various other cleanups.
Stefan
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: treesit-fold.patch --]
[-- Type: text/x-diff, Size: 31500 bytes --]
diff --git a/treesit-fold-indicators.el b/treesit-fold-indicators.el
index b51cffa90e..4cec410302 100644
--- a/treesit-fold-indicators.el
+++ b/treesit-fold-indicators.el
@@ -122,8 +122,9 @@
(add-hook 'after-change-functions #'treesit-fold-indicators--trigger-render nil t)
(add-hook 'after-save-hook #'treesit-fold-indicators--trigger-render nil t)
(add-hook 'post-command-hook #'treesit-fold-indicators--post-command nil t)
- (add-hook 'window-size-change-functions #'treesit-fold-indicators--size-change)
- (add-hook 'window-scroll-functions #'treesit-fold-indicators--scroll)
+ (add-hook 'window-size-change-functions #'treesit-fold-indicators--size-change nil t)
+ (add-hook 'window-scroll-functions #'treesit-fold-indicators--scroll nil t)
+ (add-hook 'treesit-fold-on-fold-hook #'treesit-fold-indicators-refresh nil t)
(treesit-fold-indicators--render-buffer))
(treesit-fold-indicators-mode -1)))
diff --git a/treesit-fold-parsers.el b/treesit-fold-parsers.el
index b8c2f2f0dc..73e05baa4d 100644
--- a/treesit-fold-parsers.el
+++ b/treesit-fold-parsers.el
@@ -122,17 +122,17 @@
(defun treesit-fold-parsers-asm ()
"Rule set for Assembly."
- '((label . treesit-fold-range-asm-label)
+ `((label . treesit-fold-range-asm-label)
(block_comment . treesit-fold-range-c-like-comment)
(line_comment
- . (lambda (node offset)
- (let ((text (treesit-node-text node)))
- (cond ((string-prefix-p ";;" text)
- (treesit-fold-range-line-comment node offset ";;"))
- ((string-prefix-p "#" text)
- (treesit-fold-range-line-comment node offset "#"))
- (t
- (treesit-fold-range-c-like-comment node offset))))))))
+ . ,(lambda (node offset)
+ (let ((text (treesit-node-text node)))
+ (cond ((string-prefix-p ";;" text)
+ (treesit-fold-range-line-comment node offset ";;"))
+ ((string-prefix-p "#" text)
+ (treesit-fold-range-line-comment node offset "#"))
+ (t
+ (treesit-fold-range-c-like-comment node offset))))))))
(defun treesit-fold-parsers-awk ()
"Rule set for Awk."
@@ -141,18 +141,18 @@
(defun treesit-fold-parsers-bash ()
"Rule set for Bash."
- '((compound_statement . treesit-fold-range-seq)
+ `((compound_statement . treesit-fold-range-seq)
(do_group . (treesit-fold-range-seq 1 -3))
(comment
- . (lambda (node offset)
- (treesit-fold-range-line-comment node offset "#")))))
+ . ,(lambda (node offset)
+ (treesit-fold-range-line-comment node offset "#")))))
(defun treesit-fold-parsers-beancount ()
"Rule set for Beancount."
- '((transaction . treesit-fold-range-beancount-transaction)
+ `((transaction . treesit-fold-range-beancount-transaction)
(comment
- . (lambda (node offset)
- (treesit-fold-range-line-comment node offset ";;")))))
+ . ,(lambda (node offset)
+ (treesit-fold-range-line-comment node offset ";;")))))
(defun treesit-fold-parsers-c ()
"Rule set for C."
@@ -172,19 +172,19 @@
(defun treesit-fold-parsers-clojure ()
"Rule set for Clojure."
- '((list_lit . treesit-fold-range-clojure-function)
+ `((list_lit . treesit-fold-range-clojure-function)
(map_lit . treesit-fold-range-seq)
(str_lit . treesit-fold-range-seq)
(comment
- . (lambda (node offset)
- (treesit-fold-range-line-comment node offset ";;")))))
+ . ,(lambda (node offset)
+ (treesit-fold-range-line-comment node offset ";;")))))
(defun treesit-fold-parsers-cmake ()
"Rule set for CMake."
- '((body . treesit-fold-range-cmake-body)
+ `((body . treesit-fold-range-cmake-body)
(line_comment
- . (lambda (node offset)
- (treesit-fold-range-line-comment node offset "#")))))
+ . ,(lambda (node offset)
+ (treesit-fold-range-line-comment node offset "#")))))
(defun treesit-fold-parsers-csharp ()
"Rule set for C#."
@@ -220,63 +220,63 @@
(defun treesit-fold-parsers-elisp ()
"Rule set for Elisp."
- '((macro_definition . treesit-fold-range-elisp-function)
+ `((macro_definition . treesit-fold-range-elisp-function)
(function_definition . treesit-fold-range-elisp-function)
(comment
- . (lambda (node offset)
- (treesit-fold-range-line-comment node offset ";;")))))
+ . ,(lambda (node offset)
+ (treesit-fold-range-line-comment node offset ";;")))))
(defun treesit-fold-parsers-elixir ()
"Rules set for Elixir."
- '((list . treesit-fold-range-seq)
+ `((list . treesit-fold-range-seq)
(map . treesit-fold-range-seq)
(tuple . treesit-fold-range-seq)
(do_block . treesit-fold-range-elixir)
(comment
- . (lambda (node offset)
- (treesit-fold-range-line-comment node offset "#")))))
+ . ,(lambda (node offset)
+ (treesit-fold-range-line-comment node offset "#")))))
(defun treesit-fold-parsers-erlang ()
"Rules set for Erlang."
- '((list . treesit-fold-range-seq)
+ `((list . treesit-fold-range-seq)
(clause_body . treesit-fold-range-erlang-clause-body)
(type_guards . treesit-fold-range-erlang-type-guards)
(comment
- . (lambda (node offset)
- (treesit-fold-range-line-comment node offset "%")))))
+ . ,(lambda (node offset)
+ (treesit-fold-range-line-comment node offset "%")))))
(defun treesit-fold-parsers-fish ()
"Rules set for Fish."
- '((function_definition . treesit-fold-range-fish-function)
+ `((function_definition . treesit-fold-range-fish-function)
(if_statement . treesit-fold-range-fish-if)
(switch_statement . treesit-fold-range-fish-if)
(for_statement . treesit-fold-range-fish-if)
(while_statement . treesit-fold-range-fish-if)
(case_clause . treesit-fold-range-fish-case)
(comment
- . (lambda (node offset)
+ . ,(lambda (node offset)
(treesit-fold-range-line-comment node offset "#")))))
(defun treesit-fold-parsers-gdscript ()
"Rule set for GGScript."
- '((body . (treesit-fold-range-seq -1 1))
+ `((body . (treesit-fold-range-seq -1 1))
(comment
- . (lambda (node offset)
- (treesit-fold-range-line-comment node offset "#")))))
+ . ,(lambda (node offset)
+ (treesit-fold-range-line-comment node offset "#")))))
(defun treesit-fold-parsers-gleam ()
"Rules set for Gleam."
- '((function . treesit-fold-range-gleam)
+ `((function . treesit-fold-range-gleam)
(type_definition . treesit-fold-range-gleam)
(anonymous_function . treesit-fold-range-gleam)
(block . treesit-fold-range-gleam)
(list . treesit-fold-range-seq)
(module_comment
- . (lambda (node offset)
- (treesit-fold-range-line-comment node offset "////")))
+ . ,(lambda (node offset)
+ (treesit-fold-range-line-comment node offset "////")))
(statement_comment
- . (lambda (node offset)
- (treesit-fold-range-line-comment node offset "///")))))
+ . ,(lambda (node offset)
+ (treesit-fold-range-line-comment node offset "///")))))
(defun treesit-fold-parsers-glsl ()
"Rule set for GLSL."
@@ -286,14 +286,14 @@
(defun treesit-fold-parsers-go ()
"Rule set for Go."
- '((block . treesit-fold-range-seq)
+ `((block . treesit-fold-range-seq)
(comment . treesit-fold-range-c-like-comment)
- (const_declaration . (lambda (node offset)
- (treesit-fold-range-markers node offset "(" ")")))
+ (const_declaration . ,(lambda (node offset)
+ (treesit-fold-range-markers node offset "(" ")")))
(field_declaration_list . treesit-fold-range-seq)
(import_spec_list . treesit-fold-range-seq)
- (interface_type . (lambda (node offset)
- (treesit-fold-range-markers node offset "{" "}")))))
+ (interface_type . ,(lambda (node offset)
+ (treesit-fold-range-markers node offset "{" "}")))))
(defun treesit-fold-parsers-groovy ()
"Rule set for Groovy."
@@ -366,7 +366,7 @@
(defun treesit-fold-parsers-julia ()
"Rule set for Julia."
- '((block_comment . (treesit-fold-range-seq 1 -1))
+ `((block_comment . (treesit-fold-range-seq 1 -1))
(for_statement . treesit-fold-range-julia-if)
(function_definition . treesit-fold-range-julia-function)
(if_statement . treesit-fold-range-julia-if)
@@ -379,8 +379,8 @@
(try_statement . (treesit-fold-range-seq 2 -2))
(while_statement . treesit-fold-range-julia-function)
(comment
- . (lambda (node offset)
- (treesit-fold-range-line-comment node offset "#")))))
+ . ,(lambda (node offset)
+ (treesit-fold-range-line-comment node offset "#")))))
(defun treesit-fold-parsers-kotlin ()
"Rule set for Kotlin."
@@ -395,39 +395,39 @@
(defun treesit-fold-parsers-latex ()
"Rule set for LaTex."
- '((generic_environment . treesit-fold-range-latex-environment)
+ `((generic_environment . treesit-fold-range-latex-environment)
(math_environment . treesit-fold-range-latex-environment)
(section . treesit-fold-range-latex-section)
(subsection . treesit-fold-range-latex-section)
(subsubsection . treesit-fold-range-latex-section)
(curly_group . treesit-fold-range-seq)
(line_comment
- . (lambda (node offset)
- (treesit-fold-range-line-comment node offset "%")))))
+ . ,(lambda (node offset)
+ (treesit-fold-range-line-comment node offset "%")))))
(defun treesit-fold-parsers-lisp ()
"Rule set for Lisp."
- '((defun . treesit-fold-range-lisp-function)
+ `((defun . treesit-fold-range-lisp-function)
(comment
- . (lambda (node offset)
- (treesit-fold-range-line-comment node
- (treesit-fold--cons-add offset '(0 . -1))
- ";;")))))
+ . ,(lambda (node offset)
+ (treesit-fold-range-line-comment node
+ (treesit-fold--cons-add offset '(0 . -1))
+ ";;")))))
(defun treesit-fold-parsers-llvm ()
"Rule set for LLVM."
- '((function_body . treesit-fold-range-seq)
+ `((function_body . treesit-fold-range-seq)
(label . treesit-fold-range-llvm-label)
(comment
- . (lambda (node offset)
- (treesit-fold-range-line-comment node offset ";;")))))
+ . ,(lambda (node offset)
+ (treesit-fold-range-line-comment node offset ";;")))))
(defun treesit-fold-parsers-llvm-mir ()
"Rule set for LLVM MIR."
- '((basic_block . treesit-fold-range-llvm-mir-label)
+ `((basic_block . treesit-fold-range-llvm-mir-label)
(comment
- . (lambda (node offset)
- (treesit-fold-range-line-comment node offset ";;")))))
+ . ,(lambda (node offset)
+ (treesit-fold-range-line-comment node offset ";;")))))
(defun treesit-fold-parsers-lua ()
"Rule set for Lua."
@@ -443,10 +443,10 @@
(defun treesit-fold-parsers-make ()
"Rule set for Make."
- '((recipe . treesit-fold-range-make-recipe)
+ `((recipe . treesit-fold-range-make-recipe)
(comment
- . (lambda (node offset)
- (treesit-fold-range-line-comment node offset "#")))))
+ . ,(lambda (node offset)
+ (treesit-fold-range-line-comment node offset "#")))))
(defun treesit-fold-parsers-markdown ()
"Rule set for Markdown."
@@ -474,26 +474,26 @@
(defun treesit-fold-parsers-mermaid ()
"Rule set for Mermaid."
- '((diagram_flow . treesit-fold-range-mermaid-diagram)
+ `((diagram_flow . treesit-fold-range-mermaid-diagram)
(diagram_sequence . treesit-fold-range-mermaid-diagram)
(diagram_class . treesit-fold-range-mermaid-diagram)
(diagram_er . treesit-fold-range-mermaid-diagram)
(class_stmt_class . treesit-fold-range-mermaid-block)
(er_stmt_entity_block . treesit-fold-range-mermaid-block)
(comment
- . (lambda (node offset)
- (treesit-fold-range-line-comment node
- (treesit-fold--cons-add offset '(0 . -1))
- "%%")))))
+ . ,(lambda (node offset)
+ (treesit-fold-range-line-comment node
+ (treesit-fold--cons-add offset '(0 . -1))
+ "%%")))))
(defun treesit-fold-parsers-ninja ()
"Rule set for Ninja."
- '((build . (treesit-fold-range-seq 4 0))
+ `((build . (treesit-fold-range-seq 4 0))
(comment
- . (lambda (node offset)
- (treesit-fold-range-line-comment node
- (treesit-fold--cons-add offset '(0 . -1))
- "#")))))
+ . ,(lambda (node offset)
+ (treesit-fold-range-line-comment node
+ (treesit-fold--cons-add offset '(0 . -1))
+ "#")))))
(defun treesit-fold-parsers-noir ()
"Rule set for Noir."
@@ -502,12 +502,12 @@
(defun treesit-fold-parsers-nix ()
"Rule set for Nix."
- '((attrset_expression . treesit-fold-range-seq)
+ `((attrset_expression . treesit-fold-range-seq)
(interpolation . treesit-fold-range-seq)
(list_expression . treesit-fold-range-seq)
(comment
- . (lambda (node offset)
- (treesit-fold-range-line-comment node offset "#")))))
+ . ,(lambda (node offset)
+ (treesit-fold-range-line-comment node offset "#")))))
(defun treesit-fold-parsers-ocaml ()
"Rule set for OCaml."
@@ -528,36 +528,36 @@
(defun treesit-fold-parsers-perl ()
"Rule set for Perl."
- '((block . treesit-fold-range-seq)
+ `((block . treesit-fold-range-seq)
(list_expression . treesit-fold-range-seq)
(comment
- . (lambda (node offset)
- (treesit-fold-range-line-comment node offset "#")))))
+ . ,(lambda (node offset)
+ (treesit-fold-range-line-comment node offset "#")))))
(defun treesit-fold-parsers-php ()
"Rule set for PHP."
- '((namespace_use_group . treesit-fold-range-seq)
+ `((namespace_use_group . treesit-fold-range-seq)
(declaration_list . treesit-fold-range-seq)
(use_list . treesit-fold-range-seq)
(switch_block . treesit-fold-range-seq)
(compound_statement . treesit-fold-range-seq)
(comment
- . (lambda (node offset)
- (if (string-prefix-p "#" (treesit-node-text node))
- (treesit-fold-range-line-comment node offset "#")
- (treesit-fold-range-c-like-comment node offset))))))
+ . ,(lambda (node offset)
+ (if (string-prefix-p "#" (treesit-node-text node))
+ (treesit-fold-range-line-comment node offset "#")
+ (treesit-fold-range-c-like-comment node offset))))))
(defun treesit-fold-parsers-python ()
"Rule set for Python."
- '((function_definition . treesit-fold-range-python-def)
+ `((function_definition . treesit-fold-range-python-def)
(class_definition . treesit-fold-range-python-def)
(list . treesit-fold-range-seq)
(dictionary . treesit-fold-range-seq)
(parenthesized_expression . treesit-fold-range-seq)
(expression_statement . treesit-fold-range-python-expression-statement)
(comment
- . (lambda (node offset)
- (treesit-fold-range-line-comment node offset "#")))))
+ . ,(lambda (node offset)
+ (treesit-fold-range-line-comment node offset "#")))))
(defun treesit-fold-parsers-qss ()
"Rule set for QSS."
@@ -574,20 +574,20 @@
(defun treesit-fold-parsers-ruby ()
"Rule set for Ruby."
- '((class . treesit-fold-range-ruby-class-def)
+ `((class . treesit-fold-range-ruby-class-def)
(method . treesit-fold-range-ruby-class-def)
(array . treesit-fold-range-seq)
- (do . (treesit-fold-range-seq 1 -2)) ; match with `end`
- (do_block . (treesit-fold-range-seq 1 -2)) ; match with `end`, in spec file
- (then . treesit-fold-range-ruby-if) ; `if` and `elsif` block
- (else . (treesit-fold-range-ruby-if 4 0)) ; `else` block
+ (do . (treesit-fold-range-seq 1 -2)) ; match with `end`
+ (do_block . (treesit-fold-range-seq 1 -2)) ; match with `end`, in spec file
+ (then . treesit-fold-range-ruby-if) ; `if` and `elsif` block
+ (else . (treesit-fold-range-ruby-if 4 0)) ; `else` block
(comment
- . (lambda (node offset)
- (treesit-fold-range-line-comment node offset "#")))))
+ . ,(lambda (node offset)
+ (treesit-fold-range-line-comment node offset "#")))))
(defun treesit-fold-parsers-rust ()
"Rule set for Rust."
- '((declaration_list . treesit-fold-range-seq)
+ `((declaration_list . treesit-fold-range-seq)
(enum_variant_list . treesit-fold-range-seq)
(field_declaration_list . treesit-fold-range-seq)
(use_list . treesit-fold-range-seq)
@@ -597,10 +597,10 @@
(block . treesit-fold-range-seq)
(token_tree . treesit-fold-range-seq)
(line_comment
- . (lambda (node offset)
- (treesit-fold-range-line-comment node
- (treesit-fold--cons-add offset '(0 . -1))
- "///")))
+ . ,(lambda (node offset)
+ (treesit-fold-range-line-comment node
+ (treesit-fold--cons-add offset '(0 . -1))
+ "///")))
(block_comment . treesit-fold-range-block-comment)))
(defun treesit-fold-parsers-scala ()
@@ -612,21 +612,21 @@
(defun treesit-fold-parsers-scheme ()
"Rule set for Scheme."
- '((list . treesit-fold-range-seq)
+ `((list . treesit-fold-range-seq)
(comment
- . (lambda (node offset)
- (treesit-fold-range-line-comment node offset ";;")))))
+ . ,(lambda (node offset)
+ (treesit-fold-range-line-comment node offset ";;")))))
(defun treesit-fold-parsers-sql ()
"Rule set for SQL."
- '((block . treesit-fold-range-sql-block)
+ `((block . treesit-fold-range-sql-block)
(subquery . treesit-fold-range-seq)
(list . treesit-fold-range-seq)
(column_definitions . treesit-fold-range-seq)
- (marginalia . treesit-fold-range-c-like-comment) ; This is the comment!
+ (marginalia . treesit-fold-range-c-like-comment) ; This is the comment!
(comment
- . (lambda (node offset)
- (treesit-fold-range-line-comment node offset "--")))))
+ . ,(lambda (node offset)
+ (treesit-fold-range-line-comment node offset "--")))))
(defun treesit-fold-parsers-svelte ()
"Rule set for Svelte."
@@ -654,11 +654,11 @@
(defun treesit-fold-parsers-toml ()
"Rule set for TOML."
- '((table . treesit-fold-range-toml-table)
+ `((table . treesit-fold-range-toml-table)
(array . treesit-fold-range-seq)
(comment
- . (lambda (node offset)
- (treesit-fold-range-line-comment node offset "#")))))
+ . ,(lambda (node offset)
+ (treesit-fold-range-line-comment node offset "#")))))
(defun treesit-fold-parsers-typescript ()
"Rule set for TypeScript."
@@ -695,22 +695,22 @@
(defun treesit-fold-parsers-yaml ()
"Rule set for YAML."
- '((comment
- . (lambda (node offset)
- (treesit-fold-range-line-comment node offset "#")))
+ `((comment
+ . ,(lambda (node offset)
+ (treesit-fold-range-line-comment node offset "#")))
(block_mapping_pair
- . ((lambda (node offset)
+ . (,(lambda (node offset)
(treesit-fold-range-markers node offset ":"))
0 1))))
(defun treesit-fold-parsers-zig ()
"Rule set for Zig."
- '((ErrorSetDecl . (lambda (node offset)
- (treesit-fold-range-markers node offset "{")))
- (ContainerDecl . (lambda (node offset)
- (treesit-fold-range-markers node offset "{")))
- (SwitchExpr . (lambda (node offset)
- (treesit-fold-range-markers node offset "{")))
+ `((ErrorSetDecl . ,(lambda (node offset)
+ (treesit-fold-range-markers node offset "{")))
+ (ContainerDecl . ,(lambda (node offset)
+ (treesit-fold-range-markers node offset "{")))
+ (SwitchExpr . ,(lambda (node offset)
+ (treesit-fold-range-markers node offset "{")))
(Block . treesit-fold-range-seq)
(InitList . treesit-fold-range-seq)
(line_comment . treesit-fold-range-c-like-comment)))
diff --git a/treesit-fold.el b/treesit-fold.el
index e063f3eca1..afa7bae30b 100644
--- a/treesit-fold.el
+++ b/treesit-fold.el
@@ -195,60 +195,62 @@
(yaml-ts-mode . ,(treesit-fold-parsers-yaml))
(k8s-mode . ,(treesit-fold-parsers-yaml))
(zig-mode . ,(treesit-fold-parsers-zig)))
- "An alist of (major-mode . (foldable-node-type . function)).
-
+ "An alist of (MAJOR-MODE . (FOLDABLE-NODE-TYPE . FUNCTION)).
+Used as a fallback when the major mode has not set `treesit-fold--ranges'.
FUNCTION is used to determine where the beginning and end for FOLDABLE-NODE-TYPE
in MAJOR-MODE. It should take a single argument (the syntax node with type
FOLDABLE-NODE-TYPE) and return the buffer positions of the beginning and end of
the fold in a cons cell. See `treesit-fold-range-python-def' for an example."
:type '(alist :key-type symbol
- :value-type (alist :key-type symbol :value-type function))
- :group 'treesit-fold)
+ :value-type (alist :key-type symbol :value-type function)))
+
+(defvar-local treesit-fold-ranges nil
+ "List (FOLDABLE-NODE-TYPE . FUNCTION).
+FUNCTION is used to determine where the beginning and end for FOLDABLE-NODE-TYPE
+in MAJOR-MODE. It should take a single argument (the syntax node with type
+FOLDABLE-NODE-TYPE) and return the buffer positions of the beginning and end of
+the fold in a cons cell. See `treesit-fold-range-python-def' for an example.
+If nil, the info is fetched from `treesit-fold-range-alist' instead.")
(defcustom treesit-fold-mode-hook nil
"Hook to run when enabling `treesit-fold-mode`."
- :type 'hook
- :group 'treesit-fold)
+ :type 'hook)
(defcustom treesit-fold-on-fold-hook nil
"Hook runs on folding."
- :type 'hook
- :group 'treesit-fold)
+ :type 'hook)
(defcustom treesit-fold-on-next-line t
"If non-nil, we leave ending keywords on the next line.
This is only used in languages that uses keyword to end the scope.
For example, Lua, Ruby, etc."
- :type 'boolean
- :group 'treesit-fold)
+ :type 'boolean)
(defcustom treesit-fold-replacement "..."
+ ;; FIXME: Default to `truncate-string-ellipsis'?
"Show this string instead of the folded text."
- :type 'string
- :group 'treesit-fold)
+ :type 'string)
(defcustom treesit-fold-priority 30
+ ;; FIXME: Overlay priorities are rarely the right solution.
+ ;; Why do we need it and why does the default have to be non-nil?
"Fold range overlay's priority."
- :type 'integer
- :group 'treesit-fold)
+ :type 'integer)
(defface treesit-fold-replacement-face
'((t :foreground "#808080" :box (:line-width -1 :style pressed-button)))
- "Face used to display the fold replacement text."
- :group 'treesit-fold)
+ "Face used to display the fold replacement text.")
(defface treesit-fold-replacement-mouse-face
'((t :foreground "#808080" :box (:line-width -1 :style released-button)))
- "Face used to when mouse hovering replacement text."
- :group 'treesit-fold)
+ "Face used to when mouse hovering replacement text.")
(defface treesit-fold-fringe-face
'((t ()))
- "Face used to display fringe contents."
- :group 'treesit-fold)
+ "Face used to display fringe contents.")
-(defcustom treesit-fold-modes '(prog-mode conf-mode python-ts-mode)
+(defcustom treesit-fold-modes '(prog-mode conf-mode)
"Modes in which `treesit-fold-mode' gets enabled."
:type '(repeat symbol))
@@ -258,7 +260,8 @@ For example, Lua, Ruby, etc."
(defvar treesit-fold-indicators-mode)
-(declare-function treesit-fold-indicators-mode "treesit-fold-indicators.el")
+;; FIXME: These functions are autoloaded, AFAICT so these
+;; `declare-function' should be redundant, no?
(declare-function treesit-fold-indicators-refresh "treesit-fold-indicators.el")
;;
@@ -293,27 +296,21 @@ For example, Lua, Ruby, etc."
(defun treesit-fold--trigger ()
"Toggle `treesit-fold-mode' when the current mode is treesit-fold compatible."
(when (treesit-fold-ready-p)
- (if (treesit-fold-usable-mode-p)
- (treesit-fold-mode 1)
- (treesit-fold-mode -1))))
+ (treesit-fold-mode (if (treesit-fold--ranges) 1 -1))))
;;;###autoload
(define-minor-mode treesit-fold-mode
"Folding code using tree sitter."
- :group 'treesit-fold
- :init-value nil
:lighter "Treesit-Fold"
(if treesit-fold-mode (treesit-fold--enable) (treesit-fold--disable)))
;;;###autoload
(define-minor-mode global-treesit-fold-mode
"Use `treesit-fold-mode' wherever possible."
- :group 'treesit-fold
- :init-value nil
- :lighter nil
:global t
(if global-treesit-fold-mode
(progn
+ ;; FIXME: Use `after-change-major-mode-hook'?
(dolist (hook (mapcar (lambda (m) (intern (format "%s-hook" m))) treesit-fold-modes))
(add-hook hook #'treesit-fold--trigger))
;; try to turn on in all buffers.
@@ -323,18 +320,17 @@ For example, Lua, Ruby, etc."
(dolist (hook (mapcar (lambda (m) (intern (format "%s-hook" m))) treesit-fold-modes))
(remove-hook hook #'treesit-fold--trigger))))
-(defun treesit-fold-usable-mode-p (&optional mode)
- "Return non-nil if `treesit-fold' has defined folds for MODE."
- (let ((mode (or mode major-mode)))
- (alist-get mode treesit-fold-range-alist)))
+(define-obsolete-function-alias 'treesit-fold-usable-mode-p
+ #'treesit-fold--ranges "2024")
+(defun treesit-fold--ranges ()
+ "Return the ranges alist for the current mode."
+ (or treesit-fold-ranges
+ (alist-get major-mode treesit-fold-range-alist)))
;;;###autoload
(define-minor-mode treesit-fold-line-comment-mode
"Enable line comment folding."
- :group 'treesit-fold
- :init-value nil
- (when (bound-and-true-p treesit-fold-indicators-mode)
- (treesit-fold-indicators-refresh)))
+ :init-value nil)
;;
;; (@* "Core" )
@@ -355,7 +351,7 @@ For example, Lua, Ruby, etc."
(defun treesit-fold--get-fold-range (node)
"Return the beginning (as buffer position) of fold for NODE.
Return nil if there is no fold to be made."
- (when-let* ((fold-alist (alist-get major-mode treesit-fold-range-alist))
+ (when-let* ((fold-alist (treesit-fold--ranges))
(fold-func (alist-get (intern (treesit-node-type node)) fold-alist)))
(cond ((functionp fold-func) (funcall fold-func node (cons 0 0)))
((listp fold-func) (funcall (nth 0 fold-func) node (cons (nth 1 fold-func) (nth 2 fold-func))))
@@ -379,7 +375,7 @@ Return nil if no valid node is found.
This function is borrowed from `tree-sitter-node-at-point'."
(let* ((pos (or pos (point)))
- (mode-ranges (alist-get major-mode treesit-fold-range-alist))
+ (mode-ranges (treesit-fold--ranges))
(root (treesit-buffer-root-node))
(node (treesit-node-descendant-for-range root pos pos))
;; Used for looping
@@ -420,18 +416,20 @@ This function is borrowed from `tree-sitter-node-at-point'."
(defun treesit-fold--open-invisible-temporary (ov hide-p)
"Temporary show/hide OV depends on HIDE-P flag."
(if hide-p (treesit-fold--hide-ov ov)
- (treesit-fold--show-ov ov)))
+ (treesit-fold--show-ov ov))
+ ;; FIXME: How 'bout running `treesit-fold-on-fold-hook' instead?
+ (treesit-fold-indicators-refresh))
(defun treesit-fold--on-change (ov &rest _)
"Open overlay OV during content is changed."
+ ;; FIXME: Shouldn't we run `treesit-fold-on-fold-hook'?
(delete-overlay ov))
(defun treesit-fold--show-ov (ov &rest _)
"Show the OV."
(overlay-put ov 'invisible nil)
(overlay-put ov 'display nil)
- (overlay-put ov 'face nil)
- (treesit-fold-indicators-refresh))
+ (overlay-put ov 'face nil))
(defun treesit-fold--hide-ov (ov &rest _)
"Hide the OV."
@@ -441,8 +439,7 @@ This function is borrowed from `tree-sitter-node-at-point'."
(overlay-put ov 'display (or (and treesit-fold-summary-show
(treesit-fold-summary--get (buffer-substring beg end)))
treesit-fold-replacement))
- (overlay-put ov 'face 'treesit-fold-replacement-face))
- (treesit-fold-indicators-refresh))
+ (overlay-put ov 'face 'treesit-fold-replacement-face)))
(defun treesit-fold-overlay-at (node)
"Return the treesit-fold overlay at NODE if NODE is foldable and folded.
@@ -466,12 +463,14 @@ Return nil otherwise."
(progn ,@body)
(user-error "Ignored, no tree-sitter parser in current buffer")))
+;; FIXME: Why are the below commands autoloaded? Do we expect users to
+;; run them without having enabled `treesit-fold-mode'?
+
;;;###autoload
(defun treesit-fold-close (&optional node)
"Fold the syntax node at `point` if it is foldable.
-Foldable nodes are defined in `treesit-fold-range-alist' for the
-current `major-mode'.
+Foldable nodes are defined in `treesit-fold-ranges'.
If no NODE is found in point, do nothing."
(interactive)
@@ -516,11 +515,11 @@ If the current node is not folded or not foldable, do nothing."
(interactive)
(treesit-fold--ensure-ts
(let (nodes)
- (let* ((treesit-fold-indicators-mode)
+ (let* ((treesit-fold-indicators-mode) ;FIXME: Redundant?
(treesit-fold-on-fold-hook)
(node (treesit-buffer-root-node))
(patterns (seq-mapcat (lambda (fold-range) `((,(car fold-range)) @name))
- (alist-get major-mode treesit-fold-range-alist)))
+ (treesit-fold--ranges)))
(query (treesit-query-compile (treesit-node-language node) patterns)))
(setq nodes (treesit-query-capture node query)
nodes (cl-remove-if (lambda (node)
@@ -558,19 +557,6 @@ If the current syntax node is not foldable, do nothing."
t)
(treesit-fold-close))))
-(defun treesit-fold--after-command (&rest _)
- "Function call after interactive commands."
- (treesit-fold-indicators-refresh))
-
-(let ((commands '(treesit-fold-close
- treesit-fold-open
- treesit-fold-open-recursively
- treesit-fold-close-all
- treesit-fold-open-all
- treesit-fold-toggle)))
- (dolist (command commands)
- (advice-add command :after #'treesit-fold--after-command)))
-
;;
;; (@* "Rule Helpers" )
;;
^ permalink raw reply related [flat|nested] 8+ messages in thread
* Re: [NonGNU ELPA] Submitting treesit-fold to NonGNU ELPA
2024-07-02 3:24 ` Elijah G.
2024-07-02 13:00 ` Stefan Monnier
@ 2024-07-02 21:30 ` Jen-Chieh Shen
2024-07-03 1:46 ` Submitting treesit-fold to GNU ELPA (was: [NonGNU ELPA] Submitting treesit-fold to NonGNU ELPA) Elijah G.
1 sibling, 1 reply; 8+ messages in thread
From: Jen-Chieh Shen @ 2024-07-02 21:30 UTC (permalink / raw)
To: Elijah G.
Cc: Stefan Monnier, Yuan Fu, Emacs Devel, Philip Kaludercic,
Stefan Kangas
[-- Attachment #1: Type: text/plain, Size: 3287 bytes --]
> I'would also like that the pacakge can get into GNU ELPA, but IMO the
> problem would be the contributions since i think it could limit it
> (due paperwork), also since this package is a fork of another
> one [ts-fold][https://github.com/emacs-tree-sitter/ts-fold] i don't know
> if it could be a problem, Jen-Chieh what do you think about this?.
I am unsure since I have not submitted packages to GNU ELPA or non-GNU ELPA.
As seven people (including myself) have made contributions to more than 15
LOC,
I assumed we would need to get them all to sign the paperwork.
- jcs090218 <https://github.com/jcs090218> (+12,214/-8,638) - signed
- Junyi Hou <https://github.com/junyi-hou> (+402/-39)
- Nidish96 <https://github.com/Nidish96> (+215/-107)
- samrjack <https://github.com/samrjack> (+567/-258)
- DevelopmentCool2449 <https://github.com/DevelopmentCool2449> (+434/-360)
- mattiasdrp <https://github.com/mattiasdrp> (+199/-90)
- akirak <https://github.com/akirak> (+29/-2)
On Mon, Jul 1, 2024 at 8:25 PM Elijah G. <eg642616@gmail.com> wrote:
> Stefan Monnier <monnier@iro.umontreal.ca> writes:
>
> >> Thanks for working on this! Treesit-fold is quite useful and through.
> >> It’ll be a great addition to NonGNU ELPA or ELPA!
> >
> > I just added it to `nongnu.git`. It should hopefully appear at NonGNU
> > later today.
> >
> > I see that there are very few other contributors beside Jen-Chieh Shen
> > (the main author). Since he signed the copyright paperwork, it might
> > not be too hard to get this into GNU ELPA.
>
> I'would also like that the pacakge can get into GNU ELPA, but IMO the
> problem would be the contributions since i think it could limit it
> (due paperwork), also since this package is a fork of another
> one [ts-fold][https://github.com/emacs-tree-sitter/ts-fold] i don't know
> if it could be a problem, Jen-Chieh what do you think about this?.
>
> > Another thing I noticed: just as for the EditorConfig thingy, this
> package
> > comes with a `<blabla>-alist` holding per-major-mode information which
> > should ideally be provided directly by the major modes rather than by
> > the package. But just as with the EditorConfig thingy, the package did
> > not come with a variable which the major mode can set buffer-locally for
> > that purpose. Not sure how we can encourage such a design, tho.
>
> I'm not understanding this, but if the major mode (-ts-modes) comes with
> a variable for the treesitter nodes folding (like something that maybe
> hideshow can use) maybe it can be possible use the
> variable instead define them, the problem that i see is the
> compatibility with emacs-29.
>
> something like this?:
> ```
> (defvar c-ts-mode-nodes-alist '((compound_statement .
> treesit-fold-range-seq) (declaration_list . treesit-fold-range-seq)
> (enumerator_list . treesit-fold-range-seq) (field_declaration_list .
> treesit-fold-range-seq) (preproc_if . treesit-fold-range-c-preproc-if)
> (preproc_ifdef . treesit-fold-range-c-preproc-ifdef) (preproc_elif .
> treesit-fold-range-c-preproc-elif) (preproc_else .
> treesit-fold-range-c-preproc-else) (comment .
> treesit-fold-range-c-like-comment)))
> ```
>
> --
> E.G. from Gnus The Emacs Newsreader and E-mail client
>
[-- Attachment #2: Type: text/html, Size: 4200 bytes --]
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: Submitting treesit-fold to GNU ELPA (was: [NonGNU ELPA] Submitting treesit-fold to NonGNU ELPA)
2024-07-02 21:30 ` Jen-Chieh Shen
@ 2024-07-03 1:46 ` Elijah G.
2024-07-03 5:55 ` Jen-Chieh Shen
0 siblings, 1 reply; 8+ messages in thread
From: Elijah G. @ 2024-07-03 1:46 UTC (permalink / raw)
To: Jen-Chieh Shen
Cc: Stefan Monnier, Yuan Fu, Emacs Devel, Philip Kaludercic,
Stefan Kangas
Jen-Chieh Shen <jcs090218@gmail.com> writes:
>> I'would also like that the pacakge can get into GNU ELPA, but IMO the
>> problem would be the contributions since i think it could limit it
>> (due paperwork), also since this package is a fork of another
>> one [ts-fold][https://github.com/emacs-tree-sitter/ts-fold] i don't know
>> if it could be a problem, Jen-Chieh what do you think about this?.
>
> I am unsure since I have not submitted packages to GNU ELPA or non-GNU ELPA.
> As seven people (including myself) have made contributions to more than 15 LOC,
> I assumed we would need to get them all to sign the paperwork.
Sure, opening a issue for calling them for the paperwork.
The _Advantage_ of submit it to GNU ELPA is that it can get into emacs-30/31
(since there is interest for merge it into core as far as i can see).
> - jcs090218 (+12,214/-8,638) - signed
> - Junyi Hou (+402/-39)
> - Nidish96 (+215/-107)
> - samrjack (+567/-258)
> - DevelopmentCool2449 (+434/-360)
```diff
-- DevelopmentCool2449 (+434/-360)
+- DevelopmentCool2449 (+434/-360) - signed
```
DevelopmentCool2449 has already signed paperwork since it's me :-).
--
E.G. from Gnus The Emacs Newsreader and E-mail client
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: Submitting treesit-fold to GNU ELPA (was: [NonGNU ELPA] Submitting treesit-fold to NonGNU ELPA)
2024-07-03 1:46 ` Submitting treesit-fold to GNU ELPA (was: [NonGNU ELPA] Submitting treesit-fold to NonGNU ELPA) Elijah G.
@ 2024-07-03 5:55 ` Jen-Chieh Shen
0 siblings, 0 replies; 8+ messages in thread
From: Jen-Chieh Shen @ 2024-07-03 5:55 UTC (permalink / raw)
To: Elijah G.
Cc: Stefan Monnier, Yuan Fu, Emacs Devel, Philip Kaludercic,
Stefan Kangas
[-- Attachment #1: Type: text/plain, Size: 443 bytes --]
> Sure, opening a issue for calling them for the paperwork.
> The _Advantage_ of submit it to GNU ELPA is that it can get into
emacs-30/31
> (since there is interest for merge it into core as far as i can see).
Got it. I've opened up an issue at
https://github.com/emacs-tree-sitter/treesit-fold/issues/11 to gather
people to sign the paperwork.
> DevelopmentCool2449 has already signed paperwork since it's me :-).
Awesome! Thank you! :D
[-- Attachment #2: Type: text/html, Size: 680 bytes --]
^ permalink raw reply [flat|nested] 8+ messages in thread
end of thread, other threads:[~2024-07-03 5:55 UTC | newest]
Thread overview: 8+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2024-06-21 21:27 [NonGNU ELPA] Submitting treesit-fold to NonGNU ELPA Elijah G.
2024-07-01 5:51 ` Yuan Fu
2024-07-01 14:05 ` Stefan Monnier
2024-07-02 3:24 ` Elijah G.
2024-07-02 13:00 ` Stefan Monnier
2024-07-02 21:30 ` Jen-Chieh Shen
2024-07-03 1:46 ` Submitting treesit-fold to GNU ELPA (was: [NonGNU ELPA] Submitting treesit-fold to NonGNU ELPA) Elijah G.
2024-07-03 5:55 ` Jen-Chieh Shen
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.