bug#18296: 24.4.50; doc string of `whitespace-mode'

bug#18296: 24.4.50; doc string of `whitespace-mode'

[Drew Adams]

1. Please mention which faces are used for which kinds of highlighting.

2. Wording:

 So, for example, if indentation and indentation::space are
 included in `whitespace-style' list, the indentation value is
 evaluated instead of indentation::space value.

 One reason for not visualize spaces via faces (if `face' is not
 included in `whitespace-style') is to use exclusively for
 cleaning up a buffer.  See `whitespace-cleanup' and
 `whitespace-cleanup-region' for documentation.

A minimal fix:

 For example, if `indentation' and `indentation::space' are included in
 `whitespace-style', the `indentation' value is used instead of the
 `indentation::space' value.

 One reason to not use faces to visualize spaces (i.e., not include
 `face' in `whitespace-style') is to use `whitespace-mode' only for
 cleaning up a buffer.  See `whitespace-cleanup' and
 `whitespace-cleanup-region'.


In GNU Emacs 24.4.50.1 (i686-pc-mingw32)
 of 2014-06-28 on ODIEONE
Bzr revision: 117431 rgm@gnu.org-20140628015517-eku6hj8mpgcvfnso
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/Devel/emacs/snapshot/trunk
 --enable-checking=yes,glyphs 'CFLAGS=-O0 -g3'
 LDFLAGS=-Lc:/Devel/emacs/lib 'CPPFLAGS=-DGC_MCHECK=1
 -Ic:/Devel/emacs/include''

bug#18296: 24.4.50; doc string of `whitespace-mode'

[Lars Ingebrigtsen]

Drew Adams <drew.adams@oracle.com> writes:

> 1. Please mention which faces are used for which kinds of highlighting.

Well, there's a lot of faces, and I think it's unusual for modes like
this to enumerate them.  But perhaps a link to the customisation group
would be nice?  Is there a syntax for that?

> 2. Wording:
>
>  So, for example, if indentation and indentation::space are
>  included in `whitespace-style' list, the indentation value is
>  evaluated instead of indentation::space value.
>
>  One reason for not visualize spaces via faces (if `face' is not
>  included in `whitespace-style') is to use exclusively for
>  cleaning up a buffer.  See `whitespace-cleanup' and
>  `whitespace-cleanup-region' for documentation.
>
> A minimal fix:
>
>  For example, if `indentation' and `indentation::space' are included in
>  `whitespace-style', the `indentation' value is used instead of the
>  `indentation::space' value.
>
>  One reason to not use faces to visualize spaces (i.e., not include
>  `face' in `whitespace-style') is to use `whitespace-mode' only for
>  cleaning up a buffer.  See `whitespace-cleanup' and
>  `whitespace-cleanup-region'.

Installed.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#18296: 24.4.50; doc string of `whitespace-mode'

[Drew Adams]

> > 1. Please mention which faces are used for which kinds of highlighting.
> 
> Well, there's a lot of faces, and I think it's unusual for modes like
> this to enumerate them.

There are N faces, nicely documented in `whitespace.el'.
Why not put this info in the doc?

`whitespace-space'            highlight SPACE
`whitespace-hspace'           highlight HARD SPACE
`whitespace-tab'              highlight TAB
`whitespace-newline'          highlight NEWLINE char mapping
`whitespace-trailing'	        highlight trailing blanks
`whitespace-line'             highlight "long" lines
`whitespace-space-before-tab' highlight SPACEs before TAB
`whitespace-indentation'      highlight 8+ SPACEs at bol
`whitespace-big-indent'       highlight big indentation
`whitespace-empty'            highlight empty lines at bob/eob
`whitespace-space-after-tab'  highlight 8+ SPACEs after TAB

(Quickly abbreviated from the commentary - not suggesting
that those are the best descriptions.  E.g., what is a newline
char mapping? what is "big" indentation?)

> But perhaps a link to the customisation group would be nice?

That would be OK too.  But the mode help is where I think
it belongs.

> Is there a syntax for that?

Dunno - not that I can think of.

bug#18296: 24.4.50; doc string of `whitespace-mode'

[Eli Zaretskii]

> Date: Sat, 30 Apr 2016 07:52:03 -0800 (GMT-08:00)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 18296@debbugs.gnu.org
> 
> There are N faces, nicely documented in `whitespace.el'.
> Why not put this info in the doc?

Because it is confusing, unless expanded and elaborated.

> `whitespace-space'            highlight SPACE
> `whitespace-hspace'           highlight HARD SPACE
> `whitespace-tab'              highlight TAB
> `whitespace-newline'          highlight NEWLINE char mapping
> `whitespace-trailing'	        highlight trailing blanks
> `whitespace-line'             highlight "long" lines
> `whitespace-space-before-tab' highlight SPACEs before TAB
> `whitespace-indentation'      highlight 8+ SPACEs at bol
> `whitespace-big-indent'       highlight big indentation
> `whitespace-empty'            highlight empty lines at bob/eob
> `whitespace-space-after-tab'  highlight 8+ SPACEs after TAB

Quick: what's the difference between "big indentation" and "SPACEs
before TAB"?  How can you determine which one will be applied to a
specific line?  And what's the difference between "SPACE" and "HARD
SPACE"?  And what is "NEWLINE char mapping"?  Etc., etc.

IOW, someone should work on this stuff before it can be put in a doc
string.

bug#18296: 24.4.50; doc string of `whitespace-mode'

[Drew Adams]

> IOW, someone should work on this stuff before it can be put
> in a doc string.

I agree.

bug#18296: 24.4.50; doc string of `whitespace-mode'

[Lars Ingebrigtsen]

Lars Ingebrigtsen <larsi@gnus.org> writes:

>> 1. Please mention which faces are used for which kinds of highlighting.
>
> Well, there's a lot of faces, and I think it's unusual for modes like
> this to enumerate them.  But perhaps a link to the customisation group
> would be nice?  Is there a syntax for that?

There wasn't, but I've now added it to Emacs 28, and I've also added a
link from the whitespace-mode doc string.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no