checkdoc (was: mh-e 6.2 imminent)

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)

[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: 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[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)

[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]

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)

[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)

[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)

[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)

[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)

[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)

[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)

[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)

[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)

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

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"