| 1 |
@c -*- mode: texinfo -*- |
| 2 |
\input texinfo |
| 3 |
|
| 4 |
@c %**start of header |
| 5 |
@setfilename info/folding |
| 6 |
@settitle folding |
| 7 |
@documentencoding ISO-8859-1 |
| 8 |
@c %**end of header |
| 9 |
|
| 10 |
@c This file was trivially adapted from emacs-goodies-el.texi |
| 11 |
@c EDITION 30.2 |
| 12 |
@c UPDATED 25 Nov 2009 |
| 13 |
@c Copyright: 2000-2003 Roland Mas <[email protected]>, |
| 14 |
@c 2005-2014 Peter S Galbraith <[email protected]> |
| 15 |
@c 2014 Julian Gilbey <[email protected]> |
| 16 |
@c License: GPL-2+ |
| 17 |
|
| 18 |
@dircategory Emacs |
| 19 |
@direntry |
| 20 |
* Folding: (folding). Folding editor minor mode for Emacs. |
| 21 |
@end direntry |
| 22 |
|
| 23 |
@node Top, folding Installation, (dir), (dir) |
| 24 |
@noindent Author: Jamie Lokier <jamie@@imbolc.ucc.ie> |
| 25 |
Jari Aalto <jari.aalto@@poboxes.com> |
| 26 |
Anders Lindgren <andersl@@csd.uu.se> |
| 27 |
@menu |
| 28 |
* folding Installation:: |
| 29 |
* folding Documentation:: |
| 30 |
* folding Customization:: |
| 31 |
* folding Examples:: |
| 32 |
@end menu |
| 33 |
|
| 34 |
This package provides a minor mode, compatible with all major |
| 35 |
editing modes, for folding (hiding) parts of the edited text or |
| 36 |
program. |
| 37 |
|
| 38 |
Folding mode handles a document as a tree, where each branch |
| 39 |
is bounded by special markers @{@{@{ and @}@}@}. A branch can be |
| 40 |
placed inside another branch, creating a complete hierarchical |
| 41 |
structure. |
| 42 |
|
| 43 |
Folding mode can CLOSE a fold, leaving only the initial `@{@{@{' |
| 44 |
and possibly a comment visible. |
| 45 |
|
| 46 |
It can also ENTER a fold, which means that only the current |
| 47 |
fold will be visible, all text above `@{@{@{' and below `@}@}@}' |
| 48 |
will be invisible. |
| 49 |
|
| 50 |
Please note, that the maintainers do not recommend to use only |
| 51 |
folding for you your code layout and navigation. Folding.el is |
| 52 |
on its best when it can "chunk" large sections of code inside |
| 53 |
folds. The larger the chunks, the more the usability of |
| 54 |
folding will increase. Folding.el is not meant to hide |
| 55 |
individual functions: you may be better served by hideshow.el |
| 56 |
or imenu.el (which can parse the function indexes) |
| 57 |
|
| 58 |
@node folding Installation |
| 59 |
|
| 60 |
The best way to use folding is to turn it on explicitely when |
| 61 |
needed using @command{M-x folding-mode}. |
| 62 |
|
| 63 |
But if you always use folding, then consider adding these lines |
| 64 |
to your @file{~/.emacs} file: |
| 65 |
|
| 66 |
@example |
| 67 |
(if (load "folding" 'nomessage 'noerror) |
| 68 |
(folding-mode-add-find-file-hook)) |
| 69 |
@end example |
| 70 |
|
| 71 |
The same folding marks can be used in `vim' editor command |
| 72 |
"set fdm=marker". |
| 73 |
|
| 74 |
@noindent To remove folding, call `M-x' `folding-uninstall'. |
| 75 |
|
| 76 |
@node folding Documentation, folding Customization, folding Installation, Top |
| 77 |
|
| 78 |
@noindent Tutorial |
| 79 |
|
| 80 |
To start folding mode, give the command: @command{M-x |
| 81 |
folding-mode}. The mode line should contain the string "Fld" |
| 82 |
indicating that folding mode is activated. |
| 83 |
|
| 84 |
When loading a document containing fold marks, Folding mode is |
| 85 |
automatically started and all folds are closed. For example when |
| 86 |
loading my init file, only the following lines (plus a few lines of |
| 87 |
comments) are visible: |
| 88 |
|
| 89 |
@verbatim |
| 90 |
;;{{{ General... |
| 91 |
;;{{{ Keyboard... |
| 92 |
;;{{{ Packages... |
| 93 |
;;{{{ Major modes... |
| 94 |
;;{{{ Minor modes... |
| 95 |
;;{{{ Debug... |
| 96 |
@end verbatim |
| 97 |
|
| 98 |
To enter a fold, use @key{C-c @ >}. To show it without entering, use |
| 99 |
@key{C-c @ C-s}, which produces this display: |
| 100 |
|
| 101 |
@verbatim |
| 102 |
;;{{{ Minor modes |
| 103 |
|
| 104 |
;;{{{ Follow mode... |
| 105 |
;;{{{ Font-lock mode... |
| 106 |
;;{{{ Folding... |
| 107 |
|
| 108 |
;;}}} |
| 109 |
@end verbatim |
| 110 |
|
| 111 |
To show everything, just as the file would look like if Folding |
| 112 |
mode hadn't been activated, give the command @command{M-x |
| 113 |
folding-open-buffer}, normally bound to @key{C-c @ C-o}. To |
| 114 |
close all folds and go to the top level, the command |
| 115 |
@command{folding-whole-buffer} could be used. |
| 116 |
|
| 117 |
@noindent Mouse support |
| 118 |
|
| 119 |
Folding mode v2.0 introduced mouse support. Folds can be shown or |
| 120 |
hidden by simply clicking on a fold mark using mouse button 3. The |
| 121 |
mouse routines have been designed to call the original function bound |
| 122 |
to button 3 when the user didn't click on a fold mark. |
| 123 |
|
| 124 |
@noindent The menu |
| 125 |
|
| 126 |
A menu is placed in the "Tools" menu. Should no Tools menu exist |
| 127 |
(Emacs 19.28) the menu will be placed in the menu bar. |
| 128 |
|
| 129 |
@noindent ISearch |
| 130 |
|
| 131 |
When searching using the incremental search (C-s) facilities, |
| 132 |
folds will be automagically entered and closed. |
| 133 |
|
| 134 |
@noindent Problems |
| 135 |
|
| 136 |
Uneven fold marks |
| 137 |
|
| 138 |
Oops, I just deleted some text, and a fold mark got deleted! |
| 139 |
What should I do? Trust me, you will eventually do this sometime. the |
| 140 |
easiest way is to open the buffer using @command{folding-open-buffer} |
| 141 |
(@key{C-c @ C-o}) and add the fold mark by hand. To find mismatching |
| 142 |
fold marks, the package `occur' is useful. The command: |
| 143 |
|
| 144 |
@verbatim |
| 145 |
M-x occur RET {{{\|}}} RET |
| 146 |
@end verbatim |
| 147 |
|
| 148 |
will extract all lines containing folding marks and present them |
| 149 |
in a separate buffer. |
| 150 |
|
| 151 |
Even though all folding marks are correct, Folding mode sometimes |
| 152 |
gets confused, especially when entering and leaving folds very |
| 153 |
often. To get it back on track, press @key{C-g} a few times and give the |
| 154 |
command @command{folding-open-buffer} (@key{C-c @ C-o}). |
| 155 |
|
| 156 |
Fold must have a label |
| 157 |
|
| 158 |
When you make a fold, be sure to write some text for the name of |
| 159 |
the fold, otherwise there may be an error "extraneous fold mark..." |
| 160 |
Write like this: |
| 161 |
|
| 162 |
@verbatim |
| 163 |
;;{{{ Note |
| 164 |
;;}}} |
| 165 |
@end verbatim |
| 166 |
|
| 167 |
instead of |
| 168 |
|
| 169 |
@verbatim |
| 170 |
;;{{{ |
| 171 |
;;}}} |
| 172 |
@end verbatim |
| 173 |
|
| 174 |
folding-whole-buffer doesn't fold whole buffer |
| 175 |
|
| 176 |
If you call commands @command{folding-open-buffer} and |
| 177 |
@command{folding-whole-buffer} and notice that there are open fold |
| 178 |
sections in the buffer, then you have mismatch of folds somewhere. Run |
| 179 |
@command{M-x occur} and type the regexp @code{@{@{@{\|@}@}@}} to check where |
| 180 |
is the extra open or closing fold mark. |
| 181 |
|
| 182 |
@noindent Folding and outline modes |
| 183 |
|
| 184 |
Folding mode is not the same as Outline mode, a major and minor |
| 185 |
mode which is part of the Emacs distribution. The two packages do, |
| 186 |
however, resemble each other very much. The main differences between |
| 187 |
the two packages are: |
| 188 |
|
| 189 |
@itemize @bullet |
| 190 |
@item |
| 191 |
Folding mode uses explicit marks, @code{@{@{@{} and `@}@}@}', to |
| 192 |
mark the beginning and the end of a branch. |
| 193 |
Outline, on the other other hand, tries to use already |
| 194 |
existing marks, like the `\section' string in a TeX |
| 195 |
document. |
| 196 |
|
| 197 |
@item |
| 198 |
Outline mode has no end marker which means that it is |
| 199 |
impossible for text to follow a sub-branch. |
| 200 |
|
| 201 |
@item |
| 202 |
Folding mode use the same markers for branches on all depths, |
| 203 |
Outline mode requires that marks should be longer the |
| 204 |
further, down in the tree you go, e.g `\chap', \section', |
| 205 |
`\subsection', `\subsubsection'. This is needed to |
| 206 |
distinguish the next mark at the current or higher levels |
| 207 |
from a sub-branch, a problem caused by the lack of |
| 208 |
end-markers. |
| 209 |
|
| 210 |
@item |
| 211 |
Folding mode has mouse support, you can navigate through a |
| 212 |
folded document by clicking on fold marks. (The XEmacs version |
| 213 |
of Outline mode has mouse support.) |
| 214 |
|
| 215 |
@item |
| 216 |
The Isearch facilities of Folding is capable of |
| 217 |
automatically to open folds. Under Outline, the the entire |
| 218 |
document must be opened prior isearch. |
| 219 |
@end itemize |
| 220 |
|
| 221 |
In conclusion, Outline mode is useful when the document being |
| 222 |
edited contains natural markers, like LaTeX. When writing code natural |
| 223 |
markers are hard to find, except if you're happy with one function per |
| 224 |
fold (I'm not). |
| 225 |
|
| 226 |
@noindent Personal reflections by Anders Lindgren |
| 227 |
|
| 228 |
When writing this, version 2.0 of Folding mode is just about to |
| 229 |
be released. The current version has proven itself stable during a |
| 230 |
months of testing period. In other words: we haven't had time to touch |
| 231 |
the folding for quite some time. |
| 232 |
|
| 233 |
Our plan was from the beginning to rewrite the entire package, |
| 234 |
including replacing the core of the program, written using old Emacs |
| 235 |
technology (selective display), and replace it with modern |
| 236 |
equivalences, like overlays or text-properties for Emacs and extents |
| 237 |
for XEmacs. |
| 238 |
|
| 239 |
Unfortunately, this has not yet been done, even though we have |
| 240 |
implemented most other items on our to-do agenda. |
| 241 |
|
| 242 |
It is not likely that any of us, even in the near future, will |
| 243 |
find the time required to rewrite the core of the package. Since the |
| 244 |
package, in it's current state, is much more powerful than the |
| 245 |
original, we have decided to release this code. |
| 246 |
|
| 247 |
@node folding Customization, folding Examples, folding Documentation, Top |
| 248 |
|
| 249 |
@noindent Customization: general |
| 250 |
|
| 251 |
The behavior of Folding mode is controlled mainly by a set of |
| 252 |
Emacs Lisp variables. This section will discuss the most useful ones, |
| 253 |
for more details please see the code. The descriptions below assumes |
| 254 |
that you know a bit about how to use simple Emacs Lisp and knows how |
| 255 |
to edit ~/.emacs, your init file. |
| 256 |
|
| 257 |
@noindent Customization: hooks |
| 258 |
|
| 259 |
The normal procedure when customizing a package is to write a |
| 260 |
function doing the customization. The function is then added to a hook |
| 261 |
which is called at an appropriate time. (Please see the example |
| 262 |
section below.) The following hooks are available: |
| 263 |
@table @samp |
| 264 |
@item folding-mode-hook |
| 265 |
Called when folding mode is activated. |
| 266 |
@item <major mode>-folding-hook |
| 267 |
Called when starting folding mode in a buffer with major |
| 268 |
mode set to <major mode>. (e.g. When editing C code |
| 269 |
the hook `c-mode-folding-hook' is called.) |
| 270 |
@item folding-load-hook |
| 271 |
Called when folding mode is loaded into Emacs. |
| 272 |
@end table |
| 273 |
|
| 274 |
@noindent Customization: The Mouse |
| 275 |
|
| 276 |
The variable @code{folding-behave-table} contains the actions |
| 277 |
which should be performed when the user clicks on an open fold, a |
| 278 |
closed fold etc. For example, if you prefer to `enter' a fold rather |
| 279 |
than `open' it you should rebind this variable. |
| 280 |
|
| 281 |
The variable @code{folding-default-mouse-keys-function} contains |
| 282 |
the name of the function used to bind your mouse keys. To use your own |
| 283 |
mouse bindings, create a function, say |
| 284 |
@command{my-folding-bind-mouse}, and set this variable to it. |
| 285 |
|
| 286 |
@noindent Customization: Keymaps |
| 287 |
|
| 288 |
When Emacs 19.29 was released, the keymap was divided into strict |
| 289 |
parts. (This division existed before, but a lot of packages, even the |
| 290 |
ones delivered with Emacs, ignored them.) |
| 291 |
|
| 292 |
@verbatim |
| 293 |
C-c <letter> -- Reserved for the users private keymap. |
| 294 |
C-c C-<letter> -- Major mode. (Some other keys are |
| 295 |
reserved as well.) |
| 296 |
C-c <Punctuation Char> <Whatever> |
| 297 |
-- Reserved for minor modes. |
| 298 |
@end verbatim |
| 299 |
|
| 300 |
The reason why @key{C-c@@} was chosen as the default prefix is |
| 301 |
that it is used by outline-minor-mode. It is not likely that few |
| 302 |
people will try to use folding and outline at the same time. |
| 303 |
|
| 304 |
However, old key bindings have been kept if possible. The |
| 305 |
variable @code{folding-default-keys-function} specifies which function |
| 306 |
should be called to bind the keys. There are various function to |
| 307 |
choose from how user can select the keybindings. To use the old key |
| 308 |
bindings, add the following line to your init file: |
| 309 |
|
| 310 |
@verbatim |
| 311 |
(setq folding-default-keys-function |
| 312 |
'folding-bind-backward-compatible-keys) |
| 313 |
@end verbatim |
| 314 |
|
| 315 |
To define keys similar to the keys used by Outline mode, use: |
| 316 |
|
| 317 |
@verbatim |
| 318 |
(setq folding-default-keys-function |
| 319 |
'folding-bind-outline-compatible-keys) |
| 320 |
@end verbatim |
| 321 |
|
| 322 |
@noindent Customization: adding new major modes |
| 323 |
|
| 324 |
To add fold marks for a new major mode, use the function |
| 325 |
@command{folding-add-to-marks-list}. Example: |
| 326 |
|
| 327 |
@verbatim |
| 328 |
(folding-add-to-marks-list |
| 329 |
'c-mode "/* {{{ " "/* }}} */" " */" t) |
| 330 |
(folding-add-to-marks-list |
| 331 |
'java-mode "// {{{ " "// }}}" nil t) |
| 332 |
@end verbatim |
| 333 |
|
| 334 |
@noindent Customization: ISearch |
| 335 |
|
| 336 |
If you don't like the extension folding.el applies to isearch, |
| 337 |
set the variable `folding-isearch-install' to nil before loading this |
| 338 |
package. |
| 339 |
|
| 340 |
@node folding Examples, , folding Customization, Top |
| 341 |
|
| 342 |
@noindent Example: personal setup |
| 343 |
|
| 344 |
To define your own key binding instead of using the standard |
| 345 |
ones, you can do like this: |
| 346 |
|
| 347 |
@verbatim |
| 348 |
(setq folding-mode-prefix-key "\C-c") |
| 349 |
;; |
| 350 |
(setq folding-default-keys-function |
| 351 |
'(folding-bind-backward-compatible-keys)) |
| 352 |
;; |
| 353 |
(setq folding-load-hook 'my-folding-load-hook) |
| 354 |
|
| 355 |
|
| 356 |
(defun my-folding-load-hook () |
| 357 |
"Folding setup." |
| 358 |
|
| 359 |
(folding-install) ;; just to be sure |
| 360 |
|
| 361 |
;; ............................................... markers ... |
| 362 |
|
| 363 |
;; Change text-mode fold marks. Handy for quick |
| 364 |
;; sh/perl/awk code |
| 365 |
|
| 366 |
(defvar folding-mode-marks-alist nil) |
| 367 |
|
| 368 |
(let* ((ptr (assq 'text-mode folding-mode-marks-alist))) |
| 369 |
(setcdr ptr (list "# {{{" "# }}}"))) |
| 370 |
|
| 371 |
;; ........................................ bindings ... |
| 372 |
|
| 373 |
;; Put `folding-whole-buffer' and `folding-open-buffer' |
| 374 |
;; close together. |
| 375 |
|
| 376 |
(defvar folding-mode-prefix-map nil) |
| 377 |
|
| 378 |
(define-key folding-mode-prefix-map "\C-w" nil) |
| 379 |
(define-key folding-mode-prefix-map "\C-s" |
| 380 |
'folding-show-current-entry) |
| 381 |
(define-key folding-mode-prefix-map "\C-p" |
| 382 |
'folding-whole-buffer)) |
| 383 |
@end verbatim |
| 384 |
|
| 385 |
@noindent Example: changing default fold marks |
| 386 |
|
| 387 |
In case you're not happy with the default folding marks, you can |
| 388 |
change them easily. Here is an example |
| 389 |
|
| 390 |
@verbatim |
| 391 |
(setq folding-load-hook 'my-folding-load-hook) |
| 392 |
|
| 393 |
(defun my-folding-load-hook () |
| 394 |
"Folding vars setup." |
| 395 |
(let* ((ptr (assq 'text-mode folding-mode-marks-alist))) |
| 396 |
(setcdr ptr (list "# {{{" "# }}}")))) |
| 397 |
@end verbatim |
| 398 |
|
| 399 |
|
| 400 |
@noindent Example: choosing different fold marks for mode |
| 401 |
|
| 402 |
Suppose you sometimes want to use different fold marks for the |
| 403 |
major mode: e.g. to alternate between "# @{@{@{" and "@{@{@{" in `text-mode' |
| 404 |
Call @command{M-x my-folding-text-mode-setup} to change the marks. |
| 405 |
|
| 406 |
@verbatim |
| 407 |
(defun my-folding-text-mode-setup (&optional use-custom-folding-marks) |
| 408 |
(interactive |
| 409 |
(list (y-or-n-p "Use Custom fold marks now? "))) |
| 410 |
(let* ((ptr (assq major-mode folding-mode-marks-alist)) |
| 411 |
(default-begin "# {{{") |
| 412 |
(default-end "# }}}") |
| 413 |
(begin "{{{") |
| 414 |
(end "}}}")) |
| 415 |
(when (eq major-mode 'text-mode) |
| 416 |
(unless use-custom-folding-marks |
| 417 |
(setq begin default-begin end default-end))) |
| 418 |
(setcdr ptr (list begin end)) |
| 419 |
(folding-set-marks begin end))) |
| 420 |
@end verbatim |
| 421 |
|
| 422 |
@noindent Example: AucTex setup |
| 423 |
|
| 424 |
Suppose you're using comment.sty with AucTeX for editing LaTeX2e |
| 425 |
documents and you have these comment types. You would like to be able |
| 426 |
to set which of these 3 is to be folded at any one time, using a |
| 427 |
simple key sequence: move back and forth easily between the different |
| 428 |
comment types, e.g., "unfold everything then fold on \x". |
| 429 |
|
| 430 |
@verbatim |
| 431 |
\O ... \endO |
| 432 |
\L ... \endL |
| 433 |
\B ... \endB |
| 434 |
|
| 435 |
(setq folding-load-hook 'my-folding-load-hook) |
| 436 |
|
| 437 |
(defun my-folding-load-hook () |
| 438 |
"Folding vars setup." |
| 439 |
(let ((ptr (assq 'text-mode folding-mode-marks-alist))) |
| 440 |
(setcdr ptr (list "\\O" "\\endO")) |
| 441 |
(define-key folding-mode-prefix-map "C" |
| 442 |
'my-folding-marks-change))) |
| 443 |
|
| 444 |
(defun my-folding-marks-change (&optional selection) |
| 445 |
"Select folding marks: prefixes nil, C-u and C-u C-u." |
| 446 |
(interactive "P") |
| 447 |
(let ((ptr (assq major-mode folding-mode-marks-alist)) |
| 448 |
input) |
| 449 |
(when (string-match "^\\(plain-\\|la\\|auc\\)?tex-" |
| 450 |
(symbol-name major-mode)) |
| 451 |
(setq input |
| 452 |
(read-string "Latex \\end(X) Marker (default O): " |
| 453 |
nil nil "O" nil)) |
| 454 |
(setq input (upcase input)) |
| 455 |
(turn-off-folding-mode) |
| 456 |
(folding-add-to-marks-list |
| 457 |
major-mode |
| 458 |
(concat "\\" input) (concat "\\end" input) nil nil t) |
| 459 |
;; (setcdr ptr (list (concat "\\" input) (concat "\\end" input))) |
| 460 |
(turn-on-folding-mode)))) |
| 461 |
;; End of example |
| 462 |
@end verbatim |