+;; * Customization
+;;
+;; You can use `M-x customize-variable' on the following variables:
+;;
+;; - hs-hide-comments-when-hiding-all -- self-explanatory!
+;; - hs-hide-all-non-comment-function -- if non-nil, when doing a
+;; `hs-hide-all', this function
+;; is called w/ no arguments
+;; - hs-isearch-open -- what kind of hidden blocks to
+;; open when doing isearch
+;;
+;; Some languages (e.g., Java) are deeply nested, so the normal behavior
+;; of `hs-hide-all' (hiding all but top-level blocks) results in very
+;; little information shown, which is not very useful. You can use the
+;; variable `hs-hide-all-non-comment-function' to implement your idea of
+;; what is more useful. For example, the following code shows the next
+;; nested level in addition to the top-level:
+;;
+;; (defun ttn-hs-hide-level-1 ()
+;; (hs-hide-level 1)
+;; (forward-sexp 1))
+;; (setq hs-hide-all-non-comment-function 'ttn-hs-hide-level-1)
+;;
+;; Hideshow works w/ incremental search (isearch) by setting the variable
+;; `hs-headline', which is the line of text at the beginning of a hidden
+;; block that contains a match for the search. You can have this show up
+;; in the mode line by modifying the variable `mode-line-format'. For
+;; example, the following code prepends this info to the mode line:
+;;
+;; (unless (memq 'hs-headline mode-line-format)
+;; (setq mode-line-format
+;; (append '("-" hs-headline) mode-line-format)))
+;;
+;; See documentation for `mode-line-format' for more info.
+;;
+;; Hooks are run after some commands:
+;;
+;; hs-hide-hook in hs-hide-block, hs-hide-all, hs-hide-level
+;; hs-show-hook hs-show-block, hs-show-all
+;;
+;; One of `hs-hide-hook' or `hs-show-hook' is run for the toggling
+;; commands when the result of the toggle is to hide or show blocks,
+;; respectively. All hooks are run w/ `run-hooks'. See docs for each
+;; variable or hook for more info.
+;;
+;; Normally, hideshow tries to determine appropriate values for block
+;; and comment definitions by examining the buffer's major mode. If
+;; there are problems, hideshow will not activate and in that case you
+;; may wish to override hideshow's heuristics by adding an entry to
+;; variable `hs-special-modes-alist'. Packages that use hideshow should
+;; do something like:
+;;
+;; (let ((my-mode-hs-info '(my-mode "{{" "}}" ...)))
+;; (if (not (member my-mode-hs-info hs-special-modes-alist))
+;; (setq hs-special-modes-alist
+;; (cons my-mode-hs-info hs-special-modes-alist))))
+;;
+;; If you have an entry that works particularly well, consider
+;; submitting it for inclusion in hideshow.el. See docstring for
+;; `hs-special-modes-alist' for more info on the entry format.
+
+;; * Bugs
+;;
+;; (1) Hideshow does not work w/ emacs 18 because emacs 18 lacks the
+;; function `forward-comment' (among other things). If someone
+;; writes this, please send me a copy.
+;;
+;; (2) Sometimes `hs-headline' can become out of sync. To reset, type
+;; `M-x hs-minor-mode' twice (that is, deactivate then re-activate
+;; hideshow).
+;;
+;; (3) Hideshow 5.x is developed and tested on GNU Emacs 20.7.
+;; XEmacs compatibility may have bitrotted since 4.29.
+;;
+;; (4) Some buffers can't be `byte-compile-file'd properly. This is because
+;; `byte-compile-file' inserts the file to be compiled in a temporary
+;; buffer and switches `normal-mode' on. In the case where you have
+;; `hs-hide-initial-comment-block' in `hs-minor-mode-hook', the hiding of
+;; the initial comment sometimes hides parts of the first statement (seems
+;; to be only in `normal-mode'), so there are unbalanced "(" and ")".
+;;
+;; The workaround is to clear `hs-minor-mode-hook' when byte-compiling:
+;;
+;; (defadvice byte-compile-file (around
+;; byte-compile-file-hideshow-off
+;; act)
+;; (let ((hs-minor-mode-hook nil))
+;; ad-do-it))
+;;
+;; (5) Hideshow interacts badly with Ediff and `vc-diff'. At the moment, the
+;; suggested workaround is to turn off hideshow entirely, for example:
+;;
+;; (defun turn-off-hideshow () (hs-minor-mode -1))
+;; (add-hook 'ediff-prepare-buffer-hook 'turn-off-hideshow)
+;; (add-hook 'vc-before-checkin-hook 'turn-off-hideshow)
+;;
+;; In the case of `vc-diff', here is a less invasive workaround:
+;;
+;; (add-hook 'vc-before-checkin-hook
+;; '(lambda ()
+;; (goto-char (point-min))
+;; (hs-show-block)))
+;;
+;; Unfortunately, these workarounds do not restore hideshow state.
+;; If someone figures out a better way, please let me know.
+
+;; * Correspondance
+;;
+;; Correspondance welcome; please indicate version number. Send bug
+;; reports and inquiries to <ttn@gnu.org>.