RE: checkdoc (was: mh-e 6.2 imminent)

RE: checkdoc (was: mh-e 6.2 imminent)

[Eric M. Ludlam]

Hi,

  Every suggestion from the Emacs Lisp reference manual that could be
easily tested, and auto-fixed was put into checkdoc.  This has oft
provided contention over if the tests were good or bad.  I opted not
to post judgment and have no personal stake in the different tests.

  Every test in the checkdoc code is prefixed with a comment that
specifies why the test is there, thus a quote from the manual is
there, or I wrote in "Addendum" when I added something I thought was
lacking.

  I do recommend changing the manual if you want to hack out a test
though.

  Lastly, checkdoc's original organic growth lead to some lack of
configurability.  I have a reconstituted checkdoc engine, but never
finished porting the tests.  The engine would keep every test in it's
own function, and the test selection would be customizable via a
simple list.  Lute.Kamstra@cwi.nl offered to take that engine, and
finish porting the tests.  I don't know what the current state is.
It will be a long task though.

Eric

>> I've never heard of this `convention,' and indeed, it sounds kind of
>> dumb -- a `-flag' suffix doesn't really add any useful information
>> (if you know the _meaning_ of a variable, then you already know whether
>> it's boolean or not, and if you don't know the meaning, well, then it
>> hardly helps you to know that it's boolean!).
>
>It's sadly even mentioned in the elisp doc :-(
>
>	work/emacs-0% grep -C flag lispref/tips.texi 
>	@item
>	If a user option variable records a true-or-false condition, give it a
>	name that ends in @samp{-flag}.
>	[...]
>
>Luckily it's rarely folowed.
>
>> Why on earth does checkdoc try to enforce this?  Can we take that out?
>
>I'd be happy to.
>
>> [I have my own agendas of course -- I'd like to make checkdoc complain
>> if people use a `-p' suffix for variables, or a `-face' suffix for
>> faces...]
>
>Agreed for the `-p'.  For `-face', I'm still not sure either way.
>
>
>	Stefan
>

-- 
          Eric Ludlam:                 zappo@gnu.org, eric@siege-engine.com
   Home: http://www.ludlam.net            Siege: www.siege-engine.com
Emacs: http://cedet.sourceforge.net               GNU: www.gnu.org

Re: checkdoc (was: mh-e 6.2 imminent)

[Stefan Monnier]

>   Every suggestion from the Emacs Lisp reference manual that could be
> easily tested, and auto-fixed was put into checkdoc.  This has oft
> provided contention over if the tests were good or bad.  I opted not
> to post judgment and have no personal stake in the different tests.

And I agree with your approach.  The only problem I can see really
(besides those in the coding convention ;-), is that when a
test fails, the testing is aborted.  That is unfortunate when
I want to leave one argument unmentioned but would still want
to check that the symbols are properly quoted.

Also that means that C-u checkdoc-current-buffer RET does not
actually list all the issues.  Maybe there's a way to configure
it differently, but it I didn't see it.


	Stefan

Re[2]: checkdoc (was: mh-e 6.2 imminent)

[Eric M. Ludlam]

>>> "Stefan Monnier" <monnier+gnu/emacs@rum.cs.yale.edu> seems to think that:
>>   Every suggestion from the Emacs Lisp reference manual that could be
>> easily tested, and auto-fixed was put into checkdoc.  This has oft
>> provided contention over if the tests were good or bad.  I opted not
>> to post judgment and have no personal stake in the different tests.
>
>And I agree with your approach.  The only problem I can see really
>(besides those in the coding convention ;-), is that when a
>test fails, the testing is aborted.  That is unfortunate when
>I want to leave one argument unmentioned but would still want
>to check that the symbols are properly quoted.
>
>Also that means that C-u checkdoc-current-buffer RET does not
>actually list all the issues.  Maybe there's a way to configure
>it differently, but it I didn't see it.
  [ ... ]

Yes, the mechanism is not very flexible which is why I had originally
started trying to rearchitect the insides.  I guess I couldn't fathom
why anyone would not want to fix all the problems. ;)

The prefix argument should allow more than one error message per doc
string, with a few exceptions in some cascading style checks.
Perhaps it broke somewhere in its history.

Eric

-- 
          Eric Ludlam:                 zappo@gnu.org, eric@siege-engine.com
   Home: http://www.ludlam.net            Siege: www.siege-engine.com
Emacs: http://cedet.sourceforge.net               GNU: www.gnu.org

Re: checkdoc (was: mh-e 6.2 imminent)

[Bill Wohler]

"Eric M. Ludlam" <eric@siege-engine.com> writes:

>   I do recommend changing the manual if you want to hack out a test
> though.

  Definitely. The manual and checkdoc should be kept in sync and not
  play different tunes.

--
Bill Wohler <wohler@newt.com>  http://www.newt.com/wohler/  GnuPG ID:610BD9AD
Maintainer of comp.mail.mh FAQ and mh-e. Vote Libertarian!
If you're passed on the right, you're in the wrong lane.

