branch: elpa/magit
commit cf9d129d3612c7a900a82263951310b186860834
Author: Jonas Bernoulli <[email protected]>
Commit: Jonas Bernoulli <[email protected]>
manual: Add notes relevant when defining a refresh function
Closes #5415.
---
docs/magit-section.org | 19 +++++++++++++++++++
docs/magit-section.texi | 19 +++++++++++++++++++
2 files changed, 38 insertions(+)
diff --git a/docs/magit-section.org b/docs/magit-section.org
index 598d202cb8..a616820aa5 100644
--- a/docs/magit-section.org
+++ b/docs/magit-section.org
@@ -140,6 +140,25 @@ source for suitable examples before asking me for help.
Thanks!
buffer is reached. FUNCTION has to move point forward or return
~nil~.
+You have to define some function that calls ~magit-insert-section~ to
+populate a buffer with sections. After doing so, that function also
+has to call a few other functions, to put the sections in a good
+initial state. You will likely need these lines:
+
+#+begin_src emacs-lisp
+ (let ((magit-section-cache-visibility nil))
+ (magit-section-show magit-root-section))
+ (magit-section-update-highlight)
+ (set-buffer-modified-p nil)
+#+end_src
+
+Magit does that in ~magit-refresh-buffer~. Look at that function for
+inspiration, and also check out how that function is being used in in
+~magit-mode.el~. The code in that library is to specialized to Magit's
+needs to be made part of the ~magit-section~ package, but a magit-like
+package will likely have to perform mode and buffer setup in a similar
+fashion.
+
* Core Functions
- Function: magit-current-section ::
diff --git a/docs/magit-section.texi b/docs/magit-section.texi
index 512bb9a2ae..fde0e2b502 100644
--- a/docs/magit-section.texi
+++ b/docs/magit-section.texi
@@ -183,6 +183,25 @@ buffer is reached. FUNCTION has to move point forward or
return
@code{nil}.
@end defun
+You have to define some function that calls @code{magit-insert-section} to
+populate a buffer with sections. After doing so, that function also
+has to call a few other functions, to put the sections in a good
+initial state. You will likely need these lines:
+
+@lisp
+(let ((magit-section-cache-visibility nil))
+ (magit-section-show magit-root-section))
+(magit-section-update-highlight)
+(set-buffer-modified-p nil)
+@end lisp
+
+Magit does that in @code{magit-refresh-buffer}. Look at that function for
+inspiration, and also check out how that function is being used in in
+@code{magit-mode.el}. The code in that library is to specialized to Magit's
+needs to be made part of the @code{magit-section} package, but a magit-like
+package will likely have to perform mode and buffer setup in a similar
+fashion.
+
@node Core Functions
@chapter Core Functions
