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