diff options
| author | Jack Jamison <jackqjamison@gmail.com> | 2026-07-30 20:09:00 -0400 |
|---|---|---|
| committer | Jack Jamison <jackqjamison@gmail.com> | 2026-07-30 20:18:37 -0400 |
| commit | 8c4e09dff83847ac7f07bf1da7751e9328006c4d (patch) | |
| tree | a0e245567ce225f8bcb63b66e4d2373b5d033e4a /.config/emacs/lisp/magit/docs/magit-section.org | |
| parent | 1e33b30749bb1043ffc6ceb5a2fb0977446788b3 (diff) | |
actual final changes and get rid of junk in lisp dir
actually works fine
Diffstat (limited to '.config/emacs/lisp/magit/docs/magit-section.org')
| -rw-r--r-- | .config/emacs/lisp/magit/docs/magit-section.org | 309 |
1 files changed, 0 insertions, 309 deletions
diff --git a/.config/emacs/lisp/magit/docs/magit-section.org b/.config/emacs/lisp/magit/docs/magit-section.org deleted file mode 100644 index a731113..0000000 --- a/.config/emacs/lisp/magit/docs/magit-section.org +++ /dev/null @@ -1,309 +0,0 @@ -#+title: Magit-Section Developer Manual -:PREAMBLE: -#+author: Jonas Bernoulli -#+email: emacs.magit@jonas.bernoulli.dev -#+date: 2015-{{{year}}} - -#+texinfo_dir_category: Emacs -#+texinfo_dir_title: Magit-Section: (magit-section). -#+texinfo_dir_desc: Use Magit sections in your own packages. -#+subtitle: for version 4.5.0 - -#+setupfile: .orgconfig - -This package implements the main user interface of Magit — the -collapsible sections that make up its buffers. This package used -to be distributed as part of Magit but how it can also be used by -other packages that have nothing to do with Magit or Git. - -To learn more about the section abstraction and available commands and -user options see [[info:magit#Sections]]. This manual documents how you -can use sections in your own packages. - -#+texinfo: @noindent -This manual is for Magit-Section version 4.5.0. - -#+texinfo: @insertcopying -:END: -* Introduction - -This package implements the main user interface of Magit — the -collapsible sections that make up its buffers. This package used -to be distributed as part of Magit but how it can also be used by -other packages that have nothing to do with Magit or Git. - -To learn more about the section abstraction and available commands -and user options see [[info:magit#Sections]]. This manual documents -how you can use sections in your own packages. - -When the documentation leaves something unaddressed, then please -consider that Magit uses this library extensively and search its -source for suitable examples before asking me for help. Thanks! - -* Creating Sections - -- Macro: magit-insert-section [name] (type &optional value hide) &rest body :: - - Create a section object of type CLASS, storing VALUE in its - ~value~ slot, and insert the section at point. CLASS is a - subclass of `magit-section' or has the form ~(eval FORM)~, in - which case FORM is evaluated at runtime and should return a - subclass. In other places a sections class is often referred - to as its "type". - - Many commands behave differently depending on the class of the - current section and sections of a certain class can have their - own keymap, which is specified using the `keymap' class slot. - The value of that slot should be a variable whose value is a - keymap. - - For historic reasons Magit and Forge in most cases use symbols - as CLASS that don't actually identify a class and that lack the - appropriate package prefix. This works due to some undocumented - kludges, which are not available to other packages. - - When optional HIDE is non-~nil~ collapse the section body by - default, i.e., when first creating the section, but not when - refreshing the buffer. Else expand it by default. This can be - overwritten using ~magit-section-set-visibility-hook~. When a - section is recreated during a refresh, then the visibility of - predecessor is inherited and HIDE is ignored (but the hook is - still honored). - - BODY is any number of forms that actually insert the section's - heading and body. Optional NAME, if specified, has to be a - symbol, which is then bound to the object of the section being - inserted. - - Before BODY is evaluated the ~start~ of the section object is set - to the value of `point' and after BODY was evaluated its ~end~ is - set to the new value of ~point~; BODY is responsible for moving - ~point~ forward. - - If it turns out inside BODY that the section is empty, then - ~magit-cancel-section~ can be used to abort and remove all traces - of the partially inserted section. This can happen when creating - a section by washing Git's output and Git didn't actually output - anything this time around. - -- Function: magit-insert-heading [child-count] &rest args :: - - Insert the heading for the section currently being inserted. - - This function should only be used inside ~magit-insert-section~. - - When called without any arguments, then just set the ~content~ - slot of the object representing the section being inserted to - a marker at ~point~. The section should only contain a single - line when this function is used like this. - - When called with arguments ARGS, which have to be strings, or - ~nil~, then insert those strings at point. The section should not - contain any text before this happens and afterwards it should - again only contain a single line. If the ~face~ property is set - anywhere inside any of these strings, then insert all of them - unchanged. Otherwise use the `magit-section-heading' face for - all inserted text. - - The ~content~ property of the section object is the end of the - heading (which lasts from ~start~ to ~content~) and the beginning - of the the body (which lasts from ~content~ to ~end~). If the - value of ~content~ is ~nil~, then the section has no heading and - its body cannot be collapsed. If a section does have a heading, - then its height must be exactly one line, including a trailing - newline character. This isn't enforced, you are responsible for - getting it right. The only exception is that this function does - insert a newline character if necessary. - - If provided, optional CHILD-COUNT must evaluate to an integer or - boolean. If ~t~, then the count is determined once the children have been - inserted, using ~magit-insert-child-count~ (which see). For historic - reasons, if the heading ends with ":", the count is substituted for - that, at this time as well. If ~magit-section-show-child-count~ is ~nil~, - no counts are inserted - -- Macro: magit-insert-section-body &rest body :: - - Use BODY to insert the section body, once the section is expanded. - If the section is expanded when it is created, then this is - like ~progn~. Otherwise BODY isn't evaluated until the section - is explicitly expanded. - -- Function: magit-cancel-section :: - - Cancel inserting the section that is currently being inserted. - Remove all traces of that section. - -- Function: magit-wash-sequence function :: - - Repeatedly call FUNCTION until it returns ~nil~ or the end of the - buffer is reached. FUNCTION has to move point forward or return - ~nil~. - -* Core Functions - -- Function: magit-current-section :: - - Return the section at point or where the context menu was invoked. - When using the context menu, return the section that the user - clicked on, provided the current buffer is the buffer in which - the click occurred. Otherwise return the section at point. - -- Function magit-section-at &optional position :: - - Return the section at POSITION, defaulting to point. Default to - point even when the context menu is used. - -- Function: magit-section-ident section :: - - Return an unique identifier for SECTION. The return value has the - form ~((TYPE . VALUE)...)~. - -- Function: magit-section-ident-value value :: - - Return a constant representation of VALUE. - - VALUE is the value of a ~magit-section~ object. If that is an - object itself, then that is not suitable to be used to identify - the section because two objects may represent the same thing but - not be equal. If possible a method should be added for such - objects, which returns a value that is equal. Otherwise the - catch-all method is used, which just returns the argument - itself. - -- Function: magit-get-section ident &optional root :: - - Return the section identified by IDENT. - IDENT has to be a list as returned by ~magit-section-ident~. - If optional ROOT is non-~nil~, then search in that section tree - instead of in the one whose root ~magit-root-section~ is. - -- Function: magit-section-lineage section &optional raw :: - - Return the lineage of SECTION. - If optional RAW is non-~nil~, return a list of section objects, - beginning with SECTION, otherwise return a list of section types. - -- Function: magit-section-content-p section :: - - Return non-~nil~ if SECTION has content or an unused washer function. - -The next two functions are replacements for the Emacs functions that -have the same name except for the ~magit-~ prefix. Like -~magit-current-section~ they do not act on point, the cursors position, -but on the position where the user clicked to invoke the context menu. - -If your package provides a context menu and some of its commands act -on the "thing at point", even if just as a default, then use the -prefixed functions to teach them to instead use the click location -when appropriate. - -- Function magit-point :: - - Return point or the position where the context menu was invoked. - When using the context menu, return the position the user clicked - on, provided the current buffer is the buffer in which the click - occurred. Otherwise return the same value as ~point~. - -- Function magit-thing-at-point thing &optional no-properties :: - - Return the THING at point or where the context menu was invoked. - When using the context menu, return the thing the user clicked - on, provided the current buffer is the buffer in which the click - occurred. Otherwise return the same value as ~thing-at-point~. - For the meaning of THING and NO-PROPERTIES see that function. - -* Matching Functions - -- Function: magit-section-match condition &optional (section (magit-current-section)) :: - - Return ~t~ if SECTION matches CONDITION. - - SECTION defaults to the section at point. If SECTION is not - specified and there also is no section at point, then return - ~nil~. - - CONDITION can take the following forms: - - - ~(CONDITION...)~ matches if any of the CONDITIONs matches. - - ~[CLASS...]~ matches if the section's class is the same - as the first CLASS or a subclass of that; - the section's parent class matches the - second CLASS; and so on. - - - ~[* CLASS...]~ matches sections that match [CLASS...] and - also recursively all their child sections. - - ~CLASS~ matches if the section's class is the same - as CLASS or a subclass of that; regardless - of the classes of the parent sections. - - Each CLASS should be a class symbol, identifying a class that - derives from ~magit-section~. For backward compatibility CLASS - can also be a "type symbol". A section matches such a symbol - if the value of its ~type~ slot is ~eq~. If a type symbol has - an entry in ~magit--section-type-alist~, then a section also - matches that type if its class is a subclass of the class that - corresponds to the type as per that alist. - - Note that it is not necessary to specify the complete section - lineage as printed by ~magit-describe-section-briefly~, unless - of course you want to be that precise. - -- Function: magit-section-value-if condition &optional section :: - - If the section at point matches CONDITION, then return its value. - - If optional SECTION is non-~nil~ then test whether that matches - instead. If there is no section at point and SECTION is ~nil~, - then return ~nil~. If the section does not match, then return - ~nil~. - - See ~magit-section-match~ for the forms CONDITION can take. - -- Macro: magit-section-case &rest clauses :: - - Choose among clauses on the type of the section at point. - - Each clause looks like ~(CONDITION BODY...)~. The type of the - section is compared against each CONDITION; the BODY forms of the - first match are evaluated sequentially and the value of the last - form is returned. Inside BODY the symbol ~it~ is bound to the - section at point. If no clause succeeds or if there is no - section at point, return ~nil~. - - See ~magit-section-match~ for the forms CONDITION can take. - Additionally a CONDITION of ~t~ is allowed in the final clause, and - matches if no other CONDITION match, even if there is no section - at point. - -* Copying -:PROPERTIES: -:COPYING: t -:END: - -#+begin_quote -Copyright (C) 2015-{{{year}}} Jonas Bernoulli <emacs.magit@jonas.bernoulli.dev> - -You can redistribute this document and/or modify it under the terms -of the GNU General Public License as published by the Free Software -Foundation, either version 3 of the License, or (at your option) any -later version. - -This document is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -General Public License for more details. -#+end_quote - -# LocalWords: ARGS CONDITIONs EVAL Git Git's IDENT -# LocalWords: LocalWords MERCHANTABILITY Magit Makefile -# LocalWords: alist eval featurep ident keymap magit ol -# LocalWords: runtime src texinfo utils - -# IMPORTANT: Also update ORG_ARGS and ORG_EVAL in the Makefile. -# Local Variables: -# eval: (require 'magit-base nil t) -# eval: (require 'ol-man nil t) -# indent-tabs-mode: nil -# org-src-preserve-indentation: nil -# End: |
