Author: Jamie Lokier <jamie@imbolc.ucc.ie> Jari Aalto
<jari.aalto@poboxes.com> Anders Lindgren <andersl@csd.uu.se>

   This package provides a minor mode, compatible with all major editing
modes, for folding (hiding) parts of the edited text or program.

   Folding mode handles a document as a tree, where each branch is
bounded by special markers {{{ and }}}.  A branch can be placed inside
another branch, creating a complete hierarchical structure.

   Folding mode can CLOSE a fold, leaving only the initial '{{{' and
possibly a comment visible.

   It can also ENTER a fold, which means that only the current fold will
be visible, all text above '{{{' and below '}}}' will be invisible.

   Please note, that the maintainers do not recommend to use only
folding for you your code layout and navigation.  Folding.el is on its
best when it can "chunk" large sections of code inside folds.  The
larger the chunks, the more the usability of folding will increase.
Folding.el is not meant to hide individual functions: you may be better
served by hideshow.el or imenu.el (which can parse the function indexes)

The best way to use folding is to turn it on explicitely when needed
using 'M-x folding-mode'.

   But if you always use folding, then consider adding these lines to
your '~/.emacs' file:

              (if (load "folding" 'nomessage 'noerror)
                  (folding-mode-add-find-file-hook))

   The same folding marks can be used in 'vim' editor command "set
fdm=marker".

To remove folding, call 'M-x' 'folding-uninstall'.

Tutorial

   To start folding mode, give the command: 'M-x folding-mode'.  The
mode line should contain the string "Fld" indicating that folding mode
is activated.

   When loading a document containing fold marks, Folding mode is
automatically started and all folds are closed.  For example when
loading my init file, only the following lines (plus a few lines of
comments) are visible:

