Rename Documentation/ to docs/

1 files changed, 283 insertions, 0 deletions

diff --git a/docs/magit-section.org b/docs/magit-section.org
new file mode 100644
index 0000000..6828408
--- /dev/null
+++ b/docs/magit-section.org
@@ -0,0 +1,283 @@
+#+TITLE: Magit-Section Developer Manual
+:PREAMBLE:
+#+AUTHOR: Jonas Bernoulli
+#+EMAIL: jonas@bernoul.li
+#+DATE: 2015-{{{year}}}
+#+LANGUAGE: en
+
+#+TEXINFO_DIR_CATEGORY: Emacs
+#+TEXINFO_DIR_TITLE: Magit-Section: (magit-section).
+#+TEXINFO_DIR_DESC: Use Magit sections in your own packages.
+#+SUBTITLE: for version {{{version}}}
+
+#+TEXINFO_DEFFN: t
+#+OPTIONS: H:4 num:3 toc:2
+#+PROPERTY: header-args :eval never
+#+MACRO: version (eval (ox-texinfo+-get-version 'mixed))
+#+MACRO: year (eval (format-time-string "%Y"))
+
+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 {{{version}}}.
+
+#+BEGIN_QUOTE
+Copyright (C) 2015-{{{year}}} Jonas Bernoulli <jonas@bernoul.li>
+
+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
+: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 oftern 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 &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.
+
+- 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.
+
+- 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
+
+  Return the lineage of SECTION.
+  The return value has the form ~(TYPE...)~.
+
+* 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 <jonas@bernoul.li>
+
+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-utils nil t)
+# eval: (require 'ol-man      nil t)
+# eval: (require 'ox-texinfo+ nil t)
+# indent-tabs-mode: nil
+# org-src-preserve-indentation: nil
+# End: