new *Help* argument highlighting

new *Help* argument highlighting

[Miles Bader]

I've just seen the effect of the argument highlighting in
describe-function *Help* buffers, and it seems like _way_ too much.
It's nice to have some highlighting for the args, but I think
`font-lock-variable-name-face' is the wrong thing to use.  In an
otherwise monochrome help-buffer, that makes the args stand out like
lasers, and distracts attention from everything else (a typical source
buffer using font-lock is a neon fruit salad anyway, so that face is
appropriate there).

I tried changing the `help-argument-name' face to be just italic
instead, and that seemed a bit better (after all in documentation
italics is often used for arguments), but since the args are uppercased,
it looked slightly odd -- uppercase italics are generally a bit weird.
I ended up thinking `the arguments are _already_ in uppercase, which is
pretty noticeable, why is necessary to highlight them further at all?'

-Miles
-- 
=====
(^o^;
(()))
*This is the cute octopus virus, please copy it into your sig so it can spread.

Re: new *Help* argument highlighting

[Juanma Barranquero]

On 07 May 2004 14:32:46 +0900
Miles Bader <miles@lsi.nec.co.jp> wrote:

> I've just seen the effect of the argument highlighting in
> describe-function *Help* buffers, and it seems like _way_ too much.
> It's nice to have some highlighting for the args, but I think
> `font-lock-variable-name-face' is the wrong thing to use.

Not only I fully agree with you, but one or two days ago I changed it to
use (:face '(:weight bold)), which seems much more sensible as a default...
:)  The font-lock-variable-name-face was just a test version.

> I ended up thinking `the arguments are _already_ in uppercase, which is
> pretty noticeable, why is necessary to highlight them further at all?'

There are several reasons:

 - Many docstrings have other uppercase words (for example, most def*
   functions, like defface, define-minor-mode, defcustom...), so the
   highlighting helps to distinguish which ones are really function
   arguments.

 - It makes easier to look for an argument when the docstring is long.

 - The feature can be used to highlight just *one* (or a set of)
   argument. That could help in places where we're asking for input for
   an argument and want to show the entire docstring, but highlight the
   item we're requesting (that's the original motivation).

Help argument highlighting has proved already very useful to find
docstrings with typos in argument names, or which use a different name
in the arglist and the docstring.

My (admitedly *very* biased opinion :) is that some people finds the
feature useful, so I suggest that, instead of removing it, thoso who
don't like it set the face to default.

                                                                Juanma

Re: new *Help* argument highlighting

[Juri Linkov]

I like this feature.  However, I think that by highlighting only
argument names it causes such a feeling that other text in the Help
buffer is less important.  This is especially wrong for a function
name which should be regarded as more important than its arguments.
So perhaps highlighting a function name will help a bit.

[Note that all function references are already highlighted as buttons.
What I propose is to add highlighting to the name of a function
which is described in the Help buffer.]

BTW, there is one bug.  The following string is incorrectly fontified:

[Arg list not available until function definition is loaded.]

-- 
Juri Linkov
http://www.jurta.org/emacs/

Re: new *Help* argument highlighting

[Juanma Barranquero]

On Sun, 09 May 2004 01:22:45 +0300, Juri Linkov <juri@jurta.org> wrote:

> So perhaps highlighting a function name will help a bit.

Hmm. I don't object to changing what it does now, obviously, but I fear
too highlighting would turn the *Help* buffer into a christmas tree. So
let's hear what others have to say about it.

> What I propose is to add highlighting to the name of a function
> which is described in the Help buffer.]

Yes, I understand.

> [Arg list not available until function definition is loaded.]

Which function are you describing, please?

Thanks,

                                                           /L/e/k/t/u

Re: new *Help* argument highlighting

[Juri Linkov]

Juanma Barranquero <lektu@mi.madritel.es> writes:
> On Sun, 09 May 2004 01:22:45 +0300, Juri Linkov <juri@jurta.org> wrote:
>> [Arg list not available until function definition is loaded.]
>
> Which function are you describing, please?

This is displayed with any function defined by `autoload':

(autoload 'some-mode "some-mode" "Some mode." t)

-- 
Juri Linkov
http://www.jurta.org/emacs/

Re: new *Help* argument highlighting

[Miles Bader]

On Sun, May 09, 2004 at 01:32:25AM +0200, Juanma Barranquero wrote:
> > So perhaps highlighting a function name will help a bit.
> 
> Hmm. I don't object to changing what it does now, obviously, but I fear
> too highlighting would turn the *Help* buffer into a christmas tree. So
> let's hear what others have to say about it.

I agree[*].

I think that if the highlighted args are too noticeable, we should reduce
their highlighting, not start highlighting everything else.  Perhaps Juanma's
suggestion of changing the arg-highlighting to `bold' instead of
`font-lock-...-face' will do that.  Personally I wish we had even more subtle
methods of highlighting (e.g., an underline with very sparsely-spaced dots
instead of a solid line).

[*] Note that a *Help* buffer is very different from a source code buffer: a
    source code buffer is usually very long and full of text, and using
    colored faces helps you visually organize the mass of text more quickly,
    but a *Help* buffer is usually short and concise, and already written
    with easy readability as a goal, so excessive highlighting often just
    detracts from readability.

-Miles
-- 
Fast, small, soon; pick any 2.

Re: new *Help* argument highlighting

[Juanma Barranquero]

On Sat, 8 May 2004 19:49:56 -0400, Miles Bader <miles@gnu.org> wrote:

> I think that if the highlighted args are too noticeable, we should reduce
> their highlighting, not start highlighting everything else.

Yes.

Personally I find arg highlighting very useful (it helps me a lot to
quickly extract information from help buffers, in particular from
long-winded docstrings) but I think the key is that args are somewhat
more visible, not the absolute focus of attention. That would be
distracting.

> Personally I wish we had even more subtle
> methods of highlighting (e.g., an underline with very sparsely-spaced dots
> instead of a solid line).

That could perhaps be done with stipples, but seems a bit over the top.
Another alternative is to use a soft shade of gray, for example this:

(defface myhelp-argument-name '(((background light) :foreground "gray45")
				((background dark) :foreground "gray70"))
	 "Face to highlight argument names in *Help* buffers")

                                                           /L/e/k/t/u

Re: new *Help* argument highlighting

[Juanma Barranquero]

On Sun, 09 May 2004 02:47:34 +0300, Juri Linkov <juri@jurta.org> wrote:

> This is displayed with any function defined by `autoload':

Ok, I'll fix it.

Thanks,

                                                           /L/e/k/t/u

Re: new *Help* argument highlighting

[Richard Stallman]

    I like this feature.  However, I think that by highlighting only
    argument names it causes such a feeling that other text in the Help
    buffer is less important.

Let's use italic for the argument names, when italic is available.
That matches what the manual does.

Re: new *Help* argument highlighting

[Miles Bader]

On Sun, May 09, 2004 at 02:47:29PM -0400, Richard Stallman wrote:
>     I like this feature.  However, I think that by highlighting only
>     argument names it causes such a feeling that other text in the Help
>     buffer is less important.
> 
> Let's use italic for the argument names, when italic is available.
> That matches what the manual does.

The problem is that the argument names are already uppercase, and
uppercase+italic looks kinda weird, certainly not very much like what's in
the manuals.

-Miles
-- 
.Numeric stability is probably not all that important when you're guessing.

Re: new *Help* argument highlighting

[Juanma Barranquero]

On Sun, 9 May 2004 18:25:55 -0400, Miles Bader <miles@gnu.org> wrote:

> The problem is that the argument names are already uppercase, and
> uppercase+italic looks kinda weird, certainly not very much like what's in
> the manuals.

I agree, but I don't see it as a problem because people can customize it.
What we're trying to find is a non-intrusive default, and italics seems
like a good one.

I've changed the face to italics. Let's see what people think.


                                                           /L/e/k/t/u



BTW, you wanted a subtle highlighting: did you try with (:underline
"gray70") or the like?

Re: new *Help* argument highlighting

[Stefan Monnier]

>> The problem is that the argument names are already uppercase, and
>> uppercase+italic looks kinda weird, certainly not very much like what's in
>> the manuals.

> I agree, but I don't see it as a problem because people can customize it.
> What we're trying to find is a non-intrusive default, and italics seems
> like a good one.

I think uppercase is intrusive enough.
It makes sense to add highlighting for cases where the user wants to
highlight a particular argument (as in the original situation which
prompted this long thread).  But highlighting all args doesn't seem of much
use to me.  At leaqst with the current appearance where
nothing's highlighted.

I think the additional highlight would make more sense in a situation where
the *Help* buffer uses a larger font for the function/variable name at the
top (i.e. like a title), then some other font (probably courrier) for the
usage, then yet some other (something proportional) for the body, ...


        Stefan

Re: new *Help* argument highlighting

[Juanma Barranquero]

On 09 May 2004 19:10:19 -0400, Stefan Monnier <monnier@iro.umontreal.ca> wrote:

> I think uppercase is intrusive enough.

As with all issues regarding colors and defaults, it seems there aren't
two users/developers who agree on this one... :)

> It makes sense to add highlighting for cases where the user wants to
> highlight a particular argument (as in the original situation which
> prompted this long thread).

Hm. We could allow passing a numeric argument to describe function, so
"C-3 C-h f my-function" would highlight the third argument of myfunction
(only half joking...)

> But highlighting all args doesn't seem of much
> use to me.

Oh, I don't find it very useful to describe `nth'; but
`define-minor-mode' or `define-key', definitely yes.

> I think the additional highlight would make more sense in a situation where
> the *Help* buffer uses a larger font for the function/variable name at the
> top (i.e. like a title), then some other font (probably courrier) for the
> usage, then yet some other (something proportional) for the body, ...

That's doable, but I think many people would find it way too much
highlighting.  However, if that's the way to go, I'd take a look into
implementing it.

I'm not going to push for any specific default color/highlighting on
this issue; whatever is decided is OK by me. But I certainly wouldn't
like the feature to go. At the very least, we can set the face to
'default and let the user decide.

                                                           /L/e/k/t/u

Re: new *Help* argument highlighting

[Stefan Monnier]

>> But highlighting all args doesn't seem of much use to me.

> Oh, I don't find it very useful to describe `nth'; but
> `define-minor-mode' or `define-key', definitely yes.

I just find it odd to highlight arguments more than, say, the function's
name (i.e. basically the title of the help buffer).

Maybe italics will make it less strange, but the current bold I see is just
very surprising because it highlights (in the literal sense) parts of the
docstring as if they were THE-THING-I-VE-BEEN-LOOKING-FOR, even when it
has strictly no indication that it's what I'm interested in.

>> I think the additional highlight would make more sense in a situation where
>> the *Help* buffer uses a larger font for the function/variable name at the
>> top (i.e. like a title), then some other font (probably courrier) for the
>> usage, then yet some other (something proportional) for the body, ...

> That's doable, but I think many people would find it way too
> much highlighting.

I didn't say fruit salad.  I meant a sober presentation like you'd find in
a book (e.g. generated from Texinfo).

> I'm not going to push for any specific default color/highlighting on
> this issue;

No colors, please.


        Stefan

Re: new *Help* argument highlighting

[Juanma Barranquero]

On 09 May 2004 20:00:07 -0400, Stefan Monnier <monnier@iro.umontreal.ca> wrote:

> I just find it odd to highlight arguments more than, say, the function's
> name (i.e. basically the title of the help buffer).

I've read that already on the thread, and I find it very surprising.
When I read a describe-function *Help* buffer, I'm never interested in
the function's name: I already know that, I *typed* it. In 100% of cases,
the reason I type C-h f is precisely to find what to pass to the args.
In a great many cases, I'm interested in just a few args, because the
others I remember from previous uses of the function, so having a way to
quickly determine where on the docstring are these args referred seems a
big win, performance-wise. I think other people must be using C-h f in
very different ways to mine...

> Maybe italics will make it less strange, but the current bold I see is just
> very surprising because it highlights (in the literal sense) parts of the
> docstring as if they were THE-THING-I-VE-BEEN-LOOKING-FOR, even when it
> has strictly no indication that it's what I'm interested in.

Bold, or italics, just reinforce the convention already stated by using
uppercase, I think.

> I didn't say fruit salad.  I meant a sober presentation like you'd find in
> a book (e.g. generated from Texinfo).

Yeah, sorry, I didn't intend to imply that. But I get the feeling (I can
be wrong) that there are people who simply likes the Help buffers with
no highlighting/font-locking at all. That's also a bit surprising to me,
given that we use font-locking in a lot of cases, like the recently
added `completions-fist-difference' and `completions-common-part' faces.
It's not like help-argument-name introduces highlighting on an otherwise
very sober Emacs environment... :)

> No colors, please.

No, not as default. I don't think anyone would like that.

                                                           /L/e/k/t/u

Re: new *Help* argument highlighting

[Stefan Monnier]

> Yeah, sorry, I didn't intend to imply that. But I get the feeling (I can
> be wrong) that there are people who simply likes the Help buffers with
> no highlighting/font-locking at all.

I think you're wrong.  There's a lot of problems with adding colors.
But playing with font size is pretty safe (at least, I can't remember
a single complaint from the font-size change in Info-mode, for example).
Bold sometimes causes problems as does italics.  Too bad: I find
them irreplaceable.

Using proportional fonts OTOH is asking for trouble, not because "some
people won't like it" but because we'll encounter many bugs linked to the
poor support for proportional fonts in the current code.

> That's also a bit surprising to me, given that we use font-locking in
> a lot of cases, like the recently added `completions-fist-difference' and
> `completions-common-part' faces.  It's not like help-argument-name
> introduces highlighting on an otherwise very sober Emacs environment... :)

As said, it's not the fact of highlighting that surprises, it's just the
fact that args and only args are highlighted as if they were so
very special.  Note that I try to consistently say "surprise" rather than
"bother".  I'm not opposed to it, but I think it currently looks odd.


        Stefan

Re: new *Help* argument highlighting

[Juanma Barranquero]

On 09 May 2004 20:25:13 -0400, Stefan Monnier <monnier@iro.umontreal.ca> wrote:

> I think you're wrong.  There's a lot of problems with adding colors.

Sure. But we already have lots of faces, some of which add colors with
not much remorse:

(defface comint-highlight-prompt
  '((((background dark)) (:foreground "cyan"))
    (t (:foreground "dark blue")))
  "Face to use to highlight prompts."
  :group 'comint)

(defface hi-yellow
  '((((background dark)) (:background "yellow" :foreground "black"))
    (t (:background "yellow")))
  "Default face for hi-lock mode."
  :group 'hi-lock-faces)

(defface smerge-mine-face
  '((((background light))
     (:foreground "blue"))
    (((background dark))
     (:foreground "cyan")))
  "Face for your code."
  :group 'smerge)

(defface speedbar-button-face '((((class color) (background light))
                                 (:foreground "green4"))
                                (((class color) (background dark))
                                 (:foreground "green3")))
  "Face used for +/- buttons."
  :group 'speedbar-faces)

That said, I wouldn't advocate adding colors to this as a default.


> But playing with font size is pretty safe (at least, I can't remember
> a single complaint from the font-size change in Info-mode, for example).

As I said, it's OK to me if that's what's decided.

> As said, it's not the fact of highlighting that surprises, it's just the
> fact that args and only args are highlighted as if they were so
> very special.

Aren't? In an elisp function's help, I honestly don't know what else
could be special... Perhaps if we had a more structured style guide for
function docstrings, with sections à la:


 MYFUNCTION is a function in .emacs.el.              # where/bindings
 It is bound to H-z.

 (myfunction A B &optional C)                        # function header

 MYFUNCTION is an obsolete function                  # obsolescence info
 since the beginning of time; do not use it.

 The object of MYFUNCTION is serving as an example.  # function description
 You can use it at your leisure.

 Argument A is for whatever you want.                # argument usage
 B, on the other hand, is unused.
 Optional C defaults to nil, and should stay so.

 Example:                                            # example

   (myfunction 7 "I'm being ignored")

 Notes:                                              # additional notes

   You really shouldn't use this function.
   It hasn't been tested on the wild so
   it could misfire.

then I'd understand why highlighting just arguments would be weird.

> Note that I try to consistently say "surprise" rather than
> "bother".  I'm not opposed to it, but I think it currently looks odd.

Yeah, I understand. Let's see whether we can agree on something
generally useful and non-surprising/non-bothering. 

Thanks,

                                                           /L/e/k/t/u

Re: new *Help* argument highlighting

[Miles Bader]

Juanma Barranquero <lektu@mi.madritel.es> writes:
> > I think you're wrong.  There's a lot of problems with adding colors.
> 
> Sure. But we already have lots of faces, some of which add colors with
> not much remorse:
...
> That said, I wouldn't advocate adding colors to this as a default.

Whether or not colors are appropriate depends a lot on the context; each
case has to be thought about separately.  What people (including me) are
saying is that colors are the wrong thing for this case.

