<?xml version="1.0" encoding="UTF-8"?>
<sect1 id="OpenPaths">
  <title>ファイルとフォルダを開く</title>

  <para>WinMerge allows selecting/opening paths in several ways. Using
  Open-dialog is just one of them.</para>

  <sect2>
    <title>開く-ダイアログ</title>

    <para>Basic use of Open-dialog is described in <link
    linkend="QuickStart">Quick start</link>. Here is some more detailed
    information and tips about how to use Open-dialog more efficiently.</para>

    <sect3>
      <title>環境変数</title>

      <para>Environment variables can be used as (part of) paths. An
      environment variable is expanded when its name is put between two
      <constant>%</constant>:s.</para>

      <example>
        <title>環境変数の使用</title>

        <para>If an environment variable named <envar>WORKDIR</envar> contains
        the path <filename class="directory">c:\workfiles</filename> then
        <envar>%WORKDIR%\project1</envar> is expanded to path <filename
        class="directory">c:\workfiles\project1</filename> .</para>
      </example>
    </sect3>

    <sect3 id="OpeningArchives">
      <title>アーカイブファイルを開く</title>

      <para>Archive file support requires 7-Zip plugin to be installed. See
      <link linkend="Installing">Installing instructions</link>.</para>

      <para>Opening two archive files is similar to normal files: select two
      archive files to Open-dialog's "<guilabel>Left</guilabel>" and
      "<guilabel>Right</guilabel>" fields. If WinMerge recognizes the archive
      format, it opens the contents of the archive files to folder
      compare.</para>

      <para><link linkend="CompareDirs">Folder Compare</link> chapter
      describes how to work with archive files. If the archive file contains
      subfolders <filename class="directory">Original/</filename> and
      <filename class="directory">Altered/</filename> it must be opened by
      selecting same filename to both sides in
      <guilabel>Open</guilabel>-dialog or command line. Then WinMerge can
      compare contents of those two subfolders.</para>

      <tip>
        <para>When dragging an archive file to WinMerge window, press
        <keycap>Shift</keycap> when dropping the file and WinMerge will
        automatically copy the same filename to both sides and open the
        archive file.</para>
      </tip>
    </sect3>

    <sect3>
      <title>フィルタの選択</title>

      <para>Third edit field in <guilabel>Open</guilabel> dialog is for
      filter. This field can contain list of file extensions to include or
      file filter name.</para>

      <para>Extensions must always be in format
      <filename>*.extension</filename>. So file extension list cannot be used
      for more advanced selecting, file filters are there for it. Different
      extensions can be separated by spaces, commas, colons or
      semicolons.</para>

      <example>
        <title>拡張子リスト</title>

        <screen>*.h;*.cpp *.txt,*.ini</screen>
      </example>

      <tip>
        <para><filename>*.</filename> (star, dot and no extension) selects
        files without any extension, for example
        "<filename>README</filename>".</para>
      </tip>

      <para>Field can also contain file filter name. Easiest way to select
      file filter is using <guilabel>Filters</guilabel>-dialog which can be
      opened with "<guibutton>Select...</guibutton>" button next to field.
      That dialog allows also creating, editing and deleting of filter
      files.</para>

      <note>
        <para>If filter cannot be found by name or extension list is not valid
        WinMerge selects all files (i.e. uses <filename>*.*</filename> as
        extension list).</para>
      </note>
    </sect3>
  </sect2>

  <sect2>
    <title>シェル統合</title>
    <title><indexterm>
        <primary>シェル統合</primary>
      </indexterm>シェル統合</title>

    <para>The Shell Integration is a convenient way to select the paths using
    Windows Explorer. Installer enables Shell Integration if chosen so. Shell
    Integration can be enabled or disabled from
    <guilabel>Options</guilabel>/<guilabel>System</guilabel>. When the Shell
    Integration is enabled item <guimenuitem>WinMerge</guimenuitem> is added
    to the Explorer context menu (click right mouse button over file or folder
    in Explorer).</para>

    <para>WinMerge accepts one or two paths. When one path is selected through
    Shell Integration WinMerge places it as "<guilabel>Left</guilabel>" path
    and open Open-dialog for user to select "<guilabel>Right</guilabel>" path.
    Also if two paths are selected but another path couldn't be opened for
    reason or another WinMerge shows Open-dialog for selecting valid
    paths.</para>

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

        <caption><para>Simple WinMerge context menu</para></caption>
      </mediaobject></para>

    <sect3>
      <title>高度なシェル統合</title>

      <para>Selecting "<guilabel>Enable advanced menu</guilabel>" for Shell
      Integration from options adds more choices for path selection. Now
      WinMerge adds two menu items to Explorer context menu:
      "<guimenuitem>Compare To</guimenuitem>" and
      "<guimenuitem>Compare...</guimenuitem>". <guimenuitem>Compare
      To</guimenuitem> selects path as first ("<guilabel>Left</guilabel>")
      path. When one path is already selected (memorized) WinMerge adds items
      "<guimenuitem>Compare</guimenuitem>" and '<guimenuitem>Re-select
      First</guimenuitem>" to context menu. Now
      <guimenuitem>Compare</guimenuitem> selects path as
      "<guilabel>Right</guilabel>" path and compares it with previously
      selected path. <guimenuitem>Re-select First</guimenuitem> allows
      re-selecting first path. Handy when wrong item got accidentally selected
      as first path.</para>

      <para>Sounds complicated, but luckily it is not - in practice:</para>

      <orderedlist>
        <listitem>
          <simpara>Select first item you want to compare, open context menu
          and select first "<guimenuitem>Compare To</guimenuitem>" item. Path
          is now in memory.</simpara>
        </listitem>

        <listitem>
          <simpara>Browse to location of second item you want to compare and
          select it. Open context menu and move menu selection over first
          "<guimenuitem>Compare</guimenuitem>" item. Now Explorer's status bar
          shows memorized path to which you are comparing newly selected
          path.</simpara>
        </listitem>
      </orderedlist>

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

          <caption><para>Advanced WinMerge context menu</para></caption>
        </mediaobject></para>

      <para>After memorized path is used for compare it is forgotten. So user
      cannot select one item to memorize and then compare it against several
      paths.</para>

      <tip>
        <para>Take benefit of <guilabel>Open</guilabel> dialog's MRU lists!
        <guimenuitem>Compare...</guimenuitem> Item selects path
        as"<guilabel>Left</guilabel>" path and opens
        <guilabel>Open</guilabel>-dialog. Now you can select
        "<guilabel>Right</guilabel>" path from MRU list. This is very handy
        when you need to compare one file/folder against several
        files/folders.</para>
      </tip>
    </sect3>

    <sect3>
      <title>サブフォルダを含める</title>

      <para>Shell Integration by default does not include subfolders into
      comparison. This default behavior can be changed using <guilabel>Include
      Subfolders by Default</guilabel> option in System options. Default
      behavior can be also changed by holding down <keycap>Control</keycap>
      -key while selecting <guimenuitem>Compare</guimenuitem>-item from the
      Explorer context menu.</para>
    </sect3>
  </sect2>

  <sect2>
    <title><indexterm>
        <primary>ドラッグアンドドロップ</primary>
      </indexterm>ドラッグアンドドロップ</title>

    <para>One or two paths can be drag and dropped to WinMerge window from
    Windows Explorer, Desktop or whatever source Windows allows dragging paths
    from. If only one path is dropped to the WinMerge window, the Open dialog
    is opened for selecting the second path. If the single path is a path to
    the project file, then the project file is opened.</para>

    <para>WinMerge does not by default include subfolders in compare.
    Subfolders can be included by pressing <keycap>Control</keycap>-key while
    dropping paths. Another useful key when dropping paths is
    <keycap>Shift</keycap>. When there is only one path dropped and
    <keycap>Shift</keycap> is pressed that same path is opened to both sides.
    This is a handy way to open archive files, see <link
    linkend="OpeningArchives">Opening archive files</link>.</para>

    <para>Paths can be drag and dropped into the Open dialog. The usual use
    case is to first drag and drop first path to the WinMerge window and then
    drag and drop second path to the Open dialog. When the path is dropped
    into the Open dialog, it is placed into:</para>

    <itemizedlist>
      <listitem>
        <simpara>left path - if left path edit field is empty, or both path edit
        fields have already a path</simpara>
      </listitem>

      <listitem>
        <simpara>right path - if left path is not empty and right path is
        empty</simpara>
      </listitem>
    </itemizedlist>
  </sect2>

  <sect2>
    <title><indexterm>
        <primary>プロジェクトファイル</primary>
      </indexterm>プロジェクトファイル</title>

    <para>Project files allow fast and easy opening of commonly used paths
    (and filter). The user can easily save currently open paths as project
    file for later use.</para>

    <sect3>
      <title>プロジェクトファイルを開く</title>

      <para>Project file can be given to command line like normal file or
      opened from <menuchoice>
          <guimenu>File</guimenu>

          <guimenuitem>Open Project...</guimenuitem>
        </menuchoice> WinMerge reads paths from project file and if two paths
      are given opens them. If only one path is given or one of paths is
      invalid, the <guilabel>Open</guilabel>-dialog is shown for user to
      select the second path or valid paths.</para>

      <para>Project file can be selected also in <guilabel>Open</guilabel>
      dialog. There are couple of things to remember:</para>

      <itemizedlist>
        <listitem>
          <simpara>If two project files are selected, project files themselves
          are compared.</simpara>
        </listitem>

        <listitem>
          <simpara>If project file is selected as left-side file, and
          right-side file is empty, project file is opened like using
          <menuchoice>
              <guimenu>File</guimenu>

              <guimenuitem>Open Project...</guimenuitem>
            </menuchoice> dialog.</simpara>
        </listitem>

        <listitem>
          <simpara>If project file is selected as left-side file and any other
          file as right-side file, contents of project file and another file
          are compared.</simpara>
        </listitem>
      </itemizedlist>
    </sect3>

    <sect3>
      <title>プロジェクトファイルの編集と保存</title>

      <para>Project files can be edited and saved using <guilabel>Project
      File</guilabel> -dialog that can be opened from <menuchoice>
          <guimenu>File</guimenu>

          <guimenuitem>Save Project...</guimenuitem>
        </menuchoice> When opened, the dialog is initialized with values from
      the current compare. Values can be edited and saved to the project file
      with <guilabel>Save...</guilabel> button. One can also load existing
      project file with <guilabel>Open...</guilabel> button.</para>

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

        <caption><para>Project File -dialog</para></caption>
      </mediaobject>
    </sect3>

    <sect3>
      <title>フォーマット</title>

      <para>Project files are simple XML files with <filename
      class="extension">.WinMerge</filename> extension.</para>

      <screen>&lt;?xml version='1.0' encoding='UTF-8'?&gt;
