Subject: Fvwm autoconf

From: Dan Espen <[email-masked]>
Date: Sun, 01 Nov 1998 20:15:41 -0500

Steve Robbins <[email-masked]> writes:
> OK, autoconf is in.  I'm very interested to hear reports of success or
> failure with the new configure system! 

This is so   trivial, I'm almost  embarrased to  mention it, but   you
missed the references to fvwm.tmpl in the fvwm.1 man page.

Whats going on in the ChangeLog file?  Is that some byproduct of using
emacs and  cvs?  I have no problem  adopting that style, and I've seen
changelogs that look   like that before, I  just  want to know how  to
accomplish it.

The only   drawback I see  is our  web site  contains the  text of the
changelog and offers that as end user documentation.  The format isn't
particularly readable for a non-developer.

> 
> --
> Steve Robbins                              <[email-masked]>
> 

--
Dan Espen                                Phone: (732) 699-5570
444 Hoes Lane  Room RRC 1C-214           E-mail: [email-masked]
Piscataway, NJ 08854
--
Visit the official FVWM web page at <URL:http://www.hpc.uh.edu/fvwm/>.
To unsubscribe from the list, send "unsubscribe fvwm-workers" in the
body of a message to [email-masked].
To report problems, send mail to [email-masked].

---

From: Steve Robbins <[email-masked]>
Date: Sun, 1 Nov 1998 23:56:35 -0500 (EST)

> missed the references to fvwm.tmpl in the fvwm.1 man page.

Oh, I hope people don't feel embarassed to mention bugs!  As far as I'm
concerned, no bug is too trivial to get fixed. 

As for man pages: other than renaming all the files, (xxx.man --> xxx.1) I
have not touched them. In fact, I didn't even realise that the man page
mentions the configuration process!
 
> changelogs that look   like that before, I  just  want to know how  to

That's emacs' "changelog" mode; nothing to do with CVS.  I vastly prefer
it because the entries are date- & person-stamped.  With >1 developer,
both of these features are vital, IMHO.

As far as accomplishing it, after editing some source file (anywhere in
the tree), do "CTRL-X 4 a".  Very cool.

> particularly readable for a non-developer.

Right.  The ChangeLog is for developers.  User-visible changes are written
up in a different file, called "NEWS" in the GNU conventions (I think).

---

From: [email-masked] (Paul D. Smith)
Date: 02 Nov 1998 01:11:25 -0500

%% Dan Espen <[email-masked]> writes:

  de> Whats going on in the ChangeLog file?  Is that some byproduct of using
  de> emacs and  cvs?  I have no problem  adopting that style, and I've seen
  de> changelogs that look   like that before, I  just  want to know how  to
  de> accomplish it.

As Steve points out, that's Emacs' changelog mode.  Quite handy.  C-x 4
a while point is in the function you changed, and voila.  Will group
changes for a single day, etc. etc.

  de> The only drawback I see is our web site contains the text of the
  de> changelog and offers that as end user documentation.  The format
  de> isn't particularly readable for a non-developer.

Again, Steve has already mentioned that ChangeLog's _are_ developer
documentation.  The NEWS file is supposed to contain user-level change
documentation: new features, changes to old features, backward
compatibility warnings, etc. that users need to know.

I would like to encourage everyone to create changelogs.  On many GNU
projects the way it works is people submitting patches don't submit a
patch for the changelog, since that often breaks when the changelog is
so dynamic; instead they include the changelog entry first, as plain
text, then the patch below it.  For GNU make I try to never accept any
patch without a suitable ChangeLog entry.

-- 
-------------------------------------------------------------------------------
 Paul D. Smith <[email-masked]>         Network Management Development
 "Please remain calm...I may be mad, but I am a professional." --Mad Scientist
-------------------------------------------------------------------------------
   These are my opinions---Nortel Networks takes no responsibility for them.
--
Visit the official FVWM web page at <URL:http://www.hpc.uh.edu/fvwm/>.
To unsubscribe from the list, send "unsubscribe fvwm-workers" in the
body of a message to [email-masked].
To report problems, send mail to [email-masked].

---

From: Dan Espen <[email-masked]>
Date: Mon, 02 Nov 1998 08:32:28 -0500

> patch without a suitable ChangeLog entry.

Realistically, I don't  see  how I can  fight  GNU conventions, but  I
thought I just finished the WEB documentation update and  now I have a
new problem.

As you  are all probably aware,  fvwm has both  a ChangeLog and a NEWS
file.  Both were  being used as end  user documentation.   I guess I'm
going to  have to move  the old  ChangeLog stuff  into the  NEWS file?
Perhaps I'll remove the ChangeLog from the WEB interface.