mh-e 6.2 imminent

[Bill Wohler]

  I noticed that Emacs is in pre-release. We expect to release a beta of
  mh-e 6.2 at the end of the month. I assume that the pre-release means
  that only bug fixes are allowed, but if this isn't strictly the case,
  I was wondering if I'd be able to update mh-e when we're ready. It's a
  pretty big release (release notes enclosed), but is limited to just
  the mh-e files so it should be little or no risk to the rest of the
  project.


* Changes in mh-e 6.2

This is a major minor release which includes a lot of new features
including improved MIME handling, speedbar folder browsing, and
indexed searching. In this version, mh-e runs under XEmacs and
compiles clean under all supported platforms.

** New Features in mh-e 6.2

*** Speedbar

There is now support for the speedbar. Try "M-x speedbar" (closes SF
#503727). 

Press the middle mouse button on the `+' icons to open a folder,
middle mouse button on a folder name to open the folder. Folders with
unseen messages are shown in bold, so this is a handy way to browse
new messages that you have filed with procmail or slocal.

See the new customization variable `mh-large-folder,' which controls
when the speedbar asks for how many messages to scan when opening a
large folder.

*** Indexed search

Interoperability with swish, glimpse, and namazu has been added to
enable lightening-fast searches of your mail. If none of these are
present, grep is used. Try "F i (mh-index-search)".

For more information, read the documentation for the functions
`mh-swish-execute-search,' `mh-namazu-execute-search,' or
`mh-glimpse-execute-search' depending on your preferred indexing
program to see what kind of setup is needed to generate the index.
You'll first need to run "F i" or load "mh-thread" to read the
documentation.

*** Threading

Use "T t (mh-toggle-threads)" to view the threads in the folder. Use
it again to return to a non-threaded view.

*** Brief help

Use "? (mh-help)" and "X ? (mh-prefix-help)," where X is a prefix
character, for a brief synopsis in the minibuffer of frequently used
commands. In the MH-Letter or MH-Pick buffers, use "C-c ? (mh-help)"
(closes SF #493740).

*** Folder keymap shared by show buffer

You can now use the MH-Folder mode commands from the MH-Show buffer.
Because of this, the MH-Show buffer is now read-only (closes SF
#527946) and you now have to use "M (mh-modify)" to edit a message.
 
*** Better scanning

You no longer have to modify your scan format if your folders have
more than 9999 messages in them. If you've only modified your scan
format file to allow for the wider message numbers, consider removing
your modifications of `mh-scan.*-regexp' and `mh-cmd-note', set the
new customization variable `mh-adaptive-cmd-note' to t, and
`mh-scan-format-file' to its default (t).

You may still want the updated format files for running MH commands
outside of mh-e, but these changes will simplify your mh-e
configuration considerably.

*** X-Face

mh-e now displays the content of the X-Face header field in the From
field. When sending a message, an X-Face field is appended to the
header if it doesn't already exist and "~/.face" is present. See the
new customization variables `mh-show-use-xface' and `mh-x-face-file'
(closes SF #480770).

mh-e depends on the external x-face package found in
ftp://ftp.jpl.org/pub/elisp/ to do this.

*** Graphical smileys

Smiley's are now converted to cute little images. See the new
customization variable `mh-graphical-smileys-p.'

*** Text emphasis

ASCII formatting is now converted to the appropriate font. For
example, *bold* appears in bold, /italic/ appears in italic, etc. See
the new customization variables `mh-decode-mime' and
`mh-graphical-emphasis-p.'

*** Attachment handling

Inline attachments are now displayed. Regular attachments appear as
buttons in show buffer. Use "K TAB (mh-next-button)" or "K SHIFT-TAB
(mh-prev-button)" to cycle through these buttons. Use "K v
(mh-folder-toggle-mime-part)" to view, "K o
(mh-folder-save-mime-part)" to save one part or "M-x
mh-store-mime-parts" to save all parts, or "K i
(mh-folder-inline-mime-part)" to view the attachment inline.

See the new customization variable `mh-decode-mime' for additional
information. In additiona, see the new customization variable
`mh-store-mime-parts-default-directory.'

HTML documents can be viewed inline if Gnus v5.9 and w3 or w3m lisp
packages are present. Set the customization variable
`mm-text-html-renderer' accordingly (closes SF #453352).

*** Quoted-printable handling

Quoted-printable body parts are now decoded.

*** More choices for `mh-yank-from-start-of-msg'

Historically, if this variable was t, the entire message, with full
headers would be included and every line would begin with
`mh-ins-buf-prefix.' This usage is deprecated in favor of the setting
`supercite' below. The default has been changed to `attribution.' The
following symbols are now understood:

`body': yank the message minus the header.

`supercite': include the entire message, with full headers. This also
causes the invocation of `sc-cite-original' without the setting of
`mail-citation-hook', now deprecated practice.

`autosupercite': do as for `supercite' automatically when show buffer
matches the message being replied-to.

`attribution': yank the message minus the header and add a simple
attribution line at the top.

`autoattrib': do as for `attribution' automatically when show buffer
matches the message being replied-to.

There is a new customization variable called
`mh-extract-from-attribution-verb' which is used for attribution which
provides a method for setting a different language.

*** Use Gnus mml instead of mhn

When inserting attachments into a message draft, Gnus mml directives
are now used instead of mhn directives. One beneficial side-effect of
this is that attachments can now appear inline as well as separate.

The new customization variable `mh-compose-insertion' controls whether
Gnus or mhn is used to insert MIME message directives in messages
(default: 'gnus, if the mml library exists).

*** Content-Type now obtained automatically

The value of the Content-Type no longer needs to be entered by the
user.

*** Attachments automatically included upon send

You no longer have to run "C-c C-e (mh-edit-mhn)" before sending a
message with attachments--this is done automatically when you send the
message with "C-c C-c (mh-send-letter)". There is, however, a new key
binding "C-c C-m m (mh-mml-to-mime)" which is analogous to "C-c C-e
(mh-edit-mhn)".

** New Variables in mh-e 6.2

New customization variables not mentioned earlier include:

*** mh-tool-bar-reply-3-buttons

Non-nil means use three buttons for reply commands in tool-bar. If you
have room on your tool-bar because you are using a large font, you may
set this variable to expand the single reply button into three buttons
that won't lead to minibuffer prompt about who to reply to.

** Bug Fixes in mh-e 6.2

*** mh-delete-msg, mh-refile-msg, mh-undo

Mandrake Linux includes XEmacs initialization code that binds
`transient-mark-mode' which causes problems in mh-e. These problems
have been fixed (closes SF #541915).

*** mh-edit-again

This would sometimes yield a read-only buffer. This has been fixed
(closes SF #624283).

*** mh-next-undeleted-msg, mh-previous-undeleted-msg 

If there are no more undeleted messages the point remains at its
original position and a message is produced (closes SF #494304).

*** mh-refile-msg, mh-write-msg-to-file

These functions stomped on the variables that held the name of the
last file and folder respectively for the other function. This has
been fixed so that the last folder or file name is preserved (closes
SF #580772).

*** mh-region-to-sequence

If the region in MH-Folder was set with "C-x h (mark-whole-buffer)",
you couldn't perform operations on all of the messages as you would
expect. This has been fixed (closes SF #621632).

*** mh-reply

Performing an undo the first thing after replying would blank out the
entire draft. Now just the insertion of the yanked message is undone
leaving the header and signature intact for additional editing (closes
SF #623693).

*** mh-subject-thread-to-sequence

Make 'subject sequence a real one, exported to MH. This means you can,
for example, mh-forward it. But it also shows up with a mark in the
scan output (closes SF #489445).



--
Bill Wohler <wohler@newt.com>  http://www.newt.com/wohler/  GnuPG ID:610BD9AD
Maintainer of comp.mail.mh FAQ and mh-e. Vote Libertarian!
If you're passed on the right, you're in the wrong lane.

Re: mh-e 6.2 imminent

[Richard Stallman]

      I noticed that Emacs is in pre-release. We expect to release a beta of
      mh-e 6.2 at the end of the month. I assume that the pre-release means
      that only bug fixes are allowed, but if this isn't strictly the case,

You can update mh-e fully whenever you like.  The current pretest is
irrelevant to this.

Re: mh-e 6.2 imminent

[Bill Wohler]

Kim F. Storm <storm@cua.dk> wrote:

> Release 21.3 is a maintenance release from the 21.1 release branch.
> 
> Release 21.4 is to be released from the CVS trunk which is still not
> in feature freeze, so currently it would be ok to update mh-e on the
> trunk.

  Ah, that explains a lot.

> > This is a major minor release
> 
> A major minor release :-) 

  So you noticed ;-). In addition to all of the new features, we also
  took pains to get mh-e to compile cleanly. It now also passes checkdoc
  cleanly, except for some old boolean variables that don't end in
  -flag. We'd like to fix those up before committing to Emacs and reduce
  the user exposure to the change, and obviously bump the major version
  to reflect that change (7.0).

Richard Stallman <rms@gnu.org> wrote:

> You can update mh-e fully whenever you like.

  Thank you. Will do. Expect a version 7.0 that will be more robust than
  6.2 would have been by the end of November or so.

--
Bill Wohler <wohler@newt.com>  http://www.newt.com/wohler/  GnuPG ID:610BD9AD
Maintainer of comp.mail.mh FAQ and mh-e. Vote Libertarian!
If you're passed on the right, you're in the wrong lane.

Re: mh-e 6.2 imminent

[Stefan Monnier]

>   So you noticed ;-). In addition to all of the new features, we also
>   took pains to get mh-e to compile cleanly. It now also passes checkdoc
>   cleanly, except for some old boolean variables that don't end in
>   -flag. We'd like to fix those up before committing to Emacs and reduce
>   the user exposure to the change, and obviously bump the major version
>   to reflect that change (7.0).

Don't take checkdoc too literally.  I for one strongly dislike the
idea of using -flag postfixes, as I've already mentioned somewhere,
among other things because it's not a widely followed convention
and because many boolean variables turn into 3-way (or more) variables
over time.
It's more important to keep the old names than to try to follow some
rarely followed convention.


	Stefan

Re: mh-e 6.2 imminent

[Miles Bader]

"Stefan Monnier" <monnier+gnu/emacs@rum.cs.yale.edu> writes:
> Don't take checkdoc too literally.  I for one strongly dislike the
> idea of using -flag postfixes, as I've already mentioned somewhere,
> among other things because it's not a widely followed convention
> and because many boolean variables turn into 3-way (or more) variables
> over time.

I've never heard of this `convention,' and indeed, it sounds kind of
dumb -- a `-flag' suffix doesn't really add any useful information
(if you know the _meaning_ of a variable, then you already know whether
it's boolean or not, and if you don't know the meaning, well, then it
hardly helps you to know that it's boolean!).

Why on earth does checkdoc try to enforce this?  Can we take that out?

[I have my own agendas of course -- I'd like to make checkdoc complain
if people use a `-p' suffix for variables, or a `-face' suffix for
faces...]

-Miles
-- 
`Life is a boundless sea of bitterness'

checkdoc (was: mh-e 6.2 imminent)

[Stefan Monnier]

> I've never heard of this `convention,' and indeed, it sounds kind of
> dumb -- a `-flag' suffix doesn't really add any useful information
> (if you know the _meaning_ of a variable, then you already know whether
> it's boolean or not, and if you don't know the meaning, well, then it
> hardly helps you to know that it's boolean!).

It's sadly even mentioned in the elisp doc :-(

	work/emacs-0% grep -C flag lispref/tips.texi 
	@item
	If a user option variable records a true-or-false condition, give it a
	name that ends in @samp{-flag}.
	[...]

Luckily it's rarely folowed.

> Why on earth does checkdoc try to enforce this?  Can we take that out?

I'd be happy to.

> [I have my own agendas of course -- I'd like to make checkdoc complain
> if people use a `-p' suffix for variables, or a `-face' suffix for
> faces...]

Agreed for the `-p'.  For `-face', I'm still not sure either way.


	Stefan

Re: checkdoc (was: mh-e 6.2 imminent)

[Kim F. Storm]

"Stefan Monnier" <monnier+gnu/emacs@rum.cs.yale.edu> writes:

re. removing check for -flag, count me in!

> 
> > [I have my own agendas of course -- I'd like to make checkdoc complain
> > if people use a `-p' suffix for variables, or a `-face' suffix for
> > faces...]
> 
> Agreed for the `-p'.  For `-face', I'm still not sure either way.

Well, I agree with Miles that formally, the -face suffix is redundant
since faces have their own namespace.

However, when you want to customize a group, I think having the face
suffix makes a big difference to the user.  

E.g. try customize-group on ido; there you will see the following
headings to customize ido's faces:

	Ido First Match Face: (sample) [Show Face]
	
	Ido Only Match Face: (sample) [Show Face]
	
	Ido Subdir Face: (sample) [Show Face]
	
	Ido Indicator Face: (sample) [Show Face]

which I definitely prefer to 

	Ido First Match: (sample) [Show Face]
	
	Ido Only Match: (sample) [Show Face]
	
	Ido Subdir: (sample) [Show Face]
	
	Ido Indicator: (sample) [Show Face]

Also, for code maintenance, I personally think having the -face suffix
on faces makes the code easier to read!

So in my option -face suffix is preferable, and I would actually
argue in favour of _recommending_ using it (which most lisp
packages seem to do anyway)!

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: checkdoc (was: mh-e 6.2 imminent)

[Miles Bader]

On Thu, Oct 24, 2002 at 01:13:11PM +0200, Kim F. Storm wrote:
> However, when you want to customize a group, I think having the face
> suffix makes a big difference to the user.  
> 
> E.g. try customize-group on ido; there you will see the following
> headings to customize ido's faces:
> 
> 	Ido First Match Face: (sample) [Show Face]
> 
> which I definitely prefer to 
> 
> 	Ido First Match: (sample) [Show Face]

Have you tried it with a non `-face' face?  Customize-face will automatically
put in a `face:' after the name to make it more clear.

> So in my option -face suffix is preferable, and I would actually
> argue in favour of _recommending_ using it (which most lisp
> packages seem to do anyway)!

No, it's probably more about half and half.  In particular, the `base' faces
(those defined in faces.el) don't use it.

As far as I can figure, the use of `-face' results from people confusing
faces with variables that point to faces; it seems that the latter used to
be more common than they are now (e.g. the variables and faces used by
font-lock).

-Miles
-- 
P.S.  All information contained in the above letter is false,
      for reasons of military security.

Re: checkdoc (was: mh-e 6.2 imminent)

[Kim F. Storm]

Miles Bader <miles@gnu.org> writes:

> Have you tried it with a non `-face' face?  Customize-face will automatically
> put in a `face:' after the name to make it more clear.

Obviuosly not :-)

> 
> > So in my option -face suffix is preferable, and I would actually
> > argue in favour of _recommending_ using it (which most lisp
> > packages seem to do anyway)!
> 
> No, it's probably more about half and half.  In particular, the `base' faces
> (those defined in faces.el) don't use it.

Gnus/message/customize/widget/diff/ediff/font-lock all use the -face suffix.
Only the basic faces seem not to use the -face suffix.

> 
> As far as I can figure, the use of `-face' results from people confusing
> faces with variables that point to faces; it seems that the latter used to
> be more common than they are now (e.g. the variables and faces used by
> font-lock).

True.

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: checkdoc (was: mh-e 6.2 imminent)

[Miles Bader]

On Thu, Oct 24, 2002 at 06:15:42PM +0200, Kim F. Storm wrote:
> Gnus/message/customize/widget/diff/ediff/font-lock all use the -face suffix.
> Only the basic faces seem not to use the -face suffix.

A quick grep shows:  out of 498 defface's 312 use `-face', so 3/5.

-Miles
-- 
P.S.  All information contained in the above letter is false,
      for reasons of military security.

Re: checkdoc (was: mh-e 6.2 imminent)

[Richard Stallman]

    Gnus/message/customize/widget/diff/ediff/font-lock all use the -face suffix.
    Only the basic faces seem not to use the -face suffix.

Perhaps we should rename the others for greater consistency.

Re: checkdoc (was: mh-e 6.2 imminent)

[Kim F. Storm]

Richard Stallman <rms@gnu.org> writes:

>     Gnus/message/customize/widget/diff/ediff/font-lock all use the -face suffix.
>     Only the basic faces seem not to use the -face suffix.
> 
> Perhaps we should rename the others for greater consistency.

Given Miles' statistics, that's +300 face names to be changed!

Since some (many?) of those are user customizeable, changing their
name would be problematic -- so I suggest leaving things as they are!


-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: checkdoc (was: mh-e 6.2 imminent)

[Richard Stallman]

    Given Miles' statistics, that's +300 face names to be changed!

    Since some (many?) of those are user customizeable, changing their
    name would be problematic -- so I suggest leaving things as they are!

We could make an alias mechanism for faces.

Re: checkdoc (was: mh-e 6.2 imminent)

[Kim F. Storm]

Richard Stallman <rms@gnu.org> writes:

>     Given Miles' statistics, that's +300 face names to be changed!
> 
>     Since some (many?) of those are user customizeable, changing their
>     name would be problematic -- so I suggest leaving things as they are!
> 
> We could make an alias mechanism for faces.

Yes, but I still feel we could spend our time better on other things
than renaming and creating aliases for 300+ faces -- if the _users_
will never see the difference (as Miles pointed out, customize adds
"Face" to the face name if its missing...

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: checkdoc (was: mh-e 6.2 imminent)

[Richard Stallman]

    Yes, but I still feel we could spend our time better on other things
    than renaming and creating aliases for 300+ faces -- if the _users_
    will never see the difference (as Miles pointed out, customize adds
    "Face" to the face name if its missing...

You may be right.  But we can still document a convention for this,
for the future.

One interesting question is, are there cases where ending a face name
with -face is actually beneficial?  What do people think?

Re: checkdoc (was: mh-e 6.2 imminent)

[Henrik Enberg]

Richard Stallman <rms@gnu.org> writes:

> One interesting question is, are there cases where ending a face name
> with -face is actually beneficial?  What do people think?

I think it's pretty natural to end them with -face.  For one thing, it
makes it easy to look up with apropos.  And take something like
`font-lock-keyword-face', what would be a better name?  the current
name is self-documenting.

-- 
Booting... /vmemacs.el

Re: checkdoc (was: mh-e 6.2 imminent)

[Miles Bader]

On Mon, Oct 28, 2002 at 08:38:10PM +0100, Henrik Enberg wrote:
> I think it's pretty natural to end them with -face.  And take something
> like `font-lock-keyword-face', what would be a better name?

`font-lock-keyword'

[e.g., (setq font-lock-keyword-face 'font-lock-keyword) ]

> the current name is self-documenting.

If we ended every variable in `-variable', they would all be "self
documenting" too.

The question is whether this is useful property, more than it is an annoying
one (and I think you'll agree that calling every variable foo-variable would
be really annoying!).

When I look at source code [I just did this using grep] that refers to
constant face names, which is the main place where this matters, I see
things like:

   (defface foo-face ...)

   (defvar blah-blah-face 'foo-face)

   (put-text-property X Y 'face 'foo-face)

   (set-face-foreground 'foo-face "...")

   (copy-face 'foo-face)

   (let ((face (make-face 'foo-face))) ...)

   (cons 'foo-face list-of-faces)

Note that all these cases, the `-face' in the face name doesn't help at all,
because the variable/function/macro/property two which the constant face is
being assigned/passed almost always _explicitly_ makes it clear that a face
is being operated upon.  In the `-face' suffix seems redundant, because it's
entirely obvious -- even to someone who doesn't understand what the source
code does! -- that it's a face being manipulated.

I find the above situation pretty typical.

The main exception, as far as I can see, is font-lock specifications, which
generally look like indecipherable gobs of hair, so the face names tend to
stand out as the one thing who's meaning is obvious.

So to summarize, I don't think such face names really help at all, they just
make the source code ugly.

-Miles
-- 
P.S.  All information contained in the above letter is false,
      for reasons of military security.

Re: checkdoc (was: mh-e 6.2 imminent)

[Kim F. Storm]

Miles Bader <miles@gnu.org> writes:

> On Mon, Oct 28, 2002 at 08:38:10PM +0100, Henrik Enberg wrote:
> > I think it's pretty natural to end them with -face.  And take something
> > like `font-lock-keyword-face', what would be a better name?
> 
> `font-lock-keyword'
> 
> [e.g., (setq font-lock-keyword-face 'font-lock-keyword) ]
> 
> > the current name is self-documenting.
> 
> If we ended every variable in `-variable', they would all be "self
> documenting" too.
> 
> The question is whether this is useful property, more than it is an annoying
> one (and I think you'll agree that calling every variable foo-variable would
> be really annoying!).

Of course we don't need that .... as long as we call the faces -face :-)

> 
> When I look at source code [I just did this using grep] that refers to
> constant face names, which is the main place where this matters, I see
> things like:
> 
>    (defface foo-face ...)
> 
>    (defvar blah-blah-face 'foo-face)
> 
>    (put-text-property X Y 'face 'foo-face)
> 
>    (set-face-foreground 'foo-face "...")
> 
>    (copy-face 'foo-face)
> 
>    (let ((face (make-face 'foo-face))) ...)
> 
>    (cons 'foo-face list-of-faces)
> 
> Note that all these cases, the `-face' in the face name doesn't help at all,

.. except if you need to grep for all uses of a given face.  I find
it more precise to grep for FOO-face rather than FOO -- which for some
FOO gives a lot of false matches.

Try to find all uses of the region and mouse faces...  I bet that you
get numerous false hits that you wouldn't have got had they been named
region-face and mouse-face.  

> because the variable/function/macro/property two which the constant face is
> being assigned/passed almost always _explicitly_ makes it clear that a face
> is being operated upon.  In the `-face' suffix seems redundant, because it's
> entirely obvious -- even to someone who doesn't understand what the source
> code does! -- that it's a face being manipulated.
> 
> I find the above situation pretty typical.

And I like all of them better than the non -face alternatives!

> 
> The main exception, as far as I can see, is font-lock specifications, which
> generally look like indecipherable gobs of hair, so the face names tend to
> stand out as the one thing who's meaning is obvious.

I fully agree re. font-lock!!

> 
> So to summarize, I don't think such face names really help at all, they just
> make the source code ugly.

Well, FWIW, I disagree.

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: checkdoc (was: mh-e 6.2 imminent)

[Miles Bader]

On Tue, Oct 29, 2002 at 12:19:13AM +0100, Kim F. Storm wrote:
> Try to find all uses of the region and mouse faces...  I bet that you
> get numerous false hits that you wouldn't have got had they been named
> region-face and mouse-face.  

Because of the property I've already noted -- that uses of constant faces
almost always occur in contexts where the use of a face is _explicit_,
e.g. accompanying a variable or function called `...-face' -- I can do this:

  grep "face.*'region" ...

which in fact works quite well.

One way you can test this is to pick some existing face called `foo-face',
and grep for both "foo-face" and "face.*foo" in the sources.  It's best to
pick a face that _doesn't_ have an identically-named variable, because
otherwise you tend to get lots of false hits in the `foo-face' case

[this is a problem, incidentally, with faces like `foo-face' -- code such as
font-lock tends to be even more confusing because there are _identical_
symbols being used for both variables and faces, in ways that are not that
easy to distinguish at first glance; I think it would actually be _more_
clear if only the variables were called `foo-face']

Here's an example:

First using the `-face' suffix:

   grep -nH "gnus-cite-attribution-face" lisp/gnus/*.el
   lisp/gnus/gnus-cite.el:126:(defface gnus-cite-attribution-face '((t
   lisp/gnus/gnus-cite.el:130:(defcustom gnus-cite-attribution-face 'gnus-cite-attribution-face
   lisp/gnus/gnus-cite.el:317:corresponding citation merged with `gnus-cite-attribution-face'.
   lisp/gnus/gnus-cite.el:367:	(gnus-cite-add-face number skip gnus-cite-attribution-face))
   lisp/gnus/gnus-cite.el:375:	(gnus-cite-add-face number skip gnus-cite-attribution-face)))))

Now without it:

   grep -nH "face.*gnus-cite-attribution" lisp/gnus/*.el
   lisp/gnus/gnus-cite.el:126:(defface gnus-cite-attribution-face '((t
   lisp/gnus/gnus-cite.el:130:(defcustom gnus-cite-attribution-face 'gnus-cite-attribution-face
   lisp/gnus/gnus-cite.el:367:	(gnus-cite-add-face number skip gnus-cite-attribution-face))
   lisp/gnus/gnus-cite.el:375:	(gnus-cite-add-face number skip gnus-cite-attribution-face)))))

Note that the second catches all the same cases except a mention in a
doc-string.

-Miles
-- 
Come now, if we were really planning to harm you, would we be waiting here, 
 beside the path, in the very darkest part of the forest?

Re: checkdoc (was: mh-e 6.2 imminent)

[Kim F. Storm]

Miles Bader <miles@gnu.org> writes:

> On Tue, Oct 29, 2002 at 12:19:13AM +0100, Kim F. Storm wrote:
> > Try to find all uses of the region and mouse faces...  I bet that you
> > get numerous false hits that you wouldn't have got had they been named
> > region-face and mouse-face.  
> 
> Because of the property I've already noted -- that uses of constant faces
> almost always occur in contexts where the use of a face is _explicit_,
> e.g. accompanying a variable or function called `...-face' -- I can do this:
> 
>   grep "face.*'region" ...
> 
> which in fact works quite well.

But fails if face and region are on different lines...

> 
> One way you can test this is to pick some existing face called `foo-face',
> and grep for both "foo-face" and "face.*foo" in the sources.  It's best to
> pick a face that _doesn't_ have an identically-named variable, because
> otherwise you tend to get lots of false hits in the `foo-face' case

I think it is a matter of taste whether those identically named
variables are false hits.

> 
> [this is a problem, incidentally, with faces like `foo-face' -- code such as
> font-lock tends to be even more confusing because there are _identical_
> symbols being used for both variables and faces, in ways that are not that
> easy to distinguish at first glance; I think it would actually be _more_
> clear if only the variables were called `foo-face']
> 
> Here's an example:
> 
> First using the `-face' suffix:
> 
>    grep -nH "gnus-cite-attribution-face" lisp/gnus/*.el
>    lisp/gnus/gnus-cite.el:126:(defface gnus-cite-attribution-face '((t
>    lisp/gnus/gnus-cite.el:130:(defcustom gnus-cite-attribution-face 'gnus-cite-attribution-face
>    lisp/gnus/gnus-cite.el:317:corresponding citation merged with `gnus-cite-attribution-face'.
>    lisp/gnus/gnus-cite.el:367:	(gnus-cite-add-face number skip gnus-cite-attribution-face))
>    lisp/gnus/gnus-cite.el:375:	(gnus-cite-add-face number skip gnus-cite-attribution-face)))))
> 
> Now without it:
> 
>    grep -nH "face.*gnus-cite-attribution" lisp/gnus/*.el
>    lisp/gnus/gnus-cite.el:126:(defface gnus-cite-attribution-face '((t
>    lisp/gnus/gnus-cite.el:130:(defcustom gnus-cite-attribution-face 'gnus-cite-attribution-face
>    lisp/gnus/gnus-cite.el:367:	(gnus-cite-add-face number skip gnus-cite-attribution-face))
>    lisp/gnus/gnus-cite.el:375:	(gnus-cite-add-face number skip gnus-cite-attribution-face)))))
> 
> Note that the second catches all the same cases except a mention in a
> doc-string.

I don't have problems separating those in general -- a face is usually
quoted, a variable is not.


I think somebody else should express their opinions -- as you and I
obviously cannot agree on this (IMHO non-)issue.

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: checkdoc (was: mh-e 6.2 imminent)

[Henrik Enberg]

Miles Bader <miles@gnu.org> writes:

> On Mon, Oct 28, 2002 at 08:38:10PM +0100, Henrik Enberg wrote:
>> I think it's pretty natural to end them with -face.  And take something
>> like `font-lock-keyword-face', what would be a better name?
>
> `font-lock-keyword'
>
> [e.g., (setq font-lock-keyword-face 'font-lock-keyword) ]
>
>> the current name is self-documenting.
>
> If we ended every variable in `-variable', they would all be "self
> documenting" too.

No, that would just be silly.  There is no need to to over-consistent.

> The question is whether this is useful property, more than it is an annoying
> one (and I think you'll agree that calling every variable foo-variable would
> be really annoying!).
>
> When I look at source code [I just did this using grep] that refers to
> constant face names, which is the main place where this matters, I see
> things like:
>
>    (defface foo-face ...)

[...]

>    (cons 'foo-face list-of-faces)
>
> Note that all these cases, the `-face' in the face name doesn't help at all,
> because the variable/function/macro/property two which the constant face is
> being assigned/passed almost always _explicitly_ makes it clear that a face
> is being operated upon.  In the `-face' suffix seems redundant, because it's
> entirely obvious -- even to someone who doesn't understand what the source
> code does! -- that it's a face being manipulated.

It _is_ pretty redundant when writing code, but from a user perspective,
it make them easier to find,  I think a typical user is more likely to
use ``C-h v'' and apropos than to grep the source code.

-- 
Booting... /vmemacs.el

Re: checkdoc (was: mh-e 6.2 imminent)

[Stefan Monnier]

> The main exception, as far as I can see, is font-lock specifications, which
> generally look like indecipherable gobs of hair, so the face names tend to
> stand out as the one thing who's meaning is obvious.

Most font-lock specifications don't use face names but variable names.
So it's actually not an exception,


	Stefan

Re: checkdoc (was: mh-e 6.2 imminent)

[Kim F. Storm]

Henrik Enberg <henrik@enberg.org> writes:

> Richard Stallman <rms@gnu.org> writes:
> 
> > One interesting question is, are there cases where ending a face name
> > with -face is actually beneficial?  What do people think?
> 
> I think it's pretty natural to end them with -face.  For one thing, it
> makes it easy to look up with apropos.  And take something like
> `font-lock-keyword-face', what would be a better name?  the current
> name is self-documenting.

In general, I prefer the -face suffix for the same reasons as Henrik.

The only place where I really don't like the -face suffix is in the
output from M-x list-faces-display.

BTW, that list doesn't use the same names as used by Customize -- which
replaces dashes by spaces and adds "Face" if missing.

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: checkdoc (was: mh-e 6.2 imminent)

[Miles Bader]

storm@cua.dk (Kim F. Storm) writes:
> BTW, that list doesn't use the same names as used by Customize -- which
> replaces dashes by spaces and adds "Face" if missing.

[though the added "face" is actually visually distinct -- it's in a
different font, and is lower case (all words in the `pretty' names
generated by customize are capitalized).  In other words, the point is
not to make it look like `face' is part of the name, but simply to make
clear that it's a face being customized.]

-Miles
-- 
Quidquid latine dictum sit, altum viditur.

Re: checkdoc (was: mh-e 6.2 imminent)

[Richard Stallman]

    The only place where I really don't like the -face suffix is in the
    output from M-x list-faces-display.

    BTW, that list doesn't use the same names as used by Customize -- which
    replaces dashes by spaces and adds "Face" if missing.

We could make it change dashes to spaces and *remove* "Face" at the
end.  However, that might cause confusion if programmers use it
to find the actual Lisp names of faces they want to use.

Re: checkdoc (was: mh-e 6.2 imminent)

[Richard Stallman]

    I think it's pretty natural to end them with -face.  For one thing, it
    makes it easy to look up with apropos.  And take something like
    `font-lock-keyword-face', what would be a better name?  the current
    name is self-documenting.

But we don't want to end all of them with `face'.  It would be a pain
in the neck if faces like `italic' and `underline' ended that way.

Have you actually used this to look them up with apropos?

Re: checkdoc (was: mh-e 6.2 imminent)

[Miles Bader]

On Tue, Oct 29, 2002 at 06:28:58AM -0500, Richard Stallman wrote:
> Have you actually used this to look them up with apropos?

You know, if searching for faces is truly a problem (it isn't for me -- there
are so few of them that I usually just use `list-faces-display'), we could
add an `apropos-face' command...  [Perhaps it makes sense to do that
regardless, since it _is_ a separate namespace, and adding specialized
apropos commands isn't hard.]

-Miles
-- 
P.S.  All information contained in the above letter is false,
      for reasons of military security.

Re: checkdoc (was: mh-e 6.2 imminent)

[Henrik Enberg]

Richard Stallman <rms@gnu.org> writes:

>     I think it's pretty natural to end them with -face.  For one thing, it
>     makes it easy to look up with apropos.  And take something like
>     `font-lock-keyword-face', what would be a better name?  the current
>     name is self-documenting.
>
> But we don't want to end all of them with `face'.  It would be a pain
> in the neck if faces like `italic' and `underline' ended that way.

Those kinds on names are pretty common when it comes to
typography, but names like font-lock-keyword or diff-added would be
less clear.

> Have you actually used this to look them up with apropos?

Occasionally, when I was a newbie, though I didn't know about
list-faces-display then.  I think Miles idea about an appropos-face
command sounds useful. 

-- 
Booting... /vmemacs.el

Re: checkdoc (was: mh-e 6.2 imminent)

[Miles Bader]

Henrik Enberg <henrik@enberg.org> writes:
> > But we don't want to end all of them with `face'.  It would be a pain
> > in the neck if faces like `italic' and `underline' ended that way.
> 
> Those kinds on names are pretty common when it comes to
> typography, but names like font-lock-keyword or diff-added would be
> less clear.

Well, less clear when you mention them out-of-context, but the point
I've been trying to make is that face names are almost always used in a
context where their meaning is pretty obvious.  [In other words, don't
just say `less clear,' say `less clear in such-and-such a circumstance.']

-Miles
-- 
"1971 pickup truck; will trade for guns"