more comments

git-svn-id: http://svn.irssi.org/repos/irssi/trunk@1095 dbcabf3a-b0e7-0310-adc4-f8d773084564

default.theme

@@ -3,15 +3,53 @@
 # to /SAVE it first. Remember also that /SAVE overwrites the theme file with
 # old data so keep backups :)
 
+# TEMPLATES:
+
+# The real text formats that irssi uses are the ones you can find with
+# /FORMAT command. Back in the old days all the colors and texts were mixed
+# up in those formats, and it was really hard to change the colors since you
+# might have had to change them in tens of different places. So, then came
+# this templating system.
+
+# Now the /FORMATs don't have any colors in them, and they also have very
+# little other styling. Most of the stuff you need to change is in this
+# theme file. If you can't change something here, you can always go back
+# to change the /FORMATs directly, they're also saved in these .theme files.
+
+# So .. the templates. They're those {blahblah} parts you see all over the
+# /FORMATs and here. Their usage is simply {name parameter1 parameter2}.
+# When irssi sees this kind of text, it goes to find "name" from abstracts
+# block below and sets "parameter1" into $0 and "parameter2" into $1 (you
+# can have more parameters of course). Templates can have subtemplates.
+# Here's a small example:
+#   /FORMAT format hello {colorify {underline world}}
+#   abstracts = { colorify = "%G$0-%n"; underline = "%U$0-%U"; }
+# When irssi expands the templates in "format", the final string would be:
+#   hello %G%Uworld%U%n
+# ie. underlined bright green "world" text.
+# and why "$0-", why not "$0"? $0 would only mean the first parameter,
+# $0- means all the parameters. With {underline hello world} you'd really
+# want to underline both of the words, not just the hello (and world would
+# actually be removed entirely).
+
+# COLORS:
+
+# You can find definitions for the color format codes in docs/formats.txt.
+
+# There's one difference here though. %n format. Normally it means the
+# default color of the terminal (white mostly), but here it means the
+# "reset color back to the one it was in higher template". For example
+# if there was /FORMAT test %g{foo}bar, and foo = "%Y$0%n", irssi would
+# print yellow "foo" (as set with %Y) but "bar" would be green, which was
+# set at the beginning before the {foo} template. If there wasn't the %g
+# at start, the normal behaviour of %n would occur.
+
+#############################################################################
+
 # these characters are automatically replaced with specified color
+# (dark grey by default)
 replaces = { "[]<>=" = "%K$0-%n"; };
 
-# %n specifies the color set in higher level, like in
-#   {ctcp {nick $0-} requested ... }
-# if the ctcp was specified as "%g$0-" and nick was "%W$0-%n", the
-# "requested" text would be green
-
-# information about the %format is found from docs/formats.txt
 abstracts = {
   ##
   ## generic
@@ -124,16 +162,27 @@ abstracts = {
   privmsgnick = "{msgnick  %R$0-%n}";
 
   ##
-  ## other IRC events
+  ## Actions (/ME stuff)
   ##
 
-  # actions
+  # generic one that's used by most actions
   action = "%W * $0-%n ";
+
+  # own action, both private/public
   ownaction = "{action $0-}";
+
+  # private action sent by others
   pvtaction = "%W (*) $0-%n ";
   pvtaction_query = "{action $0-}";
+
+  # public action sent by others
   pubaction = "{action $0-}";
 
+
+  ##
+  ## other IRC events
+  ##
+
   # notices
   ownnotice = "[%r$0%K(%R$1-%K)]%n ";
   notice = "%K-%M$0-%K-%n ";
@@ -166,9 +215,11 @@ abstracts = {
   dcc = "%g$0-%n";
   dccfile = "%_$0-%_";
 
-  # DCC chat
+  # DCC chat, own msg/action
   dccownmsg = "[%r$0%K(%R$1-%K)%n] ";
   dccownaction = "{action $0-}";
+
+  # DCC chat, others
   dccmsg = "[%G$1-%K(%g$0%K)%n] ";
   dccquerynick = "%G$0-%n";
   dccaction = "%W (*dcc*) $0-%n %|";