<?xml version="1.0" encoding="UTF-8"?>
<sect1 id="Configuration">
  <title>Options &amp; configuration</title>

  <para>Options dialog can be opened from <guimenu>View</guimenu>-menu or from
  toolbar button. Changes made are saved when dialog is closed using
  <guibutton>OK</guibutton>-button (or pressing
  <keycap>Enter</keycap>-key).</para>

  <sect2>
    <title>General options</title>

    <sect3>
      <title>Backup original file</title>

      <para>When this option is enabled backup copy is created before saving
      the file. Filename for backup file is generated by replacing filename
      extension with <filename class="extension">BAK</filename>.</para>
    </sect3>

    <sect3>
      <title>Automatically scroll to first difference</title>

      <para>When this option is enabled:<simplelist>
          <member>after directory compare selection is moved to first
          different files or directories</member>

          <member>after opening files for compare first difference in files is
          scrolled visible and selected</member>
        </simplelist></para>
    </sect3>

    <sect3>
      <title>Disable splash screen</title>

      <para>User can disable splash screen appearing when WinMerge is started.
      It does not make WinMerge start faster (splash screen can be missed by
      clicking it with mouse) but it saves one click.</para>
    </sect3>

    <sect3>
      <title>Close compare statepane automatically</title>

      <para>User can allow WinMerge to close compare statepane automatically
      after directory compare is ready. After compare statuspane is closed it
      can be reopened from <guimenu>View</guimenu>-menu (<guimenuitem>Compare
      Statepane</guimenuitem>).</para>
    </sect3>

    <sect3>
      <title>Close Windows with <keycap>ESC</keycap></title>

      <para>If this option is enabled, WinMerge closes document windows and
      application with <keycap>ESC</keycap> key. One window is closed with one
      keypress, so if user has file compare window open one needs three
      keypresses to close WinMerge: file compare window, directory compare
      window and then the application.</para>
    </sect3>

    <sect3>
      <title>Automatically verify paths in Open-dialog</title>

      <para>When enabled: Open-dialog checks both paths given for validity and
      doesn't enable <guibutton>OK</guibutton> button until both paths are
      valid. Unfortunately this checking needs little delay and some users
      find this delay annoying.</para>

      <para>When disabled: Open-dialog enabled <guibutton>OK</guibutton>
      button by default and lets user to try to open all paths. However error
      message is shown if path is not valid. This is faster to use, there is
      no any delay in enabling <guibutton>OK</guibutton>. But user must look
      at error-dialogs.</para>
    </sect3>

    <sect3>
      <title>Allow only one instance to run</title>

      <para>Limits WinMerge program instances to one. If new instance is tried
      to start, old instance is activated instead. If new instance is tried to
      open with paths, new paths replace existing ones in previous instance.
      Or, if multiple compare window support is enabled new compare windows
      are opened for new paths. (See below.)</para>
    </sect3>

    <sect3>
      <title>Enable multiple compare windows for</title>

      <para>Allows opening multiple folder or file compare windows into one
      WinMerge instance. WinMerge has separate compare documents for folder-
      and file compare and this option allows selecting multi-window support
      for both of them independently.</para>

      <note>
        <para>File compare windows are always related to folder compare
        windows. Even if you disable multiple file compare windows you still
        can open one file compare window for every folder compare
        window.</para>
      </note>
    </sect3>

    <sect3>
      <title>Reset messageboxes (Reset-button)</title>

      <para>WinMerge allows user to hide (suppress) some common messageboxes.
      For example if user doesn't want to see <guilabel>The files are
      identical</guilabel> messagebox every time two identical files are
      opened user can check checkbox in that messagebox and close messagebox.
      Then that messagebox will not be shown again.</para>

      <para>However sometimes user may want to see again those hidden
      messageboxes. Selecting <guibutton>Reset</guibutton> button makes all
      messageboxes visible again.</para>

      <note>
        <para>It is recommended to reset messageboxes when updating to newer
        version of WinMerge. Installer does that automatically but if
        installer is not used then it should be done using this
        <guibutton>Reset</guibutton> button.</para>
      </note>
    </sect3>
  </sect2>

  <sect2>
    <title>Compare options</title>

    <para>Several compare options allow to ignore some specific type of
    differences. This is useful in reducing insignificant differences for
    review purposes.</para>

    <para>Ignored difference is shown with different color and it cannot be
    merged. Difference counts do not include ignored differences. So if files
    contains only ignored differences they are shown as identical in directory
    compare.</para>

    <important>
      <para>Ignoring differences affects merging! If user ignores whitespace
      changes, then e.g. indentation changes in source code files are ignored.
      That means file's indentation gets messed up when merging. It is
      strongly recommended to turn off all difference ignore options before
      merging files!</para>
    </important>

    <sect3>
      <title>Whitespace</title>

      <para><guilabel>Compare Whitespace</guilabel>, <guilabel>Ignore
      whitespace change</guilabel> and <guilabel>Ignore all
      whitespace</guilabel> are three different levels for comparing/ignoring
      whitespace characters.</para>

      <para><guilabel>Ignore whitespace change</guilabel> ignores changes in
      whitespace chars. First three lines in example below illustrate this,
      those three lines are detected as identical if this option is set.
      However change between zero and more whitespace characters is NOT
      ignored. So fourth line is different from first two lines<example>
          <title>Ignore whitespace change</title>

          <para>One space between words:<screen format="linespecific">Two Words</screen></para>

          <para>Two spaces between words:<screen format="linespecific">Two  Words</screen></para>

          <para>Tab between words:<screen format="linespecific">Two	Words</screen></para>

          <para>No spaces between words:<screen format="linespecific">TwoWords</screen></para>
        </example></para>

      <para><guilabel>Ignore all whitespace</guilabel> ignores all whitespace
      characters, except linefeeds. WinMerge compares lines, and even when
      this option is set linefeeds are intact. All lines in example below are
      detected as identical.<example>
          <title>Ignore all whitespace</title>

          <para>One space between words:<screen format="linespecific">Two Words</screen></para>

          <para>Tab between words:<screen format="linespecific">Two	Words</screen></para>

          <para>No spaces between words:<screen format="linespecific">TwoWords</screen></para>
        </example></para>
    </sect3>

    <sect3>
      <title>Ignore blank lines</title>

      <para>Ignores differences that have only blank (empty) lines. Blank
      lines are shown in file view, but difference is shown with ignored
      difference colors and it cannot be merged.</para>
    </sect3>

    <sect3>
      <title>Ignore case</title>

      <para>If this option is enabled WinMerge ignores differences between
      lowercase and uppercase letters. For example "LowerCase" and "LOWERCASE"
      and "lowercase" are same.</para>
    </sect3>

    <sect3>
      <title>Ignore carriage return differences (DOS/UNIX/MAC)</title>

      <para>If this option is not set WinMerge does not detect EOL style
      differences as differences. If two lines differ only by EOL characters
      (e.g. DOS EOL and Unix EOL) WinMerge detects files as identical.</para>
    </sect3>

    <sect3>
      <title>Enable moved block detection</title>

      <para>When this option is enabled WinMerge tries to detect lines that
      are moved inside file. Moved lines have own difference colors. Also
      location pane can show moved lines with line between bars. This makes it
      easier to visualise changes in files. However if there are a lot of
      moved lines it may get messy looking.</para>
    </sect3>

    <sect3>
      <title>File compare method</title>

      <para>File compare method has three choices:</para>

      <itemizedlist>
        <listitem>
          <para><guilabel>Full Contents</guilabel> - full comparison of files
          by content, with all the bells and whistles. This method invokes
          plugins and uses diffutils engine for fully accurate differencing
          and moved block detection. This is the most complete and recommended
          method.</para>
        </listitem>

        <listitem>
          <para><guilabel>Quick Contents</guilabel> - slimmed down comparison
          of files by content. This method uses streamlines file comparison
          code which skips plugins and moved block detection. The only
          advantage of this method over Full Contents is that this method does
          not load the files into method, and so is faster.</para>

          <para>Drawback is linefilters are not applied when comparing. Even
          if linefilters ignore all differences in files and files are
          considered identical by <guilabel>Full Contents</guilabel> -compare
          method this method sees files as different.</para>
        </listitem>

        <listitem>
          <para><guilabel>Modified Date</guilabel> - comparison of
          modification dates on files. This method only examines the
          modification dates on the files, so it is far faster than either of
          the contents methods, but obviously is only as accurate as the
          modification dates.</para>
        </listitem>
      </itemizedlist>
    </sect3>

    <sect3>
      <title>Stop after first difference</title>

      <note>
        <para>This option is enabled only when <guilabel>Quick
        Contents</guilabel> -compare method is selected.</para>
      </note>

      <para><emphasis></emphasis>This option allows to optimize compare by not
      looking whole files, but only until first difference is found.</para>

      <para>Drawback is WinMerge may be unable to recognize binary files as
      such. This is even likely if first difference is in begin of file. Don't
      enable this if you don't know which kind of files you are comparing. If
      you know your files then this is a nice way to make compare even
      faster.</para>
    </sect3>
  </sect2>

  <sect2>
    <title>Editor options</title>

    <sect3>
      <title>Syntax highlighting</title>

      <para>From <guilabel>Editor</guilabel>-page user can enable/disable
      syntax highlighting. WinMerge can syntax highlight many programming
      language source codes, web formats etc. Syntax highlighting consumes
      some processing power, so if WinMerge screen updating seems to be slow,
      turning off this option might help.</para>
    </sect3>

    <sect3>
      <title>Apply to unrecognized side</title>

      <para>When this options is enabled WinMerge applies known file format's
      syntax highlight to another file even if that file's extension is not
      known. For example, if you compare files, <filename>file.cpp</filename>
      and <filename>file.cpp.bak</filename>, WinMerge detects
      <filename>file.cpp</filename> needs C++ syntax highlight. And then uses
      same rules for <filename>file.cpp.bak</filename> too.</para>
    </sect3>

    <sect3>
      <title>Automatic rescan</title>

      <para>Enabling automatic rescanning forces WinMerge to rescan after
      every change done to files, including typing. That's how WinMerge 1.7.1
      behaves. For bigger files this can make editing files very slow. To make
      file editing faster edit events are 'delayed'.</para>

      <para>Delaying means WinMerge waits one second after last edit event
      before rescanning. If new edit event happens during that time editing is
      done and counter reset to one second. So there should be no rescans
      during normal typing, but only after user stops typing.</para>

      <para>When automatic rescan is disabled, rescan is done only when user
      selects <guimenuitem>Rescan</guimenuitem> or user merges
      difference.</para>

      <para>WinMerge 2.2 release delays more edit events than 2.0.x releases,
      so selecting between automatic and manual rescan is mostly a matter of
      taste.</para>
    </sect3>

    <sect3>
      <title>Preserve original EOL chars</title>

      <important>
        <para>This is an advanced option for users who are familiar with EOL
        bytes and who want to compare files with different EOL styles inside
        ONE file. It is recommended that this option not be set unless this
        advanced functionality is needed.</para>
      </important>

      <para>Setting this option allows handling and comparing files with
      different EOL styles inside ONE file. Two files with different EOL
      styles can be compared even without this option set! One example reveals
      functionality behind this option.</para>

      <screen format="linespecific">This is one example 