[Though, FWIW, I think that changes in _brightness_ are generally less
intrusive than changes in _hue_, especially if they're subtle.]

-Miles
-- 
Ich bin ein Virus. Mach' mit und kopiere mich in Deine .signature.

Re: new *Help* argument highlighting

[Stefan Monnier]

>> I think you're wrong.  There's a lot of problems with adding colors.
> Sure. But we already have lots of faces, some of which add colors with
> not much remorse:

I know, but you were saying that there is some resistance against adding
highlighting, and I think the resistance is more against colors.
The reason why the two are often mixed is because indeed most highlighting
adds color (believe me, I don't like that: the fist thing I did when
I tried font-lock was to remove all colors (other than grey for comments)
and restrict myself to bold/italics.  Nowadays I live with colors on
various faces for the simple reason that there are too many faces and
I don't have the time/energy to customize them all to something else).

> (defface smerge-mine-face

Funnily, for SMerge, I think colors are the way to go (in my setup at
least) because those faces are added to the ones normally added by
font-lock, so since my font-lock faces don't use colors, my smerge faces
are properly combined with the font-lock ones.

>> As said, it's not the fact of highlighting that surprises, it's just the
>> fact that args and only args are highlighted as if they were so
>> very special.
> Aren't? In an elisp function's help, I honestly don't know what else
> could be special... Perhaps if we had a more structured style guide for
> function docstrings, with sections à la:

Well I find the highlighting attracts my eye to the arguments, but not to
the text that surrounds it, whereas I don't care so much about the argument
as I care about the text.

Basically, my reaction is "Hmm... the argument OVERLAY is used three times
in the docstring; now, why should I care?".


        Stefan

Re: new *Help* argument highlighting

[Juanma Barranquero]

On 10 May 2004 10:32:06 +0900
Miles Bader <miles@lsi.nec.co.jp> wrote:

> Whether or not colors are appropriate depends a lot on the context; each
> case has to be thought about separately.

Yes.

> What people (including me) are
> saying is that colors are the wrong thing for this case.

I think we all agree on this one. I initially used
font-lock-variable-name-face because it seemed vaguely related, but
after a short while I came to understand it just wasn't right and
changed it to bold (that's what I'd prefer, as a default), and then to
italics per RMS' suggestion.

> [Though, FWIW, I think that changes in _brightness_ are generally less
> intrusive than changes in _hue_, especially if they're subtle.]

Sure, I agree on this one too. The only problem (in this case) is
finding the right highlight, subtle but not invisible (or perhaps in
this case non-visible is just the right default, I don't know).

                                                                Juanma

Re: new *Help* argument highlighting

[Juanma Barranquero]

On 09 May 2004 22:42:01 -0400
Stefan Monnier <monnier@iro.umontreal.ca> wrote:

> I know, but you were saying that there is some resistance against adding
> highlighting, and I think the resistance is more against colors.

Yes, I agree.

In this case, though, nobody's proposing to add color (except, perhaps,
a shade of gray, which could be understood as changing intensity).

> Well I find the highlighting attracts my eye to the arguments, but not to
> the text that surrounds it, whereas I don't care so much about the argument
> as I care about the text.
> 
> Basically, my reaction is "Hmm... the argument OVERLAY is used three times
> in the docstring; now, why should I care?".

I think it boils down to personal differences. My though is more like
"Ah, so OVERLAY is described here, here and... oh, here. Let's se what
does it say about it."

If we had very strict style requirements to writing docstrings, we could
put marking on an argument's description, so we would be able to
highlight (with whichever method is subtle enough) the doc's paragraph(s)
were the argument is described and used. You could then type 1, 2, 3...
on a *Help* buffer to switch highlighting between first, second, third
argument, etc. But nowadays a docstring is just a bunch of text that
satisfies a few loose guidelines: using args in uppercase, making the
first line stand-alone for apropos, etc. As it stands, there's not easy
way to show the Help information in a more useful make up.

                                                                Juanma

Re: new *Help* argument highlighting

[Thien-Thi Nguyen]

suggestions:
 - recognize args by all-uppercase.
 - make only the first N instances of the arg stand out.
 - default N is 1, but add a user-defineable function to
	evaluate context and possibly return another number.
 - keep "stand out" as bold.

this makes it easy to locate the general area of an arg's
description, w/o overwhelming decoration, by default, and
at the same time allow programmers who like to explore their
heuristical sensibilities go wild.

thi

Re: new *Help* argument highlighting

[Juanma Barranquero]

On 10 May 2004 08:45:46 -0400
Thien-Thi Nguyen <ttn@glug.org> wrote:

>  - recognize args by all-uppercase.

That's what's done now, but exploring just the arglist info, not the
full docstring.

>  - make only the first N instances of the arg stand out.

That would be easy to implement. But...

> this makes it easy to locate the general area of an arg's
> description, w/o overwhelming decoration, by default

...I don't think it would work right in many cases of long docstrings.
Examples: defmacro, open-network-stream (-nowait, -server), define-key,
etc.

>  - default N is 1, but add a user-defineable function to
> 	evaluate context and possibly return another number.

My gut feeling is that this would add unneeded complexity for such a
simple featurette. I think there's people who likes it (for different
levels of subtlety), and people who just don't and will customize it out
of their Emacs :)

>  - keep "stand out" as bold.

Whatever is decided.

Thanks,

                                                                Juanma

Re: new *Help* argument highlighting

[Robert J. Chassell]

    But playing with font size is pretty safe ...

No, it is not.

    Bold sometimes causes problems...

Yes, you are right.  But the word `sometimes' is not accurate.  Bold
*always* causes a problem when I change font size to 10x20.  In a mode
line, `m' becomes unreadable.  (That font size is best for the display
I mostly use.  Everything looks fine in the default font.)

Back in December 2002, Miles Bader fixed the problem by providing a
patch to emacs/src/xfaces.c and an Emacs Lisp file to load.  The patch
works fine.  I have been incorporating it with the current xfaces.c
source ever since.

Because I do not understand it, I have held back from committing
Miles' change.

First, will someone who understands the patch review it?  Or should I
commit the merged version of xfaces.c and see whether it breaks others
people's installations?

Here is the patch itself.  As I said, the patch works fine with the
current CVS.


RCS file: /cvsroot/emacs/emacs/src/xfaces.c,v
retrieving revision 1.266
diff -u -r1.266 xfaces.c
--- src/xfaces.c	17 Nov 2002 23:51:19 -0000	1.266
+++ src/xfaces.c	18 Dec 2002 05:26:34 -0000
@@ -422,6 +422,13 @@
 
 Lisp_Object Vtty_defined_color_alist;
 
+/* A list of functions to perturb faces before final realization.
+   They are passed a lisp-vector containing all the attributes of the
+   fully-specified face, and can change any that they wish. */
+
+Lisp_Object Vrealize_face_filter_functions;
+
+
 /* Counter for calls to clear_face_cache.  If this counter reaches
    CLEAR_FONT_TABLE_COUNT, and a frame has more than
    CLEAR_FONT_TABLE_NFONTS load, unused fonts are freed.  */
@@ -481,7 +488,7 @@
 static unsigned char *xstrlwr P_ ((unsigned char *));
 static void signal_error P_ ((char *, Lisp_Object));
 static struct frame *frame_or_selected_frame P_ ((Lisp_Object, int));
-static void load_face_font P_ ((struct frame *, struct face *, int));
+static void load_face_font P_ ((struct frame *, struct face *, Lisp_Object *, int));
 static void load_face_colors P_ ((struct frame *, struct face *, Lisp_Object *));
 static void free_face_colors P_ ((struct frame *, struct face *));
 static int face_color_gray_p P_ ((struct frame *, char *));
@@ -502,10 +509,10 @@
 static int cmp_font_names P_ ((const void *, const void *));
 static struct face *realize_face P_ ((struct face_cache *, Lisp_Object *, int,
 				      struct face *, int));
-static struct face *realize_x_face P_ ((struct face_cache *,
-					Lisp_Object *, int, struct face *));
-static struct face *realize_tty_face P_ ((struct face_cache *,
-					  Lisp_Object *, int));
+static void realize_x_face P_ ((struct face *, struct face_cache *,
+				Lisp_Object *, int, struct face *));
+static void realize_tty_face P_ ((struct face *, struct face_cache *,
+				  Lisp_Object *, int));
 static int realize_basic_faces P_ ((struct frame *));
 static int realize_default_face P_ ((struct frame *));
 static void realize_named_face P_ ((struct frame *, Lisp_Object, int));
@@ -1245,14 +1252,15 @@
 
 #ifdef HAVE_WINDOW_SYSTEM
 
-/* Load font of face FACE which is used on frame F to display
-   character C.  The name of the font to load is determined by lface
-   and fontset of FACE.  */
+/* Load font of face FACE with attributes ATTRS which is used on frame F to
+   display character C.  The name of the font to load is determined by
+   lface and fontset of FACE.  */
 
 static void
-load_face_font (f, face, c)
+load_face_font (f, face, attrs, c)
      struct frame *f;
      struct face *face;
+     Lisp_Object *attrs;
      int c;
 {
   struct font_info *font_info = NULL;
@@ -1262,7 +1270,7 @@
   face->font_info_id = -1;
   face->font = NULL;
 
-  font_name = choose_face_font (f, face->lface, face->fontset, c,
+  font_name = choose_face_font (f, attrs, face->fontset, c,
 				&needs_overstrike);
   if (!font_name)
     return;
@@ -6678,6 +6686,11 @@
      int former_face_id;
 {
   struct face *face;
+  /* The set of attributes this face is know by to the user, as opposed to
+     the set actually used to render the face.  They're usually the same
+     as, but may be different if some attribute is changed by
+     realize-face-filter.  */
+  Lisp_Object *orig_attrs = attrs;
 
   /* LFACE must be fully specified.  */
   xassert (cache != NULL);
@@ -6691,41 +6704,70 @@
       free_realized_face (cache->f, former_face);
     }
 
+  if (CONSP (Vrealize_face_filter_functions))
+    {
+      /* Call these user-defined functions to perturb the face attributes
+	 before realization.  */
+      Lisp_Object filters, cycle_check;
+      Lisp_Object lface = Fmake_vector (make_number (LFACE_VECTOR_SIZE),
+					Qunspecified);
+
+      bcopy (attrs, XVECTOR (lface)->contents,
+	     LFACE_VECTOR_SIZE * (sizeof *attrs));
+
+      cycle_check = Qnil;
+      for (filters = Vrealize_face_filter_functions;
+	   CONSP (filters);
+	   filters = XCDR (filters))
+	{
+	  safe_call1 (XCAR (filters), lface);
+	  cycle_check = CYCLE_CHECK (cycle_check, filters, 50);
+	  if (NILP (cycle_check))
+	    break;		/* cycle detected */
+	}
+
+      attrs = XVECTOR (lface)->contents;
+    }      
+
+  /* Allocate a new realized face.  */
+  face = make_realized_face (orig_attrs);
+
+  /* Fill it in.  */
   if (FRAME_WINDOW_P (cache->f))
-    face = realize_x_face (cache, attrs, c, base_face);
+    realize_x_face (face, cache, attrs, c, base_face);
   else if (FRAME_TERMCAP_P (cache->f) || FRAME_MSDOS_P (cache->f))
-    face = realize_tty_face (cache, attrs, c);
+    realize_tty_face (face, cache, attrs, c);
   else
     abort ();
 
   /* Insert the new face.  */
-  cache_face (cache, face, lface_hash (attrs));
+  cache_face (cache, face, lface_hash (orig_attrs));
 #ifdef HAVE_WINDOW_SYSTEM
   if (FRAME_WINDOW_P (cache->f) && face->font == NULL)
-    load_face_font (cache->f, face, c);
+    load_face_font (cache->f, face, attrs, c);
 #endif  /* HAVE_WINDOW_SYSTEM */
   return face;
 }
 
 
-/* Realize the fully-specified face with attributes ATTRS in face
-   cache CACHE for character C.  Do it for X frame CACHE->f.  If C is
-   a multibyte character, BASE_FACE is a face that has the same
-   attributes.  Otherwise, BASE_FACE is ignored.  If the new face
-   doesn't share font with the default face, a fontname is allocated
-   from the heap and set in `font_name' of the new face, but it is not
-   yet loaded here.  Value is a pointer to the newly created realized
-   face.  */
+/* Realize into FACE the fully-specified face with attributes ATTRS in face
+   cache CACHE for character C.  Do it for X frame CACHE->f.  If C is a
+   multibyte character, BASE_FACE is a face that has the same attributes.
+   Otherwise, BASE_FACE is ignored.  If the new face doesn't share font
+   with the default face, a fontname is allocated from the heap and set in
+   `font_name' of the new face, but it is not yet loaded here.  Value is a
+   pointer to the newly created realized face.  */
 
-static struct face *
-realize_x_face (cache, attrs, c, base_face)
+static void
+realize_x_face (face, cache, attrs, c, base_face)
+     struct face *face;
      struct face_cache *cache;
      Lisp_Object *attrs;
      int c;
      struct face *base_face;
 {
 #ifdef HAVE_WINDOW_SYSTEM
-  struct face *face, *default_face;
+  struct face *default_face;
   struct frame *f;
   Lisp_Object stipple, overline, strike_through, box;
 
@@ -6733,9 +6775,6 @@
   xassert (SINGLE_BYTE_CHAR_P (c)
 	   || base_face);
 
-  /* Allocate a new realized face.  */
-  face = make_realized_face (attrs);
-
   f = cache->f;
 
   /* If C is a multibyte character, we share all face attirbutes with
@@ -6751,7 +6790,7 @@
 
       /* to force realize_face to load font */
       face->font = NULL;
-      return face;
+      return;
     }
 
   /* Now we are realizing a face for ASCII (and unibyte) characters.  */
@@ -6921,7 +6960,6 @@
     face->stipple = load_pixmap (f, stipple, &face->pixmap_w, &face->pixmap_h);
 
   xassert (FACE_SUITABLE_FOR_CHAR_P (face, c));
-  return face;
 #endif /* HAVE_WINDOW_SYSTEM */
 }
 
@@ -7012,17 +7050,16 @@
 }
 
 
-/* Realize the fully-specified face with attributes ATTRS in face
-   cache CACHE for character C.  Do it for TTY frame CACHE->f.  Value is a
-   pointer to the newly created realized face.  */
+/* Realize into FACE the fully-specified face with attributes ATTRS in face
+   cache CACHE for character C.  Do it for TTY frame CACHE->f.  */
 
-static struct face *
-realize_tty_face (cache, attrs, c)
+static void
+realize_tty_face (face, cache, attrs, c)
+     struct face *face;
      struct face_cache *cache;
      Lisp_Object *attrs;
      int c;
 {
-  struct face *face;
   int weight, slant;
   int face_colors_defaulted = 0;
   struct frame *f = cache->f;
@@ -7030,8 +7067,6 @@
   /* Frame must be a termcap frame.  */
   xassert (FRAME_TERMCAP_P (cache->f) || FRAME_MSDOS_P (cache->f));
 
-  /* Allocate a new realized face.  */
-  face = make_realized_face (attrs);
   face->font_name = FRAME_MSDOS_P (cache->f) ? "ms-dos" : "tty";
 
   /* Map face attributes to TTY appearances.  We map slant to
@@ -7068,8 +7103,6 @@
       && face->background == FACE_TTY_DEFAULT_FG_COLOR
       && face->foreground == FACE_TTY_DEFAULT_BG_COLOR)
     face->tty_bold_p = 0;
-
-  return face;
 }
 
 
@@ -7670,6 +7703,14 @@
 Each element is a regular expression that matches names of fonts to
 ignore.  */);
   Vface_ignored_fonts = Qnil;
+
+  DEFVAR_LISP ("realize-face-filter-functions",
+	       &Vrealize_face_filter_functions,
+	       doc:/* A list of functions to perturb faces before final realization.
+They are passed a lisp-vector containing all the attributes of the
+fully-specified face, and can change any that they wish. */);
+  Vrealize_face_filter_functions = Qnil;
+
 
 #ifdef HAVE_WINDOW_SYSTEM
   defsubr (&Sbitmap_spec_p);



-- 
    Robert J. Chassell                         Rattlesnake Enterprises
    As I slowly update it,                     bob@rattlesnake.com
        I rewrite a "What's New" segment for   http://www.rattlesnake.com

Re: new *Help* argument highlighting

[Richard Stallman]

    The problem is that the argument names are already uppercase, and
    uppercase+italic looks kinda weird, certainly not very much like what's in
    the manuals.

Yes, it would be good to downcase them in the Help buffer
as well as italicizing them.

Re: new *Help* argument highlighting

[Stefan Monnier]

>     But playing with font size is pretty safe ...
> No, it is not.

Care to back up your claim with at least some kind of data, so we have
a chance of estimating how serious the problem is?
As I said, I haven't seen a single complaint about the font-size change
in Info-mode in Emacs-21.

>     Bold sometimes causes problems...
> Yes, you are right.  But the word `sometimes' is not accurate.  Bold
> *always* causes a problem when I change font size to 10x20.  In a mode

I think "sometimes" is perfectly correct.  It was clear that I didn't
mean for the problem to be non-deterministic, but just to depend on
the situation.

BTW, I still haven't understood why bold is such a problem for you.  Is it
that you don't have a bold face and Emacs creates one automatically (and
that one is unreadable) or is it that you do have a bold face but
it's unreadable?  If the latter, is it there a reason why the face is
unreadable (other than "the font author just did a bad job")?

> line, `m' becomes unreadable.  (That font size is best for the display
> I mostly use.  Everything looks fine in the default font.)

With the 6x13 font I use, "m" in bold looks basically like a solid block,
but I've never found it to be unreadable because it still looks clearly
different from all others (including "w").
Is your situation similar except that the solid block does bother you
(maybe because you sight is not as good as mine)?

> First, will someone who understands the patch review it?  Or should I
> commit the merged version of xfaces.c and see whether it breaks others
> people's installations?

My understanding of the patch is that it introduces risks of crashes.
If you set realize-face-filter-functions to functions that are simple
enough, it might be safe (tho maybe only if you compile with -DSYNC_INPUT).


        Stefan

Re: new *Help* argument highlighting

[Juanma Barranquero]

On Mon, 10 May 2004 13:54:11 -0400, Richard Stallman <rms@gnu.org> wrote:

> Yes, it would be good to downcase them in the Help buffer
> as well as italicizing them.

That's a one-line patch, and the effect is nice, and scarcely intrusive.
However, it has the problem that if someone customizes
help-argument-face to the default face, he's lost also the uppercase, so
now arguments do not stand out at all.

To solve that, we'd have do something like:

(defvar help-arg-highlighting-function
  #'(lambda (arg) (propertize (downcase arg) 'face '(:slant italic)))
  "Function to call to highlight argument names in `describe-function' *Help* buffers.")

instead of having a help-argument-name face.

                                                           /L/e/k/t/u

Re: new *Help* argument highlighting

[David Kastrup]

Juanma Barranquero <lektu@mi.madritel.es> writes:

> On Mon, 10 May 2004 13:54:11 -0400, Richard Stallman <rms@gnu.org> wrote:
> 
> > Yes, it would be good to downcase them in the Help buffer
> > as well as italicizing them.
> 
> That's a one-line patch, and the effect is nice, and scarcely
> intrusive.  However, it has the problem that if someone customizes
> help-argument-face to the default face, he's lost also the
> uppercase, so now arguments do not stand out at all.

His choice.  How about an uppercase-face?

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: new *Help* argument highlighting

[Juanma Barranquero]

On 10 May 2004 23:28:54 +0200, David Kastrup <dak@gnu.org> wrote:

> His choice.  How about an uppercase-face?

