If no-one comments further, I'm going to see if I have perms to change the wiki page with this tutorial.
-Robin On Thu, Jul 19, 2012 at 12:58:34PM -0700, Robin Lee Powell wrote: > On Thu, Jul 19, 2012 at 10:55:07AM -0700, Robin Lee Powell wrote: > > On Thu, Jul 19, 2012 at 10:48:03AM -0700, Robin Lee Powell wrote: > > > On Thu, Jul 19, 2012 at 12:44:31PM -0500, David Champion wrote: > > > > * On 19 Jul 2012, Robin Lee Powell wrote: > > > > > The section about tags in > > > > > http://wiki.mutt.org/?MuttGuide/Macros is flat-out wrong in > > > > > 1.5.21 and 1.5.20, as far as I can tell, and > > > > > > > > In what way, specifically? The statements appear to be correct > > > > and there are no functional examples (only illustrative ones), > > > > so it's hard to infer what's incorrect. > > > > > > "If you define a macro to work with a single entry, then it can > > > not be applied to tagged entries just by using > > > <tag-prefix>macro-key!!!" is flat-out false in every version of > > > mutt I have access to. This means that the entire section > > > "Special usage: applying to several tagged entries" is both false > > > and useless. > > > > > > Based on that statement, given the following macro: > > > > > > macro index ,t <tag-entry> > > > > > > I would expect the following sequence of characters to error out: > > > > > > ttt;,t > > > > > > But in fact it works perfectly. > > > > It just occured to me that it may be that it is intended to mean > > that given: > > > > macro index ,t <tag-entry> > > > > this won't work: > > > > macro index ,x <tag-prefix>,t > > > > But in fact that is also false; all 4 of the following work exactly > > as you'd expect: > > > > macro index ,t t > > macro index ,T <tag-entry> > > macro index ,x <tag-prefix>,t > > macro index ,X <tag-prefix>,T > > > > at least in 1.5.21, where I just tested them. > > And now I think I understand what it's *actually* trying to say. > > I took: > > If you define a macro to work with a single entry, then it can not > be applied to tagged entries just by using > <tag-prefix>macro-key!!! > > to mean that *no* macros *ever* work with tags unless set to do so > explicitely, but it means that *some* macros will do unpexpected > things. > > I'm going to suggest some wording here that I'd like to put in that > section of the wiki, and y'all can tell me if it's halfway decent. > > Tags, Advancement, And Other Macro Surprises > > All macros devolve in the end, essentially, to a sequence of > keystrokes sent to mutt. This means that working with tagged > messages in macros can be tricky, at least unless you have > auto_tag turned on, because if you simply hit the tag-prefix key > (default ;) before the macro, the tag-prefix key will only apply > to the first action. > > If your macro does more than one thing, each seperate thing that > it does must be tag-prefixed seperately. > > Here's an example; this (totally useless) macro: > > macro index ,g '<pipe-entry>wc -l<enter><delete-message>' "useless: count > lines, throw away the count, and then delete" > > pipes a message to a shell command and then deletes it. > > If, however, you use tab-prefix first (i.e. ";,g"), it doesn't > pipe each message to the shell and then delete them, it pipes them > all to the shell and then deletes the one under the cursor. In > other words, assuming default bindings and using <enter> to stand > in for hitting the enter key, the keystrokes: > > |wc -l<enter>d > > become: > > ;|wc -l<enter>d > > which pipes all the messages but only deletes one message (and not > any of the ones you had tagged, probably, but rather the one under > the cursor!) and not: > > ;|wc -l<enter>;d > > which pipes and deletes all of them, as you might expect. > > A slightly tricky bit there is that pipe-entry asks for user > input, which you might not want in a macro; this can be handled by > temporarily disabling that behaviour and then (assuming you want > it on) turning it back on, like so: > > macro index ,G '<enter-command>set wait_key=no<enter><pipe-entry>wc > -l<enter><delete-message><enter-command>set wait_key=no<enter>' "useless: > count lines, don't wait, throw away the count, and then delete" > > The wait_key bit is to stop it from explicitely asking you to > press enter. > > This behaves even worse with tag-prefix, because what you end up > with is: > > ;:set wait_key=no<enter>|wc -l<enter>d:set wait_key=yes<enter> > > Which is a problem because as soon as you type the :, the > prefix-ness just gets completely lost; you might as well have not > even typed ;. > > For some macros, there's no problem; this macro will work just > fine with tag-prefix: > > macro index ,s '<save-message>=spam<enter>' "Dump to spam folder" > > Because it only performs one action, with tag prefix this turns > into: > > ;s=spam<enter> > > which works perfectly. > > If you do need a macro that performs multiple actions, though, > what you'll need to do is have a version that expects no tags, and > a versian that accepts tags. > > [INSERT CURRENT CONTENTS OF "Special usage: applying to several > tagged entries" HERE] > > Another surprise is that most commands in mutt at the index level > move to the next message, at least with default settings, and this > is true when they are invoked as macros as well. This means that: > > macro index ,t '<toggle-new><delete-message>' "broken: toggle new, then > delete something else" > > is almost certainly a totally useless macro, with tags or not. > > Without tag-prefix, it toggles the new flag on the message under > the cursor, advances to the next message, and deletes that! > > With tag-prefix, it toggles the new flag on all the tagged > messages and deletes the one under the cursor, as per the > discussion above. > > The solution here is to temporarily turn off the > advance-to-next-message behaviour for the run of your macro: > > macro index ,d "<enter-command>unset > resolve<enter><toggle-new><delete-message><enter-command>set resolve<enter>" > "Read and Delete Message" > > This version works fine without tag prefix; it toggles new-ness on > the current message, the cursor doesn't move, and then it deletes > the message under the cursor. > > It does exactly the same thing with tag-prefix, though, > unfortunately. > > There's no way to fix that except to make a tag-specific version: > > macro index ,D "<tag-prefix><toggle-new><tag-prefix><delete-message>" > "Read and Delete Tagged Messages" > > This would be called with ",D" after you've tagged what you want, > not ";,D". You'll notice that this doesn't touch the resolve > variable at all; that's because operating on tagged messages > doesn't trigger resolve (i.e. doesn't advance the cursor whether > resolve is set or not), so it's not relevant. > > Another issue is that when you save a message, tags are removed. > Let's say that you want to save a message to a folder but not > delete it. This turns out to require complexity in both the > tagged and untagged cases, but complexity of different kinds. > > Here's the untagged version, which uses only tricks we've > previously discussed: > > macro index ,p "<enter-command>unset > resolve<enter><save-message>=spam<enter><undelete-message><enter-command>set > resolve<enter>" "Save and undelete message" > > This works just fine. If you try to do this with tag-prefix, > though: > > macro index ,P > "<tag-prefix><save-message>=spam<enter><tag-prefix><undelete-message>" "Save > and undelete message" > > you'll find that the messages are still deleted, and the message > under the cursor gets undeleted. This is because the act of > saving or deleting untags all relevant messages. The fix is like > so: > > macro index ,q "<enter-command>unset > delete_untag<enter><<tag-prefix><save-message>=spam<enter><tag-prefix><undelete-message><enter-command>set > delete_untag<enter><" "Save and undelete message" > > Unsetting that variable turns off the untag-on-deletion behaviour > (which is also how thnigs get untagged on save). > > So you end up with a prefix-based version and a single-mail > version, and both work, but the semantics of the two are quite > distinct. > > -Robin > -- http://singinst.org/ : Our last, best hope for a fantastic future. .i ko na cpedu lo nu stidi vau loi jbopre .i danfu lu na go'i li'u .e lu go'i li'u .i ji'a go'i lu na'e go'i li'u .e lu go'i na'i li'u .e lu no'e go'i li'u .e lu to'e go'i li'u .e lu lo mamta be do cu sofybakni li'u
