<?xml version="1.0" encoding="UTF-8"?>
<sect1 id="CompareFiles">
  <title>ファイルの比較</title>

  <para>File compare window is basically two files opened to editor into two
  horizontal panes. The editor allows user to do a basic file editing inside
  WinMerge without needing to open files to external editor program or
  development environment.</para>

  <mediaobject>
    <imageobject>
      <imagedata fileref="screenshots/filecomp1.png" format="PNG" />
    </imageobject>

    <caption><para>File Compare Window</para></caption>
  </mediaobject>

  <para>WinMerge editor is not comparable to specialized editor programs, but
  it has basic features like
  <guilabel>Undo</guilabel>/<guilabel>Redo</guilabel>,
  <guilabel>Find</guilabel>/<guilabel>Replace</guilabel> and
  <guilabel>Goto</guilabel> (to linenumber). The editor also has a syntax
  highlighting feature supporting several file formats (colors configurable).
  Note however WinMerge does not syntax highlight text inside differences.
  Syntax highlighting can be disabled from options.</para>

  <tip>
    <para>If <guilabel>Automatic rescan</guilabel> is not enabled manual
    refresh is recommended after editing.</para>
  </tip>

  <sect2>
    <title>差異の表示</title>

    <para>WinMerge uses different (user configurable) colors to highlight and
    select differences. By default WinMerge shows different lines with yellow
    background and missing lines with gray background. If user selects the
    difference, it is shown with red background and missing lines with milder
    red.</para>
  </sect2>

  <sect2>
    <title>タブ</title>

    <para>WinMerge can show open windows in tab bar below toolbar. Tab bar can
    be shown and hidden from menu <menuchoice>
        <guimenu>View</guimenu>

        <guimenuitem>Tab Bar</guimenuitem>
      </menuchoice>. When the tab bar is shown it has one tab for every open
    window. The tab contains last part of the folder names or file
    names.</para>
  </sect2>

  <sect2>
    <title>ファイルヘッダーバー</title>

    <para>The file headerbar has several functionalities. See screenshot
    below:</para>

    <para><inlinemediaobject>
        <imageobject>
          <imagedata fileref="screenshots/file_headerbar1.png" format="PNG" />
        </imageobject>
      </inlinemediaobject></para>

    <para>Headerbar shows full path to the open file. If the path is longer
    than available space one part of the path is replaced with an ellipsis
    (...). Headerbar also shows:<itemizedlist>
        <listitem>
          <simpara>the current active file with sunken border (like in the
          above screenshot), the non-active file is shown with flat
          headerbar.</simpara>
        </listitem>

        <listitem>
          <simpara>if the file has been modified (has unsaved changes). This
          is indicated by adding asterisk (<guilabel>*</guilabel>) before the
          filename, like in the screenshot.</simpara>
        </listitem>
      </itemizedlist></para>

    <para>Headerbar has a context menu with items to copy full path or
    filename to clipboard.</para>
  </sect2>

  <sect2>
    <title>ステータスバー</title>

    <para><inlinemediaobject>
        <imageobject>
          <imagedata fileref="screenshots/filecomp_statusbar1.png"
                     format="PNG" />
        </imageobject>
      </inlinemediaobject></para>

    <para>Statusbar upper line shows information about current line. In first
    pane:</para>

    <itemizedlist>
      <listitem>
        <simpara><guilabel>Ln</guilabel> : current linenumber</simpara>
      </listitem>

      <listitem>
        <simpara><guilabel>Col</guilabel>: current column for cursor and total
        number of columns in line</simpara>
      </listitem>

      <listitem>
        <simpara><guilabel>Ch</guilabel> : current char for cursor and total
        number of chars in line</simpara>
      </listitem>

      <listitem>
        <simpara><guilabel>EOL</guilabel> : current line EOL style (shown only
        when <guilabel>Preserve original EOL chars</guilabel>-option is
        enabled)</simpara>
      </listitem>
    </itemizedlist>

    <note>
      <para><guilabel>Col</guilabel> counts <keycap>TAB</keycap> as
      <replaceable>X</replaceable> chars (as defined in editor options) and
      <guilabel>Ch</guilabel> counts <keycap>TAB</keycap> as one
      character.</para>
    </note>

    <para>Other three panes are:</para>

    <para><itemizedlist>
        <listitem>
          <simpara>read-only: <guilabel>RO</guilabel> is shown in the pane if
          the file is read-only / protected</simpara>
        </listitem>

        <listitem>
          <simpara>encoding: this pane shows codepage number for ANSI files
          and Unicode encoding type for Unicode files</simpara>
        </listitem>

        <listitem>
          <simpara>EOL style: EOL style can be <guilabel>Win</guilabel> for
          Windows/DOS files (CRLF), <guilabel>Unix</guilabel> (LF) or
          <guilabel>Mac</guilabel> (CR)</simpara>
        </listitem>
      </itemizedlist>Note there are two different ways to show EOL style. When
    per-line EOL style is not remembered, EOL style is shown on own pane in
    statusbar. And when per-line EOL style is remembered line's EOL style is
    shown after char number. When per-line EOL style is used there is no
    file-wide EOL style.</para>

    <para>Difference between column and char is that column counts tabulator
    character as so many (space) chars as it occupies (4 by default, can be
    changed from options). But char count counts tabulator char as one
    char.</para>

    <para>Lower line in statusbar shows current difference and amount of
    differences. Text can be:<itemizedlist>
        <listitem>
          <simpara><guilabel>Identical</guilabel> : files are identical there
          are no differences</simpara>
        </listitem>

        <listitem>
          <simpara><guilabel>X differences Found</guilabel> : amount of
          differences, no difference is selected</simpara>
        </listitem>

        <listitem>
          <simpara><guilabel>Difference X of Y</guilabel> : amount of
          differences (<guilabel>Y</guilabel>) and number of selected
          difference (<guilabel>X</guilabel>)</simpara>
        </listitem>
      </itemizedlist></para>
  </sect2>

  <sect2>
    <title>エディタマージン</title>

    <para>The editor panes (file panes) have optional gray margin area for
    line numbers and some symbols. This margin can be shown/hidded from menu
    <menuchoice>
        <guimenu>View</guimenu>

        <guimenuitem>View Margins</guimenuitem>
      </menuchoice>. The margin shows:</para>

    <itemizedlist>
      <listitem>
        <simpara>Line numbers (from menu <menuchoice>
            <guimenu>View</guimenu>

            <guimenuitem>View Line Numbers</guimenuitem>
          </menuchoice>)</simpara>
      </listitem>

      <listitem>
        <simpara>Bookmarks (menu <menuchoice>
            <guimenu>Edit</guimenu>

            <guisubmenu>Bookmarks</guisubmenu>
          </menuchoice>)</simpara>
      </listitem>

      <listitem>
        <simpara>Word wrap symbols, when word wrap is enabled</simpara>
      </listitem>
    </itemizedlist>

    <para>When line numbers are not shown then margin is shown like screenshot
    below.</para>

    <para><inlinemediaobject>
        <imageobject>
          <imagedata fileref="screenshots/filecomp_margin1.png" format="PNG" />
        </imageobject>
      </inlinemediaobject></para>

    <para>Blue circle is a Bookmark. And arrow marks word-wrapped line. Next
    screenshot shows same lines without word-wrap and with linenumbers.</para>

    <para><inlinemediaobject>
        <imageobject>
          <imagedata fileref="screenshots/filecomp_margin2.png" format="PNG" />
        </imageobject>
      </inlinemediaobject></para>

    <para>If linenubmers are not visible it takes pretty minimal width. Note
    that with linenumbers the margin width is set so that the longest line
    number fits into it. So with large files with lots of lines it needs space
    for several numbers.</para>
  </sect2>

  <sect2>
    <title><indexterm>
        <primary>差異行のナビゲート</primary>

        <secondary>ファイル比較</secondary>
      </indexterm>差異へのナビゲート</title>

    <para>Difference navigation commands are in <guimenu>Merge</guimenu>
    menu:</para>

    <para><inlinemediaobject>
        <imageobject>
          <imagedata fileref="screenshots/merge_menu.png" format="PNG" />
        </imageobject>
      </inlinemediaobject></para>

    <sect3>
      <title>差異行の選択</title>

      <para>Before difference can be merged, it must be selected. Selecting
      can happen by difference navigation keys/items (see below) or by
      selecting wanted difference directly:</para>

      <itemizedlist>
        <listitem>
          <simpara>Double-click over difference with mouse</simpara>
        </listitem>

        <listitem>
          <simpara>Move cursor inside difference and select it with
          <guimenuitem>Current Difference</guimenuitem>.</simpara>
        </listitem>
      </itemizedlist>
    </sect3>

    <sect3>
      <title>差異行のナビゲート</title>

      <para><guimenu>Merge</guimenu>-menu has items for navigating to
      next/previous and first/last difference. Navigation is always done based
      on current cursor location. So <guimenuitem>Next
      Difference</guimenuitem>-command selects next difference from cursor,
      not from current selected difference.</para>

      <note>
        <para>When difference is selected with navigation commands cursor is
        moved to begin of first line of difference. In both files.</para>
      </note>
    </sect3>

    <sect3>
      <title><guimenuitem>現在の差異</guimenuitem>-コマンド</title>

      <para>This command has two important functions:<itemizedlist>
          <listitem>
            <simpara>When there is no difference selected and cursor is inside
            difference, it selects this difference. This is very handy way to
            select difference from keyboard.</simpara>
          </listitem>

          <listitem>
            <simpara>When there is selected difference, it scrolls to selected
            difference. This is handy if user has scrolled selected difference
            out of screen. So this allows user to scroll files to see other
            contents and quickly return back to selected difference.</simpara>
          </listitem>
        </itemizedlist></para>
    </sect3>

    <sect3>
      <title>行または差異への移動</title>

      <para>Using <guimenuitem>Go To</guimenuitem> from
      <guimenu>Edit</guimenu>-menu user can jump to certain line or
      difference. Go To -dialog shows current line and side when
      opened.</para>

      <tip>
        <para>Go To line number is useful if there is need to merge same
        change to several target files from one original file. Rather than
        using <guimenuitem>Find</guimenuitem> or difference navigation it is
        faster to jump to first line of difference.</para>
      </tip>
    </sect3>
  </sect2>

  <sect2>
    <title><indexterm>
        <primary>差異のマージ</primary>
      </indexterm>差異のマージ</title>

    <para>Merging commands are located in <guimenu>Merge</guimenu>-menu after
    navigation commands. Basically there are only two types of merging
    commands - copy difference from right to left and copy difference from
    left to right. Additional commands make merging several differences
    easier.</para>

    <para><guimenuitem>Copy to Right</guimenuitem> and <guimenuitem>Copy to
    Left</guimenuitem> copy difference from side to side. At simplest this
    means replacing text in destination difference with text in source
    difference. But because difference can contain also removed lines, new
    lines may be created or some lines removed. If there are several
    differences selected, then all fully selected differences are merged with
    one command. This makes merging many small differences a lot
    faster.</para>

    <para>WinMerge rescans files after every merging operation. This is done
    to ensure differences were copied correctly and all changes after last
    rescanning are taken care of. If <guilabel>Automatic
    rescan</guilabel>-option is not set, user may have edited files and
    differences may not have shown correctly before merging. If result of
    merging is not what were wanted, user can undo merging operation.</para>

    <important>
      <para>It is strongly advised to run <guimenuitem>Rescan</guimenuitem>
      (<keycap>F5</keycap>) before merging differences if <guilabel>Automatic
      rescan</guilabel> is set off. Usually files get out of sync when editing
      and merging differences may have unpredictable results. If merging
      result looks incorrect try undoing (<menuchoice>
          <guimenu>Edit</guimenu>

          <guimenuitem>Undo</guimenuitem>
        </menuchoice> from menu or <keycombo>
          <keycap>Ctrl</keycap>

          <keycap>Z</keycap>
        </keycombo>) it and rescanning files. And then merging again.</para>
    </important>

    <para><guimenuitem>Copy to Right/Left and Advance</guimenuitem>-commands
    merge current difference and then select next difference (if there is
    one). Using these commands makes merging several differences easier and
    faster.</para>

    <para><guimenuitem>Copy All to Right/Left</guimenuitem>-commands sync two
    open files by merging all differences. Note that you can undo this whole
    operation with one undo command.</para>

    <tip>
      <para>Enable <guilabel>Automatically scroll to first
      difference</guilabel> -option from general options. This saves you from
      scrolling to first difference and selecting it. See <link
      linkend="Configuration">Options &amp; Configuration</link> -chapter for
      more information.</para>
    </tip>
  </sect2>

  <sect2>
    <title><indexterm>
        <primary>マージモード</primary>
      </indexterm>マージモード</title>

    <para>Merge mode can be enabled from the <guimenu>File</guimenu>-menu. It
    restores the WinMerge 1.7.1 single keys for difference merging and
    navigating:</para>

    <itemizedlist>
      <listitem>
        <simpara><keycap>Up-</keycap> and <keycap>Down arrow</keycap> keys
        select previous and next difference</simpara>
      </listitem>

      <listitem>
        <simpara><keycap>Left-</keycap> and <keycap>Right arrow</keycap> keys
        merge difference to left side or right side.</simpara>
      </listitem>
    </itemizedlist>

    <para>Unlike the normal mode, in this schema the <keycap>Alt</keycap>-key
    is not needed for these basic operations (which makes them quicker and
    more convenient). Note that <keycombo>
        <keycap>Shift</keycap>

        <keycap>Arrow</keycap>
      </keycombo>, <keycombo>
        <keycap>Alt</keycap>

        <keycap>Arrow</keycap>
      </keycombo> and <keycombo>
        <keycap>Ctrl</keycap>

        <keycap>Alt</keycap>

        <keycap>Arrow</keycap>
      </keycombo> keys work in merge mode like in normal mode.</para>

    <para>When merge mode is enabled <guilabel>Merge</guilabel> text is shown
    in statusbar.</para>
  </sect2>

  <sect2>
    <title>最新の情報に更新</title>

    <para>Refreshing updates differences after changes are made to files. It
    is important to do a refresh before merging changes between files.</para>

    <note>
      <para>Refresh does not reload file. That means, if another programs has
      updated files etc, those changes are not seen. Refresh updates
      differences according changes user has done.</para>
    </note>
  </sect2>

  <sect2>
    <title>空白の表示</title>

    <para>When enabled from <guimenu>View</guimenu> menu <guimenuitem>View
    Whitespace</guimenuitem> feature shows all whitespace characters (spaces,
    tabulators, line ends). This is very useful for example when there are
    spaces in other file and tabulators in other. Also, if <guilabel>Preserve
    original EOL chars</guilabel> is enabled, WinMerge shows type of EOL
    (<guilabel>Windows</guilabel>/<guilabel>Unix</guilabel>/<guilabel>Mac</guilabel>).</para>
  </sect2>

  <sect2>
    <title>ファイルの編集</title>

    <para>Normal editing features work in WinMerge editor. User can type and
    delete text, select text, copy, cut and paste text etc. There is some
    customisation because there can be removed lines in files (lines existing
    only in other side). Anyway these customisations are not usually visible
    to users otherwise that lines can sometimes "jump" when WinMerge has to
    relocate matching/non-matching files.</para>
  </sect2>

  <sect2>
    <title>行内差異強調表示</title>

    <para>WinMerge can automatically highlight all differences it finds in
    lines. This makes it fast to look through and find differences. See
    screenshot below for an example of highlighted differences.</para>

    <mediaobject>
      <imageobject>
        <imagedata fileref="screenshots/filecomp_inlinediff.png" format="PNG" />
      </imageobject>
    </mediaobject>

    <para>This feature can be enabled and disabled from menu <menuchoice>
        <guimenu>View</guimenu>

        <guimenuitem>View Line Differences</guimenuitem>
      </menuchoice>.</para>

    <para>With default settings WinMerge uses whitespace characters (namely
    spaces and tabulators) to separate words. WinMerge does not consider
    commas or dots as word separators. That means WinMerge thinks "For
    Example" is two words but "For,Example" is one word. More characters can
    be included as word-separator characters from editor options (select from
    menu <menuchoice>
        <guimenu>Edit</guimenu>

        <guimenuitem>Options</guimenuitem>
      </menuchoice> and <guilabel>Editor</guilabel> page). See <link
    linkend="Configuration">Options &amp; Configuration</link> -chapter for
    more information.</para>
  </sect2>

  <sect2>
    <title>行内差異選択</title>

    <para>Many times it is useful to see exact differences inside lines.
    WinMerge can highlight different area between lines. This feature is
    called <guilabel>Select Line Difference</guilabel>. It is available in
    <guimenu>Edit</guimenu>-menu, toolbar and shortcut key
    (<keycap>F4</keycap>). In screenshot below there is one difference
    highlighted</para>

    <mediaobject>
      <imageobject>
        <imagedata fileref="screenshots/linediff.png" format="PNG" />
      </imageobject>
    </mediaobject>
  </sect2>

  <sect2>
    <title>ロケーションペイン</title>

    <para>Location pane is a handy side-pane showing a overall (difference)
    map of files compared.</para>

    <para><inlinemediaobject>
        <imageobject>
          <imagedata fileref="screenshots/filecomp_locpane.png" format="PNG" />
        </imageobject>
      </inlinemediaobject></para>

    <para>Location Pane shows differences as they are located in the files. So
    it gives a good overall view for files compared. Location Pane shows
    differences with same colors than editor panes. There are different
    indicators in Location Pane:</para>

    <itemizedlist>
      <listitem>
        <simpara>small triangles point to begin of the selected
        difference</simpara>
      </listitem>

      <listitem>
        <simpara>selected difference is shown with different color</simpara>
      </listitem>

      <listitem>
        <simpara>area visible in editor panes is shown with different
        background color</simpara>
      </listitem>
    </itemizedlist>

    <para>Clicking with mouse in Location Pane moves cursor to place clicked
    in file. Right-clicking with mouse opens the context menu with items to
    select line to go to. And the visible area locator (area with different
    background color) can be used like a scrollbar thumb - after pressing down
    the left mouse button over it can be dragged upwards and downwards to
    scroll the files.</para>
  </sect2>

  <sect2>
    <title>コンテキストメニュー</title>

    <para>File compare context menu contains items for frequently used
    features:</para>

    <para><inlinemediaobject>
        <imageobject>
          <imagedata fileref="screenshots/filecomp_context1.png" format="PNG" />
        </imageobject>
      </inlinemediaobject></para>

    <para>Most of these items are familiar from Main menu. Worth noting is
    last item <guimenuitem>Open</guimenuitem>. It allows to open file with
    (system) registered application or with external editor. Also context menu
    merge-commands are not relative to active file. They always merge the
    selected difference.</para>
  </sect2>

  <sect2>
    <title>フォント</title>

    <para>Font used by editor can be changed from <menuchoice>
        <guimenu>View</guimenu>

        <guimenuitem>Select Font...</guimenuitem>
      </menuchoice>. Due to limitations in the editor, only fixed width fonts
    are supported in WinMerge.</para>

    <para>Font suggestions for use of WinMerge with East Asian
    languages:</para>

    <itemizedlist>
      <listitem>
        <simpara>Simplified Chinese texts with the <guilabel>SimSun</guilabel>
        or <guilabel>SimHei</guilabel> fixed-width fonts</simpara>
      </listitem>

      <listitem>
        <simpara>Traditional Chinese texts with the
        <guilabel>MingLiU</guilabel> fixed-width font, or</simpara>
      </listitem>

      <listitem>
        <simpara>Japanese texts with the <guilabel>MS Gothic</guilabel> or
        <guilabel>MS Mincho</guilabel> fixed-width fonts</simpara>
      </listitem>

      <listitem>
        <simpara>Korean texts with the <guilabel>GulimChe</guilabel>
        fixed-width font (not Gulim as this variant uses proportional-spacing
        glyphs that are not centered in grid cells and then poorly aligned in
        fixed-width mode)</simpara>
      </listitem>
    </itemizedlist>
  </sect2>

  <sect2 id="ResolveConflictFiles">
    <title><indexterm>
        <primary>コンフリクトファイル</primary>
      </indexterm>コンフリクトファイルの解決</title>

    <para>WinMerge can resolve conflict files several version control systems
    produce when merging files. Conflict file is basically two different
    versions of files embedded into one file. WinMerge reads this file and
    separates it into its original files, and shows those files in file
    compare. So conflicted file can be resolved using normal WinMerge file
    compare functionality.</para>

    <sect3>
      <title>コンフリクトファイルを開く</title>

      <para>Conflict files can be opened into WinMerge using <menuchoice>
          <guimenu>File</guimenu>

          <guimenuitem>Open Conflict File...</guimenuitem>
        </menuchoice>. Conflict file to resolve can be selected using file
      selection dialog that opens. At the moment there are no other ways to
      open conflict files.</para>

      <warning>
        <para>WinMerge overwrites original conflict file. If original file is
        wanted to save, it must be copied to another folder or another
        filename before opening it into WinMerge.</para>
      </warning>
    </sect3>

    <sect3>
      <title>コンフリクトの解決</title>

      <para>WinMerge opens conflict file into normal file compare (see above).
      All normal WinMerge file compare features are in use. Files in two
      panels are:</para>

      <simplelist>
        <member><emphasis>Left panel</emphasis>: this file is called
        "<emphasis>theirs</emphasis>" file. It is usually the file that is in
        version control system's repository. This file usually cannot be
        edited. An as such, WinMerge opens left-side file as read-only.
        Differences can be moved only from this file to the another
        file.</member>

        <member><emphasis>Right panel</emphasis>: this file is called
        "<emphasis>mine</emphasis>" file. It is the user's working file
        originally. All changes should be done to this file. I.e. this file is
        at the same time the result file.</member>
      </simplelist>

      <para>After the wanted resolved file is in right-side panel, it can be
      saved like normal file. WinMerge saves the file over original
      file.</para>

      <para>Left side "<emphasis>mine</emphasis>" file is set to modified
      after opening conflict file. This allows fast resolve by just saving the
      file when user's file is the wanted end result. This also prevents
      accidentally not resolving the files. As resolving only happens when
      file is saved. If file is no saved, original conflict file is kept
      unmodified.</para>

      <para>Many version control tools allow configuring external merge tool.
      WinMerge accepts three filenames ("T<guilabel>heirs</guilabel>",
      "<guilabel>Mine</guilabel>" and "<guilabel>Resolved</guilabel>") as
      command line parameters. See more info from <link
      linkend="CommandLine">Command Line</link> -chapter. Single path to the
      conflict file is also accepted in command line.</para>
    </sect3>
  </sect2>
</sect1>