;;{{{ General...
;;{{{ Keyboard...
;;{{{ Packages...
;;{{{ Major modes...
;;{{{ Minor modes...
;;{{{ Debug...

   To enter a fold, use <C-c  >>.  To show it without entering, use <C-c
 C-s>, which produces this display:

;;{{{ Minor modes

;;{{{ Follow mode...
;;{{{ Font-lock mode...
;;{{{ Folding...

;;}}}

   To show everything, just as the file would look like if Folding mode
hadn't been activated, give the command 'M-x folding-open-buffer',
normally bound to <C-c  C-o>.  To close all folds and go to the top
level, the command 'folding-whole-buffer' could be used.

Mouse support

   Folding mode v2.0 introduced mouse support.  Folds can be shown or
hidden by simply clicking on a fold mark using mouse button 3.  The
mouse routines have been designed to call the original function bound to
button 3 when the user didn't click on a fold mark.

The menu

   A menu is placed in the "Tools" menu.  Should no Tools menu exist
(Emacs 19.28) the menu will be placed in the menu bar.

ISearch

   When searching using the incremental search (C-s) facilities, folds
will be automagically entered and closed.

Problems

   Uneven fold marks

   Oops, I just deleted some text, and a fold mark got deleted!  What
should I do?  Trust me, you will eventually do this sometime.  the
easiest way is to open the buffer using 'folding-open-buffer' (<C-c
 C-o>) and add the fold mark by hand.  To find mismatching fold marks,
the package 'occur' is useful.  The command:

         M-x occur RET {{{\|}}} RET

   will extract all lines containing folding marks and present them in a
separate buffer.

   Even though all folding marks are correct, Folding mode sometimes
gets confused, especially when entering and leaving folds very often.
To get it back on track, press <C-g> a few times and give the command
'folding-open-buffer' (<C-c  C-o>).

   Fold must have a label

   When you make a fold, be sure to write some text for the name of the
fold, otherwise there may be an error "extraneous fold mark..."  Write
like this:

         ;;{{{ Note
         ;;}}}

   instead of

         ;;{{{
         ;;}}}

   folding-whole-buffer doesn't fold whole buffer

   If you call commands 'folding-open-buffer' and 'folding-whole-buffer'
and notice that there are open fold sections in the buffer, then you
have mismatch of folds somewhere.  Run 'M-x occur' and type the regexp
'{{{\|}}}' to check where is the extra open or closing fold mark.

Folding and outline modes

   Folding mode is not the same as Outline mode, a major and minor mode
which is part of the Emacs distribution.  The two packages do, however,
resemble each other very much.  The main differences between the two
packages are:

   * Folding mode uses explicit marks, '{{{' and '}}}', to mark the
     beginning and the end of a branch.  Outline, on the other other
     hand, tries to use already existing marks, like the '\section'
     string in a TeX document.

   * Outline mode has no end marker which means that it is impossible
     for text to follow a sub-branch.

   * Folding mode use the same markers for branches on all depths,
     Outline mode requires that marks should be longer the further, down
     in the tree you go, e.g '\chap', \section', '\subsection',
     '\subsubsection'.  This is needed to distinguish the next mark at
     the current or higher levels from a sub-branch, a problem caused by
     the lack of end-markers.

   * Folding mode has mouse support, you can navigate through a folded
     document by clicking on fold marks.  (The XEmacs version of Outline
     mode has mouse support.)

   * The Isearch facilities of Folding is capable of automatically to
     open folds.  Under Outline, the the entire document must be opened
     prior isearch.

   In conclusion, Outline mode is useful when the document being edited
contains natural markers, like LaTeX. When writing code natural markers
are hard to find, except if you're happy with one function per fold (I'm
not).

Personal reflections by Anders Lindgren

   When writing this, version 2.0 of Folding mode is just about to be
released.  The current version has proven itself stable during a months
of testing period.  In other words: we haven't had time to touch the
folding for quite some time.

   Our plan was from the beginning to rewrite the entire package,
including replacing the core of the program, written using old Emacs
technology (selective display), and replace it with modern equivalences,
like overlays or text-properties for Emacs and extents for XEmacs.

   Unfortunately, this has not yet been done, even though we have
implemented most other items on our to-do agenda.

   It is not likely that any of us, even in the near future, will find
the time required to rewrite the core of the package.  Since the
package, in it's current state, is much more powerful than the original,
we have decided to release this code.

Customization: general

   The behavior of Folding mode is controlled mainly by a set of Emacs
Lisp variables.  This section will discuss the most useful ones, for
more details please see the code.  The descriptions below assumes that
you know a bit about how to use simple Emacs Lisp and knows how to edit
~/.emacs, your init file.

Customization: hooks

   The normal procedure when customizing a package is to write a
function doing the customization.  The function is then added to a hook
which is called at an appropriate time.  (Please see the example section
below.)  The following hooks are available:
'folding-mode-hook'
     Called when folding mode is activated.
'<major mode>-folding-hook'
     Called when starting folding mode in a buffer with major mode set
     to <major mode>.  (e.g.  When editing C code the hook
     'c-mode-folding-hook' is called.)
'folding-load-hook'
     Called when folding mode is loaded into Emacs.

Customization: The Mouse

   The variable 'folding-behave-table' contains the actions which should
be performed when the user clicks on an open fold, a closed fold etc.
For example, if you prefer to 'enter' a fold rather than 'open' it you
should rebind this variable.

   The variable 'folding-default-mouse-keys-function' contains the name
of the function used to bind your mouse keys.  To use your own mouse
bindings, create a function, say 'my-folding-bind-mouse', and set this
variable to it.

Customization: Keymaps

   When Emacs 19.29 was released, the keymap was divided into strict
parts.  (This division existed before, but a lot of packages, even the
ones delivered with Emacs, ignored them.)

         C-c <letter>    -- Reserved for the users private keymap.
         C-c C-<letter>  -- Major mode. (Some other keys are
                            reserved as well.)
         C-c <Punctuation Char> <Whatever>
                         -- Reserved for minor modes.

   The reason why <C-c@> was chosen as the default prefix is that it is
used by outline-minor-mode.  It is not likely that few people will try
to use folding and outline at the same time.

   However, old key bindings have been kept if possible.  The variable
'folding-default-keys-function' specifies which function should be
called to bind the keys.  There are various function to choose from how
user can select the keybindings.  To use the old key bindings, add the
following line to your init file:

         (setq folding-default-keys-function
               'folding-bind-backward-compatible-keys)

   To define keys similar to the keys used by Outline mode, use:

         (setq folding-default-keys-function
               'folding-bind-outline-compatible-keys)

Customization: adding new major modes

   To add fold marks for a new major mode, use the function
'folding-add-to-marks-list'.  Example:

         (folding-add-to-marks-list
          'c-mode "/* {{{ " "/* }}} */" " */" t)
         (folding-add-to-marks-list
          'java-mode "// {{{ " "// }}}" nil t)

Customization: ISearch

   If you don't like the extension folding.el applies to isearch, set
the variable 'folding-isearch-install' to nil before loading this
package.

Example: personal setup

   To define your own key binding instead of using the standard ones,
you can do like this:

          (setq folding-mode-prefix-key "\C-c")
          ;;
          (setq folding-default-keys-function
              '(folding-bind-backward-compatible-keys))
          ;;
          (setq folding-load-hook 'my-folding-load-hook)

          (defun my-folding-load-hook ()
            "Folding setup."

            (folding-install)  ;; just to be sure

            ;; ............................................... markers ...

            ;;  Change text-mode fold marks. Handy for quick
            ;;  sh/perl/awk code

            (defvar folding-mode-marks-alist nil)

            (let* ((ptr (assq 'text-mode folding-mode-marks-alist)))
              (setcdr ptr (list "# {{{" "# }}}")))

            ;; ........................................ bindings ...

            ;;  Put `folding-whole-buffer' and `folding-open-buffer'
            ;;  close together.

            (defvar folding-mode-prefix-map nil)

            (define-key folding-mode-prefix-map "\C-w" nil)
            (define-key folding-mode-prefix-map "\C-s"
                        'folding-show-current-entry)
            (define-key folding-mode-prefix-map "\C-p"
                        'folding-whole-buffer))

Example: changing default fold marks

   In case you're not happy with the default folding marks, you can
change them easily.  Here is an example

         (setq folding-load-hook 'my-folding-load-hook)

         (defun my-folding-load-hook ()
           "Folding vars setup."
           (let* ((ptr (assq 'text-mode folding-mode-marks-alist)))
             (setcdr ptr (list "# {{{" "# }}}"))))

Example: choosing different fold marks for mode

   Suppose you sometimes want to use different fold marks for the major
mode: e.g.  to alternate between "# {{{" and "{{{" in 'text-mode' Call
'M-x my-folding-text-mode-setup' to change the marks.

   (defun my-folding-text-mode-setup (&optional use-custom-folding-marks)
     (interactive
       (list (y-or-n-p "Use Custom fold marks now? ")))
     (let* ((ptr (assq major-mode folding-mode-marks-alist))
            (default-begin "# {{{")
            (default-end   "# }}}")
            (begin "{{{")
            (end   "}}}"))
       (when (eq major-mode 'text-mode)
         (unless use-custom-folding-marks
           (setq  begin default-begin  end default-end)))
       (setcdr ptr (list begin end))
       (folding-set-marks begin end)))

Example: AucTex setup

   Suppose you're using comment.sty with AucTeX for editing LaTeX2e
documents and you have these comment types.  You would like to be able
to set which of these 3 is to be folded at any one time, using a simple
key sequence: move back and forth easily between the different comment
types, e.g., "unfold everything then fold on \x".

         \O   ...  \endO
         \L   ...  \endL
         \B   ...  \endB

         (setq folding-load-hook 'my-folding-load-hook)

         (defun my-folding-load-hook ()
           "Folding vars setup."
           (let ((ptr (assq 'text-mode folding-mode-marks-alist)))
             (setcdr ptr (list "\\O" "\\endO"))
             (define-key folding-mode-prefix-map "C"
                        'my-folding-marks-change)))

         (defun my-folding-marks-change (&optional selection)
           "Select folding marks: prefixes nil, C-u and C-u C-u."
           (interactive "P")
           (let ((ptr (assq major-mode folding-mode-marks-alist))
                 input)
             (when (string-match "^\\(plain-\\|la\\|auc\\)?tex-"
                                 (symbol-name  major-mode))
               (setq input
                     (read-string "Latex \\end(X) Marker (default O): "
                                  nil nil "O" nil))
               (setq input (upcase input))
               (turn-off-folding-mode)
               (folding-add-to-marks-list
                major-mode
                (concat "\\" input) (concat "\\end" input) nil nil t)
               ;; (setcdr ptr (list (concat "\\" input) (concat "\\end" input)))
               (turn-on-folding-mode))))
         ;;  End of example