File: `whitespace.el.html`

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

Introduction
------------

This package is a minor mode to visualize blanks (TAB, (HARD) SPACE and NEWLINE).

whitespace uses two ways to visualize blanks: faces and display table.

* Faces are used to highlight the background with a color.
whitespace uses font-lock to highlight blank characters.

* Display table changes the way a character is displayed, that is,
it provides a visual mark for characters, for example, at the end
of line (?\xB6), at SPACEs (?\xB7) and at TABs (?\xBB).

The whitespace-style variable selects which way blanks are visualized.

Note that when whitespace is turned on, whitespace saves the font-lock state, that is, if font-lock is on or off. And whitespace restores the font-lock state when it is turned off. So, if whitespace is turned on and font-lock is off, whitespace also turns on the font-lock to highlight blanks, but the font-lock will be turned off when whitespace is turned off. Thus, turn on font-lock before whitespace is on, if you want that font-lock continues on after whitespace is turned off.

When whitespace is on, it takes care of highlighting some special characters over the default mechanism of nobreak-char-display
(which see) and show-trailing-whitespace (which see).

The trailing spaces are not highlighted while point is at end of line. Also the spaces at beginning of buffer are not highlighted while point is at beginning of buffer; and the spaces at end of buffer are not highlighted while point is at end of buffer.

There are two ways of using whitespace: local and global.

* Local whitespace affects only the current buffer.

* Global whitespace affects all current and future buffers. That
  is, if you turn on global whitespace and then create a new
  buffer, the new buffer will also have whitespace on. The
  whitespace-global-modes variable controls which major-mode will
  be automagically turned on.

You can mix the local and global usage without any conflict. But local whitespace has priority over global whitespace. Whitespace mode is active in a buffer if you have enabled it in that buffer or if you have enabled it globally.

When global and local whitespace are on:

* if local whitespace is turned off, whitespace is turned off for
the current buffer only.

* if global whitespace is turned off, whitespace continues on only
in the buffers in which local whitespace is on.

whitespace was inspired by:

whitespace.el Rajesh Vaidheeswarran <rv@gnu.org>
Warn about and clean bogus whitespaces in the file
(inspired the idea to warn and clean some blanks)
This was the original whitespace.el which was replaced by blank-mode.el. And later blank-mode.el was renamed to whitespace.el.

   show-whitespace-mode.el Aurelien Tisne <aurelien.tisne@free.fr>
      Simple mode to highlight whitespaces
      (inspired the idea to use font-lock)

   whitespace-mode.el Lawrence Mitchell <wence@gmx.li>
      Major mode for editing Whitespace
      (inspired the idea to use display table)

   visws.el Miles Bader <miles@gnu.org>
      Make whitespace visible
      (handle display table, his code was modified, but the main
      idea was kept)

Using whitespace
----------------

There is no problem if you mix local and global minor mode usage.

* LOCAL whitespace:
+ To toggle whitespace options locally, type:

M-x whitespace-toggle-options RET

+ To activate whitespace locally, type:

C-u 1 M-x whitespace-mode RET

+ To deactivate whitespace locally, type:

C-u 0 M-x whitespace-mode RET

+ To toggle whitespace locally, type:

M-x whitespace-mode RET

* GLOBAL whitespace:
+ To toggle whitespace options globally, type:

M-x global-whitespace-toggle-options RET

+ To activate whitespace globally, type:

C-u 1 M-x global-whitespace-mode RET

+ To deactivate whitespace globally, type:

C-u 0 M-x global-whitespace-mode RET

+ To toggle whitespace globally, type:

M-x global-whitespace-mode RET

There are also the following useful commands:

whitespace-newline-mode(var)/whitespace-newline-mode(fun)
Toggle NEWLINE minor mode visualization ("nl" on mode line).

global-whitespace-newline-mode(var)/global-whitespace-newline-mode(fun)
Toggle NEWLINE global minor mode visualization ("NL" on mode line).

whitespace-page-delimiters-mode(var)/whitespace-page-delimiters-mode(fun)
Display page delimiters characters as horizontal lines ("pd" on mode line).

