added formats, and some copypasta from default.theme comments into theme

1 files changed, 56 insertions, 0 deletions

diff --git a/docs/Irssi/UI/Theme.pod b/docs/Irssi/UI/Theme.pod
index 56e3a3f..4fff169 100644
--- a/docs/Irssi/UI/Theme.pod
+++ b/docs/Irssi/UI/Theme.pod
@@ -1,3 +1,5 @@
+__END__
+
 =head1 NAME
 
 Irssi::UI::Theme
@@ -6,3 +8,57 @@ Irssi::UI::Theme
 
 =head1 METHODS
 
+=head1 THEME DOCUMENTATION
+
+When testing changes, the easiest way to reload the theme is with /RELOAD.
+This reloads the configuration file too, so if you did any changes remember
+to /SAVE it first. Remember also that /SAVE overwrites the theme file with
+old data so keep backups :)
+
+=head2 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 C</FORMAT>s 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 C<{blahblah}> parts you see all over the
+/FORMATs and here. Their usage is simply C<{name parameter1 parameter2}>.
+
+When irssi sees this kind of text, it goes to find "name" from abstracts block
+below and sets C<parameter1> into C<$0> and C<parameter2> into C<$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 C<$0->, why not C<$0>? C<$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).
+
+=head2 COLORS
+
+You can find definitions for the color format codes in L<Formats>
+
+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. If you _really_ want
+to use the terminal's default color, use %N.