weechat/doc/en/user/plugin_logger.en.xml

<?xml version="1.0" encoding="UTF-8"?>

<!--

WeeChat documentation (english version)

Copyright (c) 2003-2009 by FlashCode <flashcode@flashtux.org>

This manual is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 3 of the License, or
(at your option) any later version.

This manual is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.

-->

<section id="secPluginLogger">
  <title>Logger plugin</title>
  
  <para>
    The Logger plugin lets you save content of buffers to files, with options
    about what and how it is saved.
  </para>
  
  <section id="secLoggerOptions">
    <title>Options (file logger.conf)</title>
    
    <para>
      &logger_options.xml;
    </para>
    
  </section>
  
  <section id="secLoggerCommands">
    <title>Commands</title>
    
    <para>
      &logger_commands.xml;
    </para>
    
  </section>
  
  <section id="secLoggerInfosHooked">
    <title>Infos and infolists</title>
    
    <para>
      <informaltable colsep="0" frame="none">
        <tgroup cols="3">
          <thead>
            <row>
              <entry>Type</entry>
              <entry>Name</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>
            &logger_infos.xml;
          </tbody>
        </tgroup>
      </informaltable>
    </para>
    
  </section>
  
  <section id="secLoggerLevels">
    <title>Levels</title>
    
    <para>
      Logging is made with a level for each buffer. Default level is 9 (log
      all messages displayed on buffer).
      You can change level for one buffer, or a group of buffers.
    </para>
    
    <para>
      Possible levels are 0 to 9. Zero means "<literal>do not log
      anything</literal>" and 9 means "<literal>log all messages</literal>".
    </para>
    
    <para>
      Plugins are using different levels for messages displayed.
      IRC plugin uses following levels:
      <itemizedlist>
        <listitem>
          <para>
            Level 1: message from user (on channel or private)
          </para>
        </listitem>
        <listitem>
          <para>
            Level 2: nick change (you or someone else)
          </para>
        </listitem>
        <listitem>
          <para>
            Level 3: any server message (except join/part/quit)
          </para>
        </listitem>
        <listitem>
          <para>
            Level 4: server message join/part/quit
          </para>
        </listitem>
      </itemizedlist>
      So if you set level 3 for an IRC channel, WeeChat will log all messages,
      but not join/part/quit.
    </para>
    
    <para>
      Some examples:
      <itemizedlist>
        <listitem>
          <para>
            set level 3 for IRC channel #weechat:
            <screen>/set logger.level.irc.freenode.#weechat 3</screen>
          </para>
        </listitem>
        <listitem>
          <para>
            set level 3 for freenode server buffer:
            <screen>/set logger.level.irc.server.freenode 3</screen>
          </para>
        </listitem>
        <listitem>
          <para>
            set level 3 for all channels on server freenode:
            <screen>/set logger.level.irc.freenode 3</screen>
          </para>
        </listitem>
        <listitem>
          <para>
            set level 2 for all IRC buffers:
            <screen>/set logger.level.irc 2</screen>
          </para>
        </listitem>
      </itemizedlist>
    </para>
    
  </section>
  
  <section id="secLoggerMasks">
    <title>Filename masks</title>
    
    <para>
      It is possible to define a filename mask for each buffer, and use local
      buffer variables to build filename (to see local variables for current
      buffer: <command>/buffer localvar</command>).
    </para>
    
    <para>
      For example if you want one directory by IRC server and one file by
      channel inside:
      <screen>/set logger.mask.irc "irc/$server/$channel.weechatlog"</screen>
      You'll have following files:
<screen>
~/.weechat/
    |--- logs/
        |--- irc/
            |--- freenode/
            |       freenode.weechatlog
            |       #weechat.weechatlog
            |       #mychan.weechatlog
            |--- oftc/
            |       oftc.weechatlog
            |       #chan1.weechatlog
            |       #chan2.weechatlog
</screen>
    </para>
    
  </section>
  
</section>