@c -*- mode: texinfo -*- \input texinfo @c %**start of header @setfilename info/folding @settitle folding @documentencoding ISO-8859-1 @c %**end of header @c This file was trivially adapted from emacs-goodies-el.texi @c EDITION 30.2 @c UPDATED 25 Nov 2009 @c Copyright: 2000-2003 Roland Mas , @c 2005-2014 Peter S Galbraith @c 2014 Julian Gilbey @c License: GPL-2+ @dircategory Emacs @direntry * Folding: (folding). Folding editor minor mode for Emacs. @end direntry @node Top, folding Installation, (dir), (dir) @noindent Author: Jamie Lokier Jari Aalto Anders Lindgren @menu * folding Installation:: * folding Documentation:: * folding Customization:: * folding Examples:: @end menu 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) @node folding Installation The best way to use folding is to turn it on explicitely when needed using @command{M-x folding-mode}. But if you always use folding, then consider adding these lines to your @file{~/.emacs} file: @example (if (load "folding" 'nomessage 'noerror) (folding-mode-add-find-file-hook)) @end example The same folding marks can be used in `vim' editor command "set fdm=marker". @noindent To remove folding, call `M-x' `folding-uninstall'. @node folding Documentation, folding Customization, folding Installation, Top @noindent Tutorial To start folding mode, give the command: @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: @verbatim ;;{{{ General... ;;{{{ Keyboard... ;;{{{ Packages... ;;{{{ Major modes... ;;{{{ Minor modes... ;;{{{ Debug... @end verbatim To enter a fold, use @key{C-c @ >}. To show it without entering, use @key{C-c @ C-s}, which produces this display: @verbatim ;;{{{ Minor modes ;;{{{ Follow mode... ;;{{{ Font-lock mode... ;;{{{ Folding... ;;}}} @end verbatim To show everything, just as the file would look like if Folding mode hadn't been activated, give the command @command{M-x folding-open-buffer}, normally bound to @key{C-c @ C-o}. To close all folds and go to the top level, the command @command{folding-whole-buffer} could be used. @noindent 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. @noindent 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. @noindent ISearch When searching using the incremental search (C-s) facilities, folds will be automagically entered and closed. @noindent 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 @command{folding-open-buffer} (@key{C-c @ C-o}) and add the fold mark by hand. To find mismatching fold marks, the package `occur' is useful. The command: @verbatim M-x occur RET {{{\|}}} RET @end verbatim 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 @key{C-g} a few times and give the command @command{folding-open-buffer} (@key{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: @verbatim ;;{{{ Note ;;}}} @end verbatim instead of @verbatim ;;{{{ ;;}}} @end verbatim folding-whole-buffer doesn't fold whole buffer If you call commands @command{folding-open-buffer} and @command{folding-whole-buffer} and notice that there are open fold sections in the buffer, then you have mismatch of folds somewhere. Run @command{M-x occur} and type the regexp @code{@{@{@{\|@}@}@}} to check where is the extra open or closing fold mark. @noindent 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: @itemize @bullet @item Folding mode uses explicit marks, @code{@{@{@{} 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. @item Outline mode has no end marker which means that it is impossible for text to follow a sub-branch. @item 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. @item 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.) @item The Isearch facilities of Folding is capable of automatically to open folds. Under Outline, the the entire document must be opened prior isearch. @end itemize 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). @noindent 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. @node folding Customization, folding Examples, folding Documentation, Top @noindent 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. @noindent 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: @table @samp @item folding-mode-hook Called when folding mode is activated. @item -folding-hook Called when starting folding mode in a buffer with major mode set to . (e.g. When editing C code the hook `c-mode-folding-hook' is called.) @item folding-load-hook Called when folding mode is loaded into Emacs. @end table @noindent Customization: The Mouse The variable @code{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 @code{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 @command{my-folding-bind-mouse}, and set this variable to it. @noindent 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.) @verbatim C-c -- Reserved for the users private keymap. C-c C- -- Major mode. (Some other keys are reserved as well.) C-c -- Reserved for minor modes. @end verbatim The reason why @key{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 @code{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: @verbatim (setq folding-default-keys-function 'folding-bind-backward-compatible-keys) @end verbatim To define keys similar to the keys used by Outline mode, use: @verbatim (setq folding-default-keys-function 'folding-bind-outline-compatible-keys) @end verbatim @noindent Customization: adding new major modes To add fold marks for a new major mode, use the function @command{folding-add-to-marks-list}. Example: @verbatim (folding-add-to-marks-list 'c-mode "/* {{{ " "/* }}} */" " */" t) (folding-add-to-marks-list 'java-mode "// {{{ " "// }}}" nil t) @end verbatim @noindent 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. @node folding Examples, , folding Customization, Top @noindent Example: personal setup To define your own key binding instead of using the standard ones, you can do like this: @verbatim (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)) @end verbatim @noindent 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 @verbatim (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 "# {{{" "# }}}")))) @end verbatim @noindent 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 @command{M-x my-folding-text-mode-setup} to change the marks. @verbatim (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))) @end verbatim @noindent 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". @verbatim \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 @end verbatim