whitespace-report
Report some blank problems in buffer.

whitespace-report-region
Report some blank problems in a region.

whitespace-cleanup
Cleanup some blank problems in all buffer or at region.
See the function's docstring for more information.

whitespace-cleanup-region
Cleanup some blank problems at region.

Options
-------

Whitespace's behavior can be changed with M-x customize-group whitespace, which see for the full list of options.

Hooks
-----

whitespace has the following hook variables:

whitespace-mode-hook
It is evaluated always when whitespace is turned on locally.

global-whitespace-mode-hook
It is evaluated always when whitespace is turned on globally.

whitespace-load-hook
It is evaluated after whitespace package is loaded.

Acknowledgments
---------------

Thanks to felix (EmacsWiki) for keeping highlight when switching between major modes on a file.

Thanks to David Reitter <david.reitter@gmail.com> for suggesting a whitespace-newline initialization with low contrast relative to the background color.

Thanks to Stephen Deasey <sdeasey@gmail.com> for the indent-tabs-mode(var)/indent-tabs-mode(fun) usage suggestion.

Thanks to Eric Cooper <ecc@cmu.edu> for the suggestion to have hook actions when buffer is written as the original whitespace package had.

Thanks to nschum (EmacsWiki) for the idea about highlight "long" lines tail. See EightyColumnRule (EmacsWiki).

Thanks to Juri Linkov <juri@jurta.org> for suggesting:
* define-minor-mode.
* global-whitespace-* name for global commands.

Thanks to Robert J. Chassell <bob@gnu.org> for doc fix and testing.

Thanks to Drew Adams <drew.adams@oracle.com> for toggle commands suggestion.

Thanks to Antti Kaihola <antti.kaihola@linux-aktivaattori.org> for helping to fix find-file-hooks reference.

Thanks to Andreas Roehler <andreas.roehler@easy-emacs.de> for indicating defface byte-compilation warnings.

Thanks to Tim O'Callaghan (EmacsWiki) for the idea about highlight
"long" lines. See EightyColumnRule (EmacsWiki).

Thanks to Yanghui Bian <yanghuibian@gmail.com> for indicating a new NEWLINE character mapping.

Thanks to Pete Forman <pete.forman@westgeo.com> for indicating whitespace-mode.el on XEmacs.

Thanks to Miles Bader <miles@gnu.org> for handling display table via visws.el (his code was modified, but the main idea was kept).

Thanks to:
   Rajesh Vaidheeswarran <rv@gnu.org> (original) whitespace.el
   Aurelien Tisne <aurelien.tisne@free.fr> show-whitespace-mode.el
   Lawrence Mitchell <wence@gmx.li> whitespace-mode.el
   Miles Bader <miles@gnu.org> visws.el
And to all people who contributed with them.

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

Defined variables (54)

