ChangeLog fontifications

ChangeLog fontifications

[Sam Steingold]

GNU Emacs 21.3.50.1 (i386-msvc-nt5.0.2195)
 of 2004-05-10 on WINSTEINGOLDLAP
--with-msvc (12.00)

when ChangeLog records a change in a Common Lisp function with a
package prefix, only the package name is highlighted, not the function
name:

	* foo.lisp (PACK:FUNCTION-NAME): optimized frobnifications

"PACK" is highlighted but "FUNCTION-NAME" is not.

I am pretty sure that `change-log-font-lock-keywords' in add-log.el
needs to be fixed, but I am not quite sure how...

-- 
Sam Steingold (http://www.podval.org/~sds) running w2k
<http://www.camera.org> <http://www.iris.org.il> <http://www.memri.org/>
<http://www.mideasttruth.com/> <http://www.honestreporting.com>
Single tasking: Just Say No.

Re: ChangeLog fontifications

[Juri Linkov]

Sam Steingold <sds@gnu.org> writes:
> when ChangeLog records a change in a Common Lisp function with a
> package prefix, only the package name is highlighted, not the function
> name:
>
> 	* foo.lisp (PACK:FUNCTION-NAME): optimized frobnifications
>
> "PACK" is highlighted but "FUNCTION-NAME" is not.
>
> I am pretty sure that `change-log-font-lock-keywords' in add-log.el
> needs to be fixed, but I am not quite sure how...

I see no harm in removing : from regexps of function names.  I don't
understand why such restriction was added here, given the fact that
parentheses around a function name already pretty safely enclose it.

