<<< Date Index >>>     <<< Thread Index >>>

Re: [PATCH] Document history more verbosely



Hi,

* Alain Bench [06-07-09 12:42:38 +0200] wrote:
On Wednesday, July 5, 2006 at 11:17:04 +0000, Rocco Rutte wrote:

Attached is a patch documenting how the history works.

   Much thanks! I'd propose an additional paragraph about different
prompt classes (to be inserted as 2nd paragraph):

I've added as v2 of the patch but replaced your rough listing with more correct one derived from history_class_t definitions, thanks for the hint! Btw, I also updated the $my_ doc patch with your 'unset my_foo' instead of 'set &my_foo' suggestion but pushed it out before mentioning that you're the originator (it's too late for the correction, sorry).

By the way, while looking up the classes, I noticed something really ugly. _mutt_enter_string() detects the history class by the flags it's given, okay. But: mutt_enter_string() is only called with pure numeric constants without documentation et. al. This should be replaced by properly OR'ing the flags instead of writing something like flags=9. Now what does 9 mean?

I vote for a line in UPDATING as ignoring duplicates is worth
mentioning, IMHO.

   Impossible: Nobody knows when history undupping was implemented.
Dinosaurs were still the masters in that era. Even Mutt 1.2.5 has it!
Rumors pretend it might predate the Y2K Big Bug...

It's present straight from the initial CVS import already, so we can ignore it for UPDATING. But this one:

| + Space prefix at prompts inhibits history recording (2006-07-04)

should definitely go in.

   While at it, Rocco, are you aware that providing this UPDATING list
of user visible changes was a Really Good Idea? It saved me precious
time and efforts several times these last days. Thanks!

It's inspired by the FreeBSD people whose system I use. Since I upgrade everything (software and OS) straight from source, such a document is a pure must... I also asked Thomas Glanzman for adding a link to dev.mutt.org, wiki.mutt.org has the link already, mutt-users@ knows about it.

To further help spreading the word, is it worth a paragraph in the manual?

   Writers of feature patches could also be encouraged to propose, when
appropriate, a not yet timestamped line (or short PDF slide-show) for
UPDATING. Aside of their patch, to avoid collisions.

When proposing a change of some doc/*.txt files to mention the check_sec.sh script, I thought about this issue, too. For patches it's easy to "fool" the patch(1) tool by adding a chunk to PATCHES which always gets inserted first into the file without conflicts. However, due to the explanations it doesn't work with UPDATING.

Also, as this document is official it may not even be a good idea that patch authors include their changes into it. This might cause confusion or people double-checking whether a note is present in an unpatched UPDATING document and their own.

However, the only solution I can up with so far is that people provide a chunk in the same way as for PATCHES but prepending to README.patches with content like so:

  Patch '$patchid' (<-- from 'mutt -v')
  ==================

  Description here.

with a trailing newline. The advantage is that users have a README for all patches they use along with the purpose of it which is _clearly_ separated and hence distinctable from vanilla mutt.

IMHO we really need to work to achieve more user convenience as apparently the vast majority used patched versions.

More ideas?


| 1.5.6 (2004-02-01):
|
| ! the 'list' and 'subscribe' commands now take regular expression
|   rather than string lists
   [...]
| ! mailing lists can be recognized via domain matching when
|   starting with '@'

   @domain matching was never released, because soon after superseded
by regexps. Both great work of TLR. So the 2nd entry is misleading:
nothing has to start with @. I'd propose to remove the entry, or append
a comment: (constraint obsoleted by powerfull regexp matching described
two entries above).

For that particular one, I think it's better to mention that the feature changed again (patch attached) because it could be that someone happens to run a mutt version with the '@'-feature but hasn't yet upgraded to the regex one.

This document IMHO should list just all changes and not only those which made it to the public via an official release because within the devel series, you can have totally different code-bases even within the same version.

That's also why I think it's bad that Brendan kicked the $imap_cachedir -> $message_cachedir transition (he also left $imap_cachedir in there by accident instead of removing it). It could well be that systems provided binary packages based on CVS after the addition of $imap_cachedir and now even with UPDATING there's no note about it. UPDATING looks okay for that one and the actual update breaks configs as there's no synonym and there's no way except reading ChangeLog to find out about the replacement (...which is very inconvenient for poeple with binary packages).

Summary: I vote for UPDATING being prepend-only no matter what happened in the past (from a future point of view) (in the spirit of the attached patch).

  bye, Rocco
--
:wq!
diff --git a/UPDATING b/UPDATING
index 4fcab17..0c922de 100644
--- a/UPDATING
+++ b/UPDATING
@@ -87,7 +87,8 @@ Mutt 1.5.7 (2005-01-28):
 1.5.6 (2004-02-01):
 
   ! the 'list' and 'subscribe' commands now take regular expression
-    rather than string lists
+    rather than string lists which obsoletes the '@' domain matching
+    syntax
   ! the $alternates option is replaced by the 'alternates' command
     taking lists of regular expressions
   ! mailing lists can be recognized via domain matching when