`global-whitespace-mode`	Non-nil if Global Whitespace mode is enabled.
`global-whitespace-mode-hook`	Hook run after entering or leaving ‘global-whitespace-mode’.
`global-whitespace-newline-mode`	Non-nil if Global Whitespace-Newline mode is enabled.
`global-whitespace-newline-mode-hook`	Hook run after entering or leaving ‘global-whitespace-newline-mode’.
`whitespace--page-delimiters-keyword`	Used to add page delimiters keywords to ‘whitespace-font-lock-keywords’.
`whitespace-action`	Specify which action is taken when a buffer is visited or written.
`whitespace-active-style`	Used to save locally ‘whitespace-style’ value.
`whitespace-big-indent-regexp`	Regexp to match big indentation at BOL that should be visualized.
`whitespace-bob-marker`	Position of the buffer’s first non-empty line.
`whitespace-buffer-changed`	Used to indicate locally if buffer changed.
`whitespace-display-mappings`	Alist of mappings for displaying characters.
`whitespace-display-table`	Used to save a local display table.
`whitespace-display-table-was-local`	Used to remember whether a buffer initially had a local display table.
`whitespace-empty`	Symbol face used to visualize empty lines at beginning and/or end of buffer.
`whitespace-empty-at-bob-regexp`	Regexp to match empty lines at beginning of buffer that should be visualized.
`whitespace-empty-at-eob-regexp`	Regexp to match empty lines at end of buffer that should be visualized.
`whitespace-enable-predicate`	Predicate to decide which buffers obey ‘global-whitespace-mode’.
`whitespace-eob-marker`	Position after the buffer’s last non-empty line.
`whitespace-font-lock-keywords`	Used to save the value ‘whitespace-color-on’ adds to ‘font-lock-keywords’.
`whitespace-global-modes`	Modes for which global ‘whitespace-mode’ is automagically turned on.
`whitespace-help-buffer-name`	The buffer name for whitespace toggle options.
`whitespace-help-text`	Text for whitespace toggle options.
`whitespace-hspace`	Symbol face used to visualize HARD SPACE.
`whitespace-hspace-regexp`	Regexp to match HARD SPACE characters that should be visualized.
`whitespace-indentation`	Symbol face used to visualize ‘tab-width’ or more SPACEs at beginning of line.
`whitespace-indentation-regexp`	Regexps to match indentation whitespace that should be visualized.
`whitespace-line`	Symbol face used to visualize "long" lines.
`whitespace-line-column`	Column beyond which the line is highlighted.
`whitespace-mode`	Non-nil if Whitespace mode is enabled.
`whitespace-mode-hook`	Hook run after entering or leaving ‘whitespace-mode’.
`whitespace-newline`	Symbol face used to visualize NEWLINE char mapping.
`whitespace-newline-mode`	Non-nil if Whitespace-Newline mode is enabled.
`whitespace-newline-mode-hook`	Hook run after entering or leaving ‘whitespace-newline-mode’.
`whitespace-page-delimiters-mode`	Non-nil if Whitespace-Page-Delimiters mode is enabled.
`whitespace-page-delimiters-mode-hook`	Hook run after entering or leaving ‘whitespace-page-delimiters-mode’.
`whitespace-point`	Used to save locally current point value.
`whitespace-point--used`	Region whose highlighting depends on ‘whitespace-point’.
`whitespace-report-buffer-name`	The buffer name for whitespace bogus report.
`whitespace-report-list`	List of whitespace bogus symbol and corresponding regexp.
`whitespace-report-text`	Text for whitespace bogus report.
`whitespace-space`	Symbol face used to visualize SPACE.
`whitespace-space-after-tab`	Symbol face used to visualize ‘tab-width’ or more SPACEs after TAB.
`whitespace-space-after-tab-regexp`	Regexps to match multiple SPACEs after TAB that should be visualized.
`whitespace-space-before-tab`	Symbol face used to visualize SPACEs before TAB.
`whitespace-space-before-tab-regexp`	Regexp to match SPACEs before TAB that should be visualized.
`whitespace-space-regexp`	Regexp to match SPACE characters that should be visualized.
`whitespace-style`	Determine the kinds of whitespace are visualized.
`whitespace-style-value-list`	List of valid ‘whitespace-style’ values.
`whitespace-tab`	Symbol face used to visualize TAB.
`whitespace-tab-regexp`	Regexp to match TAB characters that should be visualized.
`whitespace-toggle-option-alist`	Alist of toggle options.
`whitespace-toggle-style`	Used to toggle the global ‘whitespace-style’ value.
`whitespace-trailing`	Symbol face used to visualize trailing blanks.
`whitespace-trailing-regexp`	Regexp to match trailing characters that should be visualized.

Defined functions (51)