text. To show how
smart WinMerge
can be handling 
EOL differences.</screen>

      <para>And same text in bytes:</para>

      <screen format="linespecific">5468 6973 2069 7320 6F6E 6520 6578 616D 706C 6520 0D0A
7465 7874 2E20 546F 2073 686F 7720 686F 7720 0D0A
736D 6172 7420 5769 6E4D 6572 6765 0D
6361 6E20 6265 2068 616E 646C 696E 6720 0D0A
454F 4C20 6469 6666 6572 656E 6365 732E</screen>

      <para>The example presents one simple text file with five lines of text.
      All lines, except third, are terminated with DOS style EOL (0D0A). Third
      line has Unix style EOL (0D).</para>

      <para>If <guilabel>Preserve original EOL chars</guilabel>-option is not
      set WinMerge determines file is meant to be DOS style file and converts
      third line's last bytes to 0D0A before comparing. Missing EOL char is
      usually an error in file, so WinMerge is smart and fixes this error
      instead of reporting it as a difference. That's right, WinMerge changes
      user's file without telling about it to user. WinMerge also shows files
      EOL style as <guilabel>DOS</guilabel> in filecompare statusbar.</para>

      <para>Advanced user might want to handle files without this automatic
      fixing, file might be handled in systems with different EOL styles (e.g.
      Windows and Linux). In that case, user can set this option and see
      WinMerge showing EOL style for every line.</para>
    </sect3>

    <sect3>
      <title>Tab options</title>

      <para>From <guilabel>General</guilabel>-page user can set size tabulator
      character in spaces. Maximum value is 64.</para>

      <para>Another selection is if user wants WinMerge to add tab characters
      or spaces (amount specified by tab size -option) when
      <keycap>Tab</keycap>-key is pressed.</para>
    </sect3>

    <sect3>
      <title>Line Difference Coloring</title>

      <para>This option controls coloring of differences inside lines.
      Normally (<guilabel>Break at whitespace</guilabel> selected) finding
      differences stops at whitespace characters. This basically means whole
      words are highlighted.</para>

      <para>But if <guilabel>Break at whitespace or punctuation</guilabel> is
      selected difference finding stops at punctuation characters as well.
      When this is selected WinMerge can better handle comma separated lists
      etc. For example, for lines:</para>

      <para><screen>10,20,30,40,50</screen></para>

      <para>and</para>

      <para><screen>10,25,30,45,50</screen></para>

      <para>WinMerge would highlight whole lines when using <guilabel>Break at
      whitespace</guilabel> but only numbers 20/25 and 40/25 when using
      <guilabel>Break at whitespace or punctuation</guilabel>.</para>
    </sect3>
  </sect2>

  <sect2>
    <title>System options</title>

    <sect3>
      <title>Send deleted files to Recycle Bin</title>

      <para>When this options is enabled files and folders deleted in
      directory compare are moved to Recycle Bin. Note that use of Recycle Bin
      may have disabled from system.</para>
    </sect3>

    <sect3>
      <title>Add to explorer context menu</title>

      <para>This option enables/disables shell integration. When enabled, new
      menuitem <guimenuitem>WinMerge</guimenuitem> is added to explorer's
      context menu. User can select one or two files/folders and then select
      that menuitem to open files/folders to WinMerge.</para>
    </sect3>

    <sect3>
      <title>Enable advanced menu</title>

      <para>If this option is enabled there are two items shown in explorer's
      context menu. First item (<guimenuitem>Compare</guimenuitem>) allows
      user to select path to "memory" and then pick another path and compare
      those two. This means user does not need to select both paths from same
      view, but user can select them from different drives etc. Path is
      forgotten from memory when its compared.</para>

      <para>Second item (<guimenuitem>Compare...</guimenuitem>) in menu always
      opens WinMerge with selected path(s).</para>
    </sect3>

    <sect3>
      <title>External editor</title>

      <para>WinMerge has a pretty good editor for most basic editing needs.
      However, it doesn't even compare to many other editors in functionality.
      WinMerge allows user to define one's personally preferred editor to
      external editor. Files can be opened in the external editor from the
      directory compare's context menu.</para>

      <para>Notepad is used as the default editor, because it is found on all
      Windows platforms.</para>

      <tip>
        <para>Commandline parameters can be given, in format:
        <command><replaceable>&lt;path to .exe&gt;</replaceable></command>
        <option>-option1</option> <option>-option2</option>
        <option><replaceable>...</replaceable></option></para>
      </tip>
    </sect3>
  </sect2>

  <sect2>
    <title>Archive Support</title>

    <para>This page contains download link to 7-zip plugin and contains option
    related to archive support.</para>

    <sect3>
      <title>Enable archive file support</title>

      <para>Enables or disables archive file support (based on 7-Zip
      integration).</para>

      <para>Like described in Installation section of this manual, there are
      two different methods how 7-zip can be integrated. Integration method
      can be changed using this option dialog after install.</para>
    </sect3>

    <sect3>
      <title>Detect archive type from file signature</title>

      <para>Enabling this option allows WinMerge to recognize archive files
      even if their file extension is not known. Basically WinMerge reads
      beginning of the file and searches for archive-specific signature
      bytes.</para>

      <tip>
        <para>Enabling this option allows WinMerge to recognize and for
        example Open Office files.</para>
      </tip>
    </sect3>
  </sect2>

  <sect2>
    <title>Codepage options</title>

    <para>These options allow selecting codepage WinMerge uses for ANSI files
    and if codepage should be read from file contents for specific file
    formats.</para>

    <sect3>
      <title>Default codepage for ANSI files</title>

      <para>These three radiobuttons can be used to select default codepage
      WinMerge uses when handling ANSI files. Usually default choice of
      <guilabel>System codepage</guilabel> is best choice. However if user
      knows that files are not in same codepage than system uses then user can
      choose different codepage selecting <guilabel>Custom codepage</guilabel>
      and typing codepage number to textbox next to it.</para>

      <important>
        <para>This option is read only when files are loaded. Changing this
        option when the files are open in editor can cause unpredictable
        changes to files when saving them. <emphasis>Select codepage before
        loading the files</emphasis>.</para>
      </important>
    </sect3>

    <sect3>
      <title>Detect codepage info for these files: .html .rc .xml</title>

      <important>
        <para>Uncheck this option in <filename>WinMerge.exe</filename>.
        Characters conversions can result in lossy conversions and the risk is
        very high. <filename>WinMerge.exe</filename> can display files only
        with your current codepage.</para>
      </important>

      <para>This option is interesting when your documents use a codepage
      different from your current codepage (your current codepage is the
      codepage of your Windows configuration).</para>

      <para>For example, you may merge two Slovak or two Japanese files in an
      English environment. With the required fonts, and this option set, your
      Slovak, or Japanese, files will be displayed with Slovak, or Japanese,
      characters.</para>

      <para>Actually, WinMerge detects the codepage for these extensions :
      <filename class="extension">.html</filename>, <filename
      class="extension">.rc</filename> (resource files for VC++) and
      .<filename>xml</filename>.</para>

      <para>WinMerge also detects a codepage difference between the left/right
      files. To avoid lossy conversions during merge/copy/paste, WinMerge
      proposes you to ignore the codepage information.</para>

      <caution>
        <para>When you paste/copy text to an external application, the
        external application must use the same codepage as WinMerge does. If
        your external editor does not support custom codepages, disable this
        option. Refer to the documentation for your external editor (for
        copying to WinMerge, Internet Explorer offers codepage
        selection).</para>
      </caution>
    </sect3>
  </sect2>
</sect1>