&lt;project&gt;
	&lt;paths&gt;
		&lt;left&gt;<replaceable>c:\work\project1</replaceable>&lt;/left&gt;
		&lt;left-readonly&gt;<replaceable>1</replaceable>&lt;/left-readonly&gt;
		&lt;right&gt;<replaceable>c:\work\project2</replaceable>&lt;/right&gt;
		&lt;right-readonly&gt;<replaceable>0</replaceable>&lt;/right-readonly&gt;
		&lt;filter&gt;<replaceable>Visual C++ loose</replaceable>&lt;/filter&gt;
		&lt;subfolders&gt;<replaceable>0&lt;</replaceable>/subfolders&gt;
	&lt;/paths&gt;
&lt;/project&gt;</screen>

      <para>The project file has six fields:</para>

      <itemizedlist>
        <listitem>
          <simpara><literal>&lt;left&gt;<replaceable>...</replaceable>&lt;/left&gt;</literal>
          : Left side path to open</simpara>
        </listitem>

        <listitem>
          <simpara><literal>&lt;left-readonly&gt;...&lt;/left-readonly&gt;</literal>
          : 1 if left side path is opened as readonly, 0 to open
          normally</simpara>
        </listitem>

        <listitem>
          <simpara><literal>&lt;right&gt;<replaceable>...</replaceable>&lt;/right&gt;</literal>
          : Right side path to open</simpara>
        </listitem>

        <listitem>
          <simpara><literal>&lt;right-readonly&gt;...&lt;/right-readonly&gt;</literal>
          : 1 if right side path is opened as readonly, 0 to open
          normally.</simpara>
        </listitem>

        <listitem>
          <simpara><literal>&lt;filter&gt;<replaceable>...</replaceable>&lt;/filter&gt;</literal>
          : file filter name or list of extensions</simpara>
        </listitem>

        <listitem>
          <simpara><literal>&lt;subfolders&gt;<replaceable>...</replaceable>&lt;/subfolders&gt;</literal>
          : 0 if subfolders are not included and 1 if they are
          included</simpara>
        </listitem>
      </itemizedlist>

      <para>None of the fields are required and they can be empty
      (<literal>&lt;left&gt;&lt;/left&gt;</literal>).</para>
    </sect3>
  </sect2>
</sect1>