`global-whitespace-mode`	(&optional ARG)
`global-whitespace-newline-mode`	(&optional ARG)
`global-whitespace-toggle-options`	(ARG)
`whitespace--clone`	()
`whitespace--empty-at-bob-matcher`	(LIMIT)
`whitespace--empty-at-eob-matcher`	(LIMIT)
`whitespace--indentation-matcher`	(LIMIT)
`whitespace--looking-back`	(REGEXP)
`whitespace--update-bob-eob`	(&optional BEG END &rest _)
`whitespace--variable-watcher`	(SYMBOL NEWVAL OP BUFFER)
`whitespace-action-when-on`	()
`whitespace-char-valid-p`	(CHAR)
`whitespace-cleanup`	()
`whitespace-cleanup-region`	(START END)
`whitespace-color-off`	()
`whitespace-color-on`	()
`whitespace-display-char-off`	()
`whitespace-display-char-on`	()
`whitespace-display-vector-p`	(VEC)
`whitespace-display-window`	(BUFFER)
`whitespace-help-off`	()
`whitespace-help-on`	(STYLE)
`whitespace-help-scroll`	(&optional UP)
`whitespace-indentation-regexp`	(&optional KIND)
`whitespace-insert-option-mark`	(THE-LIST THE-VALUE)
`whitespace-insert-value`	(VALUE)
`whitespace-interactive-char`	(LOCAL-P)
`whitespace-kill-buffer`	(BUFFER-NAME)
`whitespace-lines-regexp`	(LIMIT)
`whitespace-mark-x`	(NCHARS CONDITION)
`whitespace-mode`	(&optional ARG)
`whitespace-newline-mode`	(&optional ARG)
`whitespace-page-delimiters-mode`	(&optional ARG)
`whitespace-point--flush-used`	(LIMIT)
`whitespace-point--used`	(START END)
`whitespace-post-command-hook`	()
`whitespace-regexp`	(REGEXP &optional KIND)
`whitespace-replace-action`	(ACTION RSTART REND REGEXP INDEX)
`whitespace-report`	(&optional FORCE REPORT-IF-BOGUS)
`whitespace-report-region`	(START END &optional FORCE REPORT-IF-BOGUS)
`whitespace-space-after-tab-regexp`	(&optional KIND)
`whitespace-style-face-p`	()
`whitespace-style-mark-p`	()
`whitespace-toggle-list`	(LOCAL-P ARG THE-LIST)
`whitespace-toggle-options`	(ARG)
`whitespace-trailing-regexp`	(LIMIT)
`whitespace-turn-off`	()
`whitespace-turn-on`	()
`whitespace-unload-function`	()
`whitespace-warn-read-only`	(MSG)
`whitespace-write-file-hook`	()

Defined faces (13)

`whitespace-big-indent`	Face used to visualize big indentation. See ‘whitespace-big-indent-regexp’.
`whitespace-empty`	Face used to visualize empty lines at beginning and/or end of buffer. See ‘whitespace-empty-at-bob-regexp’ and ‘whitespace-empty-at-eob-regexp.
`whitespace-hspace`	Face used to visualize HARD SPACE. See ‘whitespace-hspace-regexp’.
`whitespace-indentation`	Face used to visualize ‘tab-width’ or more SPACEs at beginning of line. See ‘whitespace-indentation-regexp’.
`whitespace-line`	Face used to visualize "long" lines. See ‘whitespace-line-column’.
`whitespace-missing-newline-at-eof`	Face used to visualize missing newline at the end of the file.
`whitespace-newline`	Face used to visualize NEWLINE char mapping. See ‘whitespace-display-mappings’.
`whitespace-page-delimiter`	Face used to visualize page delimiter characters.
`whitespace-space`	Face used to visualize SPACE. See ‘whitespace-space-regexp’.
`whitespace-space-after-tab`	Face used to visualize ‘tab-width’ or more SPACEs after TAB. See ‘whitespace-space-after-tab-regexp’.
`whitespace-space-before-tab`	Face used to visualize SPACEs before TAB. See ‘whitespace-space-before-tab-regexp’.
`whitespace-tab`	Face used to visualize TAB. See ‘whitespace-tab-regexp’.
`whitespace-trailing`	Face used to visualize trailing blanks. See ‘whitespace-trailing-regexp’.

File: whitespace.el.html

Defined variables (54)

Defined functions (51)

Defined faces (13)

File: `whitespace.el.html`