whitespace

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

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'
   Toggle NEWLINE minor mode visualization ("nl" on mode line).

`global-whitespace-newline-mode'
   Toggle NEWLINE global minor mode visualization ("NL" on mode line).

`whitespace-page-delimiters-mode'
   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' 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.


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