Debian Codegraph @

folding.texi

raw
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