<?xml version="1.0" encoding="UTF-8"?>
<sect1 id="Filters">
  <title>フィルタ</title>

  <para>There are two kinds of filters in WinMerge: file filters for filtering
  files and folders in folder compare and line filters for ignoring lines from
  files before comparing.</para>

  <sect2>
    <title>正規表現</title>

    <para>Filters are based on regular expressions (regexps). Each line filter
    or file filter rule is regexp which is matched against file/folder name or
    line.</para>

    <para>Regexps can be very complex to read. Luckily most file filtering
    needs are for file extensions. File filters installed with WinMerge have
    many useful examples.</para>

    <para>WinMerge uses popular PCRE (Perl Compatible Regular Expressions)
    regular expression engine. There are lots of resources for help with Perl
    regular expression.</para>

    <sect3>
      <title>正規表現のヘルプ</title>

      <para>There are many guides and help sites in Web, for example:</para>

      <variablelist>
        <varlistentry>
          <term>Good site devoted for regexps:</term>

          <listitem>
            <simpara><ulink
            url="http://www.regular-expressions.info/">http://www.regular-expressions.info/</ulink></simpara>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Good HOWTO document for regexps:</term>

          <listitem>
            <simpara><ulink
            url="http://www.amk.ca/python/howto/regex/">http://www.amk.ca/python/howto/regex/</ulink></simpara>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Tutorial:</term>

          <listitem>
            <simpara><ulink
            url="http://www.zvon.org/other/PerlTutorial/Output/index.html">http://www.zvon.org/other/PerlTutorial/Output/index.html</ulink></simpara>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>PDF quick reference:</term>

          <listitem>
            <simpara><ulink
            url="http://www.night-ray.com/regex.pdf">http://www.night-ray.com/regex.pdf</ulink></simpara>
          </listitem>
        </varlistentry>
      </variablelist>
    </sect3>
  </sect2>

  <sect2>
    <title>ファイルフィルタ</title>

    <para>A file filter is a set of rules saved to one file. Every file and
    folder is tested against all these rules before comparing. Files and
    folders that match the rules are excluded if it is an inclusive filter, or
    included if it is an exclusive filter.</para>

    <tip>
      <para>Ignored items have "<guilabel>Skipped</guilabel>" status in folder
      compare. User can select them to visible or hidden from
      <guimenu>View</guimenu> menu. Usually its wise to keep skipped items
      hidden.</para>
    </tip>

    <para>WinMerge's filtering system allows only one filter set to be active
    at a time. Active filter set can be selected from Open-dialog or from
    menu: <menuchoice>
        <guimenu>Tools</guimenu>

        <guimenuitem>Filters</guimenuitem>
      </menuchoice>. Also empty filter can be selected when no folders or
    files are ignored.</para>

    <para>Filtered out files get only minimal needed attention by the folder
    compare. This means that WinMerge misses a lot of information it gets for
    non-ignored files. For example there is no way to know if filtered file is
    a text file or a binary file. The reason is simple: as user tolds WinMerge
    one does not care about the file, WinMerge tries to minimize the effort
    and time for the file.</para>

    <sect3>
      <title>ファイルのフィルタリング</title>

      <para>Filter files are normal text files, with an extension of <filename
      class="extension">.flt</filename>. Files have defined format which is
      explained later in this chapter. Filters-dialog allows creating new
      filter files based on template file. Filter files can be created from
      the scratch but using template file is the recommended way to create a
      new filter. The template file is named
      <filename>FileFilter.tmpl</filename> and can be modified if needed. The
      template file is located in <filename
      class="directory">WinMerge/Filters</filename> -folder.</para>

      <para>Filter files have two possible locations:</para>

      <itemizedlist>
        <listitem>
          <para>"<filename class="directory">Filters</filename>" subfolder in
          the WinMerge program folder. E.g. <filename
          class="directory">C:\Program
          Files\WinMerge\Filters</filename>.</para>
        </listitem>

        <listitem>
          <para>User-defined folder. Selected in Options (<menuchoice>
              <guimenu>Edit</guimenu>

              <guimenuitem>Options</guimenuitem>

              <guimenuitem>System</guimenuitem>

              <guilabel>Filter Folder</guilabel>
            </menuchoice>). By default it is <filename class="directory"> My
          Documents\WinMerge\Filters</filename> folder.</para>
        </listitem>
      </itemizedlist>

      <important>
        <para>With WinMerge 2.6.0 and later filter files are not anymore
        loaded from profile folder like with earlier versions. Using
        user-defined folder for filter files provides more flexibility and
        easier access to filter files.</para>
      </important>

      <para>First part of filter file defines name and basic functionality of
      the filter:</para>

      <para><screen>name: Example filter
def: include</screen>where <constant>def</constant>: is:<itemizedlist>
          <listitem>
            <para><constant>include</constant> - inclusive filter. This filter
            type filters out files and folders that match rules in
            filter.</para>
          </listitem>

          <listitem>
            <para><constant>exclude</constant> - exclusive filter. This filter
            type lets through files and folders that match rules in
            filter.</para>
          </listitem>
        </itemizedlist>When using exclusive filter its worth noting that the
      filter must contain rule to include all wanted subfolders. Usually its
      wise to use this rule to include all subfolders:</para>

      <screen>d: \\*$ ## Subfolders</screen>

      <para>There can be one filter rule in one line. And rule cannot be split
      to several lines. Common format for one filter line is like this:</para>

      <screen>f: \.ext$ ## Match files *.ext</screen>

      <para>or</para>

      <screen>d: \\folder$ ## Match given folder name</screen>

      <para>Rule begins with "<constant>f:</constant>" if it matches for
      filenames and "<constant>d:</constant>" if it matches for folder names.
      (d comes from "folder".) Filenames are given to filter as is, there are
      no special characters added. Folder names have preceding backslash
      before them (e.g. "\Folder name"). So if folder names are matched by the
      beginning of the name, the filter must start with "\\" to match the
      first backslash. "<constant>##</constant>" is a comment separator, all
      characters in line after that are ignored by WinMerge.</para>

      <para><note>
          <para>File filter rules are case-insensitive. Rule
          <constant>.\bat$</constant> matches to
          <filename>winmerge.bat</filename> and
          <filename>compare.BAT</filename>.</para>
        </note></para>

      <para>So simple filters can be for example:</para>

      <example>
        <title>シンプルなファイルフィルタのルール</title>

        <screen>f: \.cpp$ ## Match *.cpp files
