Track generated *.texi again

The ecosystem isn't read; maybe in a few more years.

1 files changed, 331 insertions, 0 deletions

diff --git a/docs/magit-section.texi b/docs/magit-section.texi
new file mode 100644
index 0000000..e7253b3
--- /dev/null
+++ b/docs/magit-section.texi
@@ -0,0 +1,331 @@
+\input texinfo    @c -*- texinfo -*-
+@c %**start of header
+@setfilename magit-section.info
+@settitle Magit-Section Developer Manual
+@documentencoding UTF-8
+@documentlanguage en
+@c %**end of header
+
+@copying
+@quotation
+Copyright (C) 2015-2024 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 quotation
+@end copying
+
+@dircategory Emacs
+@direntry
+* Magit-Section: (magit-section). Use Magit sections in your own packages.
+@end direntry
+
+@finalout
+@titlepage
+@title Magit-Section Developer Manual
+@subtitle for version 4.0.0
+@author Jonas Bernoulli
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@contents
+
+@ifnottex
+@node Top
+@top Magit-Section Developer Manual
+
+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 @ref{Sections,,,magit,}.  This manual documents how you
+can use sections in your own packages.
+
+@noindent
+This manual is for Magit-Section version 4.0.0.
+
+@insertcopying
+@end ifnottex
+
+@menu
+* Introduction::
+* Creating Sections::
+* Core Functions::
+* Matching Functions::
+@end menu
+
+@node Introduction
+@chapter 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 @ref{Sections,,,magit,}.  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!
+
+@node Creating Sections
+@chapter Creating Sections
+
+@defmac magit-insert-section [name] (type &optional value hide) &rest body
+Create a section object of type CLASS, storing VALUE in its
+@code{value} slot, and insert the section at point.  CLASS is a
+subclass of `magit-section' or has the form @code{(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 @code{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 @code{start} of the section object is set
+to the value of `point' and after BODY was evaluated its @code{end} is
+set to the new value of @code{point}; BODY is responsible for moving
+@code{point} forward.
+
+If it turns out inside BODY that the section is empty, then
+@code{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.
+@end defmac
+
+@defun magit-insert-heading [child-count] &rest args
+Insert the heading for the section currently being inserted.
+
+This function should only be used inside @code{magit-insert-section}.
+
+When called without any arguments, then just set the @code{content}
+slot of the object representing the section being inserted to
+a marker at @code{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 @code{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 @code{content} property of the section object is the end of the
+heading (which lasts from @code{start} to @code{content}) and the beginning
+of the the body (which lasts from @code{content} to @code{end}).  If the
+value of @code{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 @code{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 @code{magit-section-show-child-count} is nil,
+no counts are inserted
+@end defun
+
+@defmac 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 @code{progn}.  Otherwise BODY isn't evaluated until the section
+is explicitly expanded.
+@end defmac
+
+@defun magit-cancel-section
+Cancel inserting the section that is currently being inserted.
+Remove all traces of that section.
+@end defun
+
+@defun magit-wash-sequence function
+Repeatedly call FUNCTION until it returns @code{nil} or the end of the
+buffer is reached.  FUNCTION has to move point forward or return
+@code{nil}.
+@end defun
+
+@node Core Functions
+@chapter Core Functions
+
+@defun 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.
+@end defun
+
+@table @asis
+@item Function magit-section-at &optional position
+Return the section at POSITION, defaulting to point.  Default to
+point even when the context menu is used.
+@end table
+
+@defun magit-section-ident section
+Return an unique identifier for SECTION@. The return value has the
+form @code{((TYPE . VALUE)...)}.
+@end defun
+
+@defun magit-section-ident-value value
+Return a constant representation of VALUE@.
+
+VALUE is the value of a @code{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.
+@end defun
+
+@defun magit-get-section ident &optional root
+Return the section identified by IDENT@.
+IDENT has to be a list as returned by @code{magit-section-ident}.
+If optional ROOT is non-nil, then search in that section tree
+instead of in the one whose root @code{magit-root-section} is.
+@end defun
+
+@defun 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.
+@end defun
+
+@defun magit-section-content-p section
+Return non-nil if SECTION has content or an unused washer function.
+@end defun
+
+The next two functions are replacements for the Emacs functions that
+have the same name except for the @code{magit-} prefix.  Like
+@code{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.
+
+@table @asis
+@item 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 @code{point}.
+
+@item 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 @code{thing-at-point}.
+For the meaning of THING and NO-PROPERTIES see that function.
+@end table
+
+@node Matching Functions
+@chapter Matching Functions
+
+@defun 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:
+
+@itemize
+@item
+@code{(CONDITION...)} matches if any of the CONDITIONs matches.
+@item
+@code{[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.
+
+@item
+@code{[* CLASS...]} matches sections that match [CLASS@dots{}] and
+also recursively all their child sections.
+@item
+@code{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.
+@end itemize
+
+Each CLASS should be a class symbol, identifying a class that
+derives from @code{magit-section}.  For backward compatibility CLASS
+can also be a "type symbol".  A section matches such a symbol
+if the value of its @code{type} slot is @code{eq}.  If a type symbol has
+an entry in @code{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 @code{magit-describe-section-briefly}, unless
+of course you want to be that precise.
+@end defun
+
+@defun 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 @code{magit-section-match} for the forms CONDITION can take.
+@end defun
+
+@defmac magit-section-case &rest clauses
+Choose among clauses on the type of the section at point.
+
+Each clause looks like @code{(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 @code{it} is bound to the
+section at point.  If no clause succeeds or if there is no
+section at point, return nil.
+
+See @code{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.
+@end defmac
+
+@bye