Index: lisp/add-log.el
===================================================================
RCS file: /cvsroot/emacs/emacs/lisp/add-log.el,v
retrieving revision 1.149
diff -u -r1.149 add-log.el
--- lisp/add-log.el	19 Apr 2004 11:31:05 -0000	1.149
+++ lisp/add-log.el	11 May 2004 17:57:14 -0000
@@ -230,13 +230,13 @@
      ;; Possibly further names in a list:
      ("\\=, \\([^ ,:([\n]+\\)" nil nil (1 'change-log-file-face))
      ;; Possibly a parenthesized list of names:
-     ("\\= (\\([^) ,:\n]+\\)" nil nil (1 'change-log-list-face))
-     ("\\=, *\\([^) ,:\n]+\\)" nil nil (1 'change-log-list-face)))
+     ("\\= (\\([^) ,\n]+\\)" nil nil (1 'change-log-list-face))
+     ("\\=, *\\([^) ,\n]+\\)" nil nil (1 'change-log-list-face)))
     ;;
     ;; Function or variable names.
-    ("^\t(\\([^) ,:\n]+\\)"
+    ("^\t(\\([^) ,\n]+\\)"
      (1 'change-log-list-face)
-     ("\\=, *\\([^) ,:\n]+\\)" nil nil (1 'change-log-list-face)))
+     ("\\=, *\\([^) ,\n]+\\)" nil nil (1 'change-log-list-face)))
     ;;
     ;; Conditionals.
     ("\\[!?\\([^]\n]+\\)\\]\\(:\\| (\\)" (1 'change-log-conditionals-face))

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

Re: ChangeLog fontifications

[Sam Steingold]

> * Juri Linkov <whev@whegn.bet> [2004-05-11 21:03:03 +0300]:
>
> Sam Steingold <sds@gnu.org> writes:
>> when ChangeLog records a change in a Common Lisp function with a
>> package prefix, only the package name is highlighted, not the function
>> name:
>>
>> 	* foo.lisp (PACK:FUNCTION-NAME): optimized frobnifications
>>
>> "PACK" is highlighted but "FUNCTION-NAME" is not.
>>
>> I am pretty sure that `change-log-font-lock-keywords' in add-log.el
>> needs to be fixed, but I am not quite sure how...
>
> I see no harm in removing : from regexps of function names.  I don't
> understand why such restriction was added here, given the fact that
> parentheses around a function name already pretty safely enclose it.
>
> Index: lisp/add-log.el
> ===================================================================
> RCS file: /cvsroot/emacs/emacs/lisp/add-log.el,v
> retrieving revision 1.149
> diff -u -r1.149 add-log.el
> --- lisp/add-log.el	19 Apr 2004 11:31:05 -0000	1.149
> +++ lisp/add-log.el	11 May 2004 17:57:14 -0000
> @@ -230,13 +230,13 @@
>       ;; Possibly further names in a list:
>       ("\\=, \\([^ ,:([\n]+\\)" nil nil (1 'change-log-file-face))
>       ;; Possibly a parenthesized list of names:
> -     ("\\= (\\([^) ,:\n]+\\)" nil nil (1 'change-log-list-face))
> -     ("\\=, *\\([^) ,:\n]+\\)" nil nil (1 'change-log-list-face)))
> +     ("\\= (\\([^) ,\n]+\\)" nil nil (1 'change-log-list-face))
> +     ("\\=, *\\([^) ,\n]+\\)" nil nil (1 'change-log-list-face)))
>      ;;
>      ;; Function or variable names.
> -    ("^\t(\\([^) ,:\n]+\\)"
> +    ("^\t(\\([^) ,\n]+\\)"
>       (1 'change-log-list-face)
> -     ("\\=, *\\([^) ,:\n]+\\)" nil nil (1 'change-log-list-face)))
> +     ("\\=, *\\([^) ,\n]+\\)" nil nil (1 'change-log-list-face)))
>      ;;
>      ;; Conditionals.
>      ("\\[!?\\([^]\n]+\\)\\]\\(:\\| (\\)" (1 'change-log-conditionals-face))

that's what I first tried too, but it did not appear to work...
oh - looks like I need to reload the ChangeLog file itself!  cool!
please check this in!

Now, multiline entries are also handled incorrectly:


	* foo.lisp (aasfasdfffffffffffffffffffffffffffffffff,
        sadfggggggggggggg): ...




-- 
Sam Steingold (http://www.podval.org/~sds) running w2k
<http://www.camera.org> <http://www.iris.org.il> <http://www.memri.org/>
<http://www.mideasttruth.com/> <http://www.honestreporting.com>
Why do we want intelligent terminals when there are so many stupid users?

Re: ChangeLog fontifications

[Miles Bader]

On Tue, May 11, 2004 at 06:54:36PM -0400, Sam Steingold wrote:
> Now, multiline entries are also handled incorrectly:
> 
> 	* foo.lisp (aasfasdfffffffffffffffffffffffffffffffff,
>         sadfggggggggggggg): ...

You should use a syntax like the following for such cases:

	* foo.lisp (aasfasdfffffffffffffffffffffffffffffffff)
        (sadfggggggggggggg): ...

[Not just for font-locking, but to make the job of any ChangeLog-parsing
program easier.]

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

Re: ChangeLog fontifications

[Werner LEMBERG]

> > Now, multiline entries are also handled incorrectly:
> > 
> > 	* foo.lisp (aasfasdfffffffffffffffffffffffffffffffff,
> >         sadfggggggggggggg): ...
> 
> You should use a syntax like the following for such cases:
> 
> 	* foo.lisp (aasfasdfffffffffffffffffffffffffffffffff)
>         (sadfggggggggggggg): ...

No, no, no.  This is really ugly.  Maybe easier to parse for a
computer -- not everything should look like Lisp code...


    Werner

Re: ChangeLog fontifications

[Miles Bader]

Werner LEMBERG <wl@gnu.org> writes:
> > 	* foo.lisp (aasfasdfffffffffffffffffffffffffffffffff)
> >         (sadfggggggggggggg): ...
> 
> No, no, no.  This is really ugly.  Maybe easier to parse for a
> computer -- not everything should look like Lisp code...

Sorry, that's the syntax.

I think it looks quite fine myself.

-Miles
-- 
97% of everything is grunge

Re: ChangeLog fontifications

[Eli Zaretskii]

> From: Miles Bader <miles@lsi.nec.co.jp>
> Date: 12 May 2004 19:10:29 +0900
> 
> Werner LEMBERG <wl@gnu.org> writes:
> > > 	* foo.lisp (aasfasdfffffffffffffffffffffffffffffffff)
> > >         (sadfggggggggggggg): ...
> > 
> > No, no, no.  This is really ugly.  Maybe easier to parse for a
> > computer -- not everything should look like Lisp code...
> 
> Sorry, that's the syntax.
> 
> I think it looks quite fine myself.

Me too.

Re: ChangeLog fontifications

[Sam Steingold]

> * Miles Bader <zvyrf@yfv.arp.pb.wc> [2004-05-12 19:10:29 +0900]:
>
> Werner LEMBERG <wl@gnu.org> writes:
>> > 	* foo.lisp (aasfasdfffffffffffffffffffffffffffffffff)
>> >         (sadfggggggggggggg): ...
>> 
>> No, no, no.  This is really ugly.  Maybe easier to parse for a
>> computer -- not everything should look like Lisp code...
>
> Sorry, that's the syntax.

where is it specified?
(i.e., do I have a better reference than you message?)

-- 
Sam Steingold (http://www.podval.org/~sds) running w2k
<http://www.camera.org> <http://www.iris.org.il> <http://www.memri.org/>
<http://www.mideasttruth.com/> <http://www.honestreporting.com>
You think Oedipus had a problem -- Adam was Eve's mother.

Re: ChangeLog fontifications

[Richard Stallman]

    where is it specified?
    (i.e., do I have a better reference than you message?)

In standards.texi, node Change Logs.

I chose this syntax so there would be an open-paren at the start
of each line that lists the names of definitions altered.
So they stand out better.

Re: ChangeLog fontifications

[Stefan Monnier]

> Now, multiline entries are also handled incorrectly:

> 	* foo.lisp (aasfasdfffffffffffffffffffffffffffffffff,
>         sadfggggggggggggg): ...

It's not the highlighting that's incorrect, it's the syntax.
Actually I have extended my font-lock regexes to recognize the above and
mark it in font-lock-warning-face.
I also have a highlight pattern to try and recognize when the past tense is
used ;-)


        Stefan

Re: ChangeLog fontifications

[Juri Linkov]

Stefan Monnier <monnier@iro.umontreal.ca> writes:
>> Now, multiline entries are also handled incorrectly:
>
>> 	* foo.lisp (aasfasdfffffffffffffffffffffffffffffffff,
>>         sadfggggggggggggg): ...
>
> It's not the highlighting that's incorrect, it's the syntax.
> Actually I have extended my font-lock regexes to recognize the above and
> mark it in font-lock-warning-face.
> I also have a highlight pattern to try and recognize when the past tense is
> used ;-)

It seems your rules are useful to be added to add-log.el to help the
developers to write more correct entries in ChangeLog files.

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

Re: ChangeLog fontifications

[Eli Zaretskii]

> From: Juri Linkov <juri@jurta.org>
> Date: Wed, 12 May 2004 03:08:44 +0300
> >
> > It's not the highlighting that's incorrect, it's the syntax.
> > Actually I have extended my font-lock regexes to recognize the above and
> > mark it in font-lock-warning-face.
> > I also have a highlight pattern to try and recognize when the past tense is
> > used ;-)
> 
> It seems your rules are useful to be added to add-log.el to help the
> developers to write more correct entries in ChangeLog files.

Seconded.

Re: ChangeLog fontifications

[Stefan Monnier]

>> > It's not the highlighting that's incorrect, it's the syntax.
>> > Actually I have extended my font-lock regexes to recognize the above and
>> > mark it in font-lock-warning-face.
>> > I also have a highlight pattern to try and recognize when the past tense is
>> > used ;-)
>> It seems your rules are useful to be added to add-log.el to help the
>> developers to write more correct entries in ChangeLog files.
> Seconded.

Problem is, I expect many people use change-log-mode in files where they do
not follow all the rules and they'd be annoyed by such changes.
And of course the "detect past tense" thingy is english-only, so it's also
inappropriate in general.


        Stefan


+    ;; Style warnings.
+    ("[ \t]+$" (0 'trailing-whitespace t))
+    ("^ +" (0 'trailing-whitespace t))
+    ;; Use
+    ;;   * foo.el (bla, bli)
+    ;;   (blo, blu): Toto.
+    ;; Rather than
+    ;;   * foo.el (bla, bli,
+    ;;   blo, blu): Toto.
+    ("^\\s-+\\(\\* .*\\)?([^\n)]*,\\s-*$" (0 font-lock-warning-face t))
+    ;; Don't cut a sentence right after the first word (better to move
+    ;; the sentence on the next line, then).
+    ("[.:]\\s-+\\(\\sw+\\)\\s-*$" (1 font-lock-warning-face t))
+    ;; Change Log entries should use present tense.
+    ("):[ \t\n]*[[:alpha:]]+\\(ed\\)\\>" (1 font-lock-warning-face t))
+    ;; Change log entries start with a capital letter.
+    ("): [a-z]" (0 font-lock-warning-face t)))

Re: ChangeLog fontifications

[Bruno Haible]

Miles Bader wrote:
> You should use a syntax like the following for such cases:
> 
> 	* foo.lisp (aasfasdfffffffffffffffffffffffffffffffff)
>         (sadfggggggggggggg): ...
> 
> [Not just for font-locking, but to make the job of any ChangeLog-parsing
> program easier.]

Sorry, but the style that been in use by the entire GNU project for over 10
years is this:

> 	* foo.lisp (aasfasdfffffffffffffffffffffffffffffffff,
>       sadfggggggggggggg): ...

Examples:

gcc-3.4.0/gcc/ChangeLog

2004-04-08  Joseph S. Myers  <jsm@polyomino.org.uk>

	* fixinc/inclhack.def (rpc_xdr_lvalue_cast_a,
	rpc_xdr_lvalue_cast_b): New fixes.

gcc-3.4.0/gcc/ChangeLog.0

Fri Jul  3 02:33:35 1998  David S. Miller  <davem@pierdol.cobaltmicro.com>

	* sparc.c (sparc_operand, move_operand,	arith_operand,
	arith11_operand, arith10_operand, arith_double_operand,
	arith11_double_operand, arith10_double_operand, small_int,
	uns_small_int): Recognize CONSTANT_P_RTX.

glibc/ChangeLog.14

2004-04-02  Jakub Jelinek  <jakub@redhat.com>

	* nis/nss: Add SERVICES_AUTHORITATIVE.
	* nis/nss-nis.h (NSS_FLAG_SET, NSS_FLAG_NETID_AUTHORITATIVE,
	NSS_FLAG_SERVICES_AUTHORITATIVE): Define.

glibc/ChangeLog.1

Fri Aug 14 13:28:39 1992  Roland McGrath  (roland@churchy.gnu.ai.mit.edu)

	* sysdeps/unix/Makefile, sysdeps/unix/bsd/Makefile,
	sysdeps/generic/Makefile: Use it.
	Use $(common-objpfx) for generated things not specific to one subdir.

Mon Aug 10 17:09:40 1992  Roland McGrath  (roland@churchy.gnu.ai.mit.edu)

	* sysdeps/unix/ioctls-tmpl.c [SMIOSTATS, SMIOGETREBOOT0,
	ZIOCBCMD]: Include headers for these.

gcc-1.41/ChangeLog

Wed May  3 01:34:58 1989  Richard Stallman  (rms at sugar-bombs.ai.mit.edu)

	* tm-mips.h (TARGET_VERSNUM): Inc. to 1 08.
	(TARGET_VERSION): Change strings.
	(AL_DEBUG): Don't define it.
	(HARD_REGNO_MODE_OK): Add some casts to int.
	(STACK_ARGS_ADJUST): Name was misspelled.
	(PRINT_OPERAND_ADDRESS): Just abort for MEM, POST_INC, etc.
	(EXTRA_SECTIONS, SELECT_VARIABLE_SECTION, SELECTORS_EXTRA_SECTIONS,
	SELECT_VARIABLE_CONST_SECTION): New macros.


If fontify cannot display this correctly, fix fontify. Telling people
that the syntax they've been using for 15 years is "wrong", because
fontify does not support it, is ridiculous.

             Bruno

Re: ChangeLog fontifications

[Miles Bader]

On Thu, May 13, 2004 at 08:50:00PM +0200, Bruno Haible wrote:
> Sorry, but the style that been in use by the entire GNU project for over 10

This is the emacs mailing list, right?  Look at the emacs changelogs.

-Miles
-- 
Yo mama's so fat when she gets on an elevator it HAS to go down.

Re: ChangeLog fontifications

[Bruno Haible]

Miles Bader wrote:
> > Sorry, but the style that been in use by the entire GNU project for over
> > 10 years
>
> This is the emacs mailing list, right?  Look at the emacs changelogs.

Ok, you mean to say that emacs fontify for ChangeLogs is meant to be used
only for Emacs ChangeLogs?

Or is there some customization that would make it work also for ChangeLogs
of other GNU people and projects?

              Bruno

Re: ChangeLog fontifications

[Miles Bader]

On Thu, May 13, 2004 at 09:43:50PM +0200, Bruno Haible wrote:
> > This is the emacs mailing list, right?  Look at the emacs changelogs.
> 
> Ok, you mean to say that emacs fontify for ChangeLogs is meant to be used
> only for Emacs ChangeLogs?

Well, actually I just meant that the post was on an emacs mailing list, so I
didn't really think about other cases than emacs.... :-)

-Miles
-- 
Yo mama's so fat when she gets on an elevator it HAS to go down.

Re: ChangeLog fontifications

[Sam Steingold]

> * Miles Bader <zvyrf@tah.bet> [2004-05-13 16:38:17 -0400]:
>
> On Thu, May 13, 2004 at 09:43:50PM +0200, Bruno Haible wrote:
>> > This is the emacs mailing list, right?  Look at the emacs changelogs.
>> 
>> Ok, you mean to say that emacs fontify for ChangeLogs is meant to be used
>> only for Emacs ChangeLogs?
>
> Well, actually I just meant that the post was on an emacs mailing
> list, so I didn't really think about other cases than emacs.... :-)

We are talking about the Emacs mode for editing ChangeLog files.
I believe that is should support all valid ChangeLog files in GNU
projects.

If

	* file.lisp (afgggggggggg,
        bar): baz

is invalid, please provide a reference to a GNU standard document and
start a crusade to make all GNU ChangeLog files valid.

Otherwise, please kindly admit that we have an Emacs bug on our hands.

Thanks.

-- 
Sam Steingold (http://www.podval.org/~sds) running w2k
<http://www.camera.org> <http://www.iris.org.il> <http://www.memri.org/>
<http://www.mideasttruth.com/> <http://www.honestreporting.com>
Sinners can repent, but stupid is forever.

Re: ChangeLog fontifications

[Miles Bader]

On Thu, May 13, 2004 at 05:12:37PM -0400, Sam Steingold wrote:
> If
> 
> 	* file.lisp (afgggggggggg,
>         bar): baz
> 
> is invalid, please provide a reference to a GNU standard document.

Another poster seems to have done this (quoting the coding standards).

> and start a crusade to make all GNU ChangeLog files valid

I don't think it's really that important... :-)

-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: ChangeLog fontifications

[Alan Shutko]

Bruno Haible <bruno@clisp.org> writes:

> Sorry, but the style that been in use by the entire GNU project for over 10
> years is this:
>
>> 	* foo.lisp (aasfasdfffffffffffffffffffffffffffffffff,
>>       sadfggggggggggggg): ...
>

GNU coding standards say otherwise: 

http://www.gnu.org/prep/standards_42.html#SEC42

    Break long lists of function names by closing continued lines with
    `)', rather than `,', and opening the continuation with `(' as in
    this example:

      * keyboard.c (menu_bar_items, tool_bar_items)
    (Fexecute_extended_command): Deal with `keymap' property.

Emacs gets it right, but it's not surprising that it isn't technically
enforced on projects with large numbers of non-emacs contributers.


-- 
Alan Shutko <ats@acm.org> - I am the rocks.
Boeing: The sound a plane makes when it hits the ground

Re: ChangeLog fontifications

[Miles Bader]

On Thu, May 13, 2004 at 03:13:11PM -0500, Alan Shutko wrote:
>       * keyboard.c (menu_bar_items, tool_bar_items)
>     (Fexecute_extended_command): Deal with `keymap' property.
> 
> Emacs gets it right, but it's not surprising that it isn't technically
> enforced on projects with large numbers of non-emacs contributers.

What I think would be really keen is if changelog filling would do this
correctly -- currently, although add-log will use the right syntax, manually
typing an entry and using fill-paragraph or auto-fill can leave it in the
`incorrect' form.

-Miles
-- 
In New York, most people don't have cars, so if you want to kill a person, you
have to take the subway to their house.  And sometimes on the way, the train
is delayed and you get impatient, so you have to kill someone on the subway.
  [George Carlin]

Re: ChangeLog fontifications

[Werner LEMBERG]

> GNU coding standards say otherwise: 
> 
> http://www.gnu.org/prep/standards_42.html#SEC42
> 
>     Break long lists of function names by closing continued lines with
>     `)', rather than `,', and opening the continuation with `(' as in
>     this example:
> 
>       * keyboard.c (menu_bar_items, tool_bar_items)
>     (Fexecute_extended_command): Deal with `keymap' property.

Well, this is completely crazy in my eyes.  Either this:

  * keyboard.c (menu_bar_items) (tool_bar_items)
  (Fexecute_extended_command): Deal with `keymap' property.

or this:

  * keyboard.c (menu_bar_items, tool_bar_items,
  Fexecute_extended_command): Deal with `keymap' property.

but not something inbetween!

> Emacs gets it right, but it's not surprising that it isn't
> technically enforced on projects with large numbers of non-emacs
> contributers.

This ChangeLog style is a typographic nightmare IMHO.  What on earth
was the reason to invent such a convention?


    Werner

Re: ChangeLog fontifications

[Miles Bader]

On Thu, May 13, 2004 at 11:37:55PM +0200, Werner LEMBERG wrote:
> This ChangeLog style is a typographic nightmare IMHO.

On the contrary, it looks quite nice.  IMO.

In fact I find it more readable than the `traditional' format, as it provides
the same advantage for the human reader that it does for a parser: it makes
the type of a line obviously identifiable by looking for a token in the left
margin, where it's very easy to see.

[The alternative format you suggest, `(a)(b)(c)' does not provide any real
advantage for the reader -- embedded ") (" pairs are in fact _harder_ to
parse for a human than commas because they're busier, and less familiar.]

> What on earth was the reason to invent such a convention?

Because (1) it's more friendly to line-oriented parsers (like font-lock, but
also external tools [*]), and (2) it looks quite nice.

[*] Indeed, rather _more_ important for external tools, because many unix
scripting languages &c are quite line-oriented, more so that emacs is.

-Miles
-- 
Somebody has to do something, and it's just incredibly pathetic that it
has to be us.  -- Jerry Garcia

Re: ChangeLog fontifications

[Stefan Monnier]

>> What on earth was the reason to invent such a convention?
> Because (1) it's more friendly to line-oriented parsers (like font-lock, but
> also external tools [*]), and (2) it looks quite nice.

Indeed, I strongly suspect that the convention was designed before
font-lock existed.

In any case we have to live with the fact that many projects don't follow
this part of the convention (and thus lived without complaining with
font-lock not highlighting things the way they wanted).  I think fixing
font-lock to follow their use would go in the wrong direction unless it is
decided to change the convention.  What would be better would indeed be
things like teaching fill&auto-fill how to do things right.

OTOH adding a big fat font-lock-warning-face where the convention is not
followed (like I do) would probably result in a massive popular revolt.


        Stefan

Re: ChangeLog fontifications

[Karl Eichwalder]

Miles Bader <miles@gnu.org> writes:

> [The alternative format you suggest, `(a)(b)(c)' does not provide any real
> advantage for the reader -- embedded ") (" pairs are in fact _harder_ to
> parse for a human than commas because they're busier, and less familiar.]

`(a)(b)\n(c)' is better than `(a, b)\n(c)' because the second flavor is
highly misleading: grouping is artificial.  Please, switch to `(a, b,\nc)'.

['\n' denotes newline.]

-- 
                                                         |      ,__o
                                                         |    _-\_<,
http://www.gnu.franken.de/ke/                            |   (*)/'(*)

Re: ChangeLog fontifications

[Miles Bader]

Karl Eichwalder <ke@gnu.franken.de> writes:
> > [The alternative format you suggest, `(a)(b)(c)' does not provide any real
> > advantage for the reader -- embedded ") (" pairs are in fact _harder_ to
> > parse for a human than commas because they're busier, and less familiar.]
> 
> `(a)(b)\n(c)' is better than `(a, b)\n(c)' because the second flavor is
> highly misleading: grouping is artificial.

What can I say?  You're wrong.  I've used both variants for many years,
and the `(a, b)\n(c)' style is quite a bit easier to read.  It's
marginally harder to _write_, if you don't have automatic tools to do
so, but of course emacs users do have such tools.

This isn't some sort of `make the most minimal representation' game
(aka the scheme game :-), it's a practical exercise in choosing a format
that's both easy for humans to read/write and for tools to read/write.

Doing so involves compromises, but the current emacs solution is a good
and practical one.

> Please, switch to `(a, b,\nc)'.

Ain't my decision.

-Miles
-- 
Suburbia: where they tear out the trees and then name streets after them.

Re: ChangeLog fontifications

[Robert J. Chassell]

   `(a)(b)\n(c)' is better than `(a, b)\n(c)' because the second flavor is
   highly misleading: grouping is artificial.

That is how I perceive also.  It may look all right with a parenthesis
at the beginning of the second line, but the grouping is misleading.
Troublesome as it is, `(a, b,\nc)' is better, unless, of course, the
grouping is different.

-- 
    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: ChangeLog fontifications

[Werner LEMBERG]

> > This ChangeLog style is a typographic nightmare IMHO.
>
> On the contrary, it looks quite nice.  IMO.

This is a misunderstanding.  I'm not talking about looking nice, I'm
talking about the typographical `correctness'.  As has been pointed
out by others, the grouping becomes artificial.  Besides this, it
isn't something used anywhere else in the English language, AFAIK:

  Imagine a sentence (consisting of nouns) (verbs, adjectives) (and
  other words) like this and you see what you mean.

I know that it is not of importance that a ChangeLog entry is
grammatically correct, but intentionally working against such rules is
plain wrong for me.  A good solution to make human and computerized
parsers happy could be this -- a traditional solution used by
typsetters since a few hundred years:

    * foo/bar (long_item_1, long_item_2,
        long_item_3, long_item_4,
        long_item_5): Explanation of long
        items 1 to five.

Or this (at the cost of making the entry longer):

    * foo/bar (long_item_1, long_item_2,
        long_item_3, long_item_4,
        long_item_5):
          Explanation of long items 1 to five.


Don't make man obey the tools, let's rather make the tools obey man!


     Werner

Re: ChangeLog fontifications

[Werner LEMBERG]

>   Imagine a sentence (consisting of nouns) (verbs, adjectives) (and
>   other words) like this and you see what you mean.
                                            ^^^
What I mean, of course.


    Werner

Re: ChangeLog fontifications

[Sam Steingold]

> * Miles Bader <zvyrf@tah.bet> [2004-05-13 17:56:23 -0400]:
>
>> What on earth was the reason to invent such a convention?
>
> Because (1) it's more friendly to line-oriented parsers (like font-lock, but
> also external tools [*]), and (2) it looks quite nice.
>
> [*] Indeed, rather _more_ important for external tools, because many unix
> scripting languages &c are quite line-oriented, more so that emacs is.

what are those tools?  why those who use them do not complain that they
do not work with some ChangeLog files?

I suspect that either there are no such tools or nobody uses them anymore
(otherwise the current situation would be impossible).

At any rate, the current state of affairs is broken: either the
ChangeLog standard described in
<http://www.gnu.org/prep/standards_42.html#SEC42> is obsolete (since is
it widely ignored) and must be changed - together with the Emacs
ChangeLog mode, or it should be enforced, e.g., by adding a script to
savannah cvs which will reject ChangeLog commits that do not comply
with the standard.



-- 
Sam Steingold (http://www.podval.org/~sds) running w2k
<http://www.camera.org> <http://www.iris.org.il> <http://www.memri.org/>
<http://www.mideasttruth.com/> <http://www.honestreporting.com>
There's always free cheese in a mouse trap.

Re: ChangeLog fontifications

[Richard Stallman]

For Emacs to highlight both styles properly would be best, of course.
If some projects (including non-GNU projects) use the other style,
we may as well make Emacs more useful for them.

However, if it is hard to support both, we should support the GNU
recommended style.

    What I think would be really keen is if changelog filling would do
    this correctly -- currently, although add-log will use the right
    syntax, manually typing an entry and using fill-paragraph or
    auto-fill can leave it in the `incorrect' form.

That would be a good feature.  However, we should provide an option to
turn on and off.  Those who prefer the other format would not like
Emacs to convert it to the GNU format.

But let's put that off for later, since now we want to aim towards
fixing bugs, not designing new features.


Regarding the examples you found in GCC.


    2004-04-08  Joseph S. Myers  <jsm@polyomino.org.uk>

	    * fixinc/inclhack.def (rpc_xdr_lvalue_cast_a,
	    rpc_xdr_lvalue_cast_b): New fixes.

They are apparently not following our standards.
This is not a terribly important issue, but
I will write to suggest that they follow the GNU standards
for this.

    Wed May  3 01:34:58 1989  Richard Stallman  (rms at sugar-bombs.ai.mit.edu)

	    * tm-mips.h (TARGET_VERSNUM): Inc. to 1 08.
	    ...
	    (EXTRA_SECTIONS, SELECT_VARIABLE_SECTION, SELECTORS_EXTRA_SECTIONS,
	    SELECT_VARIABLE_CONST_SECTION): New macros.

I think that 1989 was before I thought about the issue and decided that

	    (EXTRA_SECTIONS, SELECT_VARIABLE_SECTION, SELECTORS_EXTRA_SECTIONS)
	    (SELECT_VARIABLE_CONST_SECTION): New macros.

would make it easier to see the names of the functions that were
changed.

Re: ChangeLog fontifications

[Bruno Haible]

Richard Stallman wrote:
> If some projects (including non-GNU projects) use the other style,
> we may as well make Emacs more useful for them.

Yes, all GNU projects I work on use the style with a 15-year tradition.

> I will write to suggest that they follow the GNU standards
> for this.
> ...
> I think that 1989 was before I thought about the issue

After people have used to write things in a certain style for 10 years -
following the example that was given by you, by GCC, glibc and other
projects - it will be hard to explain what in this style is "wrong".

Werner said that the new Emacs style is bad because it doesn't follow the
parenthesizing conventions used in plain text.

I add that the new Emacs style is bad because it doesn't allow a newline
to be inserted anywhere, i.e. it doesn't treat newline and space conceptually
the same.

What are the advantages/benefits of the new Emacs style that should
convince me and others to use it?

Bruno

Re: ChangeLog fontifications

[Eli Zaretskii]

> From: Bruno Haible <bruno@clisp.org>
> Date: Sun, 16 May 2004 17:14:16 +0200
> 
> Yes, all GNU projects I work on use the style with a 15-year tradition.

What projects are those?

> After people have used to write things in a certain style for 10 years -
> following the example that was given by you, by GCC, glibc and other
> projects - it will be hard to explain what in this style is "wrong".

Actually, I found it rather easy to explain, in those cases where I
did.

And many code contributors write misformatted ChangeLog entries even
according to old conventions you are accustomed to.  So if a project
cares about its log formatting, maintainers typically need to watch
out for badly formatted entries anyway.  So it's not like the old
conventions are somehow automatically followed, except by those few
who are accustomed to them.

> I add that the new Emacs style is bad because it doesn't allow a newline
> to be inserted anywhere, i.e. it doesn't treat newline and space conceptually
> the same.

With suggested changes that will allow log entries to be correctly
formatted when they are refilled, this problem will go away, I think.

> What are the advantages/benefits of the new Emacs style that should
> convince me and others to use it?

The advantages/benefits were already mentioned in this thread: the new
style makes it easier for line-oriented programs to find the names of
changed functions/macros.

Re: ChangeLog fontifications

[Miles Bader]

On Sun, May 16, 2004 at 06:52:50PM +0200, Eli Zaretskii wrote:
> > What are the advantages/benefits of the new Emacs style that should
> > convince me and others to use it?
> 
> The advantages/benefits were already mentioned in this thread: the new
> style makes it easier for line-oriented programs to find the names of
> changed functions/macros.

And even more importantly it makes it easier for a _human_ to read changelog
entries -- it really does.

-Miles
-- 
Next to fried food, the South has suffered most from oratory.
  			-- Walter Hines Page

Re: ChangeLog fontifications

[Richard Stallman]

    What are the advantages/benefits of the new Emacs style that should
    convince me and others to use it?

It makes the names of functions being changed stand out more.
Without the extra parens, they tend to get lost among the rest of
the text.

I was not thinking about automated parsing--I don't do that--but
that could be another advantage.

Re: ChangeLog fontifications

[Karl Eichwalder]

Richard Stallman <rms@gnu.org> writes:

> Without the extra parens, they tend to get lost among the rest of
> the text.

The closing paren will remind you--the same way as it works in written
human languages.

-- 
                                                         |      ,__o
                                                         |    _-\_<,
http://www.gnu.franken.de/ke/                            |   (*)/'(*)

Re: ChangeLog fontifications

[Miles Bader]

Karl Eichwalder <ke@gnu.franken.de> writes:
> > Without the extra parens, they tend to get lost among the rest of
> > the text.
> 
> The closing paren will remind you--the same way as it works in written
> human languages.

It doesn't work well in `human languages' when there is a lot of text
either.

Anyway (as I keep saying), I've used both extensively, and the
`official' format is easier to read.

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

Re: ChangeLog fontifications

[Sam Steingold]

> * Miles Bader <zvyrf@yfv.arp.pb.wc> [2004-05-19 10:32:18 +0900]:
>
> Anyway (as I keep saying), I've used both extensively, and the
> `official' format is easier to read.

could it be easier to read precisely because Emacs supports it better?

-- 
Sam Steingold (http://www.podval.org/~sds) running w2k
<http://www.camera.org> <http://www.iris.org.il> <http://www.memri.org/>
<http://www.mideasttruth.com/> <http://www.honestreporting.com>
Good programmers treat Microsoft products as damage and route around it.

Re: ChangeLog fontifications

[Miles Bader]

On Wed, May 19, 2004 at 09:08:59AM -0400, Sam Steingold wrote:
> > Anyway (as I keep saying), I've used both extensively, and the
> > `official' format is easier to read.
> 
> could it be easier to read precisely because Emacs supports it better?

Probably not.

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

Re: ChangeLog fontifications

[Stefan Monnier]

>> could it be easier to read precisely because Emacs supports it better?

It's not the case for me: the Emacs support doesn't influence the display
(at least with my face configuration, maybe the default is different).


        Stefan

Re: ChangeLog fontifications

[Richard Stallman]

    > Without the extra parens, they tend to get lost among the rest of
    > the text.

    The closing paren will remind you--the same way as it works in written
    human languages.

It isn't effective when scanning the list.  That closing paren could
be several lines further down.