One more comment/objection, I've always felt change history was better
placed  in individual  source files and  a number  of my changes  have
extensive change history in the source  files.  I believe Emacs/XEmacs
has a   number of  functions  that  support  this approach.    Too bad
'add-change-log-entry-other-window' doesn't have an  option to put the
changelog in both places.

> -- 
>  Paul D. Smith <[email-masked]>         Network Management Developmen

---

From: Steve Robbins <[email-masked]>
Date: Mon, 2 Nov 1998 10:20:20 -0500 (EST)

> going to  have to move  the old  ChangeLog stuff  into the  NEWS file?

I think that's a good idea.  The itemized lists that were used as
ChangeLog previously are better suited to end users.  They are nearly
useless to me as a developer. 

> Perhaps I'll remove the ChangeLog from the WEB interface.

Or maybe just label it as "developer stuff"?
 
> changelog in both places.

One argument in favour of collecting the changes into a common ChangeLog,
rather than scattered through individual source files is that adding
feature X may involve changing several files in different places of the
source tree.  A single ChangeLog allows you to collect all the changed
files together in one entry, and gives a better overall picture of what
happened.  If the changes are only noted inside individual files, you'd
have to cross-reference each change, and run the risk of forgetting to
note that the change to a/foo.c also involves b/blah.h.

