Changes between Version 1 and Version 2 of DebugConfig

Timestamp:

2012-02-04 14:50:51 (16 months ago)

Author:

rado

Comment:

migrate wiki.mutt.org

DebugConfig

@@ -1 @@
-[http://wiki.mutt.org/?DebugConfig]
+== How to debug mutt config problems ==
+
+The basic principle:
+* '''Start''' with a '''simple''' config that works,
+** Use "mutt -n" to exclude side-effects of a global Muttrc.
+** Use "mutt -F file" for a temporary config-file. (both can be combined)
+* then expand it '''step by step''' with more of your config lines, limit your changes related to only 1 problem at a time: '''isolate, eliminate'''.
+* if you have a big file and can't find the breaking point, 1st drop one half, then the other, repeat in the broken half: '''divide + conquer'''.
+** Always check whether mutt-vars have the desired values by entering "<tt>:set ?var</tt>" at run-time.
+*** TAB-expand mutt varnames until complete, expand their values by adding "=" after the name and hitting TAB again, i.e. without the leading '?'.
+** Simplify or even disable hooks. Read carefully which applies for which task, don't mix 'em up.
+*** Verify that things work without hooks first.
+** Take care of matching quoting chars/ levels -> PatternQuoting!
+** When (error-)messages pass too fast, increase "sleep_time".
+** Compile with "debug" enabled, then run "mutt -d 3 ..." to watch output in ~/.muttdebug...
+** Use shell-scripts in place of external application calls to see whether the app or mutt produces an error and why:
+*** make executable ("man chmod") script: <tt>{ echo "Args = $@"; echo "STDIN blow: ======"; cat ; } > /tmp/mutt-interface</tt>
+*** inspect that file to check arguments and input are ok from mutt,
+*** pass examined data caught by script manually to external application on the cmd-line,
+*** verify output and exitcode of app supposed to be returned to mutt are ok.
+* until you find the error or your config is complete.
+
+* Config not portable across systems:
+** employ the logfile feature described above to see what happens, also dump mutt-vars with "mutt -D",
+** take care to reproduce the execution of functions ''identically'' on both systems and then compare the outputs with "diff".
+** If the logfile and "mutt -D" output is identical, then the system-environments differ in vital detail,\
+   which, however, vary by feature too much to list them all here: see MuttFaq.
+----
+
+Typical problems are caused by:
+* Misunderstanding of how hooks work:
+** they always need a default ("catch-all") pattern/ regex == <tt>'.'</tt>!
+** their order matters and varies by type (especially where defaults go, when "<tt>:set ?var</tt>" fails)!
+*** hooks with filename as target take the '''first hit''' exclusively (default == last),
+*** mutt-cmds as target means '''all''' hits are applied cumulatively, last hook wins (default == first).
+** cmds in hooks are executed when triggered, therefore errors, too, occur later, not at startup.
+** see send-hook vs. send2-hook, maybe the latter can help where the former can't.
+** "folder-hook" for doing stuff ''after changing folders'',
+** "account-hook" to setup account-stuff (like *_user&*_pass) ''before connecting to a site'',
+*** changing folders doesn't require new connections (stay open in background for a while).
+*** some remote sites (which might timeout differently) are checked in background without changing folders (see "mailboxes").
+* Quoting spaces and regexps/ patterns on several levels of nested cmds as args to cmds:
+** "cmd-arg" to hook/ macro must be quoted completely, since hook/ macro takes only 1 token as whole (incl. args of the cmd):
+*** if you want to specify more than 1 cmd as arg, the ";" must be quoted in the cmd-part of the hook/ macro.
+*** example double quoting with '""': <tt>hook 'pattern' 'cmd "param"; cmd2 "param2"'</tt>
+** see MuttGuide/Syntax for what is quoted when and how.
+** PatternQuoting explains how to cope with 2 levels with patterns.
+*** for each nested lvl of cmds as args to cmds you must add an extra lvl of quoting '''for that lvl''': not all chars are special on every lvl.
+* Side-effects by other config files:
+** a global Muttrc with bad defaults for all users: "<tt>mutt -v | grep SYSCONFDIR</tt>" to find it.
+** own files sourced by macros or hooks possibly overwriting vars, when the "<tt>:set ?var</tt>" check fails.
+* Side-effects by 3rd party patches: retry with '''native mutt''' before asking the wrong people, ask patch provider if it's patch-related.
+* Features not enabled in binary: see MuttGuide/Setup to figure out which are enabled and whether you need to build a new binary.
+* Special treatment of '\' line continuation with '#' comments per MuttGuide/Syntax:
+** if you comment lines, make sure you hit the beginning and don't break or oversee \-continuations, especially with hooks.
+* Macros badly defined:
+** use <> notation for functions rather than keystrikes, allows to better detect typos and more portable.
+** remember: macros are a _replay_ of keystrikes you'd normally type manually: always check whether the sequence works manually with '''each key'''!
+* Confusion about use of "set from=..." and "my_hdr", see MuttFaq/Header.
+** "my_hdr" has some issues when interacting with "send-hook" for example, read docs about both.
+----
+Sometimes the problem is not the config but the code: update to the most recent developer version and retry.
+This way you exclude problems with your old version that might have been fixed in the meantime.
+See also reported errors in the bug tracking system on the MuttWiki start page.
+----
+
+Always remember to have a look at MuttFaq if you get stuck somewhere.