<?xml version="1.0" encoding="UTF-8"?>
<article id="Plugins">
  <title>Plugins<indexterm>
      <primary>plugins</primary>
    </indexterm></title>

  <para>WinMerge plugins are custom dlls or scriptlets, written in the COM API,
  that preprocess data before a comparison. For example, you can use a plugin to
  extract text data from MS Word files for WinMerge to compare.</para>
  
  <para>Each plugin is:<indexterm>
      <primary>installing plugins</primary>
    </indexterm></para>

  <itemizedlist>
    <listitem>
      <para>A single dll or a scriptlet (<filename
      class="extension">sct</filename>) file</para>
    </listitem>

    <listitem>
      <para>Installed in the <filename class="directory">MergePlugins</filename>
      subfolder. A number of plugins can be installed for you by WinMerge.</para>
    </listitem>

    <listitem>
      <para>Easy to install: To install a plugin that is not included in the
      WinMerge installation, just copy the plugin file to <filename
      class="directory">MergePlugins</filename>. The plugin is available the
      next time you open WinMerge. You can find more plugins on the web, written
	  by other developers.</para>
    </listitem>
  </itemizedlist>

  <section>
    <title>Plugin Types</title>

    <para>Plugins are grouped into three main categories:</para>

    <variablelist>
      <varlistentry>
        <term>Editor complement<indexterm>
            <primary>editor complement plugins</primary>
          </indexterm></term>

        <listitem>
          <para>This type of plugin performs custom operations on selected text
          in the active editor (File pane) of the File Compare window.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Unpacker: transform a file to a text format<indexterm>
            <primary>unpacker plugins</primary>
          </indexterm></term>

        <listitem>
          <para>This type of plugin transforms a compressed file to a viewable
          format by decompressing it. The original file is not changed: a
          temporary transformed file is created and loaded in WinMerge.</para>

          <para>Unpacker plugins operate on entire files, not to selected text
          or diffs within files. Therefore, they are available only when you
          launch file comparisons, from either the Folder Compare window or the
          Select Files or Folders dialog. Unpacker plugins are not available in
          the File Compare window.</para>

          <para>Sometimes the unpacked file can be repacked (see the details in
          <xref linkend="Plugins_available" /> to check whether a plugin
          supports repacking). Then, you can merge and save the transformed
          file. The packing is done automatically in this case. To be safe, we
          suggest that you rename the transformed file when you save it.</para>

          <note>
            <para>When you compare folders, WinMerge can give different results
            for compressed and uncompressed files. For example, files that are
            identical when uncompressed might be different if they include the
            creation date. WinMerge applies the unpacker in all situations, and
            you are sure to have the same result when you compare a folder, or
            when you merge two versions of a file.</para>
          </note>

          <para>Example plugin: <xref linkend="CompareMSExcelFiles" />
          Displays the text contents of a 
          <trademark class="registered">Microsoft</trademark>
          <application>Excel</application> file.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Prediffer: preprocess files to hide some differences<indexterm>
            <primary>prediffer plugins</primary>
          </indexterm></term>

        <listitem>
          <para>This type of plugin does not operate on the source files
          displayed in the Compare window. It operates instead on temporary
          copies of the files, and the copies are then scanned to create the
          difference list.</para>

          <para>Example plugin: <xref linkend="IgnoreColumns" /> ignores the
          differences inside specified columns, while displaying the characters
          in these columns.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </section>

  <section>
    <title>Suggested plugins and automatic modes</title>

    <para>How is WinMerge able to apply the right plugin for a given file? Each
    plugin specifies a list of file extensions (also listed in each plugin's
    <xref linkend="Plugins_available" /> section, under <citetitle>File
    filter</citetitle>). The extensions are used to associate one or more file
    types with the plugin: when a compared file's extension matches an extension
    in the plugin's list, the plugin is considered to be a <firstterm>suggested
    plugin. </firstterm></para>

    <para>There are separate WinMerge options for the unpacking and prediffer
    types, described later in this topic, that enable you to apply the plugins
    either manually or automatically. There is no automatic mode for editor
    complement plugins.</para>

    <para>When you apply plugins to a selected file using automatic mode,
    WinMerge searches its list of suggested plugins for that file type, and
    applies the first plugin whose name matches. The search is performed in
    alphabetical order, so if there are multiple suggested plugins for a file
    type, only the first one found is applied.</para>
  </section>

  <section>
    <title>Applying plugins</title>

    <para>The following subsections describe how to apply each type of plugin.
    The methods are different for each type of plugin, and also vary depending
    on whether you are comparing folders or files.</para>

    <section>
      <title>Applying editor complement plugins in the File Compare
      window</title>

      <para>With your cursor in either File pane of the File Compare window,
      click <menuchoice>
          <guimenu>Plugins</guimenu>

          <guisubmenu>Scripts</guisubmenu>
        </menuchoice> and choose one of these functions:</para>

      <itemizedlist>
        <listitem>
          <para><function>MakeUpper</function></para>
        </listitem>

        <listitem>
          <para><function>MakeLower</function></para>
        </listitem>

        <listitem>
          <para><function>SortAscending</function></para>
        </listitem>

        <listitem>
          <para><function>SortDescending</function></para>
        </listitem>

        <listitem>
          <para><function>ExecFilterCommand</function></para>
        </listitem>

        <listitem>
          <para><function>InsertDate</function></para>
        </listitem>

        <listitem>
          <para><function>InsertTime</function></para>
        </listitem>
      </itemizedlist>

      <para>The functions are contributed to the
      <guisubmenu>Scripts</guisubmenu> menu by the <xref
      linkend="EditorAddin" /> and <xref linkend="Plugins_datetime" />
      plugins.</para>

      <note>
        <para>Editor complement plugins are not available in the Folder Compare
        window.</para>
      </note>
    </section>

    <section>
      <title>Applying unpacker plugins in the Folder Compare window</title>

      <para>Before applying unpacker plugins, you can set its mode to either
      automatic or manual mode.</para>

      <itemizedlist>
        <listitem>
          <para>To set automatic mode for this type of plugin, click <menuchoice>
              <guimenu>Plugins</guimenu>

              <guimenuitem>Automatic Unpacking</guimenuitem>
            </menuchoice>.</para>
        </listitem>

        <listitem>
          <para>To set manual mode, click <menuchoice>
              <guimenu>Plugins</guimenu>

              <guimenuitem>Manual Unpacking</guimenuitem>
            </menuchoice>.</para>
        </listitem>
      </itemizedlist>

      <para>Remember to click <keycap>F5</keycap> to reload the Folder Compare
      window using the new setting.</para>

      <section>
        <title>Using automatic mode</title>

        <para>To apply plugins when automatic unpacking is set, simply launch a
        compare operation on a file in the Folder Compare window. If the file's
        type suggested unpacker plugin (if any) preprocesses the file before
        WinMerge opens it in the File Compare window.</para>

        <para>For example, suppose you right-click an MS Word
        <filename>doc</filename> file and choose
        <guimenuitem>Compare</guimenuitem> (also assume that the <xref
        linkend="Plugins_msword" /> plugin is available). WinMerge converts the
        doc file (or rather, a copy of it ) to a plain text file and opens it in
        the File Compare window.</para>
      </section>

      <section>
        <title>Using manual mode</title>

        <para>Manual mode enables you to choose a different unpacker plugin than
        the one that is selected for you in automatic mode. You can also launch
        the compare using no plugin.</para>

        <para>To apply plugins when manual unpacking is set:</para>

        <orderedlist>
          <listitem>
            <para>Select the file you want to compare.</para>
          </listitem>

          <listitem>
            <para>Click <menuchoice>
                <guimenu>Plugins</guimenu>

                <guimenuitem>Edit with Unpacker</guimenuitem>
              </menuchoice>.</para>

            <para>This menu item is enabled only if the selected file's type is
            supported by an available unpacking plugin.</para>
          </listitem>

          <listitem>
            <para>In the Select Unpacker dialog:</para>

            <xi:include href="select_unpacker.xml"
                        xmlns:xi="http://www.w3.org/2001/XInclude"
                        xpointer="element(select-unpacker-proc)" />
          </listitem>

          <listitem>
            <para>Click <guibutton>OK</guibutton> to close the Select Unpacker
            dialog and launch the file comparison.</para>
          </listitem>
        </orderedlist>
      </section>
    </section>

    <section>
      <title>Applying unpacker plugins in the Select Files or Folders
      dialog</title>

      <para>You can use the Select Unpacker dialog to apply a plugin when you
      launch a file comparison from the Select Files or Folders dialog. See
      <xref linkend="Open_paths_unpacker" /> for details.</para>
    </section>

    <section>
      <title>Applying prediffer plugins in the Folder Compare window</title>

      <para>With prediffer plugins, you set the mode (<firstterm>Auto
      prediiffer</firstterm> or <firstterm>No prediffer</firstterm>) for
      individual files. (Contrast this with unpacker plugins, where you set the
      mode for all files.) That is, some files in the same folder have different
      prediffer modes.</para>

      <para>To set the mode for one or more files in the Folder Compare window,
      right-click the files and choose <menuchoice>
          <guimenu>Plugin Settings</guimenu>

          <guisubmenu>Prediffer Settings</guisubmenu>
        </menuchoice>, then choose one of the submenu options:</para>

      <itemizedlist>
        <listitem>
          <para><guisubmenu>Auto Prediffer</guisubmenu> selects the first
          prediffer plugin available for the file type.</para>
        </listitem>

        <listitem>
          <para><guisubmenu>No prediffer</guisubmenu> means that no prediffer
          plugin is used.</para>
        </listitem>
      </itemizedlist>

      <para>Click <keycap>F5</keycap> to update the window.</para>

      <note>
        <para>When you open a subfolder during a non-recursive compare, the mode
        is always reset to <guimenuitem>No prediffer</guimenuitem>.</para>
      </note>

      <para>When you open a file from the Folder Compare window, your prediffer
      setting for that file is applied before the File Compare window is
      opened.</para>
    </section>

    <section>
      <title>Applying prediffer plugins in the File Compare window</title>

      <para>In the File Compare winodw, you can apply a prediffer plugin by
      clicking <menuchoice>
          <guimenu>Plugins</guimenu>

          <guisubmenu>Prediffer</guisubmenu>
        </menuchoice> and choosing one of the plugins in the list. Suggested
      plugins are indicated at the top of the list. The files are compared again
      after the plugin is applied, so you don't need to rescan the files.</para>
    </section>
  </section>

  <section id="Plugins_available">
    <title>Available plugins<indexterm>
        <primary>Visual Basic dlls for plugins</primary>
      </indexterm><indexterm>
        <primary>plugins</primary>

        <secondary>Visual Basic dlls</secondary>
      </indexterm></title>

    <section id="CompareMSExcelFiles">
      <title><filename>CompareMSExcelFiles.sct<indexterm>
          <primary>CompareMSExcelFiles.sct plugin file</primary>
        </indexterm></filename></title>

      <para>Displays the text contents of a <trademark
      class="registered">Microsoft</trademark> <application>Excel</application>
      file, stripping away all formatting and embedded objects.</para>

      <para><segmentedlist>
          <segtitle>Category</segtitle>

          <segtitle>File filter</segtitle>

          <segtitle>Packing</segtitle>

          <segtitle>Settings dialog support</segtitle>

          <segtitle>Dependency</segtitle>

          <seglistitem>
            <seg>Unpacker</seg>

            <seg><filename class="extension">*.xls</filename><filename
            class="extension">*.xlsx</filename><filename
            class="extension">*.xlsm</filename><filename
            class="extension">*.xlsb</filename><filename
            class="extension">*.xla</filename><filename
            class="extension">*.xlax</filename><filename
            class="extension">*.xltx</filename><filename
            class="extension">*.xltm</filename></seg>

            <seg>No</seg>

            <seg>Yes</seg>

            <seg><trademark class="registered">Microsoft</trademark>
            <application>Excel</application></seg>
          </seglistitem>
        </segmentedlist></para>
    </section>

    <section id="Plugins_msword">
      <title><filename>CompareMSWordFiles.sct<indexterm>
          <primary>CompareMSWordFiles.sct plugin file</primary>
        </indexterm></filename></title>

      <para>Displays the text content of a <trademark
      class="registered">Microsoft</trademark> <application>Word</application>
      file, stripping away all formatting and embedded objects.</para>

      <para><segmentedlist>
          <segtitle>Category</segtitle>

          <segtitle>File filter</segtitle>

          <segtitle>Packing</segtitle>

          <segtitle>Settings dialog support</segtitle>

          <segtitle>Dependency</segtitle>

          <seglistitem>
            <seg>Unpacker</seg>

	    <seg><filename class="extension">*.doc</filename>, <filename
            class="extension">*.docx</filename>, <filename
            class="extension">*.docm</filename>, <filename
            class="extension">*.dot</filename>, <filename
            class="extension">*.dotx</filename>, <filename
            class="extension">*.dotm</filename></seg>

            <seg>No</seg>

            <seg>Yes</seg>

            <seg><trademark class="registered">Microsoft</trademark>
            <application>Word</application></seg>
          </seglistitem>
        </segmentedlist></para>
    </section>

    <section id="Plugins_powerpnt">
      <title><filename>CompareMSPowerPointFiles.sct<indexterm>
          <primary>CompareMSPowerPointFiles.sct plugin file</primary>
        </indexterm></filename></title>

      <para>Displays the text content of a <trademark
      class="registered">Microsoft</trademark> <application>PowerPoint</application>
      file, stripping away all formatting and embedded objects.</para>

      <para><segmentedlist>
          <segtitle>Category</segtitle>

          <segtitle>File filter</segtitle>

          <segtitle>Packing</segtitle>

          <segtitle>Settings dialog support</segtitle>

          <segtitle>Dependency</segtitle>

          <seglistitem>
            <seg>Unpacker</seg>

            <seg><filename class="extension">*.ppt</filename>, <filename
            class="extension">*.pptx</filename>, <filename
            class="extension">*.pptm</filename>, <filename
            class="extension">*.ppa</filename>, <filename
            class="extension">*.ppam</filename>, <filename
            class="extension">*.pot</filename>, <filename
            class="extension">*.potx</filename>, <filename
            class="extension">*.potm</filename></seg>

            <seg>No</seg>

            <seg>Yes</seg>

            <seg><trademark class="registered">Microsoft</trademark>
            <application>PowerPoint</application></seg>
          </seglistitem>
        </segmentedlist></para>
    </section>

    <section id="EditorAddin">
      <title><filename>editor addin.sct<indexterm>
          <primary>editor addin.sct plugin file</primary>
        </indexterm></filename></title>

      <para>Adds five functions to the <menuchoice>
          <guimenu>Plugins</guimenu>

          <guisubmenu>Scripts</guisubmenu>
        </menuchoice> menu:</para>

      <itemizedlist>
        <listitem>
          <simpara><guimenuitem>MakeUpper</guimenuitem> convert the selection to
          UPPER CASE.</simpara>
        </listitem>

        <listitem>
          <simpara><guimenuitem>MakeLower</guimenuitem> convert the selection to
          lower case.</simpara>
        </listitem>

        <listitem>
          <simpara><guimenuitem>SortAscending</guimenuitem> sort the selection 
          in ascending order.</simpara>
        </listitem>

        <listitem>
          <simpara><guimenuitem>SortDescending</guimenuitem> sort the selection 
          in descending order.</simpara>
        </listitem>

        <listitem>
          <simpara><guimenuitem>ExecFilterCommand</guimenuitem> replace the selection 
          with the output of the specified filter command.</simpara>
        </listitem>
      </itemizedlist>

      <para><segmentedlist>
          <segtitle>Category</segtitle>
          <segtitle>Settings dialog support</segtitle>

          <seglistitem>
            <seg>Editor complement</seg>
            <seg>No</seg>
          </seglistitem>
        </segmentedlist></para>
    </section>

    <section id="IgnoreColumns">
      <title><filename>IgnoreColumns.dll<indexterm>
          <primary>IgnoreColumns.dll plugin file</primary>
        </indexterm></filename></title>

      <para>This plugin ignores characters at specified columns. The first
      column is number 1</para>

      <para>Note that this plugin does not support files with tabs: the plugin
      does not fail, but all tabs are be treated as normal characters.</para>

      <para>To specify columns, use plugin settings dialog or rename the <filename>dll</filename> using
      following fields as parameters:</para>

      <itemizedlist>
        <listitem>
          <simpara>Delimiters between ranges: _ or ,</simpara>
        </listitem>

        <listitem>
          <simpara>Delimiters between min and max: <emphasis>anything
          else</emphasis></simpara>
        </listitem>

        <listitem>
          <simpara>Min and max are included.</simpara>
        </listitem>

        <listitem>
          <simpara>When max = min, max can be omitted.</simpara>
        </listitem>
      </itemizedlist>

      <example>
        <title><filename>IgnoreColumns.dll</filename> examples</title>

        <variablelist>
          <varlistentry>
            <term><filename>IgnoreColumns _ 3 _ 10 - 20 _ 32 -
            33.dll</filename></term>

            <listitem>
              <simpara>Ignore all characters at column 3, and in columns 10 to
              20, and 32 to 33.</simpara>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><filename>IgnoreColumns_1,30 to 40.dll</filename></term>

            <listitem>
              <simpara>Ignore all the characters in column 1, and in columns 30
              to 40.</simpara>
            </listitem>
          </varlistentry>
        </variablelist>
      </example>

      <para><segmentedlist>
          <segtitle>Category</segtitle>

          <segtitle>File filter</segtitle>

          <segtitle>Settings dialog support</segtitle>

          <seglistitem>
            <seg>Prediffer</seg>

            <seg><filename class="extension">*.txt</filename></seg>

            <seg>Yes</seg>
          </seglistitem>
        </segmentedlist></para>
    </section>

    <section>
      <title><filename>IgnoreCommentsC.dll<indexterm>
          <primary>IgnoreCommentsC.dll plugin file</primary>
        </indexterm></filename></title>

      <para>The plugin ignores comments within<constant> //</constant>... and
      <constant>/*</constant> ... <constant>*/</constant> delimiters in C, C++,
      PHP and JavaScript files.</para>

      <para><segmentedlist>
          <segtitle>Category</segtitle>

          <segtitle>File filter</segtitle>

          <segtitle>Settings dialog support</segtitle>

          <seglistitem>
            <seg>Prediffer</seg>

            <seg><filename class="extension">*.cpp</filename>, <filename
            class="extension">*.cxx</filename>, <filename
            class="extension">*.h</filename>, <filename
            class="extension">*.hxx</filename>, <filename
            class="extension">*.c</filename>, <filename
            class="extension">*.php</filename>, <filename
            class="extension">*.js</filename>,</seg>

            <seg>No</seg>
          </seglistitem>
        </segmentedlist></para>
    </section>

    <section>
      <title><filename>IgnoreFieldsComma.dll<indexterm>
          <primary>IgnoreFieldsComma.dll plugin file</primary>
        </indexterm></filename></title>

      <para>This plugin is for files with fields and commas as delimiters (CSV
      files, for example). It ignores the delimiter characters. The first field
      is number 1.</para>

      <para>To specify the delimiters, use plugin settings dialog or rename the <filename>dll</filename> using
      the same parameter fields used for <xref
      linkend="IgnoreColumns" />.</para>

      <para><segmentedlist>
          <segtitle>Category</segtitle>

          <segtitle>File filter</segtitle>

          <segtitle>Settings dialog support</segtitle>

          <seglistitem>
            <seg>Prediffer</seg>

            <seg><filename class="extension">*.csv</filename></seg>

            <seg>Yes</seg>
          </seglistitem>
        </segmentedlist></para>
    </section>

    <section>
      <title><filename>IgnoreFieldsTab.dll<indexterm>
          <primary>IgnoreFieldsTab.dll plugin file</primary>
        </indexterm></filename></title>

      <para>This plugin is for files that use fields and tabs as delimiters
      (<application>for examle, Excel</application> files saved in the <filename
      class="extension">*.txt</filename> format). It ignores the delimiter
      characters. The first field is number 1.</para>

      <para>To specify the delimiters, use plugin settings dialog or rename the <filename>dll</filename> using
      the same parameter fields used for <xref
      linkend="IgnoreColumns" />.</para>

      <para><segmentedlist>
          <segtitle>Category</segtitle>

          <segtitle>File filter</segtitle>

          <segtitle>Settings dialog support</segtitle>

          <seglistitem>
            <seg>Prediffer</seg>

            <seg><filename class="extension">*.txt</filename></seg>

            <seg>Yes</seg>
          </seglistitem>
        </segmentedlist></para>
    </section>

    <section>
      <title><filename>IgnoreLeadingLineNumbers.dll<indexterm>
          <primary>IgnoreLeadingLineNumbers.dll plugin file</primary>
        </indexterm></filename></title>

      <para>This plugin ignores the leading line numbers in text files (for
      example, NC and BASIC files).</para>

      <para><segmentedlist>
          <segtitle>Category</segtitle>

          <segtitle>File filter</segtitle>

          <segtitle>Settings dialog support</segtitle>

          <segtitle>Requirement</segtitle>

          <seglistitem>
            <seg>Prediffer</seg>

            <seg><filename class="extension">*.nc</filename></seg>

            <seg>No</seg>

            <seg><xref linkend="MSVBVM60" /></seg>
          </seglistitem>
        </segmentedlist></para>
    </section>

    <section id="Plugins_datetime">
      <title><filename>insert datetime.sct<indexterm>
          <primary>insert datetime.sct plugin file</primary>
        </indexterm></filename></title>

      <para>Adds two functions to the <menuchoice>
          <guimenu>Plugins</guimenu>

          <guisubmenu>Scripts</guisubmenu>
        </menuchoice> menu:</para>

      <itemizedlist>
        <listitem>
          <simpara><guimenuitem>InsertDate</guimenuitem> insert date in the
          current locale format.</simpara>
        </listitem>

        <listitem>
          <simpara><guimenuitem>InsertTime</guimenuitem> insert time in the
          current locale format.</simpara>
        </listitem>
      </itemizedlist>

      <para><segmentedlist>
          <segtitle>Category</segtitle>

          <segtitle>Settings dialog support</segtitle>

          <seglistitem>
            <seg>Editor complement</seg>

            <seg>No</seg>
          </seglistitem>
        </segmentedlist></para>
    </section>
  </section>

  <section>
    <title>Requirements<indexterm>
        <primary>plugins</primary>

        <secondary>Windows Script Host requirement</secondary>
      </indexterm></title>

    <section>
      <title>Windows Script Host</title>

      <para>Some editor complement plugins require this optional component from
      <trademark class="registered">Microsoft</trademark>.</para>

      <para>It should already be included in your version of Windows, 
	  unless you use some really old pre Windows XP version.</para>
    </section>

    <section id="MSVBVM60">
      <title><application>Visual Basic</application> runtime library<indexterm>
          <primary>Visual Basic dlls for plugins</primary>
        </indexterm><indexterm>
          <primary>plugins</primary>

          <secondary>Visual Basic dlls</secondary>
        </indexterm><indexterm>
          <primary>msvbvm60.dll plugin file</primary>
        </indexterm><indexterm>
          <primary>Run-Time Redistribution Pack, for Visual Basic
          library</primary>
        </indexterm></title>

      <para>Some plugins require <application>the Visual Basic</application>
      runtime library to work.</para>

      <para>You can use the <ulink
      url="https://www.microsoft.com/en-us/download/details.aspx?id=24417">Run-Time
      Redistribution Pack</ulink> from <trademark
      class="registered">Microsoft</trademark>. If you don't need the plugin,
      you can safely remove it.</para>
    </section>
  </section>
</article>
