<?xml version="1.0" encoding="UTF-8"?>
<sect1 id="OpenPaths">
  <title>Opening Files and Folders</title>

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

  <sect2>
    <title>Open-Dialog</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>Environment variables</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>Using environment variables</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>
      <title>Opening archive files</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
      <productname>WinMerge</productname> 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 commandline. Then
      <productname>WinMerge</productname> can compare contents of those two
      subfolders.</para>

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

    <sect3>
      <title>Filter selection</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>Extension list</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
      opended 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>Shell Extension</title>

    <para>Shell extension is convenient way to select paths using Windows
    Explorer. Shell Extension must be first enabled from
    <guilabel>Options</guilabel>/<guilabel>System</guilabel> before use. When
    Shell Extension is enabled item <guimenuitem>WinMerge</guimenuitem> is
    added to 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 Extension 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>

    <sect3>
      <title>Advanced Shell Extension</title>

      <para>Selecting "<guilabel>Enable advanced menu</guilabel>" for shell
      extension from options adds more choices for path selection. Now
      WinMerge adds two menuitems 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>
          <para>Select first item you want to compare, open context menu and
          select first "<guimenuitem>Compare To</guimenuitem>" item. Path is
          now in memory.</para>
        </listitem>

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

      <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>
  </sect2>

  <sect2>
    <title>Drag and Drop</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. WinMerge does not include subfolders in compare. Subfolders can be
    included by pressing <keycap>Control</keycap>-key while dropping
    paths.</para>

    <para>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.</para>
  </sect2>

  <sect2>
    <title>Project file</title>

    <para>Simple project files can be used to select commonly used paths with
    filter. Project file can be given to commandline like normal file or
    opened from <menuchoice>
        <guimenu>File</guimenu>

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

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

    <sect3>
      <title>Format</title>

      <screen>&lt;?xml version="1.0"?&gt;
&lt;project&gt;
	&lt;paths&gt;
		&lt;left&gt;<replaceable>c:\work\project1</replaceable>&lt;/left&gt;
		&lt;right&gt;<replaceable>c:\work\project2</replaceable>&lt;/right&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 four fields:</para>

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

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

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

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

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