Having said that, there is the possibility to have multiple ChangeLogs.
One in the modules directory, for example to catch changes to all modules,
(one in extras for extras/*) and one in the top to catch changes in fvwm/
and libs/, etc.  The algorithm for emacs' "ctrl-x 4 a" is: search upwards
in the directory structure for a file named ChangeLog, and use the first
one found.

Don't play cards with the Devil.  He'll deal you an awful hand.

---

From: [email-masked] (Paul D. Smith)
Date: 02 Nov 1998 11:49:20 -0500

%% Steve Robbins <[email-masked]> writes:

  sr> On Mon, 2 Nov 1998, Dan Espen wrote:

  >> file.

No it doesn't.  At least, I checked out the 2.1.0 version and there's no
NEWS file there...

Another file that's part of the "GNU standards" that we might like to
add is the AUTHORS file; it can be painful to come up with the first
version but it's a nice thing to have afterwards.

  sr> I think that's a good idea.  The itemized lists that were used as
  sr> ChangeLog previously are better suited to end users.  They are
  sr> nearly useless to me as a developer.

Agreed.
 
  >> changelog in both places.

As Steve points out, I like ChangeLogs as-is since you can go to one
file and look through it for all changes, rather than having them spread
out.

Plus, having a separate file I think makes it more likely people will
document more changes: since you can always rename the ChangeLog to
something else and start a new one if it gets too big people don't worry
about being verbose.  I think after a file's log gets too large people
start being very terse :)

  sr> Having said that, there is the possibility to have multiple
  sr> ChangeLogs.  One in the modules directory, for example to catch
  sr> changes to all modules, (one in extras for extras/*) and one in
  sr> the top to catch changes in fvwm/ and libs/, etc.  The algorithm
  sr> for emacs' "ctrl-x 4 a" is: search upwards in the directory
  sr> structure for a file named ChangeLog, and use the first one found.

I actually think it's appropriate for _each_ module to have its _own_
changelog.  After all, they're entirely separate entities and it doesn't
really seem useful to put all their changes into one place.  In the
Emacs dist. for example, there's a changelog for Emacs source, a
different one for the Lisp directory, different one for the widget
libraries, etc. etc.

But, that's up to the individual module maintainer, I guess.  Definitely
one for the modules and one for the extras directory is a bare-minimum.

---

From: Dan Espen <[email-masked]>
Date: Mon, 02 Nov 1998 13:31:08 -0500

> No it doesn't.  At least, I checked out the 2.1.0 version and there's no

Sorry, you're right.  There is  a news.html at  the Fvwm Official Home
Page site.  Its the ChangeLog, FAQ, and TO-DO files  that are run thru
a script to create HTML.

It looks  like  in the  past,   they were run  thru  something  called
txt2html that I think  came from Chuck.  I've  written my own, but I'm
starting to think I won't need it.

My plan right now is to take everything I've re-worked  and dump it in
the doc directory.  Then Jason can just copy it out of the source tree
into the filesystem the web page uses.

Since the source tree will have a FAQ.html, I think that makes the FAQ
text  file  redundant.    Probably the  same  applies   for all  these
text/HTML files.

---

From: [email-masked] (Paul D. Smith)
Date: 03 Nov 1998 12:08:21 -0500

de> Sorry, you're right.  There is  a news.html at  the Fvwm Official Home
  de> Page site.  Its the ChangeLog, FAQ, and TO-DO files  that are run thru
  de> a script to create HTML.

  de> It looks  like  in the  past,   they were run  thru  something  called
  de> txt2html that I think  came from Chuck.  I've  written my own, but I'm
  de> starting to think I won't need it.

  de> My plan right now is to take everything I've re-worked  and dump it in
  de> the doc directory.  Then Jason can just copy it out of the source tree
  de> into the filesystem the web page uses.

  de> Since the source tree will have a FAQ.html, I think that makes the FAQ
  de> text  file  redundant.    Probably the  same  applies   for all  these
  de> text/HTML files.

Not quite sure about the extent of the changes you're considering: I
don't have strong opinions on converting, say, the FAQ and TODO lists to
html.

However, I think the NEWS file needs to be kept text and available at
the top level of the distribution.  It's so useful to have that file
immediately available right where expected: people are very used to it
and look there for new features, gotchas, etc. with every upgrade.
These days whenever I open a new package tarball I always expect/hope to
see these files at the top level:

  COPYING
  ChangeLog
  INSTALL
  NEWS
  README
  configure

Seeing that makes me happy :)

---

From: Dan Espen <[email-masked]>
Date: Tue, 03 Nov 1998 13:44:23 -0500

> Seeing that makes me happy :)

Tell me one more time that you want the NEWS in the main directory and
I will go back to the txt2html approach.  I thought the main issue was
the extra work Jason had to go thru at each release.

I too,  would look for NEWS  in the main directory,  but I  might also
wander into the "docs" directory.

I don't see this as  an autoconf issue, the  txt2html step should only
have to take place at our web site.

---

From: Dan Espen <[email-masked]>
Date: Fri, 20 Nov 1998 12:23:06 -0500

> in the directory structure for a file named ChangeLog, and use the first

I thought we had   a clear policy  on this,  but  my memory failed  me
again.    You  may have  noticed  a  new  more   ChangeLogs than Steve
proposed:

machine> find . -name ChangeLog
./ChangeLog
./docs/ChangeLog
./extras/ChangeLog
./icons/ChangeLog
./modules/ChangeLog
./modules/FvwmAnimate/ChangeLog
./modules/FvwmEvent/ChangeLog
./modules/FvwmIdent/ChangeLog

I'm afraid they are my  doing.  I prefer  it, but if there are  strong
objections,  I'll   back this  stuff  out.   The   modules really  are
independent, I   think the  ChangeLogs  should be  inside the  modules
directory.

---

From: Dominik Vogt <[email-masked]>
Date: Fri, 20 Nov 1998 18:28:55 +0100

> independent, I   think the  ChangeLogs  should be  inside the  modules

My, isn't the tree getting a bit overcrowded with ChangeLog's?
I don't have any feelings about that, but if there are files for
individual modules/extras, there should be one for every single
module. The file one level higher records only add/remove/rename
of a module.

The module/extra ChangeLog's have to be cleaned up then (i.e.
move entries to the correct ChangeLog).

Bye

Dominik
-- 
Dominik Vogt, Hewlett-Packard GmbH, Dept. BVS
Herrenberger Str.130, 71034 Boeblingen, Germany
phone: 07031/14-4596, fax: 07031/14-3883, [email-masked]
--
Visit the official FVWM web page at <URL:http://www.hpc.uh.edu/fvwm/>.
To unsubscribe from the list, send "unsubscribe fvwm-workers" in the
body of a message to [email-masked].
To report problems, send mail to [email-masked].

---

From: [email-masked] (Paul D. Smith)
Date: 20 Nov 1998 13:33:54 -0500

de> I'm afraid they are my  doing.  I prefer  it, but if there are  strong
  de> objections,  I'll   back this  stuff  out.   The   modules really  are
  de> independent, I   think the  ChangeLogs  should be  inside the  modules
  de> directory.

I agree the modules are independent, and I don't have strong feelings
about it at all, but left up to me I think I'd have just three:

  ./ChangeLog
  ./modules/ChangeLog
  ./extras/ChangeLog

Reason?  I just don't think the majority of the modules we have are
significant enough to warrant a whole changelog to themselves.  In other
words, the amount of changes made to them won't justify it (is my
feeling).

If there were just one ChangeLog for modules, I could look at that one
file and see the changes for all the standard modules.  It's easy enough
to search for entries relating to the module I'm interested in.

As I said, I don't care much one way or t'other, that's just my $0.005.