f: \.h$ ## Match *.h files
f: ^My ## Match My*.* files
f: Dlg\. ## Match *Dlg.* files
d: \\test$ ## Match 'test' folders
d: ^\\Build$ ## Match 'Build' folders
d: Temp$ ## Match *Temp folders (e.g. FirstTemp)
d: Src ## Match *Src* folders</screen>
      </example>

      <para>Line begin or -end marker (<constant>"^"</constant> or
      <constant>"$"</constant>) is usually required filter to work correctly.
      Dot in filename must be "escaped" with <constant>"\"</constant> so
      <constant>"\."</constant> means dot in filename.</para>

      <note>
        <para>Don't forget "<constant>$</constant>" at end. It marks end of
        folder- or filename and without it rule may not work like expected.
        While "<literal>\.c$</literal>" matches with only filenames having
        extension <filename class="extension">.c</filename>
        "<literal>\.c</literal>" matches all extensions beginning with
        "<literal>c</literal>" (<filename class="extension">.cpp</filename>,
        <filename class="extension">.com</filename>, etc).</para>
      </note>

      <para>Since file filter rules are regular expressions more complex rules
      are also possible. Following few rules show some possibilities for more
      complex rules:</para>

      <example>
        <title>より複雑なファイルフィルタのルール</title>

        <screen format="linespecific">f: ^\.#.*$ ## .#filename.version files
f: Dlg\.c(pp)?$ ## *Dlg.c &amp; *Dlg.cpp files
f: ^I.*\.h$ ## I*.h files
f: Srv[1-9]\.def$ ## *Srv1.def - *Srv9.def files
f: ^[h,k,m] ## h*.* &amp; k*.* &amp; m*.* files</screen>
      </example>

      <para>WinMerge ignores most whitespace characters in rules definition
      lines. However comment must always start with one or more whitespace
      character (space or tabulator) and comment-marker
      (<constant>##</constant>). <constant>##</constant> can be used as part
      of rule if there is no whitespace character before it.</para>
    </sect3>
  </sect2>

  <sect2>
    <title>行フィルタ</title>

    <para>Line filters can be used to ignore single lines from compared files.
    Line filters are handy when user doesn't want to compare comments or
    certain generated code. For example version control system
    (time)stamps.</para>

    <important>
      <para>Line filter rule ignores single line it matches. It is not
      possible to ignore partial lines or several lines with file filter rule.
      Also, all lines in difference must match the filter so that difference
      is ignored. If only one line of several matches, the difference is not
      ignored.</para>
    </important>

    <para>In file compare ignored differences are shown with own colors to
    differentiate them from other differences. User can see these differences
    but cannot select or merge them.</para>

    <para>Line filter rules are regular expressions like file filter rules.
    Since filter matches if any part of line matches it is usually recommended
    to add begin (<constant>"^"</constant>) or end (<constant>"$"</constant>)
    marker to rule. Or both markers if exact line is wanted to
    filtered.</para>

    <para>Rules can be added and edited in Filters-dialog (Menu: <menuchoice>
        <guimenu>Tools</guimenu>

        <guimenuitem>Filters</guimenuitem>
      </menuchoice>). Type one rule per row to the list. At the beginning of
    the row is a checkbox for enabling / disabling single rules.</para>

    <para>Compare results are not updated automatically after changing line
    filter rules. User can update compare results by selecting <menuchoice>
        <guimenu>Edit</guimenu>

        <guimenuitem>Refresh</guimenuitem>
      </menuchoice> or <keycap>F5</keycap>.</para>

    <example>
      <title>行フィルタの例</title>

      <screen format="linespecific">^MYTAG$</screen>

      <para>- Filters out lines being exactly
      <constant>"MYTAG"</constant></para>

      <screen format="linespecific">^::</screen>

      <para>- Filters out lines beginning with
      <constant>"::"</constant></para>

      <screen format="linespecific">^/\**.\*/$</screen>

      <para>- Filters out lines beginning with <constant>"/*"</constant> and
      ending with <constant>"*/"</constant></para>

      <screen format="linespecific">^[1-5]00</screen>

      <para>- Filters out lines beginning with numbers 100, 200, 300, 400
      &amp; 500</para>
    </example>

    <example>
      <title> CVS "Id:" -行にマッチする行フィルタルール</title>

      <para>Id-lines are like this:</para>

      <screen>// $Id: Filters.xml 4884 2008-01-09 15:42:23Z kimmov $</screen>

      <para>And they can be filtered with rule:</para>

      <screen>^// \WId: .*\$</screen>
    </example>

    <example>
      <title>poファイル内の行番号コメントのフィルタリング</title>

      <para>po line number comments are like this:</para>

      <screen>#: src/filename.c:766</screen>

      <para>And they can be filtered out with rule:</para>

      <screen>^#</screen>
    </example>
  </sect2>
</sect1>