How do you do that, other than having an uppercase-only font? (Genuine
question, I don't know how to do it via Emacs faces.)


                                                           /L/e/k/t/u

Re: new *Help* argument highlighting

[Juanma Barranquero]

On 10 May 2004 23:28:54 +0200, David Kastrup <dak@gnu.org> wrote:

> His choice.  How about an uppercase-face?

How do you do that, other than having an uppercase-only font? (Genuine
question, I don't know how to do it via Emacs faces.)


                                                           /L/e/k/t/u

Re: new *Help* argument highlighting

[Robert J. Chassell]

[Regarding bold causing a problem in a mode line]

   > First, will someone who understands the patch review it?  Or should I
   > commit the merged version of xfaces.c and see whether it breaks others
   > people's installations?

   My understanding of the patch is that it introduces risks of crashes.
   If you set realize-face-filter-functions to functions that are simple
   enough, it might be safe (tho maybe only if you compile with -DSYNC_INPUT).

I did suffer some crashes immediately after installing the patch, but
none in the past year or so.  As I said a year ago, I think that some
other change to xfaces.c solved that danger.  But an alternative
explanation is that I stopped doing anything that evokes the
condition.  I don't know which is which, although I doubt the latter.

Here are extracts from the message I sent on 20 Nov 2002.  As I saw it
then, the problem is how to make a permanent global change to a
variable that is buffer local?

        ... using a `10x20' font, 
            -Misc-Fixed-Medium-R-Normal--20-200-75-75-C-100-ISO8859-1
        which has been very clear for the screen I am using.

      * I cannot permanently change 
            :weight bold 
        to
            :weight normal
        in the variable `mode-line-buffer-identification', which is
        buffer-local.

        That is to say, when I reset the value of
        `mode-line-buffer-identification' so its face is 
        :weight normal rather than :weight bold, that change is only
        temporary.  I don't know what to write in my .emacs file that
        can make a permanent global change to a variable that is
        buffer local.  If there is a method please tell me!


        Put another way, evaluating the following works temporarily
        but not permanently:

            (setq
             mode-line-buffer-identification
             (quote
              (#("%14b" 0 4
                 (face
                  ;; (:weight bold)
                  (:weight normal)
                  help-echo
                  "mouse-1: other buffer, mouse-2: prev, M-mouse-2: next, mouse-3: buffer menu"
                  local-map
                  (keymap
                   (header-line keymap
                                (down-mouse-3 . mouse-buffer-menu)
                                (mouse-2 . bury-buffer)
                                (M-mouse-2 . mode-line-unbury-buffer)
                                (mouse-1 . mode-line-other-buffer))
                   (mode-line keymap
                              (down-mouse-3 . mouse-buffer-menu)
                              (mouse-2 . bury-buffer)
                              (M-mouse-2 . mode-line-unbury-buffer))))))
              ))


        On the other hand, the following produces the face that I specify 
        when I evaluate it:

            (custom-set-faces
            ...
             '(bold ((t (:background "DodgerBlue4" :foreground "cyan"))))
            ...)

    ...


    Please tell me how to reset the bold characteristic universally.
    I talked about `mode-line-buffer-identification' because it is easy
    and obvious, but it turns out that name of directories shown in a
    PCL-CVS *cvs* buffer are also effected.  The `m' in the word `emacs'
    becomes unreadable.

-- 
    Robert J. Chassell                         Rattlesnake Enterprises
    As I slowly update it,                     bob@rattlesnake.com
        I rewrite a "What's New" segment for   http://www.rattlesnake.com

Re: new *Help* argument highlighting

[David Kastrup]

Juanma Barranquero <lektu@mi.madritel.es> writes:

> On 10 May 2004 23:28:54 +0200, David Kastrup <dak@gnu.org> wrote:
> 
> > His choice.  How about an uppercase-face?
> 
> How do you do that, other than having an uppercase-only font?
> (Genuine question, I don't know how to do it via Emacs faces.)

Neither do I.  That was a question directed at coders, not users.  To
be expanded into "Wouldn't it be nice if we had an uppercase-face?"
rather than "why don't you use an uppercase-face?".

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: new *Help* argument highlighting

[Stefan Monnier]

>> His choice.  How about an uppercase-face?
> How do you do that, other than having an uppercase-only font? (Genuine

Use smallcaps?


        Stefan

Re: new *Help* argument highlighting

[Juanma Barranquero]

On 10 May 2004 23:57:38 +0200, David Kastrup <dak@gnu.org> wrote:

> To
> be expanded into "Wouldn't it be nice if we had an uppercase-face?"
> rather than "why don't you use an uppercase-face?".

Ah, OK :)

So we still have a problem with using lowercase italics as arg
highlighting.


                                                           /L/e/k/t/u

Re: new *Help* argument highlighting

[Juanma Barranquero]

On 10 May 2004 17:59:10 -0400, Stefan Monnier <monnier@iro.umontreal.ca> wrote:

> Use smallcaps?

Sorry. I don't understand.

I don't see a way to set up a face so it shows in small caps (other than
having a smallcaps font). Is there one?

                                                           /L/e/k/t/u

Re: new *Help* argument highlighting

[Miles Bader]

On Tue, May 11, 2004 at 12:10:55AM +0200, Juanma Barranquero wrote:
> So we still have a problem with using lowercase italics as arg
> highlighting.

Still, it seems like a very nice way of presenting the arguments -- easy to
read, less SHOUTY than the old method, and more consistent with the printed
documentation[*].  I'd be happy if there was (as you suggested) a variable
holding a filter-function that help would call to munge the args, which by
default would downcase-and-italicize them.

Then change the docstring for the help-arguments face to say `you might want
to change this variable too'.

99.9% of the users won't ever change either one, so I think the nicer
display would be worth the small amount of added complexity for those who do
want to change something.

[*] Along the same lines, but probably more difficult: maybe the info reader
    should do something similar ...?

-Miles
-- 
(\(\
(^.^)
(")")
*This is the cute bunny virus, please copy this into your sig so it can spread.

Re: new *Help* argument highlighting

[Kenichi Handa]

In article <20040510234737.AE82.LEKTU@mi.madritel.es>, Juanma Barranquero <lektu@mi.madritel.es> writes:

> On 10 May 2004 23:28:54 +0200, David Kastrup <dak@gnu.org> wrote:
>>  His choice.  How about an uppercase-face?

> How do you do that, other than having an uppercase-only font? (Genuine
> question, I don't know how to do it via Emacs faces.)

Perhaps the easiest way is to implement a new face property
`display-table'.

But, please note upper/down-case is not applicable to CJK
(although it's quite rare to write a function whose
arguments are not latin).

---
Ken'ichi HANDA
handa@m17n.org

Re: new *Help* argument highlighting

[Juri Linkov]

Stefan Monnier <monnier@iro.umontreal.ca> writes:
> As I said, I haven't seen a single complaint about the font-size change
> in Info-mode in Emacs-21.

Perhaps you haven't seen complaints about font sizes in Info-mode,
because users who don't like that, has silently changed sizes
in their .emacs files :-)

> With the 6x13 font I use, "m" in bold looks basically like a solid block,
> but I've never found it to be unreadable because it still looks clearly
> different from all others (including "w").
> Is your situation similar except that the solid block does bother you
> (maybe because you sight is not as good as mine)?

This is clearly my situation with my 6x10 font, where the text
displayed in this font is hardly readable.  Even though I am able to
guess from letter shapes and context what the text is displayed in
bold, such constant guessing is too bothersome.  And note, fr xmpl, tht
vn wrds w/ vwls cn b rcgnzd, but this requires additional mental efforts.

>> First, will someone who understands the patch review it?  Or should I
>> commit the merged version of xfaces.c and see whether it breaks others
>> people's installations?
>
> My understanding of the patch is that it introduces risks of crashes.
> If you set realize-face-filter-functions to functions that are simple
> enough, it might be safe (tho maybe only if you compile with -DSYNC_INPUT).

I tried this patch a month ago, but it often causes crashes.  So without
hope to get this patch working without crashes, I solved this particular
problem with a small piece of code in .emacs:

(add-to-list 'custom-define-hook 'my-faces-set)

(defun my-faces-set (&optional frame)
  (interactive)
  ;; Check if this function is called by `custom-define-hook' from
  ;; `custom-declare-face' where the variable `face' is bound locally.
  (if (boundp 'face)
      (mapc (lambda (face)
              (when (face-bold-p face frame)
                (set-face-bold-p face nil frame)
                (set-face-underline-p face t frame))
              (when (numberp (face-attribute face :height frame))
                (set-face-attribute face frame :height 'unspecified))
              (when (numberp (face-attribute face :width frame))
                (set-face-attribute face frame :width 'unspecified)))
            (face-list))))

-- 
Juri Linkov
http://www.jurta.org/emacs/

Re: new *Help* argument highlighting

[Stefan Monnier]

>> As I said, I haven't seen a single complaint about the font-size change
>> in Info-mode in Emacs-21.
> Perhaps you haven't seen complaints about font sizes in Info-mode,
> because users who don't like that, has silently changed sizes
> in their .emacs files :-)

Of course.  I don't expect that everybody liked it.  But if they don't
whine, they get what they deserve.  When I compare that to the reaction
w.r.t colors, I conclude that "font-size changes are pretty safe".

>> With the 6x13 font I use, "m" in bold looks basically like a solid block,
>> but I've never found it to be unreadable because it still looks clearly
>> different from all others (including "w").
>> Is your situation similar except that the solid block does bother you
>> (maybe because you sight is not as good as mine)?

> This is clearly my situation with my 6x10 font, where the text
> displayed in this font is hardly readable.

I've often heard comments about my 6x13 font being pretty small already, so
I don't expect too many people to use a 6x10 font.  And those people should
expect to have to fiddle with things to get good results.  So I don't think
it's a class of users we should worry too much about.
The case of Robert's 10x20 font is different since it should be a "pretty
safe size" and the user probably expects things to be readable without
much fiddling.

> I tried this patch a month ago, but it often causes crashes.  So without
> hope to get this patch working without crashes, I solved this particular
> problem with a small piece of code in .emacs:

An elisp approach is indeed much safer.  If it's good enough, maybe we
should try such an approach (we could make it much cleaner than your code
by hooking directly in face-spec-set or face-spec-choose).


        Stefan

Re: new *Help* argument highlighting

[Juanma Barranquero]

On Mon, 10 May 2004 18:26:21 -0400
Miles Bader <miles@gnu.org> wrote:

> Still, it seems like a very nice way of presenting the arguments -- easy to
> read, less SHOUTY than the old method, and more consistent with the printed
> documentation[*].

Yes, I think is the best one suggested so far.

> I'd be happy if there was (as you suggested) a variable
> holding a filter-function that help would call to munge the args, which by
> default would downcase-and-italicize them.

That's my preferred solution too, so people can even do

(defun my-arg-highlight (arg)
  (propertize (downcase arg) 'display '(size (+ 1)) 'face '(:weight bold)))

which is not possible with a face.

> 99.9% of the users won't ever change either one, so I think the nicer
> display would be worth the small amount of added complexity for those who do
> want to change something.

Agreed.

Aside: for this to work, docstring writers still have to use the ALLCAPS
convention for arguments; I wonder if we could introduce (sometime after
21.[45], obviously :) a new (additional) convention to mark arguments in
the docstring, so less guesswork is needed. Of course, it wouldn't be
necessary to go back to change all existing docstrings (the current
guessing method would still work), but just adding the new convention to
a few complex ones would be a gain.

                                                                Juanma

Re: new *Help* argument highlighting

[Juanma Barranquero]

On Tue, 11 May 2004 08:42:52 +0900 (JST)
Kenichi Handa <handa@m17n.org> wrote:

> Perhaps the easiest way is to implement a new face property
> `display-table'.

I had no trouble thinking that some kind of filtering would allow to do
it. My question was more "Oh, so it is possible right now?" because of a
miscommunication between David and me.


                                                                Juanma

Re: new *Help* argument highlighting

[Juanma Barranquero]

On Mon, 10 May 2004 18:26:21 -0400
Miles Bader <miles@gnu.org> wrote:

> Then change the docstring for the help-arguments face to say `you might want
> to change this variable too'.

Patch attached. (I'm not commiting it yet, let's see if the dust settles...)

                                                                Juanma



--- help-fns.el.orig	2004-05-09 21:02:38.000000000 +0200
+++ help-fns.el	2004-05-11 10:59:31.000000000 +0200
@@ -239,5 +239,13 @@
 
 (defface help-argument-name '((t (:slant italic)))
-  "Face to highlight function arguments in docstrings.")
+  "Face to highlight function arguments in *Help* buffers.
+You can customize this face.  For more extensive customization,
+see variable `help-arg-highlighting-function'.")
+
+(defvar help-arg-highlighting-function
+  #'(lambda (arg) (propertize (downcase arg) 'face 'help-argument-name))
+  "Function to call to highlight function arguments in *Help* buffers.
+The function receives the argument to highlight, as a string.
+It must return the string with the desired highlighting (properties).")
 
 (defun help-do-arg-highlight (doc args)
@@ -248,5 +256,5 @@
         (setq doc (replace-regexp-in-string
                    (concat "\\<\\(" arg "\\)\\(?:es\\|s\\|th\\)?\\>")
-                   (propertize arg 'face 'help-argument-name)
+                   (funcall help-arg-highlighting-function arg)
                    doc t t 1))))
     doc))

Re: new *Help* argument highlighting

[Richard Stallman]

    That's a one-line patch, and the effect is nice, and scarcely intrusive.
    However, it has the problem that if someone customizes
    help-argument-face to the default face, he's lost also the uppercase, so
    now arguments do not stand out at all.

So he can customize two things instead of one.  That is no big deal.
(Only a few people will customize this.)

Re: new *Help* argument highlighting

[Juanma Barranquero]

On Tue, 11 May 2004 08:23:17 -0400
Richard Stallman <rms@gnu.org> wrote:

> So he can customize two things instead of one.  That is no big deal.
> (Only a few people will customize this.)

I'm not entirely sure whether that means "OK, let's use lowercase
italics and have a face and a -function var", or I'm just misreading
English again :)


                                                                Juanma

Re: new *Help* argument highlighting

[David Kastrup]

Juanma Barranquero <jmbarranquero@wke.es> writes:

> On Tue, 11 May 2004 08:23:17 -0400
> Richard Stallman <rms@gnu.org> wrote:
> 
> > So he can customize two things instead of one.  That is no big deal.
> > (Only a few people will customize this.)
> 
> I'm not entirely sure whether that means "OK, let's use lowercase
> italics and have a face and a -function var", or I'm just misreading
> English again :)

I think the least we can do is make lowercasing depending on whether
face-differs-from-default-p returns true.

If it does what I think it does.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: new *Help* argument highlighting

[Juanma Barranquero]

On 11 May 2004 16:36:56 +0200
David Kastrup <dak@gnu.org> wrote:

> I think the least we can do is make lowercasing depending on whether
> face-differs-from-default-p returns true.

Seems like a good idea, but:

ELISP> (set-face-attribute 'help-argument-name nil :slant 'unspecified)
nil
ELISP> (face-differs-from-default-p 'help-argument-name)
t
ELISP> (describe-face 'help-argument-name)

Face: help-argument-name (customize this face)
Documentation: Face to highlight function arguments in *Help* buffers.
You can customize this face.  For more extensive customization,
see variable `help-arg-highlighting-function'.

         Family: unspecified
          Width: unspecified
         Height: unspecified
         Weight: unspecified
          Slant: unspecified
     Foreground: unspecified
     Background: unspecified
      Underline: unspecified
       Overline: unspecified
 Strike-through: unspecified
            Box: unspecified
        Inverse: unspecified
        Stipple: unspecified
Font or fontset: nil
        Inherit: unspecified

                                                                Juanma

Re: new *Help* argument highlighting

[Juri Linkov]

Stefan Monnier <monnier@iro.umontreal.ca> writes:
>>> As I said, I haven't seen a single complaint about the font-size change
>>> in Info-mode in Emacs-21.
>> Perhaps you haven't seen complaints about font sizes in Info-mode,
>> because users who don't like that, has silently changed sizes
>> in their .emacs files :-)
>
> Of course.  I don't expect that everybody liked it.  But if they don't
> whine, they get what they deserve.  When I compare that to the reaction
> w.r.t colors, I conclude that "font-size changes are pretty safe".

I didn't complain about current sizes of Info faces, because I agree that
these are good defaults for font sizes larger than 6x10.

> I've often heard comments about my 6x13 font being pretty small already, so
> I don't expect too many people to use a 6x10 font.  And those people should
> expect to have to fiddle with things to get good results.  So I don't think
> it's a class of users we should worry too much about.

6x10 is the smallest font listed in the default value of `x-fixed-font-alist',
so it's already kind of "supported" by Emacs.  But I don't say that bold
properties should be avoided.  What I wanted to achieve is an ability
to adjust some properties on all faces easily.

> An elisp approach is indeed much safer.  If it's good enough, maybe we
> should try such an approach (we could make it much cleaner than your code
> by hooking directly in face-spec-set or face-spec-choose).

I'd try to add a hook to `face-spec-set', but I see one possible problem:
since `face-spec-set' processes one face at a time, it may be possible
that some faces are already processed before a user hook is added in .emacs,
and so some faces defined earlier may remain unchanged.

My current hook iterates over all faces, so it guarantees that
all faces will be changed according to the rules defined in a hook
when some new face is added later.  Though, nothing prevents from
iterating over all faces even in a hook called from `face-spec-set'.

-- 
Juri Linkov
http://www.jurta.org/emacs/

Re: new *Help* argument highlighting

[Juri Linkov]

"Robert J. Chassell" <bob@rattlesnake.com> writes:
> [Regarding bold causing a problem in a mode line]
>
>       * I cannot permanently change 
>             :weight bold 
>         to
>             :weight normal
>         in the variable `mode-line-buffer-identification'

This problem with bold faces in a mode line was solved recently
by using `Buffer-menu-buffer-face' instead of the hard-coded
`(:weight bold)'.

>     Please tell me how to reset the bold characteristic universally.
>     I talked about `mode-line-buffer-identification' because it is easy
>     and obvious, but it turns out that name of directories shown in a
>     PCL-CVS *cvs* buffer are also effected.  The `m' in the word `emacs'
>     becomes unreadable.

I don't know at which point it was changed, but currently cvs directory
names have a special face `cvs-header-face' whose bold property can be
changed easily.

Generally, I think there should not be anonymous faces, and all used
faces should have their own names to make it possible to change their
properties.

-- 
Juri Linkov
http://www.jurta.org/emacs/

Re: new *Help* argument highlighting

[Kevin Rodgers]

Juanma Barranquero wrote:
 > On Mon, 10 May 2004 13:54:11 -0400, Richard Stallman <rms@gnu.org> wrote:
 >>Yes, it would be good to downcase them in the Help buffer as well as
 >>italicizing them.
 >
 > That's a one-line patch, and the effect is nice, and scarcely intrusive.
 > However, it has the problem that if someone customizes
 > help-argument-face to the default face, he's lost also the uppercase, so
 > now arguments do not stand out at all.
 >
 > To solve that, we'd have do something like:
 >
 > (defvar help-arg-highlighting-function
 >   #'(lambda (arg) (propertize (downcase arg) 'face '(:slant italic)))
 >   "Function to call to highlight argument names in `describe-function' *Help* buffers.")
 >
 > instead of having a help-argument-name face.

No, you just need to check (face-differs-from-default-p
'help-argument-name) before downcasing the argument.

-- 
Kevin Rodgers

Re: new *Help* argument highlighting

[Stefan Monnier]

> I'd try to add a hook to `face-spec-set', but I see one possible problem:
> since `face-spec-set' processes one face at a time, it may be possible
> that some faces are already processed before a user hook is added in .emacs,
> and so some faces defined earlier may remain unchanged.

Yes, it might be  problem, but it might not: it's called once per frame, so
it depends whether it's called again after reading .emacs (when the initial
frame is resized/reshaped/... to adapt to parameter changes that took place
in .emacs).
It's at least not obviously going to fail, so it's worth trying.


        Stefan

Re: new *Help* argument highlighting

[Juanma Barranquero]

On Tue, 11 May 2004 10:51:47 -0600, Kevin Rodgers <ihs_4664@yahoo.com> wrote:

> No, you just need to check (face-differs-from-default-p
> 'help-argument-name) before downcasing the argument.

Nice, I didn't know about f-d-f-d-p until David and you mentioned it.

But still, I don't seem to be able to return a face to a non-differing
state.

ELISP> (defface test1-face '() "")
test1-face
ELISP> (face-differs-from-default-p 'test1-face)
nil
ELISP> (defface test2-face '((t (:slant italic))) "")
test2-face
ELISP> (face-differs-from-default-p 'test2-face)
t
ELISP> (set-face-attribute 'test2-face nil :slant 'unspecified :family 'unspecified)
nil
ELISP> (face-differs-from-default-p 'test2-face)
t
ELISP> 

and describe-face for test2-face shows "family or font: nil".

Any idea what I'm doing wrong?

                                                           /L/e/k/t/u

Re: new *Help* argument highlighting

[Miles Bader]

On Tue, May 11, 2004 at 06:57:09PM +0300, Juri Linkov wrote:
> This problem with bold faces in a mode line was solved recently
> by using `Buffer-menu-buffer-face' instead of the hard-coded
> `(:weight bold)'.

Which, BTW, is a silly thing to use for the mode-line -- there should be a
more generic face that's in turn :inherited by Buffer-menu-buffer-face (or
just change the buffer-menu code to use the third face directly, and add a
face alias to be backward compatible).

-Miles
-- 
I'd rather be consing.

Re: new *Help* argument highlighting

[Juri Linkov]

Miles Bader <miles@gnu.org> writes:
>> This problem with bold faces in a mode line was solved recently
>> by using `Buffer-menu-buffer-face' instead of the hard-coded
>> `(:weight bold)'.
>
> Which, BTW, is a silly thing to use for the mode-line -- there should be a
> more generic face that's in turn :inherited by Buffer-menu-buffer-face (or
> just change the buffer-menu code to use the third face directly, and add a
> face alias to be backward compatible).

I don't think new faces should be introduced if there are existing
faces for similar purposes.  However, if new proposed faces for the
mode line (major-mode, minor-mode, vc) will be added then certainly
a special face for the buffer name should be added to the same set
of mode line faces as well.

-- 
Juri Linkov
http://www.jurta.org/emacs/

Re: new *Help* argument highlighting

[Robert J. Chassell]

   This problem with bold faces in a mode line was solved recently
   by using `Buffer-menu-buffer-face' instead of the hard-coded
   `(:weight bold)'.

Thank you!  I tried it again and now it works globally.  According to
my notes, I tried it first on 2004 Apr 14 and again on May 4, but
found that the fix was buffer-local.  I still needed Miles' patch to
get it to work globally.  Now I don't.  I simply put

    (custom-set-faces '(Buffer-menu-buffer-face ((t (:weight normal))))
                      ... )

in my .emacs file.

This is with 

    Today's CVS snapshot, Tue, 2004 May 11  21:45 UTC
    GNU Emacs 21.3.50.5 (i686-pc-linux-gnu, GTK+ Version 2.2.4)

but using src/fontset.c version 1.82 rather than the new 1.86, since
version 1.86 prevented a bootstrap build.  (My apologies, but I
inadvertently overwrote the *compilation* buffer and cannot remember
the bug.)

-- 
    Robert J. Chassell                         Rattlesnake Enterprises
    As I slowly update it,                     bob@rattlesnake.com
        I rewrite a "What's New" segment for   http://www.rattlesnake.com

Re: new *Help* argument highlighting

[Miles Bader]

On Wed, May 12, 2004 at 12:51:25AM +0300, Juri Linkov wrote:
> > Which, BTW, is a silly thing to use for the mode-line -- there should be a
> > more generic face that's in turn :inherited by Buffer-menu-buffer-face (or
> > just change the buffer-menu code to use the third face directly, and add a
> > face alias to be backward compatible).
> 
> I don't think new faces should be introduced if there are existing
> faces for similar purposes.

The point is not that the faces should be separate, but that the existing
face name doesn't make sense for the extended use.

-Miles
-- 
`...the Soviet Union was sliding in to an economic collapse so comprehensive
 that in the end its factories produced not goods but bads: finished products
 less valuable than the raw materials they were made from.'  [The Economist]

Re: new *Help* argument highlighting

[Juanma Barranquero]

On Tue, 11 May 2004 10:51:47 -0600, Kevin Rodgers <ihs_4664@yahoo.com> wrote:

> No, you just need to check (face-differs-from-default-p
> 'help-argument-name) before downcasing the argument.

Well, I've finally commited it so people can take a look at the
downcase/italized setting.

I've installed the two customizable options, the face and the -function
var, because I think using a font differing or not from default is
independent of wanting the args upper or lowercase. As RMS said, not
many people will change the defaults (hopefully), but certainly *I* want
to be able to do it (I prefer args in uppercase).

Still, if face-differs-from-default-p works as expected, I'll patch the
default highlighting lambda to not downcase for default-looking faces.

                                                           /L/e/k/t/u

Re: new *Help* argument highlighting

[Richard Stallman]

    Aside: for this to work, docstring writers still have to use the ALLCAPS
    convention for arguments; I wonder if we could introduce (sometime after
    21.[45], obviously :) a new (additional) convention to mark arguments in
    the docstring, so less guesswork is needed.

That sounds like a good idea.  It would be more reliable than assuming
that upper-case words are argument names.

Re: new *Help* argument highlighting

[Miles Bader]

Richard Stallman <rms@gnu.org> writes:
>     Aside: for this to work, docstring writers still have to use the ALLCAPS
>     convention for arguments; I wonder if we could introduce (sometime after
>     21.[45], obviously :) a new (additional) convention to mark arguments in
>     the docstring, so less guesswork is needed.
> 
> That sounds like a good idea.  It would be more reliable than assuming
> that upper-case words are argument names.

Why not use the texinfo convention, @var{name} ?  Nice & easy to parse,
unlikely to occur in a docstring, and pretty understandable even if
_not_ translated into propertized text.  It might also make it easier
when updating a docstring and the manual at the same time.

There are probably other @-escapes which could be useful for docstrings too.

-Miles
-- 
Is it true that nothing can be known?  If so how do we know this?  -Woody Allen

Re: new *Help* argument highlighting

[Juanma Barranquero]

On 12 May 2004 17:15:00 +0900
Miles Bader <miles@lsi.nec.co.jp> wrote:

> Why not use the texinfo convention, @var{name} ?

I was thinking of something similar to substitute-command-keys markers,
i.e., "\<>", "\{}" and "\[]", but I really have no preference and what
you propose seems more sensible. I'll put the issue in my TODO.

Speaking of TODOs and keys... We have etc/TODO, but this is more for
features than bug reports. How do we track bugs pending to be fixed, now
that we're on bug-fixing mode? I posted a bug report for a
keybinding-related issue I don't know how to fix:

"Why does where-is-internal return nil?"
http://mail.gnu.org/archive/html/emacs-devel/2004-04/msg00952.html


                                                                Juanma

Re: new *Help* argument highlighting

[Miles Bader]

Juanma Barranquero <jmbarranquero@wke.es> writes:
> > Why not use the texinfo convention, @var{name} ?
>
> I was thinking of something similar to substitute-command-keys markers,
> i.e., "\<>", "\{}" and "\[]"

Prob with that kind of thing is that there's a very limited number of
them, and the closer you get to running out, the weirder and more
obscure they get...  :-)

It's a little tricky, since docstrings also serve as documentation in
the source file they occur in, so you don't want notation that's _too_
verbose, but personally I think @var is reasonable enough, and
docstrings are much more often viewed in *Help*.

-Miles
-- 
o The existentialist, not having a pillow, goes everywhere with the book by
  Sullivan, _I am going to spit on your graves_.

Re: new *Help* argument highlighting

[Juanma Barranquero]

On 12 May 2004 18:25:37 +0900
Miles Bader <miles@lsi.nec.co.jp> wrote:

> Prob with that kind of thing is that there's a very limited number of
> them, and the closer you get to running out, the weirder and more
> obscure they get...  :-)

Yeah, well, I was on the \+ARG+, \|ARG|, \¿ARG?, \@#$&!!!! path when
your message arrived, and I saw instant light :)

> but personally I think @var is reasonable enough, and
> docstrings are much more often viewed in *Help*.

I *fully* agree.

                                                                Juanma

Re: new *Help* argument highlighting

[Kenichi Handa]

In article <buoad0ecb97.fsf@mcspd15.ucom.lsi.nec.co.jp>, Miles Bader <miles@lsi.nec.co.jp> writes:
>>  That sounds like a good idea.  It would be more reliable than assuming
>>  that upper-case words are argument names.

> Why not use the texinfo convention, @var{name} ?  Nice & easy to parse,
> unlikely to occur in a docstring, and pretty understandable even if
> _not_ translated into propertized text.  It might also make it easier
> when updating a docstring and the manual at the same time.

> There are probably other @-escapes which could be useful for docstrings too.

I prefer a shorter convention something like @NAME or $NAME.

---
Ken'ichi HANDA
handa@m17n.org

Re: new *Help* argument highlighting

[Juanma Barranquero]

On Wed, 12 May 2004 19:47:58 +0900 (JST)
Kenichi Handa <handa@m17n.org> wrote:

> I prefer a shorter convention something like @NAME or $NAME.

The probability of a collision with current docstrings is much higher.
$NAME could happen easily in shell-related modules, and both in
perl-related ones.

                                                                Juanma

Re: new *Help* argument highlighting

[Kenichi Handa]

In article <20040512130729.FB5D.JMBARRANQUERO@wke.es>, Juanma Barranquero <jmbarranquero@wke.es> writes:

> On Wed, 12 May 2004 19:47:58 +0900 (JST)
> Kenichi Handa <handa@m17n.org> wrote:

>>  I prefer a shorter convention something like @NAME or $NAME.

> The probability of a collision with current docstrings is much higher.
> $NAME could happen easily in shell-related modules, and both in
> perl-related ones.

Really?  I think it's very rare that a docstring of a
funciton that has an argument NAME contains a reference to a
shell/perl variable NAME in the form $NAME?

I grepped "\$[a-z]" in etc/DOC but found none.

The reason I prefer a shorter name is that I want to keep
the first line of a docstring in a source code short because
we can't fill it.  And, if we use @var{NAME}, it's get a
little bit difficult to check if the first line fits in 80
columns.

---
Ken'ichi HANDA
handa@m17n.org

Re: new *Help* argument highlighting

[Juanma Barranquero]

On Wed, 12 May 2004 20:25:38 +0900 (JST)
Kenichi Handa <handa@m17n.org> wrote:

> Really?  I think it's very rare that a docstring of a
> funciton that has an argument NAME contains a reference to a
> shell/perl variable NAME in the form $NAME?

OK, but we're assuming different things.

With @var{ARG}, it wouldn't be necessary to pre-scan the usage info to
heuristically find the args, as it is done now. A simple walk through
the "doc" part of the docstring would allow to find @var{ARG}s, highlight
them and save them, so in fact the opposite is true: the information
gathered processing the doc would allow to highlight the usage info, so
arguments not referenced would *not* be highlighted in the usage info
either (and, in this way, alerting the doc writer and the user that the
argument is not described in the doc). That would also eliminate any
need to recognize CL-style arglists, BTW.

What you propose is as is done now: scan the usage, recognize the args,
and then substitute the args in the doc. That is helpful, because it
would prevent accidental highlighting, but that case is rare even now 
(defstruct, for example, mentions NAME-SLOT accessors, and the reference
is not highlighted), so perhaps is not worth the change.

To be fair, if implemented as I suggest, both the current
scan-usage-then-doc and my proposed scan-doc-then-usage methods would
have to coexist (we're not going to retroactively update thousands of
docstrings), but at least we could do: scan-doc-then-usage; if it does
not find any @{var}, fall back to old method.

> I grepped "\$[a-z]" in etc/DOC but found none.

Hu?
C:\...\etc> grep "\$[A-Za-z]" DOC
`$FOO' where FOO is an environment variable name means to substitute
`$FOO' where FOO is an environment variable name means to substitute
the entire variable name in braces.  For instance, in `ab$cd-x',
`$cd' is treated as an environment variable.
For example, invoke "emacs -batch -f batch-byte-compile $emacs/ ~/*.el".
Insert a copyright by $ORGANIZATION notice at cursor.
$               type sys$input
For example, invoke "emacs -batch -f batch-info-validate $info/ ~/*.info"
nil means the default, which is ("/usr/spool/mail/$USER")

And \@[A-Za-z] returns 33 hits.

> The reason I prefer a shorter name is that I want to keep
> the first line of a docstring in a source code short because
> we can't fill it.

Yes, I imagine as much.

> And, if we use @var{NAME}, it's get a
> little bit difficult to check if the first line fits in 80
> columns.

On one hand, you're not sure $NAME (or @var{NAME}) is going to be
substituted by a four-letter highlighted NAME (the user could make
help-arg-highlighting-function to do something weird). I admit this is
not likely.

On the other hand, we could "fix" filling for emacs-lisp docstrings so
it recognizes @var{NAME} and acts accordingly.

                                                                Juanma

Re: new *Help* argument highlighting

[Juanma Barranquero]

Kenichi Handa <handa@m17n.org> wrote:

> I prefer a shorter convention something like @NAME or $NAME.

BTW, it should be @NAME@ or $NAME$, because I want to support:

  {N}th
  {INDEX}es
  {SLOT}s
  make-{NAME}
  {NAME}-p

(the part between {} is highlighted).  All of them do happen now (see
defstruct, for example).

                                                                Juanma

Re: new *Help* argument highlighting

[Kenichi Handa]

In article <20040512133037.FB60.JMBARRANQUERO@wke.es>, Juanma Barranquero <jmbarranquero@wke.es> writes:

> With @var{ARG}, it wouldn't be necessary to pre-scan the usage info to
> heuristically find the args, as it is done now. A simple walk through
> the "doc" part of the docstring would allow to find @var{ARG}s, highlight
> them and save them, so in fact the opposite is true: the information
> gathered processing the doc would allow to highlight the usage info, so
> arguments not referenced would *not* be highlighted in the usage info
> either (and, in this way, alerting the doc writer and the user that the
> argument is not described in the doc). That would also eliminate any
> need to recognize CL-style arglists, BTW.

> What you propose is as is done now: scan the usage, recognize the args,
> and then substitute the args in the doc.  That is helpful, because it
> would prevent accidental highlighting, but that case is rare even now 
> (defstruct, for example, mentions NAME-SLOT accessors, and the reference
> is not highlighted), so perhaps is not worth the change.

I see your point.  The above discussion depends on that
@var{NAME} much much rarely appears in a docstring than $NAME.
But, with another grep ('\( \|^\)$[a-z-][a-z-]*\( \|$\)'), I
found only this docstring contains $NAME that will be treated
as an arg unless we prescan usage.

------------------------------------------------------------
copyright is an interactive autoloaded Lisp function in `copyright'.
(copyright &optional STR ARG)

Insert a copyright by $ORGANIZATION notice at cursor.
------------------------------------------------------------

We can change it to:

Insert a copyright by `$ORGANIZATION' notice at cursor.

Then we can use scan-doc-then-usage method even with $NAME
convention.

>>  I grepped "\$[a-z]" in etc/DOC but found none.

> Hu?
> C:\...\etc> grep "\$[A-Za-z]" DOC
> `$FOO' where FOO is an environment variable name means to substitute
> `$FOO' where FOO is an environment variable name means to substitute

Ah, I meant that I found none that results in
mis-highlighting.

>>  The reason I prefer a shorter name is that I want to keep
>>  the first line of a docstring in a source code short because
>>  we can't fill it.

> Yes, I imagine as much.

>>  And, if we use @var{NAME}, it's get a
>>  little bit difficult to check if the first line fits in 80
>>  columns.

> On one hand, you're not sure $NAME (or @var{NAME}) is going to be
> substituted by a four-letter highlighted NAME (the user could make
> help-arg-highlighting-function to do something weird). I admit this is
> not likely.

At least, $NAME convention is easier for keeping the first
line in 80 column even without eliminating `$'s.

> On the other hand, we could "fix" filling for emacs-lisp docstrings so
> it recognizes @var{NAME} and acts accordingly.

What do you mean?  The first `sentence' should never be
broken into multiple lines.  So only the meaningful "fix"
for fill is to make it recognize the emacs-lisp docstrings
and keep the first line untouched.

---
Ken'ichi HANDA
handa@m17n.org

Re: new *Help* argument highlighting

[Kim F. Storm]

Miles Bader <miles@gnu.org> writes:

> On Wed, May 12, 2004 at 03:15:01PM +0200, Juanma Barranquero wrote:
> > > What do you mean?  The first `sentence' should never be
> > > broken into multiple lines.  So only the meaningful "fix"
> > > for fill is to make it recognize the emacs-lisp docstrings
> > > and keep the first line untouched.
> 
> It already does that.

Also in DEFUN:s in C code ?

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

Re: new *Help* argument highlighting

[Juanma Barranquero]

On Wed, 12 May 2004 22:01:41 +0900 (JST)
Kenichi Handa <handa@m17n.org> wrote:

> I see your point.  The above discussion depends on that
> @var{NAME} much much rarely appears in a docstring than $NAME.

Yes.

> found only this docstring contains $NAME that will be treated
> as an arg unless we prescan usage.

> ------------------------------------------------------------
> copyright is an interactive autoloaded Lisp function in `copyright'.
> (copyright &optional STR ARG)
> 
> Insert a copyright by $ORGANIZATION notice at cursor.
> ------------------------------------------------------------
> 
> We can change it to:
> 
> Insert a copyright by `$ORGANIZATION' notice at cursor.

I'm not sure I understand. Are you assuming `$NAME' could not be a valid
argument reference?

> What do you mean?  The first `sentence' should never be
> broken into multiple lines.  So only the meaningful "fix"
> for fill is to make it recognize the emacs-lisp docstrings
> and keep the first line untouched.

Well, filling for docstrings could work so it doesn't wrap the first
line, but marks chars exceding 80 in a warning face orwhatever. It could
take into account $var{NAME} or $NAME$ expansion (assuming a
length-preserving highlighting) when computing the number of columns,
not only for the first line, but the rest of the docstring.

                                                                Juanma

Re: new *Help* argument highlighting

[Kenichi Handa]

In article <20040512143721.FB63.JMBARRANQUERO@wke.es>, Juanma Barranquero <jmbarranquero@wke.es> writes:

> Kenichi Handa <handa@m17n.org> wrote:

>>  I prefer a shorter convention something like @NAME or $NAME.

> BTW, it should be @NAME@ or $NAME$, because I want to support:

>   {N}th
>   {INDEX}es
>   {SLOT}s
>   make-{NAME}
>   {NAME}-p

> (the part between {} is highlighted).  All of them do happen now (see
> defstruct, for example).

Even with $NAME, it seems
  (replace-regexp "\\$\\([A-Z]\\(-*[A-Z]\\)*\\)" "{\\1}")
can correctly find parts to be highlighted (perhaps there
will be more efficient regexp).

---
Ken'ichi HANDA
handa@m17n.org

Re: new *Help* argument highlighting

[Juanma Barranquero]

On Wed, 12 May 2004 22:22:26 +0900 (JST)
Kenichi Handa <handa@m17n.org> wrote:

> Even with $NAME, it seems
>   (replace-regexp "\\$\\([A-Z]\\(-*[A-Z]\\)*\\)" "{\\1}")
> can correctly find parts to be highlighted

I'm not converting ARG1-XXX to {ARG1}-{XXX} or {ARG1-XXX} because there
can be functions which have YYY as an argument, and YYY-XXX as a
non-related "variable" in the docstring (because UPPERCASE words are
often used as additional "docstring variables" in functions which accept
complex combinations of keywords and/or structured args).

But in fact, yes, I'm sure it can be made to work.  Choosing $var{NAME}
or $NAME or $NAME$ is not very important.  Whatever people feels more
comfortable with.

                                                                Juanma

Re: new *Help* argument highlighting

[Miles Bader]

On Wed, May 12, 2004 at 03:15:01PM +0200, Juanma Barranquero wrote:
> > What do you mean?  The first `sentence' should never be
> > broken into multiple lines.  So only the meaningful "fix"
> > for fill is to make it recognize the emacs-lisp docstrings
> > and keep the first line untouched.

It already does that.

-Miles
-- 
Is it true that nothing can be known?  If so how do we know this?  -Woody Allen

Re: new *Help* argument highlighting

[Romain Francoise]

Juanma Barranquero <lektu@mi.madritel.es> writes:

> Well, I've finally commited it so people can take a look at the
> downcase/italized setting.

Italic doesn't work on terminals (at least mine), so you should probably
restrict this to window systems and leave the arguments in uppercase
otherwise.  Having no argument highlighting at all is quite disturbing.

-- 
Romain Francoise <romain@orebokech.com> | I know, you love the song but
it's a miracle -- http://orebokech.com/ | not the singer.

Re: new *Help* argument highlighting

[Richard Stallman]

    > So he can customize two things instead of one.  That is no big deal.
    > (Only a few people will customize this.)

    I'm not entirely sure whether that means "OK, let's use lowercase
    italics and have a face and a -function var", or I'm just misreading
    English again :)

To say that a user can customize something does not necessarily mean
introducing a defcustom to customize it.  That is one of many
customization mechanisms in Emacs.  Another customization mechanism
is to redefine a function.

Some customizations are natural to do in that way, and some are
important enough to be worth installing a defcustom for.  But we
should refuse to fall into thinking automatically "add a defcustom"
whenever we think something might want to be changed by some users.
Many of those things are definitely not worth adding a defcustom for.

I am not sure what is the best way to recommend users deal with
customizing this, when they want to customize this.  It depends
on how often anyone will want to change that.  That depends
on other things.

    I think the least we can do is make lowercasing depending on whether
    face-differs-from-default-p returns true.

    If it does what I think it does.

Detecting automatically when to do this is much better than adding a
separate defcustom to control whether to downcase.

(Meanwhile, in the long term, we also have the idea of defining a new
way to indicate variable names in doc strings.  With that, it won't be
a matter of downcasing any more.  But the issue of deciding whether to
upcase will replace it.)

Re: new *Help* argument highlighting

[Stefan Monnier]

Honestly, I can't believe we're spending so much energy on printing args in
a slightly nicer way:
- making sure the new highlighting pleases most people [done].
- making sure the new highlighting is OK in 99& of the environments
  [already done: including when the user changed the face to not be italics,
  or when running on a tty.]
  [left to do: detect X11 systems where the font chosen has no italics
  version.]
- define a new format like @var{foo}.
- change the help-mode to fiddle with those and only those.
- change the fill code to try and not count the @var{...} annotation.
- ...

If someone comes up with an actual use for those changes (rather than just
minor aesthetics tweaks), maybe I can buy them, but as it stands I find it
just a waste of effort.
Especially since experience on gnu.emacs.help seems to indicate that most
users don't spend that much time and effort reading docstrings.

The current convention is simple and safe, and as far as I can tell it's
quite sufficient as well.  The changes discussed here seem to be about
a new convention which is not simple, and more importantly not safe.


        Stefan

Re: new *Help* argument highlighting

[Miles Bader]

On Wed, May 12, 2004 at 03:09:26PM +0200, Kim F. Storm wrote:
> > > >  So only the meaningful "fix"
> > > > for fill is to make it recognize the emacs-lisp docstrings
> > > > and keep the first line untouched.
> > 
> > It already does that.
> 
> Also in DEFUN:s in C code ?

Not to the best of my knowledge.

But it hardly makes a difference -- the first line of doc: comments in C-code
DEFUNs are typically indented so much that they usually _already_ go way past
the left margin.

-Miles
-- 
A zen-buddhist walked into a pizza shop and
said, "Make me one with everything."

fill docstring (Re: new *Help* argument highlighting)

[Kenichi Handa]

In article <20040512140625.GA20095@fencepost>, Miles Bader <miles@gnu.org> writes:

> On Wed, May 12, 2004 at 03:15:01PM +0200, Juanma Barranquero wrote:
>>  > What do you mean?  The first `sentence' should never be
>>  > broken into multiple lines.  So only the meaningful "fix"
>>  > for fill is to make it recognize the emacs-lisp docstrings
>>  > and keep the first line untouched.

> It already does that.

Wow!  I didn't know that.  But, it seems that there's a bug.

When I move point in the following docstring and type M-q:

(defun temp ()
  "This is a fairly long first line of a function documentation string."
  nil)

the result is:

(defun temp ()
  "This is a fairly long first line of a function documentation
  string."  nil)

Another test:

(defun temp ()
  "This is a short documentation string."
  nil)

is filled as:

(defun temp ()
  "This is a short documentation string."  nil)

If the docstring is more than two lines, it works as
expected.  So, perhaps, I should not try to fill a single
line docstring which is anyway a nonsense thing.

But I found another problem.

(defun temp ()
  (interactive)
  "This is a fairly long long long long first line of an embedded Lisp string.
The second line." )

The string part is not filled, perhaps because it is
detected as a docstring?

---
Ken'ichi HANDA
handa@m17n.org

Re: new *Help* argument highlighting

[Miles Bader]

Stefan Monnier <monnier@iro.umontreal.ca> writes:
> If someone comes up with an actual use for those changes (rather than just
> minor aesthetics tweaks), maybe I can buy them, but as it stands I find it
> just a waste of effort.
> Especially since experience on gnu.emacs.help seems to indicate that most
> users don't spend that much time and effort reading docstrings.
> 
> The current convention is simple and safe, and as far as I can tell it's
> quite sufficient as well.  The changes discussed here seem to be about
> a new convention which is not simple, and more importantly not safe.

I kinda agree -- but _if_ we _do_ change to a new variable notation, it
should be something extensible like @var{...}, not yet-another magic
quote notation.  That at least provides a path for easier future
enhancements.

-Miles
-- 
o The existentialist, not having a pillow, goes everywhere with the book by
  Sullivan, _I am going to spit on your graves_.

Re: new *Help* argument highlighting

[Juanma Barranquero]

On Wed, 12 May 2004 15:40:48 -0400, Richard Stallman <rms@gnu.org> wrote:

> That is one of many
> customization mechanisms in Emacs.  Another customization mechanism
> is to redefine a function.

[...]

> I am not sure what is the best way to recommend users deal with
> customizing this, when they want to customize this.

I think we've already given too much thought to something that should be
simple, so I've done what you say: there's now no customizable face or
variable, just a function `help-default-arg-highlight'.  The NEWS entry
explains that the user should redefine the function if he's not
satisfied with the default.

The default, by the way, is lowercase italics if
display-supports-face-attributes-p says that the display supports it,
uppercase normal (non-italics) otherwise.

I'd suggest to leave the issue to rest and come back to it only if a
problem is found.

                                                           /L/e/k/t/u

Re: new *Help* argument highlighting

[Juanma Barranquero]

On 12 May 2004 16:12:32 -0400, Stefan Monnier <monnier@iro.umontreal.ca> wrote:

> Honestly, I can't believe we're spending so much energy on printing args in
> a slightly nicer way:

Me neither :)

> - making sure the new highlighting pleases most people [done].
> - making sure the new highlighting is OK in 99& of the environments

Yes.

>   [already done: including when the user changed the face to not be italics,
>   or when running on a tty.]
>   [left to do: detect X11 systems where the font chosen has no italics
>   version.]

It should work now, at least if display-supports-face-attributes-p is
reliable.

> If someone comes up with an actual use for those changes (rather than just
> minor aesthetics tweaks), maybe I can buy them, but as it stands I find it
> just a waste of effort.
> Especially since experience on gnu.emacs.help seems to indicate that most
> users don't spend that much time and effort reading docstrings.

Well, I see it different because I spend a lot of time reading
docstrings, so I don't think it's a waste of effort making them better,
even in aesthetic ways.

But certainly now is not the time to discuss it.  If we decide that more
information (structure, highlighting, or whatever) is necessary or
helpful in docstrings, we can design the new features on the 22.X
timeframe.

                                                           /L/e/k/t/u

Re: new *Help* argument highlighting

[Juanma Barranquero]

On Wed, 12 May 2004 20:29:43 +0200, Romain Francoise <romain@orebokech.com> wrote:

> Italic doesn't work on terminals (at least mine), so you should probably
> restrict this to window systems and leave the arguments in uppercase
> otherwise.

Please, try with the current HEAD and see if it works right for you.

                                                           /L/e/k/t/u

Re: new *Help* argument highlighting

[Stefan Monnier]

>> [left to do: detect X11 systems where the font chosen has no italics
>> version.]
> It should work now, at least if display-supports-face-attributes-p is
> reliable.

I strongly doubt it, because it is not a property of the display (X11
always supports italics) but of the particular font used.


        Stefan

Re: new *Help* argument highlighting

[Romain Francoise]

Juanma Barranquero <lektu@mi.madritel.es> writes:

> Please, try with the current HEAD and see if it works right for you.

It does, thanks.

-- 
Romain Francoise <romain@orebokech.com> | They're nothing but scared
it's a miracle -- http://orebokech.com/ | little mice.

Re: new *Help* argument highlighting

[Juanma Barranquero]

On 12 May 2004 21:41:31 -0400
Stefan Monnier <monnier@iro.umontreal.ca> wrote:

> I strongly doubt it, because it is not a property of the display (X11
> always supports italics) but of the particular font used.

Patches welcome. I don't know much about that stuff.

                                                                Juanma

Re: new *Help* argument highlighting

[Stefan Monnier]

>> I strongly doubt it, because it is not a property of the display (X11
>> always supports italics) but of the particular font used.
> Patches welcome.  I don't know much about that stuff.

Neither do I.  The best approach I can think of is to compare the font used
for "A" and then for (propertize "A" 'face 'help-arg-face), but I don't think
we have a function to get the font used for a given char-with-face.

Of course, even if we do, it would only be valid for the current frame which
might be different from the one in which *Help* will be displayed (IIRC the
buffer is first constructed and then displayed via pop-to-buffer).


        Stefan

Re: new *Help* argument highlighting

[Richard Stallman]

    Speaking of TODOs and keys... We have etc/TODO, but this is more for
    features than bug reports. How do we track bugs pending to be fixed, now
    that we're on bug-fixing mode?

Savannah has some sort of bug-tracking facility, but I have never used
it and I don't know how it works.  Does someone else want to find out?

Re: new *Help* argument highlighting

[Richard Stallman]

    > but personally I think @var is reasonable enough, and
    > docstrings are much more often viewed in *Help*.

    I *fully* agree.

Perhaps we should abbreviate it to @v{..} for this purpose.
Saving even 2 characters will help the formatting of the
doc strings.  Or maybe even just @{..}.  References to variables
are very very common in doc strings.

Re: new *Help* argument highlighting

[David Kastrup]

Richard Stallman <rms@gnu.org> writes:

>     > but personally I think @var is reasonable enough, and
>     > docstrings are much more often viewed in *Help*.
> 
>     I *fully* agree.
> 
> Perhaps we should abbreviate it to @v{..} for this purpose.
> Saving even 2 characters will help the formatting of the
> doc strings.

Since doc strings should be formatted with something like 60
characters or so (I don't remember the exact size right now), it would
take at least 3 mentions of @var{} in a single line before the normal
terminal line width of 80 characters in the source code would get
exceeded.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: new *Help* argument highlighting

[Juanma Barranquero]

On 13 May 2004 10:21:56 -0400, Stefan Monnier <monnier@iro.umontreal.ca> wrote:

> Of course, even if we do, it would only be valid for the current frame which
> might be different from the one in which *Help* will be displayed (IIRC the
> buffer is first constructed and then displayed via pop-to-buffer).

I have no way to test all that. I think the best thing to do is wait for
someone to trample into the problem and fix it and report back :)

                                                           /L/e/k/t/u

Re: new *Help* argument highlighting

[Richard Stallman]

    I think we've already given too much thought to something that should be
    simple,

I tend to agree.

	    so I've done what you say: there's now no customizable face or
    variable, just a function `help-default-arg-highlight'.  The NEWS entry
    explains that the user should redefine the function if he's not
    satisfied with the default.

    The default, by the way, is lowercase italics if
    display-supports-face-attributes-p says that the display supports it,
    uppercase normal (non-italics) otherwise.

    I'd suggest to leave the issue to rest and come back to it only if a
    problem is found.

That sounds good to me.

Re: new *Help* argument highlighting

[Kenichi Handa]

In article <20040512221825.GA30731@fencepost>, Miles Bader <miles@gnu.org> writes:
> But it hardly makes a difference -- the first line of doc: comments in C-code
> DEFUNs are typically indented so much that they usually _already_ go way past
> the left margin.

In such a case, can't we put the docstring as this?

  DEFVAR_LISP ("some-var", &Vsome_var,
	       doc: /*
Long long long long long long long long long first line of the docstring.
...

---
Ken'ichi HANDA
handa@m17n.org

Re: new *Help* argument highlighting

[Kenichi Handa]

In article <20040512150550.FB66.JMBARRANQUERO@wke.es>, Juanma Barranquero <jmbarranquero@wke.es> writes:

> On Wed, 12 May 2004 22:01:41 +0900 (JST)
> Kenichi Handa <handa@m17n.org> wrote:

>>  I see your point.  The above discussion depends on that
>>  @var{NAME} much much rarely appears in a docstring than $NAME.

> Yes.

>>  found only this docstring contains $NAME that will be treated
>>  as an arg unless we prescan usage.

>>  ------------------------------------------------------------
>>  copyright is an interactive autoloaded Lisp function in `copyright'.
>>  (copyright &optional STR ARG)
>>  
>>  Insert a copyright by $ORGANIZATION notice at cursor.
>>  ------------------------------------------------------------
>>  
>>  We can change it to:
>>  
>>  Insert a copyright by `$ORGANIZATION' notice at cursor.

> I'm not sure I understand. Are you assuming `$NAME' could not be a valid
> argument reference?

I think so.   If we surround $NAME with `', we should not
treat it as an argument.

---
Ken'ichi HANDA
handa@m17n.org

Re: new *Help* argument highlighting

[Miles Bader]

Kenichi Handa <handa@m17n.org> writes:
> > But it hardly makes a difference -- the first line of doc: comments
> > in C-code DEFUNs are typically indented so much that they usually
> > _already_ go way past the left margin.
> 
> In such a case, can't we put the docstring as this?
> 
> 	       doc: /*
> Long long long long long long long long long first line of the docstring.

You could I suppose (though I don't know if that has any funny
interaction with the doc-string processing code), but people don't seem
to, and instead just let the line overflow.  Perhaps that's because
c-mode, if given the chance, will screw up the indentation of such a
line, so it can be a pain to _keep_ that way (e.g., if you type a */ at
the end the line, bang, c-mode will put the indentation back...).

-Miles
-- 
Would you like fries with that?

Re: new *Help* argument highlighting

[Juanma Barranquero]

On Mon, 17 May 2004 10:16:49 +0900 (JST)
Kenichi Handa <handa@m17n.org> wrote:

> I think so.   If we surround $NAME with `', we should not
> treat it as an argument.

I think that's a consequence, not a feature, or what you're proposing.
If we had argument-name markers, I'd like for them to be honored
everywhere they appear.

                                                                Juanma

Re: new *Help* argument highlighting

[Kenichi Handa]

In article <20040517090152.E437.JMBARRANQUERO@wke.es>, Juanma Barranquero <jmbarranquero@wke.es> writes:
> On Mon, 17 May 2004 10:16:49 +0900 (JST)
> Kenichi Handa <handa@m17n.org> wrote:

>>  I think so.   If we surround $NAME with `', we should not
>>  treat it as an argument.

> I think that's a consequence, not a feature, or what you're proposing.
> If we had argument-name markers, I'd like for them to be honored
> everywhere they appear.

We anyway need some escape method for argument-name markers.
It seems to me that surrounding them by `' is an easy way.
But, I don't inisist on it that much.  Changing the
docstring to this is clearer.

Insert a copyright by the organization notice (extracted
from the environment variable ORGANIZATION) at cursor.

---
Ken'ichi HANDA
handa@m17n.org

Re: new *Help* argument highlighting

[Kim F. Storm]

Miles Bader <miles@gnu.org> writes:

> On Wed, May 12, 2004 at 03:09:26PM +0200, Kim F. Storm wrote:
> > > > >  So only the meaningful "fix"
> > > > > for fill is to make it recognize the emacs-lisp docstrings
> > > > > and keep the first line untouched.
> > > 
> > > It already does that.
> > 
> > Also in DEFUN:s in C code ?
> 
> Not to the best of my knowledge.
> 
> But it hardly makes a difference -- the first line of doc: comments in C-code
> DEFUNs are typically indented so much that they usually _already_ go way past
> the left margin.

Yes, they often go past right margin when you edit the C file, but IMO
filling should try to fill the doc string so that the first line looks
sane when the user views it with e.g C-h C-f.

That means that in c code, filling should really ignore \s*doc:\s*" at
the beginning of the line.

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

Re: new *Help* argument highlighting

[Miles Bader]

On Mon, May 17, 2004 at 04:46:30PM +0200, Kim F. Storm wrote:
> That means that in c code, filling should really ignore \s*doc:\s*" at
> the beginning of the line.

Hey I'd love it, but I can imagine the obscure bug reports ... maybe there
needs to be a special `emacs-c-mode'...

-miles
-- 
"Most attacks seem to take place at night, during a rainstorm, uphill,
 where four map sheets join."   -- Anon. British Officer in WW I

Re: new *Help* argument highlighting

[Kenichi Handa]

In article <buohdufzsxn.fsf@mctpc71.ucom.lsi.nec.co.jp>, Miles Bader <miles@lsi.nec.co.jp> writes:

> Kenichi Handa <handa@m17n.org> writes:
>>  > But it hardly makes a difference -- the first line of doc: comments
>>  > in C-code DEFUNs are typically indented so much that they usually
>>  > _already_ go way past the left margin.
>>  
>>  In such a case, can't we put the docstring as this?
>>  
>>  	       doc: /*
>>  Long long long long long long long long long first line of the docstring.

> You could I suppose (though I don't know if that has any funny
> interaction with the doc-string processing code), 

I used such format in emacs-unicode branch and it seems that
doc-string processing code has no problem with that format.

> but people don't seem
> to, and instead just let the line overflow.  Perhaps that's because
> c-mode, if given the chance, will screw up the indentation of such a
> line, so it can be a pain to _keep_ that way (e.g., if you type a */ at
> the end the line, bang, c-mode will put the indentation back...).

Yes.  If we are going to promote that format, we should
adjust the behaviour of c-mode.

---
Ken'ichi HANDA
handa@m17n.org

Bug tracking (was: new *Help* argument highlighting)

[Juanma Barranquero]

On Thu, 13 May 2004 11:45:32 -0400
Richard Stallman <rms@gnu.org> wrote:

> Savannah has some sort of bug-tracking facility, but I have never used
> it and I don't know how it works.  Does someone else want to find out?

I see no bug tracking facility on Savannah, but perhaps I didn't look at
the right places.

Still, the question remains: should we use some kind of issue tracker?

Currently we have an etc/TODO, which is sort of half wish list, half
grab bag of heterogeneous items.  I'm all for using an issue tracker, if
only because it makes easier to know where we are, release-wise, for any
given release.  For example, what's precluding us from doing a
prerelease tarball just today (not that I'm proposing it, of course)?
My guess is that a mix of:

  - Outstanding bugs (each one known to a few developers, the ones more
    interested or knowledgeable on the issue)

  - Pending documentation for new features

  - Undecided status of several patches (dynamic loading, currying,
    overridable faces, etc.)

  - Lack of consensus for the release number (OK, that's only
    half-serious :)

  - Uncertainty about where we stand right now

Of course, issue tracking systems have other advantages than I'm not
going to repeat here, unrelated to whether we're trying to do a release
right now or not.  Almost every serious free or open source project out
there uses one form or another of issue tracking.  We should do it, not
to follow suit, but for the intrinsic gain.

I said a while back that IMHO we should be a more structured project, in
the sense of having a plan for releases, with tentative dates, perhaps
even a release manager, etc.  Someone (Eli, I think, but I'm speaking
from memory) opposed on the grounds that it costs human resources that
we don't have.  But the Emacs project has 87 registered developers;
that's 33% more than Subversion, for example, and they seem to be doing
well on that regard (though, to be fair, they have four or five people
paid to work almost full-time on Subversion).

OTOH, perhaps I'm the only one that feels that way, and I'm just pissing
out my turf...

                                                                Juanma

Re: Bug tracking

[Lars Hansen]

Juanma Barranquero wrote:
> I see no bug tracking facility on Savannah, but perhaps I didn't look at
> the right places.

Look at

https://savannah.gnu.org/bugs/?group=tasklist

You can access it from the savannah start page by selecting
"GNU Task List" in the lower left part of the page, and then look for
"Public Areas: Development Tools".

I don't know anyting about the system, just noticed it was there.
BTW, it seems to be unused.

Re: Bug tracking

[Juanma Barranquero]

On Fri, 11 Jun 2004 13:20:33 +0200
Lars Hansen <larsh@math.ku.dk> wrote:

> https://savannah.gnu.org/bugs/?group=tasklist

https://savannah.gnu.org/bugs/?group=emacs

=> "This project has turned off this tracker [#1];"

so perhaps we could turn it on and take a look.


                                                                Juanma

Re: Bug tracking (was: new *Help* argument highlighting)

[Kim F. Storm]

Juanma Barranquero <jmbarranquero@wke.es> writes:

> I said a while back that IMHO we should be a more structured project, in
> the sense of having a plan for releases, with tentative dates, perhaps
> even a release manager, etc.  Someone (Eli, I think, but I'm speaking
> from memory) opposed on the grounds that it costs human resources that
> we don't have.  But the Emacs project has 87 registered developers;
> that's 33% more than Subversion, for example, and they seem to be doing
> well on that regard (though, to be fair, they have four or five people
> paid to work almost full-time on Subversion).
> 

I really don't understand that we manage to get by without using a bug
tracking system.  We seem to manage, but I'm sure there are many
issues which are never fully addressed and resolved.

I use my personal mail archives and TODO list to keep an eye on issue
that I MIGHT want to look into; actually, I have several mails more
than a year old that I really don't know (without using time I don't
have to find out) if the issue is still unresolved.

A major advantage of bug tracking is also to know WHO (if any) is 
responsible for fixing a given bug.

I have very positive experience with bugzilla from other projects, but
there may be other choices...

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

Re: Bug tracking

[Juanma Barranquero]

On 11 Jun 2004 13:39:25 +0200
storm@cua.dk (Kim F. Storm) wrote:

> I really don't understand that we manage to get by without using a bug
> tracking system.  We seem to manage, but I'm sure there are many
> issues which are never fully addressed and resolved.

I have the same feeling: we *seem* to manage.

> I use my personal mail archives and TODO list to keep an eye on issue
> that I MIGHT want to look into; actually, I have several mails more
> than a year old that I really don't know (without using time I don't
> have to find out) if the issue is still unresolved.

Same here.  I had for almost a year and half a personal note to try to
find out what caused the incompatibilities between GnuWin32 image
libraries and MSVC optimized builds.

> A major advantage of bug tracking is also to know WHO (if any) is 
> responsible for fixing a given bug.

Yes.  That also helps when preparing for a release, because people can
take a look at outstanding bug reports and appoint themselves
responsibles for issues in their area of expertise.

Another thing that I find surprising is not having any kind of
regression testing in place.  User interface issues are hard to test
automatically, but there are many things that *could* be tested (the
elisp interpretor, lots of modules, perhaps even the garbage collector).

> I have very positive experience with bugzilla from other projects, but
> there may be other choices...

If we were to use an bug/issue tracker, would it be being on Savannah a
prerequisite? (Not that I have any other system to propose, just to keep
choices open...)

                                                                Juanma

Re: Bug tracking (was: new *Help* argument highlighting)

[Miles Bader]

On Fri, Jun 11, 2004 at 01:39:25PM +0200, Kim F. Storm wrote:
> I have very positive experience with bugzilla from other projects, but
> there may be other choices...

Bugzilla and the savannah bug tracker stuff both seem to suffer from the
almost fatal flaw that they are almost entirely web-based.  Filing a simple
bug report or managing bugs with either is a painful process, because you are
largely stuck with the slow manual process of filling in a web form.

I'd much prefer something based around email, only using the web where it
makes sense.

Andrew Suffield's `BugGoo' system, which Tom Lord has started using for tla
(replacing savannah's bug tracker), looks interesting.  Andrew is a Debian
developer so I presume it is partially based on experience with Debian's
bug-tracking system (which is generally excellent, at least from a user's
point of view).  http://bugs.gnuarch.org/

-Miles
-- 
[|nurgle|]  ddt- demonic? so quake will have an evil kinda setting? one that
            will  make every christian in the world foamm at the mouth?
[iddt]      nurg, that's the goal

Re: Bug tracking (was: new *Help* argument highlighting)

[Kim F. Storm]

Miles Bader <miles@gnu.org> writes:

> On Fri, Jun 11, 2004 at 01:39:25PM +0200, Kim F. Storm wrote:
> > I have very positive experience with bugzilla from other projects, but
> > there may be other choices...
> 
> Bugzilla and the savannah bug tracker stuff both seem to suffer from the
> almost fatal flaw that they are almost entirely web-based.  Filing a simple
> bug report or managing bugs with either is a painful process, because you are
> largely stuck with the slow manual process of filling in a web form.

I have entered/updated 1000s of bugzilla trackers, and NEVER found it to be slow.
Anything complicated (the description part) can be cut/pasted if necessary.

> 
> I'd much prefer something based around email, only using the web where it
> makes sense.

To me using web interface for bug tracking makes a lot of sense...
That doesn't mean that it has to be the only interface though.

> 
> Andrew Suffield's `BugGoo' system, which Tom Lord has started using for tla
> (replacing savannah's bug tracker), looks interesting.  Andrew is a Debian
> developer so I presume it is partially based on experience with Debian's
> bug-tracking system (which is generally excellent, at least from a user's
> point of view).  http://bugs.gnuarch.org/

Looks ok on the surface -- but it seems like the only interface, e.g.
to reassign a bug, is to send mail ... seems clumsy (unless of course
there is a nice Elisp package to help you with the nitty gritty.)

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

Re: Bug tracking (was: new *Help* argument highlighting)

[Miles Bader]

On Fri, Jun 11, 2004 at 05:11:57PM +0200, Kim F. Storm wrote:
> > Bugzilla and the savannah bug tracker stuff both seem to suffer from the
> > almost fatal flaw that they are almost entirely web-based.  Filing a
> > simple bug report or managing bugs with either is a painful process,
> > because you are largely stuck with the slow manual process of filling in
> > a web form.
> 
> I have entered/updated 1000s of bugzilla trackers, and NEVER found it to be
> slow.  Anything complicated (the description part) can be cut/pasted if
> necessary.

There are two (enormous) problems with web-based bug user-interfaces:

 (1) The web UI cannot do any environmental inspection of your system at
     all.  In the case of emacs, of course, the traditional bug-reportting
     form includes _tons_ of auto-detected data, which is invaluable for
     for analyzing bug reports.

 (2) For the sophisticated user they are extremely difficult to automate,
     whereas an email-based system moves all the work to client where it's
     actually fairly easy (_especially_ for an emacs user, who is often
     using an email client integrated with emacs).

     If you report lots of bugs, or are in charge of bug-handling, a
     web-based interface can become a huge time drain for this reason.

     Note that this is the same old `GUI problem' we're all familiar with
     from other applications:  GUIs are great for occasional use by naive
     users, but when compared to a `language based' approach, they can be
     extremely inefficient for sophisticated users because of the difficulty
     of automation.

`cut and pasting' is absolutely not an answer to (2): it is a time-consuming
and fiddly process unless the entire bug report is a single text field, in
which case you might was well offer an email interface.

For some tasks, a web-based system is probably easier, such as searching of
the bug data-base, so certainly you want _some_ web tools, but you should
also export a simple protocol usable by non-web-browser clients -- see
debian's bug-reporting program for an example (it is client program, and so
can do environmental inspection, but also queries the bug database to allow
the user to make sure they aren't duplicating a bug report).

> To me using web interface for bug tracking makes a lot of sense...
> That doesn't mean that it has to be the only interface though.

If there are multiple interfaces, great, of course -- but I think the entire
functionality of the system _must_ be available via email, except where that
doesn't make much sense (e.g., I'd say that database searching is best left
to other protocols, as email-based query systems are usually too slow to be
very usable).

> > Andrew Suffield's `BugGoo' system, which Tom Lord has started using for
> > tla (replacing savannah's bug tracker), looks interesting.  Andrew is a
> > Debian developer so I presume it is partially based on experience with
> > Debian's bug-tracking system (which is generally excellent, at least from
> > a user's point of view).  http://bugs.gnuarch.org/
> 
> Looks ok on the surface -- but it seems like the only interface, e.g.
> to reassign a bug, is to send mail ... seems clumsy

I think he's only been developing it for about 5 minutes, so yeah, it's a a
bit spartan -- but it's already better than savannah's system for heavy
users...

> (unless of course there is a nice Elisp package to help you with the nitty
> gritty.)

Of course -- but this is simple if you use emacs to read your email (actually
even with reasonably facile non-emacs email clients this shouldn't be too
hard, e.g. make a shell-script called `bugh' and pipe email with commands
like "| bugh reassign kim").

Note that a (huge) advantage of email-based systems is that they make
bug-handling part of your morning email session, where besides being in a
nice familiar environment with easy automation is, it's hard to forget to do
it ... :-) Not a minor issue in practice...

-Miles
-- 
"Whatever you do will be insignificant, but it is very important that
 you do it."  Mahatma Ghandi

Re: Bug tracking (was: new *Help* argument highlighting)

[Richard Stallman]

    Still, the question remains: should we use some kind of issue tracker?

It would be useful to keep track of the problems that need to be
solved before we can make a release.  However, using some special
"issue tracker" seems like doing it the hard way.  All we need
is a file we can edit.  We can keep it in /etc using CVS and edit
it with Emacs.

The main job is collecting the information to put in the file.

Re: Bug tracking (was: new *Help* argument highlighting)

[Juanma Barranquero]

On Fri, 11 Jun 2004 21:50:59 -0400, Richard Stallman <rms@gnu.org> wrote:

> However, using some special
> "issue tracker" seems like doing it the hard way.

Why?

Why it is the good way for so many projects and would be "hard" for us?

Issue trackers have many advantages, from statistics to easy work flow,
from categorization of bugs to accesibility to outside and/or casual
users.

> The main job is collecting the information to put in the file.

I agree.  And certainly, we can do that (using an etc/BUGS file) if
that's what's decided.  It would already be better than what we do now. 
But a few of us have expressed interest in finding a good solution via a
dedicated software solution.  Are you vetoing it?

                                                           /L/e/k/t/u

Re: Bug tracking (was: new *Help* argument highlighting)

[Lars Hansen]

Juanma Barranquero wrote:

> Issue trackers have many advantages, from statistics to easy work flow,
> from categorization of bugs to accesibility to outside and/or casual
> users.

I agree.

It seems many (all?) developers have their own TODO list because of the 
lack of an Emacs bug/issue tracker.
Why not share with other developers and outside world?

Re: Bug tracking

[Juri Linkov]

Richard Stallman <rms@gnu.org> writes:
> All we need is a file we can edit.  We can keep it in /etc using CVS
> and edit it with Emacs.

This is the most simple and flexible solution!  Such file could be
in the mail-like format with relevant field names that comprise the
database of bug reports, todo items and news (the latter actually
would be either a bug report or a todo item with `Completed' status).

An example of a record for such database:

Summary: Do this and that
Category: Custom
Priority: High
Status: Open
Submitted: J. Random Hacker
Assigned: J. Random Hacker

Long multi-line description.
Long multi-line description.
Long multi-line description.

^L

"Issue trackers" written in a plain text file have many advantages:
it can be edited directly in Emacs, all changes can be easily tracked
by developers after committing this file to CVS, it allows arbitrary
text-processing operations on a file...

-- 
Juri Linkov
http://www.jurta.org/emacs/

Re: Bug tracking

[Lars Hansen]

Juri Linkov wrote:
> Richard Stallman <rms@gnu.org> writes:
> 
>>All we need is a file we can edit.  We can keep it in /etc using CVS
>>and edit it with Emacs.
> 
> 
> This is the most simple and flexible solution!  Such file could be
> in the mail-like format with relevant field names that comprise the
> database of bug reports, todo items and news (the latter actually
> would be either a bug report or a todo item with `Completed' status).

IMO database functionality is needed. I should be easy to select items 
having to do with a particular
    module/issuer/maintainer/priority/version of Emacs/OS
and possibly other. Of course that can be done with a text file, but is 
there existing (Emacs lisp) code that can do it? And IMHO it should be 
accessible from the web as well.

Re: Bug tracking (was: new *Help* argument highlighting)

[Richard Stallman]

    I'd much prefer something based around email, only using the web where it
    makes sense.

It would be nearly essential for me, if I'm to use the bug-tracker.

Re: Bug tracking

[Juanma Barranquero]

On Sat, 12 Jun 2004 11:37:05 +0300, Juri Linkov <juri@jurta.org> wrote:

> This is the most simple and flexible solution!

There is flexibility and there is flexibility.  Of course using a
custom-format, text file is the most flexible answer, at the cost of
having no tool other than what we want to develop.  Yes, we have Emacs,
but even Emacs has no "Bug Tracker" major mode, that I know of :)

> "Issue trackers" written in a plain text file have many advantages:
> it can be edited directly in Emacs, all changes can be easily tracked
> by developers after committing this file to CVS, it allows arbitrary
> text-processing operations on a file...

It doesn't have a web interface for other people, no automatic way to
extract statistics, it's *clumsy* beyond belief if you want to also
store past (and fixed or rejected) issues, has to be manually edited by
us so outside people cannot enter issues, needs that someone reads
gnu-emacs-bugs@ reports and formats them as desired, it has limited
posibilities for searching and categorizing...

                                                           /L/e/k/t/u

Re: Bug tracking

[Juri Linkov]

Lars Hansen <larsh@math.ku.dk> writes:
> IMO database functionality is needed. I should be easy to select items
> having to do with a particular
>     module/issuer/maintainer/priority/version of Emacs/OS
> and possibly other. Of course that can be done with a text file, but
> is there existing (Emacs lisp) code that can do it?

Yes, there is existing Emacs Lisp code (but obviously I am biased).
It is Ee information manager which displays data from text files
in category trees and allows to operate on displayed data:
expand/collapse categories, edit data fields, etc.  It's possible
to create different views for every data file.  Here is an
example http://www.jurta.org/emacs/ee/data/todo.en.html
how a possible issue tracker might look.

-- 
Juri Linkov
http://www.jurta.org/emacs/

Re: Bug tracking

[Juri Linkov]

Juanma Barranquero <lektu@mi.madritel.es> writes:
> There is flexibility and there is flexibility.  Of course using a
> custom-format, text file is the most flexible answer, at the cost of
> having no tool other than what we want to develop.  Yes, we have Emacs,
> but even Emacs has no "Bug Tracker" major mode, that I know of :)

Even without special mode a plain text file is the most convenient
way to edit data and to perform arbitrary Emacs operations on them.

> It doesn't have a web interface for other people, no automatic way
> to extract statistics, it's *clumsy* beyond belief if you want to
> also store past (and fixed or rejected) issues, has to be manually
> edited by us so outside people cannot enter issues,

I think there is nothing wrong with the fact that only Emacs
developers will be able to fill bug reports.  So no web interface
is really needed.

> needs that someone reads gnu-emacs-bugs@ reports and formats
> them as desired

That's exactly how it might work: developers read gnu-emacs-bugs,
create new bug entries in the text file and commit them to CVS.
And you can track changes in the text file with all the usual
features of CVS.

> it has limited posibilities for searching and categorizing...

Apart from the Ee categorizing manager, I think that some other
Emacs packages can perform these operations on text files.
AFAIK, at least Gnus should be able to read a text file in the
mail-like format and to treat it as a mail group with bug and TODO
entries as messages.  There are even many possibilities of tighter
integration with its email functionality.

-- 
Juri Linkov
http://www.jurta.org/emacs/

Re: Bug tracking (was: new *Help* argument highlighting)

[Karl Fogel]

Juanma Barranquero <jmbarranquero@wke.es> writes:
> I said a while back that IMHO we should be a more structured project, in
> the sense of having a plan for releases, with tentative dates, perhaps
> even a release manager, etc.  Someone (Eli, I think, but I'm speaking
> from memory) opposed on the grounds that it costs human resources that
> we don't have.  But the Emacs project has 87 registered developers;
> that's 33% more than Subversion, for example, and they seem to be doing
> well on that regard (though, to be fair, they have four or five people
> paid to work almost full-time on Subversion).

A data point:

The Subversion issue tracker database is almost entirely maintained by
unpaid volunteers now.  The salaried developers use it too, of course,
but not in any fundamentally different way than the unpaid developers,
and not proportionally more often.  (There are actually two or three
paid developers, by the way, not four or five).

It's very common for experienced volunteers to help new reporters file
bugs.  For example, a longtime volunteer will often

   1. See a newbie's post on the mailing list,
   2. Solicit more details,
   3. Instruct the newbie in how to file a useful bug report,
   4. Watch to confirm that the newbie did so,
   5. Add some developer-directed comments to the issue if appropriate,
   6. Possibly fix it, if they are a developer themselves.

This process is self-perpetuating.  January's newbie becomes June's
experienced volunteer.

This thread (about whether to have a bug tracker for Emacs) is quite
long, and I can't participate in detail due to time constraints,
unfortunately.  So I'll just say I'm very much in favor of having such
a system -- and yes, to track individual bugs, not just large-scale
future plans.  In the long run, it would save humans much headache,
even though there would be an initial cost to setting it up.

RMS wrote:
> I won't assume it is really good for other projects.
> I don't know whether they have thought about it carefully.
> Techies are often attracted to using the highest tech available
> whether it is better or not.
> 
> It is clear that using a special "issue tracker" would be extra work
> for many people, and it would be hard for me to use.

I understand your skepticism, and in fact harbored similar
reservations when we started Subversion.

However, we did think about it and discuss it quite carefully, both
then and now.  We have no doubt now that it's actually helping us.  It
serves a real need; otherwise we would have dispensed with it long
ago.  Regarding your comment that using an issue tracker would be hard
for you: note that it is not necessary that every developer use the
bug tracker, or use it in the same way, for it to be useful to the
project as a whole.  (I think over time you would find yourself using
it too, though, as using it is often more efficient than avoiding it.)

There is no particular need for this thread to come to a definite
conclusion.  If someone sets up a good tracker and starts using it,
others will follow.  However, it would be nice if the tracker were at
Savannah and advertised from the project pages in some obvious way;
and especially nice if 'M-x report-emacs-bug' and other "official"
sources named it as the canonical database for Emacs bugs.

I wish I had time to set such a thing up, but don't right now.  I hope
someone else does.  FWIW, the Subversion bug tracker is a
[non-portably customized] version of IssueZilla.  It's entirely
web-based.  Lack of a good email interface is one of its serious
flaws, though it hasn't been a fatal flaw for us.

I have no strong opinion about which bug tracker Emacs should use
(except that it be Free of course).  Just the subset of features
common to all bug trackers would already be useful for Emacs...

-Karl

Re: Bug tracking (was: new *Help* argument highlighting)

[Karl Fogel]

Karl Fogel <kfogel@floss.red-bean.com> writes:
> I wish I had time to set such a thing up, but don't right now.  I hope
> someone else does.  FWIW, the Subversion bug tracker is a
> [non-portably customized] version of IssueZilla.  It's entirely
> web-based.  Lack of a good email interface is one of its serious
  ^^^^^^^^^^

Sorry, I misspoke.

While the tracker does not accept input via email, it does send *out*
an email (to a list) whenever a change is made to an issue.  This is
vital functionality, of course.  You can read email to follow what's
going on with bugs, then visit the web forms only when you need to
make a comment or whatever.

(Of course, taking input via email would be even nicer.)

-Karl

Re: Bug tracking (was: new *Help* argument highlighting)

[Karl Fogel]

Miles Bader <miles@gnu.org> writes:
> It's critical, IMO -- my experience of using mozilla and savannah's bug
> tracker is that the annoyance of having to go to the web site and muddle
> through the forms significantly decreased the likelihood that I would bother
> (it was fine the first N times, but after a while I started to dread it).

Note that filing bugs by email significantly increases the likelihood
of duplicate issues.  

One of the advantages of going to the web site is that you can first
search to see if the bug already exists in the database.  Whereas if
you fire off an email, there's no query step.  Sure, the editing
environment for an email is better -- Emacs buffer, rather than web
form -- but the web forms *are* also a realtime database front end,
and that makes a difference too.

I'm not sure what interface made you "muddle through forms".  In my
experience, if you're filing a new bug, there's one form to fill out,
and if you're modifying an existing bug, then you just go to a URL and
make the appropriate change.  It's not that hard; I certainly don't
dread it.

Administering existing bugs by email would be nice, of course.  For
example, I'd like to be able to respond to an email sent by the issue
tracker, and have my response cause some new change to the bug.  But
lack of this feature is hardly a showstopper.

Please, let's not aim for perfection, that way lies madness.  Some
issue tracker is better than no issue tracker, and if one sets up the
appropriate bookmarks and URLs, one should never have to muddle
through multiple forms to get things done.

-Karl

Re: Bug tracking (was: new *Help* argument highlighting)

[Karl Fogel]

Miles Bader <miles@gnu.org> writes:
> I agree, but I'm not suggesting that, merely trying to establish some
> minimal standards.  Purely web-based systems are non-starter.

They're not perfect, but they don't have to be a non-starter.  After
all, you're not using *any* bug tracker right now.  So if some Emacs
developers start using a web-based system, and you decide not to,
we're all still better off in absolute terms than we are now, right?

All I'm asking is that, if you're not going to set up an
email-accessible bug tracking system yourself, that you not object if
someone else sets up a purely web-based one.  You don't have to use
it, though I hope you would at least try it.

Many, many people use purely web-based bug trackers, and think that
they are better off than with no bug tracker at all.

-Karl

Re: Bug tracking

[Juanma Barranquero]

On Sat, 12 Jun 2004 18:38:29 +0300, Juri Linkov <juri@jurta.org> wrote:

> Even without special mode a plain text file is the most convenient
> way to edit data and to perform arbitrary Emacs operations on them.

No, a plain text file is not necessarily "the most convenient way to
edit data", not by a long shot. Certain kinds of data, yes.  And yes, it
is easi to perform arbitrary Emacs operations on it, but we don't want
to perform arbitrary operations, but a few, very specific, widely used
kinds of operations: the ones usually associated with bug/issue
management.  Your claim is so broad that it seems like you were saying
that Emacs is "the most convenient way" to do anything.

> I think there is nothing wrong with the fact that only Emacs
> developers will be able to fill bug reports.  So no web interface
> is really needed.

Obviously, we *strongly* disagree here.  I see much wrong with only
Emacs developers being able to fill bug reports (for one, that means
someone *has* to do the work which could have made the user).  So the
web interface is, to me, really needed.

> That's exactly how it might work: developers read gnu-emacs-bugs,
> create new bug entries in the text file and commit them to CVS.
> And you can track changes in the text file with all the usual
> features of CVS.

Yes, I understand how could it work, I just happen to think that is a
extraordinarily un-optimized way to do things.  See etc/TODO: would you
dare say that it is really used for the intended purpose?  Many things
in TODO have been there for years, and almost *all* things implemented
or fixed never ever touched TODO.

> Apart from the Ee categorizing manager, I think that some other
> Emacs packages can perform these operations on text files.
> AFAIK, at least Gnus should be able to read a text file in the
> mail-like format and to treat it as a mail group with bug and TODO
> entries as messages.  There are even many possibilities of tighter
> integration with its email functionality.

Aren't you saying that we can shoehorn something into simulating being an
issue tracker, just to *not* use an issue tracker which already does all
that?


                                                           /L/e/k/t/u

Re: Bug tracking

[Miles Bader]

On Sun, Jun 13, 2004 at 12:09:04AM +0200, Juanma Barranquero wrote:
> Yes, I understand how could it work, I just happen to think that is a
> extraordinarily un-optimized way to do things.  See etc/TODO: would you
> dare say that it is really used for the intended purpose?  Many things
> in TODO have been there for years, and almost *all* things implemented
> or fixed never ever touched TODO.

I doubt a fancy `issue tracker' would make a whole lot of difference --
indeed it might make things worse, if it tried to hide what's actually a
simple, relatively small, list of items under an unnecessary search
interface.

I think the best thing for help to get TODO more used would be a bit more
structure / categorization in the file, to make it less daunting for
first-time viewers, and an easy way for regular developers to see changes to
it, without having to explicitly _do_ something, e.g., a special mailing list
just for commit diffs to TODO.

-Miles
-- 
We live, as we dream -- alone....

Re: Bug tracking (was: new *Help* argument highlighting)

[Richard Stallman]

    > However, using some special
    > "issue tracker" seems like doing it the hard way.

    Why?

    Why it is the good way for so many projects and would be "hard" for us?

I won't assume it is really good for other projects.
I don't know whether they have thought about it carefully.
Techies are often attracted to using the highest tech available
whether it is better or not.

It is clear that using a special "issue tracker" would be extra work
for many people, and it would be hard for me to use.

Re: Bug tracking

[Richard Stallman]

    An example of a record for such database:

    Summary: Do this and that
    Category: Custom
    Priority: High
    Status: Open
    Submitted: J. Random Hacker
    Assigned: J. Random Hacker

That general plan is good.

Instead of "Assigned", let's call it "Undertaken".
Here normally people choose to undertake a task,
rather than having it assigned to them.

Also, we should always list the date when the task was
undertaken, so we can tell when something has gone on
for a long time without getting done.

Completed items should be moved to a different file,
so they don't clutter the status of work remaining to be done.

Re: Bug tracking

[Richard Stallman]

    IMO database functionality is needed. I should be easy to select items 
    having to do with a particular
	module/issuer/maintainer/priority/version of Emacs/OS

It is easy enough to search a file.  If this gets to be large,
something is wrong.  We're not planning to use this to track
individual bugs, and aside from individual bugs, the number of issues
cannot be too large.

What you're proposing would be too costly to set up and maintain.
Our sysadmins would have to do it.  I can't agree to that.

Also, I would be unable to access it.  I usually do not have a net
connection, and often don't even have the possibility of one.
Therefore, I want this info to be kept in a file in the Emacs
repository, so I will be able to look at it and edit it without
a net connection.

If you want to work on Emacs code to do more sophisticated searching
of this file, please go ahead.  That would be a modular improvement
which would not impose any problems elsewhere.

Re: Bug tracking

[Juanma Barranquero]

On Sat, 12 Jun 2004 20:01:23 -0400, Richard Stallman <rms@gnu.org> wrote:

> We're not planning to use this to track
> individual bugs [...]

<sigh>


                                                           /L/e/k/t/u

Re: Bug tracking

[Juanma Barranquero]

On Sat, 12 Jun 2004 19:06:38 -0400, Miles Bader <miles@gnu.org> wrote:

> I doubt a fancy `issue tracker' would make a whole lot of difference --

I was not saying "fancy".  In fact, I have no preference for one or
another, and simple is enough.  But certainly a text file is not what I
was talking about.  I bet it won't be useful.  No, scratch that.  I bet
it won't be used.

> I think the best thing for help to get TODO more used would be a bit more
> structure / categorization in the file, to make it less daunting for
> first-time viewers, and an easy way for regular developers to see changes to
> it, without having to explicitly _do_ something, e.g., a special mailing list
> just for commit diffs to TODO.

So, we should develop a simple issue tracker, instead of using a simple,
already-existing issue tracker...

                                                           /L/e/k/t/u

Re: Bug tracking (was: new *Help* argument highlighting)

[Juanma Barranquero]

On Sat, 12 Jun 2004 20:01:11 -0400, Richard Stallman <rms@gnu.org> wrote:

> I won't assume it is really good for other projects.
> I don't know whether they have thought about it carefully.
> Techies are often attracted to using the highest tech available
> whether it is better or not.

That's hardly fair.  The GCC people, for example, is having a discussion
right now about someday replacing CVS with another version control
software.  They certainly haven't jumped to the "highest tech available",
and in fact it seems like they'll decide to just delay the decision till
more, and more mature, tools exist so they can be fairly compared.

I can't honestly object to people saying "I don't want to use a web
interface", or "it's hard for me to use it for such and such", or "I
would prefer just an e-mail system", or "text files are the way to go". 
But I simply find incredible that, confronted with the fact that many
projects put web-based issue trackers to good use and express
satisfaction with them, the answer be doubting their word.  I'm
certainly curious about how many free or open source projects the
approximate size of Emacs go along happily without some sort of issue
tracker.

> It is clear that using a special "issue tracker" would be extra work
> for many people, and it would be hard for me to use.

Oh, I doubt it would be extra work for people, unless they decide to
invest the effort on it.  This is voluntary work, after all.  And it is
equally clear that, to-day, no one has decided to invest even the "modest
effort" in maintaining issues in a simple etc/ISSUES.PENDING text file...
so we're both on the realm of theology, right now.

                                                           /L/e/k/t/u

Re: Bug tracking

[Miles Bader]

On Sun, Jun 13, 2004 at 02:08:05AM +0200, Juanma Barranquero wrote:
> So, we should develop a simple issue tracker, instead of using a simple,
> already-existing issue tracker...

Huh?  Of course not -- if you can find one that actually works for us and
meets the constraints given.  Web-only software need not apply.

-Miles
-- 
A zen-buddhist walked into a pizza shop and
said, "Make me one with everything."

Re: Bug tracking

[Juanma Barranquero]

On Sat, 12 Jun 2004 20:50:22 -0400, Miles Bader <miles@gnu.org> wrote:

> Huh?  Of course not

What I meant is that we're bound to reproduce, in text files and elisp
modules, an issue tracker.

> if you can find one that actually works for us and
> meets the constraints given.  Web-only software need not apply.

I'll take a look.

                                                           /L/e/k/t/u

Re: Bug tracking (was: new *Help* argument highlighting)

[Miles Bader]

On Sat, Jun 12, 2004 at 03:03:25PM -0500, Karl Fogel wrote:
> While the tracker does not accept input via email, it does send *out*
> an email (to a list) whenever a change is made to an issue.  This is
> vital functionality, of course.  You can read email to follow what's
> going on with bugs, then visit the web forms only when you need to
> make a comment or whatever.
> 
> (Of course, taking input via email would be even nicer.)

It's critical, IMO -- my experience of using mozilla and savannah's bug
tracker is that the annoyance of having to go to the web site and muddle
through the forms significantly decreased the likelihood that I would bother
(it was fine the first N times, but after a while I started to dread it).

-Miles
-- 
"Unless there are slaves to do the ugly, horrible, uninteresting work, culture
and contemplation become almost impossible. Human slavery is wrong, insecure,
and demoralizing.  On mechanical slavery, on the slavery of the machine, the
future of the world depends." -Oscar Wilde, "The Soul of Man Under Socialism"

Re: Bug tracking (was: new *Help* argument highlighting)

[Miles Bader]

On Sat, Jun 12, 2004 at 04:01:15PM -0500, Karl Fogel wrote:
> > It's critical, IMO -- my experience of using mozilla and savannah's bug
> > tracker is that the annoyance of having to go to the web site and muddle
> > through the forms significantly decreased the likelihood that I would
> > bother (it was fine the first N times, but after a while I started to
> > dread it).
> 
> Note that filing bugs by email significantly increases the likelihood
> of duplicate issues.  
> 
> One of the advantages of going to the web site is that you can first
> search to see if the bug already exists in the database.  Whereas if
> you fire off an email, there's no query step.  Sure, the editing
> environment for an email is better -- Emacs buffer, rather than web
> form -- but the web forms *are* also a realtime database front end,
> and that makes a difference too.

Indeed for the original bug submission, it helps to be able to search the
database, but it's not necessary to use the web to do that (even though you
might want to use an http/html-based interface of some sort for maximum
firewall transparency) -- see debian's bug system for an example of a system
that does most of the work on the client, but also uses a network
database-access protocol of some sort to allow the user to look for old bugs
(it doesn't a perfect interface; something emacs based would likely be much
better).

Note that another important area of bug submission, automatic detection of
environmental parameters, can't be done by a web interface, meaning that the
user is responsible for filling in lots of fussy details, which can make bug
reporting a real chore.

For many `bug management' tasks, the ease of automation and integration into
one's normal workflow make email-friendly systems far superior, especially
if there's an ancillary database-search mechanism that is easily accessible
for automation (i.e. simple enough for an elisp program to use).

> Please, let's not aim for perfection, that way lies madness.

I agree, but I'm not suggesting that, merely trying to establish some
minimal standards.  Purely web-based systems are non-starter.

Thanks,

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

Re: Bug tracking (was: new *Help* argument highlighting)

[David Kastrup]

Miles Bader <miles@gnu.org> writes:

> On Sat, Jun 12, 2004 at 03:03:25PM -0500, Karl Fogel wrote:
> > While the tracker does not accept input via email, it does send
> > *out* an email (to a list) whenever a change is made to an issue.
> > This is vital functionality, of course.  You can read email to
> > follow what's going on with bugs, then visit the web forms only
> > when you need to make a comment or whatever.
> > 
> > (Of course, taking input via email would be even nicer.)
> 
> It's critical, IMO -- my experience of using mozilla and savannah's
> bug tracker is that the annoyance of having to go to the web site
> and muddle through the forms significantly decreased the likelihood
> that I would bother (it was fine the first N times, but after a
> while I started to dread it).

Agreed.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Bug tracking

[Juanma Barranquero]

On Sat, 12 Jun 2004 23:34:52 -0400, Miles Bader <miles@gnu.org> wrote:

> Indeed for the original bug submission, it helps to be able to search the
> database, but it's not necessary to use the web to do that (even though you
> might want to use an http/html-based interface of some sort for maximum
> firewall transparency) -- see debian's bug system for an example of a system
> that does most of the work on the client, but also uses a network
> database-access protocol of some sort to allow the user to look for old bugs
> (it doesn't a perfect interface; something emacs based would likely be much
> better).

I think we agree that, with Emacs, a better system could be done (if not
in absolute terms, definitely better for Emacs-using developers tracking
Emacs-using users :)

Where we differ is, these Emacs-based systems do not exist.  We don't
have a project or a group of people set to create one, we don't have, as
far as I can see, even one developer with the time or the inclination to
create it.  Other systems are less perfect, but the quality of already
existing weights a lot.

> Purely web-based systems are non-starter.

Here, I agree with Karl: we don't have an issue tracker.  How could
having one, even if web-based, be a non-starter?  Nobody's forced to use
it.

                                                           /L/e/k/t/u

Re: Bug tracking

[Kai Grossjohann]

Richard Stallman <rms@gnu.org> writes:

> We're not planning to use this to track individual bugs,

Why not?  I thought the discussion was about putting things reported
by M-x report-emacs-bug RET into a database?  (The word database is
to be understood in the broadest possible sense, so that a text file
is also encompassed.)

The mailing list bug-gnu-emacs is nice, but it doesn't provide a list
of open issues, it doesn't provide a way to get a list of bugs that
are being worked on by somebody, and so on.

Kai

Re: Bug tracking (was: new *Help* argument highlighting)

[Jason Rumney]

Miles Bader <miles@gnu.org> writes:

>> Please, let's not aim for perfection, that way lies madness.
>
> I agree, but I'm not suggesting that, merely trying to establish some
> minimal standards.  Purely web-based systems are non-starter.

With the url library now part of Emacs, I think even a web-based
system could be made usable. It just requires a volunteer to write a
mode for using it from within Emacs.  It would be nice to have a
gateway to/from the bug mailing lists, but that would probably involve
more work for sysadmins, so we could come up with some elisp functions
that a few volunteers could use to enter bug reports from the mailing
lists and handle replies from people like RMS who are not always
online when they are dealing with bugs, so anything other than email
is unusable.

As for concerns about the GNU sysadmins having to maintain extra
software, there is already a bug tracker on savannah which other
projects are using. It is disabled for Emacs because users were being
misled into reporting bugs there but the developers never used it.

Re: Bug tracking

[Miles Bader]

On Sun, Jun 13, 2004 at 01:31:55PM +0200, Juanma Barranquero wrote:
> > Purely web-based systems are non-starter.
> 
> Here, I agree with Karl: we don't have an issue tracker.  How could having
> one, even if web-based, be a non-starter?

Well obviously it's not a comparison against zero; people have always managed
somehow, via files in the source tree, or mailing lists, or whatever.

These ad-hoc systems may not be all that great -- but they may very well be
better than something like what savannah offers.

> Nobody's forced to use it.

Sure, use whatever you want.

-Miles
-- 
"Unless there are slaves to do the ugly, horrible, uninteresting work, culture
and contemplation become almost impossible. Human slavery is wrong, insecure,
and demoralizing.  On mechanical slavery, on the slavery of the machine, the
future of the world depends." -Oscar Wilde, "The Soul of Man Under Socialism"

Re: Bug tracking (was: new *Help* argument highlighting)

[Robert J. Chassell]

   > (Of course, taking input via email would be even nicer.)

   It's critical, IMO -- my experience of using mozilla and savannah's bug
   tracker is that the annoyance of having to go to the web site and muddle
   through the forms significantly decreased the likelihood that I would bother
   (it was fine the first N times, but after a while I started to dread it).

Miles is right.  Please, always consider the person who is connecting
over a slow and unreliable connection.  Normally, I do not connect too
slowly -- right now I am at 26400 baud -- but sometimes my connections
are bad.  Other people suffer the same way.

Of course, my sister has fast and pretty reliable connection.  When I
visit her, I tend to forget all the annoyances of slow, unreliable,
expensive, or non-existent connections..... :)

    Note that filing bugs by email significantly increases the
    likelihood of duplicate issues.

Yes, that will happen.  You either exclude some people, like Miles and
RMS, or you deal with duplicates.

    ... So if some Emacs developers start using a web-based system,
    and you decide not to, we're all still better off in absolute
    terms than we are now, right?

No, that does not follow.  People outside the web-based system may end
up doing less, because they become afraid that their work will
duplicate others and they do not want to waste their time.

-- 
    Robert J. Chassell                         Rattlesnake Enterprises
    As I slowly update it,                     bob@rattlesnake.com
        I rewrite a "What's New" segment for   http://www.rattlesnake.com

Re: Bug tracking

[Oliver Scholz]

Miles Bader <miles@gnu.org> writes:

> On Sat, Jun 12, 2004 at 03:03:25PM -0500, Karl Fogel wrote:
[...]
>> (Of course, taking input via email would be even nicer.)
>
> It's critical, IMO -- my experience of using mozilla and savannah's bug
> tracker is that the annoyance of having to go to the web site and muddle
> through the forms significantly decreased the likelihood that I would bother
> (it was fine the first N times, but after a while I started to dread it).

Please bear with my ignorance, if I happen to say something stupid;
but couldn't just Emacs talk to the bug tracking system directly so
that a user has no need to start a browser? I imagine that this would
be less annoying. Of course this would require Emacs being able to do
http. (ISTR that there was talk about adding url to Emacs. Anyways
there is a simple package for http posts out there, written by Alex
Schröder IIRC.)

I envision something like this:

(defun example-report-emacs-bug ()
  (interactive)
  (switch-to-buffer (generate-new-buffer "*Emacs Bug Report*"))
  (let ((widgets nil))
    (widget-insert
     "Bug Report\n\nBla ... blub ...\n\n"
     (make-string fill-column ?-)
     "\n")
    (push
     (widget-create 'editable-field
		    :tag "Your mail address"
		    :format "%t: %v"
		    :size 40
		    :value user-mail-address
		    :value-to-external
		    (lambda (wid val)
		      (format "<email>%s</email>" val)))
     widgets)
    (widget-insert "\n\n")
    (push
     (widget-create 'text
		    :format "%t\n%v"
		    :tag "Please describe the symptoms of the bug"
		    :value "\n\n\n\n"
		    :value-to-external
		    (lambda (wid val)
		      (format "<descr>\n%s\n</descr>" val)))
     widgets)
    (widget-insert "\n\n")
    (widget-create 'push-button
		   :tag "Submit Bug Report"
		   :notify `(lambda (&rest ignore)
			      (example-submit-emacs-bug
			       ',(nreverse widgets))))
    (widget-insert
     "\n\n"
     (make-string fill-column ?-)
     "\n\n
By default Emacs will try to post this bug report via http to 
http://savannah.gnu.org/lirum/larum. If you want to send it via
e-mail instead, please activate the check box below.\n\n")
    (widget-create 'checkbox
		   :tag "Send as e-mail"
		   :format "%v %t")
    (widget-insert
     "\n\nEmacs will also send the information about your environment
\(below you can see which information exactly). If you do not want
this, please activate the check box below.\n\n")
    (widget-create 'checkbox
		   :format "%v %t"
		   :tag "Do not send information about my environment")
    (widget-insert "\n\n"
		   (make-string fill-column ?-)
		   "\n\n... display the information to be sent here ...")
    (use-local-map widget-keymap)
    (widget-setup)))
  
(defun example-submit-emacs-bug (widgets)
  (pop-to-buffer (generate-new-buffer "*example*"))
  (insert (format "<bug-report>\n%s\n</bug-report>"
		  (mapconcat 'widget-value widgets "\n"))))


    Oliver
-- 
Oliver Scholz               26 Prairial an 212 de la Révolution
Taunusstr. 25               Liberté, Egalité, Fraternité!
60329 Frankfurt a. M.       http://www.jungdemokratenhessen.de
Tel. (069) 97 40 99 42      http://www.jdjl.org

Re: Bug tracking

[Juanma Barranquero]

On Sun, 13 Jun 2004 13:55:54 +0200, Kai Grossjohann <kai@emptydomain.de> wrote:

> Why not?  I thought the discussion was about putting things reported
> by M-x report-emacs-bug RET into a database?

When I started the thread, I was talking mainly about exactly *that*;
it's more difficult to manage open bugs that ideas for new developments
or things to finish (etc/TODO could be used for that, even if it isn't
right now).

> The mailing list bug-gnu-emacs is nice, but it doesn't provide a list
> of open issues, it doesn't provide a way to get a list of bugs that
> are being worked on by somebody, and so on.

In other words: it doesn't help in managing open issues.  I fully agree.

                                                           /L/e/k/t/u

Re: Bug tracking (was: new *Help* argument highlighting)

[Karl Fogel]

"Robert J. Chassell" <bob@rattlesnake.com> writes:
> No, that does not follow.  People outside the web-based system may end
> up doing less, because they become afraid that their work will
> duplicate others and they do not want to waste their time.

Why would those people not worry that their efforts are duplicated
right now?

Re: Bug tracking

[Juanma Barranquero]

On Sun, 13 Jun 2004 09:28:46 -0400, Miles Bader <miles@gnu.org> wrote:

> Well obviously it's not a comparison against zero; people have always managed
> somehow, via files in the source tree, or mailing lists, or whatever.

Sure, you're right.  But my bringing this whole issue is because I feel we
manage, but we don't have information enough.  Perhaps bugs would be
better squashed if people were more conscious about how many have been
reported, their severity, and their status.

> These ad-hoc systems may not be all that great -- but they may very well be
> better than something like what savannah offers.

OK.  But what Savannah offers is not the only option (I hope).

                                                           /L/e/k/t/u

Re: Bug tracking

[Juri Linkov]

Juanma Barranquero <lektu@mi.madritel.es> writes:
> What I meant is that we're bound to reproduce, in text files and
> elisp modules, an issue tracker.

Why _bound to reproduce_?  Let's put it another way: we are
_motivated to create_ an Emacs-based issue tracker.  And once
we implement it, even other projects might benefit from that.

As for a web interface, I think it is not an absolute requirement,
and even often undesirable, since a better method for filing bugs
is `report-emacs-bug' which also adds all the necessary information
and doesn't require from Emacs users additional tools.

Though, a some kind of an add-on HTTP<->CVS gateway could be
implemented to sync data between Savannah bug database and text
files in CVS repository, if that becomes absolutely necessary.

-- 
Juri Linkov
http://www.jurta.org/emacs/

Re: Bug tracking

[Juri Linkov]

Juanma Barranquero <lektu@mi.madritel.es> writes:
> When I started the thread, I was talking mainly about exactly *that*;
> it's more difficult to manage open bugs that ideas for new developments
> or things to finish

I agree.  It's a pity so many bug reports are already lost in
bug-gnu-emacs archives without being registered and categorized
by their severity and status.

> (etc/TODO could be used for that, even if it isn't right now).

As I see it, the purpose of etc/TODO is to manage ideas rather
than open bugs.  Open bugs could be placed to a separate file.

So a set of database text files might contain only four files:

etc/BUGS
etc/TODO
etc/DONE
etc/NEWS

That's all that's needed for the simplest issue tracker.

Another question is how to add new bug reports to the BUGS file.
I think this is the task of Emacs developers to register bug
reports from bug-gnu-emacs in the BUGS file, because usually
Emacs users who report bugs on bug-gnu-emacs can't assign right
categories and severity levels to reported bugs.

-- 
Juri Linkov
http://www.jurta.org/emacs/

Re: Bug tracking

[Richard Stallman]

I will not agree to use of a system that is hard for me to access, so
we simply can't use the systems you have in mind.  Please accept that
decision.  We will use a text file that I can access with CVS.

The number of issues we want to record should not be as much as 50.

    It doesn't have a web interface for other people,

It is not important for anyone to see this file except the Emcs
developers, who will be looking for jobs they can work on to help make
the release happen.

						      no automatic way to
    extract statistics,

The purpose of this database is to keep track of jobs that need to be
done, for the release.  We don't need statistics.  They all will
need to be done.

			it's *clumsy* beyond belief if you want to also
    store past (and fixed or rejected) issues,

We can put the past issues into a DONE file in case anyone wants to
look back at them.

I don't know what you mean by "rejected" issues.  If we don't believe
a job needs to be done for the release, we won't ever put it in this
file.

Perhaps you are envisioning a bug tracking system.  That's not what
this we're trying to do here.

					       has to be manually edited by
    us so outside people cannot enter issues,

Only Emacs maintainers should edit this file.  Outsiders cannot decide
what jobs we need to do before the release, or mark them as done.

					      needs that someone reads
    gnu-emacs-bugs@ reports and formats them as desired,

That will be necessary no matter how we store the file.  Only humans
can decide what should go in the file.  It cannot be done
automatically.

							 it has limited
    posibilities for searching and categorizing...

We should not have so many items in the file that this becomes a
significant issue.

Re: Bug tracking

[Kim F. Storm]

Richard Stallman <rms@gnu.org> writes:

>     IMO database functionality is needed. I should be easy to select items 
>     having to do with a particular
> 	module/issuer/maintainer/priority/version of Emacs/OS
> 
> It is easy enough to search a file.  If this gets to be large,
> something is wrong.  We're not planning to use this to track
> individual bugs, and aside from individual bugs, the number of issues
> cannot be too large.

You lost me there -- how do we track individual bugs then?

I'm sick and tired of having +100 mails and usenet articles that are
constantly marked unread because I might have to look at them -- if
nobody else does that.

To be useful, a bug tracker must record all bugs -- trivial and non-trivial
for the purpose of knowing who (if any) is looking into each of those bugs.

And as a repository of things to look at when we have time.


The interface to the system is less important -- but I don't really
see how you can use a central tracker database if you are off-line 
most of the time.

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

Re: Bug tracking

[Juanma Barranquero]

On Sun, 13 Jun 2004 19:00:47 +0300, Juri Linkov <juri@jurta.org> wrote:

> Why _bound to reproduce_?

??

Because (IMHO) we need the functionality of an issue tracker, and we
don't have it implemented.


> Let's put it another way: we are
> _motivated to create_ an Emacs-based issue tracker.

No.  Perhaps you're motivated to create an Emacs-based issue tracker. 
I'm just motivated to *use* an issue tracker, because I think quality
would improve.  I have not a single bit of interest in developing or
helping to develop Yet Another Issue Tracker, and less so because there
are quite a few free ones to pick from.

> As for a web interface, I think it is not an absolute requirement,
> and even often undesirable, since a better method for filing bugs
> is `report-emacs-bug' which also adds all the necessary information
> and doesn't require from Emacs users additional tools.

I think we had already implicitly agreed to disagree on this one...
Every program has a context.  That doesn't mean that the users who take
the trouble to file a bug report are unable to provide that information. 
report-emacs-bug is great, and if it can be integrated with an IT,
wonderful.  But surely is not a precondition.

> Though, a some kind of an add-on HTTP<->CVS gateway could be
> implemented to sync data between Savannah bug database and text
> files in CVS repository, if that becomes absolutely necessary.

"Could be implemented".  Yeah.

                                                           /L/e/k/t/u

Re: Bug tracking

[Juanma Barranquero]

On Sun, 13 Jun 2004 17:49:32 -0400, Richard Stallman <rms@gnu.org> wrote:

> I will not agree to use of a system that is hard for me to access, so
> we simply can't use the systems you have in mind.

I don't have specific systems in mind.  I've seen one or two that could
be useful (Mantis, for example), because they seem easy.  But I'm not
married to any one answer.

> The number of issues we want to record should not be as much as 50.

You and I are talking about different things.  I brought this up with
regards to issues unfinished, from a release POV.  I'm not sure what you
include in that category: documentation to write, unfinished features,
etc.  But I certainly include in it bug reports, so I cannot put a limit
on "the issues I want to record" of 50 or 100 or any other number.

> The purpose of this database is to keep track of jobs that need to be
> done, for the release.  We don't need statistics.  They all will
> need to be done.

[...]

> We can put the past issues into a DONE file in case anyone wants to
> look back at them.
> 
> I don't know what you mean by "rejected" issues.  If we don't believe
> a job needs to be done for the release, we won't ever put it in this
> file.

I was talking about rejected bug reports, of course.  The ones that are
determined not to be a bug after all.

> Perhaps you are envisioning a bug tracking system.  That's not what
> this we're trying to do here.

Richard, excuse me, but till three days ago, no one was "trying to do"
anything on this matter (in general; of course each one of us has their
particular TODO).  What you now want to do is clear, and what I'm
interested in doing is too, and they aren't the same thing.  I accept
the decision, as you said; i.e., if you create an etc/ISSUES and put in
it things to do, I'll use it.  But this has *nothing* to do with having
or not having a bug/issue tracker.  You're talking of a planner of sorts.

                                                           /L/e/k/t/u

Re: Bug tracking (was: new *Help* argument highlighting)

[Robert J. Chassell]

   "Robert J. Chassell" <bob@rattlesnake.com> writes:
   > No, that does not follow.  People outside the web-based system may end
   > up doing less, because they become afraid that their work will
   > duplicate others and they do not want to waste their time.

kfogel@red-bean.com asked

   Why would those people not worry that their efforts are duplicated
   right now?

Because right now people expect to make duplicate reports, and then,
usually, only one person works on the problem.  When reporting and
fixing are combined in a `fast' group, then those in the `slow' group
may not bother either to report or to volunteer to do something.

-- 
    Robert J. Chassell                         Rattlesnake Enterprises
    As I slowly update it,                     bob@rattlesnake.com
        I rewrite a "What's New" segment for   http://www.rattlesnake.com

Re: Bug tracking

[Miles Bader]

On Mon, Jun 14, 2004 at 12:26:27AM +0200, Kim F. Storm wrote:
> The interface to the system is less important -- but I don't really
> see how you can use a central tracker database if you are off-line 
> most of the time.

It's not important to have an exact to-the-minute copy of the database
(because the rate of change is slow, and conflicts tend not to be critical),
so any solution that allows easy occasional synchronization would be good
enough (and with an email-based system, the synchronization can be one-way --
modification commands typically will get queued with other outgoing email).

-Miles
-- 
80% of success is just showing up.  --Woody Allen

Re: Bug tracking

[Miles Bader]

On Mon, Jun 14, 2004 at 12:52:01AM +0200, Juanma Barranquero wrote:
> Every program has a context.  That doesn't mean that the users who take
> the trouble to file a bug report are unable to provide that information. 
> report-emacs-bug is great, and if it can be integrated with an IT,
> wonderful.  But surely is not a precondition.

Most users are _lazy_ -- if reporting a bug entails a lot of extra work,
they'll either give up reporting the bug, or they'll just omit all the info
(if the interface allows it).

-Miles
-- 
"Whatever you do will be insignificant, but it is very important that
 you do it."  Mahatma Ghandi

Re: Bug tracking

[Juanma Barranquero]

On Sun, 13 Jun 2004 19:56:13 -0400
Miles Bader <miles@gnu.org> wrote:

> Most users are _lazy_ -- if reporting a bug entails a lot of extra work,
> they'll either give up reporting the bug, or they'll just omit all the info
> (if the interface allows it).

Well, two points:

 - Report quality must be not so bad, after all, when many projects use
   IT.  As users usually have to register with an e-mail, interested
   developers can always ask for more info.  That happens right now,
   even with the context information of M-x report-emacs-bug.

 - Certainly, if we are able to use an IT where M-x report-emacs-bug
   creates a report (via de url package or whatever) that'd be great. 
   Nobody's proposing dispensing with this interface.

                                                                Juanma

Re: Bug tracking

[Juanma Barranquero]

On Mon, 14 Jun 2004 09:20:49 +0200
Juanma Barranquero <jmbarranquero@wke.es> wrote:

> via de url package
      ^^
That's a phonetic typo.  Funny.

                                                                Juanma

Re: Bug tracking

[Kim F. Storm]

Juri Linkov <juri@jurta.org> writes:

> Lars Hansen <larsh@math.ku.dk> writes:
> > IMO database functionality is needed. I should be easy to select items
> > having to do with a particular
> >     module/issuer/maintainer/priority/version of Emacs/OS
> > and possibly other. Of course that can be done with a text file, but
> > is there existing (Emacs lisp) code that can do it?
> 
> Yes, there is existing Emacs Lisp code (but obviously I am biased).
> It is Ee information manager which displays data from text files
> in category trees and allows to operate on displayed data:
> expand/collapse categories, edit data fields, etc.  It's possible
> to create different views for every data file.  Here is an
> example http://www.jurta.org/emacs/ee/data/todo.en.html
> how a possible issue tracker might look.

There is also ewoc.el already included in emacs, which might be useful
as the basis of a simple emacs bug tracker interface.

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

Re: Bug tracking

[Juri Linkov]

storm@cua.dk (Kim F. Storm) writes:
> Juri Linkov <juri@jurta.org> writes:
>> Yes, there is existing Emacs Lisp code (but obviously I am biased).
>> It is Ee information manager which displays data from text files
>> in category trees and allows to operate on displayed data:
>> expand/collapse categories, edit data fields, etc.  It's possible
>> to create different views for every data file.  Here is an
>> example http://www.jurta.org/emacs/ee/data/todo.en.html
>> how a possible issue tracker might look.
>
> There is also ewoc.el already included in emacs, which might be useful
> as the basis of a simple emacs bug tracker interface.

Thanks for the information.  It seems ewoc.el might be useful as
a data-view connection between a buffer with BUGS text file and
categorized views displayed by Ee.

However, I think we should start with creating a simple mode
to support editing BUGS text files: fontification and completion of
data fields, adding new records from templates, moving existing
records, etc. with all these operations performed on a file buffer.
And later to add other packages to display statistics, summaries,
categorized views and other such additional features in a separate
view buffer.

-- 
Juri Linkov
http://www.jurta.org/emacs/

Re: Bug tracking

[Juanma Barranquero]

On Mon, 14 Jun 2004 18:09:34 +0300
Juri Linkov <juri@jurta.org> wrote:

> It seems ewoc.el might be useful as
> a data-view connection between a buffer with BUGS text file and
> categorized views displayed by Ee.

Ee is composed of 65 files, 27 of them elisp modules.  It is mature
enough, and generally useful enough, to accept it as a prerequisite for
a issue tracker on elisp?

                                                                Juanma

Re: Bug tracking

[Juri Linkov]

Juanma Barranquero <jmbarranquero@wke.es> writes:
> On Mon, 14 Jun 2004 18:09:34 +0300
> Juri Linkov <juri@jurta.org> wrote:
>> It seems ewoc.el might be useful as
>> a data-view connection between a buffer with BUGS text file and
>> categorized views displayed by Ee.
>
> Ee is composed of 65 files, 27 of them elisp modules.  It is mature
> enough, and generally useful enough, to accept it as a prerequisite for
> a issue tracker on elisp?

It is quite mature: there were no serious problems found for a year.
As for usefulness, I believe it is useful due to its general and simple
interface for presenting data by views with hierarchical categories.

However, I wouldn't say that it should be a prerequisite for managing
bug reports and TODO items in Emacs.  I think they should be editable
as normal text files (though, in a predefined format) without requiring
additional packages.

Issue trackers could be implemented on top of text files as a tool
to display data in different views (with all additional nice features
like statistics, categorizing, etc. that existing issue trackers have)
instead of default flat text.

-- 
Juri Linkov
http://www.jurta.org/emacs/

Re: Bug tracking

[Thien-Thi Nguyen]

Juanma Barranquero <jmbarranquero@wke.es> writes:

      Nobody's proposing dispensing with this interface.

the user interface can be anything but if the data representation is
more complicated than mbox, that's a step away from the shoulders of
giants, etc.

mbox (specifically mime) is tagged and recursive.  it is in use already
by other tracking systems.  general tools to manipulate mbox files are
everywhere.  these add up to a huge hint to the would-be designer of
systems that need to store tagged and recursive data.  not understanding
this hint means the first batch of bugs will be about the bug tracking
system itself, and that batch may be large, and mostly uninteresting.

i think if you separate the user interface question from the data
representation question, you will receive less static.

thi

Re: Bug tracking

[Richard Stallman]

    > We're not planning to use this to track individual bugs,

    Why not?  I thought the discussion was about putting things reported
    by M-x report-emacs-bug RET into a database?

No, this discussion is about tracking issues that need to be
resolved before the release.  Here is the message that raised this
question:

    Still, the question remains: should we use some kind of issue tracker?

    Currently we have an etc/TODO, which is sort of half wish list, half
    grab bag of heterogeneous items.  I'm all for using an issue tracker, if
    only because it makes easier to know where we are, release-wise, for any
    given release.  For example, what's precluding us from doing a
    prerelease tarball just today (not that I'm proposing it, of course)?

The answer to this question is not a list of bug reports; this job is
not bug tracking.

Tracking issues cannot mean bug tracking, because only something
important qualifies as an "issue".  A mere bug report is not (usually)
an issue.  On some occasions a certain bug report might be important
enough to be an issue, but only the Emacs developers can decide when
that is so.  Only the developers can enter issues, and it makes no
sense to have a large number of issues.

A text file is the perfect way to keep track of issues.

Bug tracking might be useful, but it is a completely different
subject.  If we use a bug-tracker, it should be easy to use via email
and cvs.

Re: Bug tracking

[Richard Stallman]

    Please bear with my ignorance, if I happen to say something stupid;
    but couldn't just Emacs talk to the bug tracking system directly so
    that a user has no need to start a browser?

This does not solve the problem.  The problem is that a web-based
system requires a net connection.  Using Emacs as the client rather
than an ordinary browser might indeed be an improvement in such systems
but it won't help those who have no net connection--such as me.

I have decided that for tracking issues we should use a text file,
not a complex system, and certainly not something web-based.

Re: Bug tracking (was: new *Help* argument highlighting)

[Richard Stallman]

    > I said a while back that IMHO we should be a more structured project, in
    > the sense of having a plan for releases, with tentative dates, perhaps
    > even a release manager, etc.

Thanks for the suggestion, but I do not like the idea of going that
way.

    (I think over time you would find yourself using
    it too, though, as using it is often more efficient than avoiding it.)

If you think that I could "find myself" using a web-based system, you
must not understand the difficulty.  If it is web based, I can't
access it.  There is little chance I will "find myself" having a net
connection more of the time.

That is the reason for my decision that we will not use a web-based
system to hold data about Emacs development.

Please consider the decision final; let's not keep discussing the
matter.

Re: Bug tracking (was: new *Help* argument highlighting)

[Karl Fogel]

Richard Stallman <rms@gnu.org> writes:
> That is the reason for my decision that we will not use a web-based
> system to hold data about Emacs development.

[Note: I'm talking about a bug tracker now.]

Would it be okay to have a system where the bug "database" (which
might be some sort of structured text file) is stored in the CVS tree,
and the interface to the database is via Emacs itself?

(This wouldn't include email access... But on the other hand many of
us read email in Emacs anyway, so manually integrating information
from email into that database wouldn't be so hard.)

Would such a system meet your constraints?

-Karl

Re: Bug tracking

[Tak Ota]

Isn't there a system that supports both UUCP like batch email service
as well as web-based service?  I am not a strong advocate of either
system but your comments do not sound forward-looking but anachronism.

Who knows, we may run emacs on a cell phone someday.  I am awfully
impressed by the advancement of today's technology.  I can compile and
run the latest emacs on a MIPS in my target embedded system while I
had to run a fastest workstation for several hours to compile emacs
which was much smaller than today. That was 15 years ago.

-Tak

Mon, 14 Jun 2004 14:50:16 -0400: Richard Stallman <rms@gnu.org> wrote:

>     Please bear with my ignorance, if I happen to say something stupid;
>     but couldn't just Emacs talk to the bug tracking system directly so
>     that a user has no need to start a browser?
> 
> This does not solve the problem.  The problem is that a web-based
> system requires a net connection.  Using Emacs as the client rather
> than an ordinary browser might indeed be an improvement in such systems
> but it won't help those who have no net connection--such as me.
> 
> I have decided that for tracking issues we should use a text file,
> not a complex system, and certainly not something web-based.
> 
> 
> 
> _______________________________________________
> Emacs-devel mailing list
> Emacs-devel@gnu.org
> http://lists.gnu.org/mailman/listinfo/emacs-devel

Re: Bug tracking

[Juanma Barranquero]

On 14 Jun 2004 12:40:43 -0400, Thien-Thi Nguyen <ttn@glug.org> wrote:

> i think if you separate the user interface question from the data
> representation question, you will receive less static.

You lost me there.  My primary interest is user interface, which is what
makes or breaks the success of a bug tracker.  Users must be able to
enter bug reports easily, and developers must be able to see what's done
and what's waiting, who's doing what, etc. also easily  Whether the data
is in cuneiform tablets or tachyonic particles oscillating between
alternate universes is an implementation detail. (Which doesn't mean all
representations are equivalent, obviously).

But in fact, and contrarily to many things heard in this thead, I'm
specifically proposing to develop *nothing* (or at least, almost nothing),
so data representation is an issue for the software already existing out
there, not for me.  I'm hearing about using text files and developing
modes to manage and display that information, and I wonder, who's going
to implement it?  Because I know I'm not (although I will use whatever
we have, if someone invests the effort in developing it).

First, though, we'd have to answer whether we want a bug tracker (as I
proposed), a pending-and-future-issues planner (as I think Richard wants),
both or none.  Personally I find little use in the planner, a text file
(with no custom elisp development) is fine.  But a bug tracker, oh yes,
I strongly think this would be good for the project.

                                                           /L/e/k/t/u

Re: Bug tracking

[Juanma Barranquero]

On Mon, 14 Jun 2004 14:50:05 -0400, Richard Stallman <rms@gnu.org> wrote:

> No, this discussion is about tracking issues that need to be
> resolved before the release.  Here is the message that raised this
> question:

Put that on English not being my native language.  I was thinking (and
referring, at least on my mind :) to both things.

> A text file is the perfect way to keep track of issues.

On that, I agree.

> Bug tracking might be useful, but it is a completely different
> subject.  If we use a bug-tracker, it should be easy to use via email
> and cvs.

Via CVS?  That meaning?

                                                           /L/e/k/t/u

Re: Bug tracking

[Kim F. Storm]

Juanma Barranquero <lektu@mi.madritel.es> writes:

> On Mon, 14 Jun 2004 14:50:05 -0400, Richard Stallman <rms@gnu.org> wrote:
> 
> > No, this discussion is about tracking issues that need to be
> > resolved before the release.  Here is the message that raised this
> > question:
> 
> Put that on English not being my native language.  I was thinking (and
> referring, at least on my mind :) to both things.
> 
> > A text file is the perfect way to keep track of issues.
> 
> On that, I agree.
> 
> > Bug tracking might be useful, but it is a completely different
> > subject.  If we use a bug-tracker, it should be easy to use via email
> > and cvs.
> 
> Via CVS?  That meaning?


We could start small and simple:

Create an emacs/tracker subdirectory and create text files 1.bug, 2.bug, etc.
with one file for each bug.

Then add a simple header to the file, initially just:

,-------------------------------------
| Subject: Title of this bug
| From: Name and email of original reporter of the bug
| Date: Date created
| Modified: Date last modified
| Status: empty | user name of developer (when assigned) | DELAY | REJECT | DONE
| Priority: RELEASE | FATAL | HIGH | NORMAL | LOW | ...
| Cc: List of email addresses to be notified when tracker is updated
| [empty line]
| Free format text about the bug
`-------------------------------------

Priority = RELEASE means that issue must be resolved before next release.
Priotity = FATAL means this bug makes emacs crash.

Then we can create fairly simple commands like bug-tracker-create
which creates an empty bug tracker, and bug-tracker-commit (bound to
C-c C-c) which checks it into cvs (automatically updating the Modified
date).

We can also make bug-tracker-create-from-message which will take
a mail or news message (in the current buffer) and create a tracker
for it by:

a) select the next unused number in tracker
b) write header + body to that tracker file tracker/N.bug
c) do cvs add + cvs commit on that file

As we progress, we can add more commands that can list, summarize,
search, update those trackers, etc. all with proper interfacing to cvs
(including committing changes at a later time if currently off-line).

The basic idea is that all trackers are recorded as simple text
(mbox-like) files in CVS.

Updates to the trackers will then automatically be mailed to anyone
subscribing to the emacs-diffs mailing list.

Such a system could be written in a couple of hours initially, and expanded
gradually as we find the time and need...  

BTW, progress about the bug can also be recorded in the cvs log, e.g.
changes to Status field.

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

Re: Bug tracking

[Miles Bader]

On Tue, Jun 15, 2004 at 01:09:38AM +0200, Kim F. Storm wrote:
> We could start small and simple:
> 
> Create an emacs/tracker subdirectory and create text files 1.bug, 2.bug, etc.
> with one file for each bug.
> 
> Then add a simple header to the file, initially just:

Please look at the link I posted earlier about Andrew Suffield's bug system
which covers many of these issues (it's an email-based system).  I don't know
that we could use his system unchanged, but it might be nice to have at least
a bit of consistency of format or something.

I think the link is:  http://bugs.gnuarch.org

[and then select some link below about explanation]

-Miles
-- 
80% of success is just showing up.  --Woody Allen

Re: Bug tracking

[Thien-Thi Nguyen]

   From: Juanma Barranquero <lektu@mi.madritel.es>
   Date: Mon, 14 Jun 2004 23:36:56 +0200

   You lost me there.  My primary interest is user interface,
   which is what makes or breaks the success of a bug tracker.
   Users must be able to enter bug reports easily, and developers
   must be able to see what's done and what's waiting, who's doing
   what, etc. also easily.  Whether the data is in cuneiform
   tablets or tachyonic particles oscillating between alternate
   universes is an implementation detail.

a system designer might say the user interface is also an
implementation detail (anything but the block diagram could be
considered so).  my primary interest is in emulating the thought
patterns of (good) system designers.

   But in fact, and contrarily to many things heard in this thead,
   I'm specifically proposing to develop *nothing* (or at least,
   almost nothing), so data representation is an issue for the
   software already existing out there, not for me.  I'm hearing
   about using text files and developing modes to manage and
   display that information, and I wonder, who's going to
   implement it?  Because I know I'm not (although I will use
   whatever we have, if someone invests the effort in developing
   it).

if the design is clean and approachable, the implementation will
tend to happen w/o too much pushing.  i was hoping you would
propose an abstract-ish design in the form of a big block diagram,
taking into consideration the wide-ranging requirements mentioned
thus far, that we could clean up and post somewhere.  the major
effort is in conceiving the big block diagram, IMHO; code will
follow, naturally.

   First, though, we'd have to answer whether we want a bug
   tracker (as I proposed), a pending-and-future-issues planner
   (as I think Richard wants), both or none.  Personally I find
   little use in the planner, a text file (with no custom elisp
   development) is fine.  But a bug tracker, oh yes, I strongly
   think this would be good for the project.

perhaps these are specializations that can be deferred?

thi

Re: Bug tracking

[Kim F. Storm]

Miles Bader <miles@gnu.org> writes:

> On Tue, Jun 15, 2004 at 01:09:38AM +0200, Kim F. Storm wrote:
> > We could start small and simple:
> > 
> > Create an emacs/tracker subdirectory and create text files 1.bug, 2.bug, etc.
> > with one file for each bug.
> > 
> > Then add a simple header to the file, initially just:
> 
> Please look at the link I posted earlier about Andrew Suffield's bug system
> which covers many of these issues (it's an email-based system).  I don't know
> that we could use his system unchanged, but it might be nice to have at least
> a bit of consistency of format or something.

Sure, but I don't want to go ahead an implement this before
we get some sort of consensus on the topic.


So the question is:

Would the proposed "trackers in cvs" + "emacs frontent" (with no email
interface) be sufficient for you and others who have voiced a strong
rejection of web based trackers?

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

Re: Bug tracking

[Juanma Barranquero]

On Tue, 15 Jun 2004 03:36:37 +0200
Thien-Thi Nguyen <ttn@surf.glug.org> wrote:

> i was hoping you would
> propose an abstract-ish design in the form of a big block diagram,
> taking into consideration the wide-ranging requirements mentioned
> thus far, that we could clean up and post somewhere.

No.

There are people here with ideas about how to do it inside an Emacs
framework.  Let's hear them (assuming they want to design such a thing).

> perhaps these are specializations that can be deferred?

You're, IMHO, overgeneralizing.  I'm not interested (in this context) in
reusable, high-level, well-designed, pattern-chocked systems to resolve
general data classification problems.  I just wanted a simple bug
tracker to, you know, track bugs...

                                                                Juanma

Re: Bug tracking

[Richard Stallman]

    Isn't there a system that supports both UUCP like batch email service
    as well as web-based service?  I am not a strong advocate of either
    system but your comments do not sound forward-looking but anachronism.

It is not my goal to be "forward-looking" for its own sake.  I made
this decision based on practicalities.

When you describe my decision to use low tech as an "anachronism",
that exaggeration means only a sneer at what is unfashionable.
That is unjust, so please don't do it here.

Re: Bug tracking

[Richard Stallman]

    > Bug tracking might be useful, but it is a completely different
    > subject.  If we use a bug-tracker, it should be easy to use via email
    > and cvs.

    Via CVS?  That meaning?

I mean that someone like me, who needs to use email and CVS,
should be able to use it with full effectiveness.

Re: Bug tracking (was: new *Help* argument highlighting)

[Richard Stallman]

    Would it be okay to have a system where the bug "database" (which
    might be some sort of structured text file) is stored in the CVS tree,
    and the interface to the database is via Emacs itself?

I am not sure whether this would be practical for me.
It depends on the size of the data.
I only sometimes have good enough connection that I can do
a cvs update on Emacs.  However, if the bulk of data is much smaller,
so I could update it in a couple of minutes on a phone line,
that would be practical everywhere.

Re: Bug tracking

[Tak Ota]

Wed, 16 Jun 2004 12:57:51 -0400: Richard Stallman <rms@gnu.org> wrote:

> It is not my goal to be "forward-looking" for its own sake.  I made
> this decision based on practicalities.

I understand this but what is practical is quite a subjective issue.
My understanding is that some people raised a question that current
emacs bug tracking mechanism was getting less practical than what was
available out there.

> When you describe my decision to use low tech as an "anachronism",
> that exaggeration means only a sneer at what is unfashionable.
> That is unjust, so please don't do it here.

I am sorry for it sounded as sneering to you.  I have no such
intention.  As network proliferate throughout the society emacs is
becoming net savvy too.  What I wanted to express was let us not go
against it but take advantage of it as long as people without net
connection are not sacrificed.  I do not care about a fashion but the
speed, accuracy, efficiency and convenience of the development.  What
I meant by "anachronism" was that let's not bound rest of the people
to the people who don't have network connection.

I regret I wrote that message.  I should have spent my time for
seeking a solution that I believe is right than writing that
message.  I apologize I wasted your time as well.

-Tak