GNU bug report logs - #18296
24.4.50; doc string of `whitespace-mode'

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 18296 in the body.
You can then email your comments to 18296 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 24.4.50; doc string of `whitespace-mode'
Date: Tue, 19 Aug 2014 07:30:52 -0700 (PDT)

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 <at> 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''

Message #8 received at 18296 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 18296 <at> debbugs.gnu.org
Subject: Re: bug#18296: 24.4.50; doc string of `whitespace-mode'
Date: Sat, 30 Apr 2016 15:27:17 +0200

Drew Adams <drew.adams <at> 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

Message #11 received at 18296 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 18296 <at> debbugs.gnu.org
Subject: RE: bug#18296: 24.4.50; doc string of `whitespace-mode'
Date: Sat, 30 Apr 2016 07:52:03 -0800 (GMT-08:00)

> > 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.

Message #14 received at 18296 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 18296 <at> debbugs.gnu.org, larsi <at> gnus.org
Subject: Re: bug#18296: 24.4.50; doc string of `whitespace-mode'
Date: Sat, 30 Apr 2016 18:58:58 +0300

> Date: Sat, 30 Apr 2016 07:52:03 -0800 (GMT-08:00)
> From: Drew Adams <drew.adams <at> oracle.com>
> Cc: 18296 <at> 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.

Message #17 received at 18296 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>, Drew Adams <drew.adams <at> oracle.com>
Cc: 18296 <at> debbugs.gnu.org, larsi <at> gnus.org
Subject: RE: bug#18296: 24.4.50; doc string of `whitespace-mode'
Date: Sat, 30 Apr 2016 09:22:39 -0800 (GMT-08:00)

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

I agree.

Message #20 received at 18296 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 18296 <at> debbugs.gnu.org
Subject: Re: bug#18296: 24.4.50; doc string of `whitespace-mode'
Date: Sat, 04 Sep 2021 10:20:05 +0200

Lars Ingebrigtsen <larsi <at> 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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.