[Winmerge-svn] SF.net SVN: winmerge:[6943] trunk/Docs/Users/Manual
Windows visual diff and merge for files and directories
Brought to you by:
christianlist,
grimmdp
From: <den...@us...> - 2009-08-03 13:04:15
|
Revision: 6943 http://winmerge.svn.sourceforge.net/winmerge/?rev=6943&view=rev Author: denisbradford Date: 2009-08-03 13:04:02 +0000 (Mon, 03 Aug 2009) Log Message: ----------- Add WinMerge tour files per Patch 2817443 and related build script. Update build scripts to include tour, add "withads" functionality, eliminate unneeded build_html_withads.xsl script. Modified Paths: -------------- trunk/Docs/Users/Manual/build/build_common.xsl trunk/Docs/Users/Manual/build/build_html.bat trunk/Docs/Users/Manual/build/build_html.xsl trunk/Docs/Users/Manual/screenshots/OpenDlg1.png trunk/Docs/Users/Manual/screenshots/ctx_menu_simple.png trunk/Docs/Users/Manual/screenshots/equal.png trunk/Docs/Users/Manual/screenshots/treeview-01.png Added Paths: ----------- trunk/Docs/Users/Manual/WinMerge_tour.xml trunk/Docs/Users/Manual/build/build_html_page.xsl trunk/Docs/Users/Manual/css/onepage.css trunk/Docs/Users/Manual/screenshots/ctx_menu_advanced_2wins.png trunk/Docs/Users/Manual/screenshots/dragndrop-files.png trunk/Docs/Users/Manual/screenshots/filecomp_diffpane2.png trunk/Docs/Users/Manual/screenshots/filecomp_diffpanesel.png trunk/Docs/Users/Manual/screenshots/filecomp_merged.png trunk/Docs/Users/Manual/screenshots/filecompwin01.png trunk/Docs/Users/Manual/screenshots/foldercomp2.png trunk/Docs/Users/Manual/screenshots/mergebtns-on.png trunk/Docs/Users/Manual/tour_comparingdirs.xml trunk/Docs/Users/Manual/tour_comparingfiles.xml trunk/Docs/Users/Manual/tour_sel_targets.xml Removed Paths: ------------- trunk/Docs/Users/Manual/build/build_html_withads.xsl Added: trunk/Docs/Users/Manual/WinMerge_tour.xml =================================================================== --- trunk/Docs/Users/Manual/WinMerge_tour.xml (rev 0) +++ trunk/Docs/Users/Manual/WinMerge_tour.xml 2009-08-03 13:04:02 UTC (rev 6943) @@ -0,0 +1,59 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"./build/dtd/docbookx.dtd"> +<book id="WinMerge_tour"> + <bookinfo> + <title>WinMerge <xi:include href="replaceables.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" xpointer="element(version)" /> + Quick Tour</title> + + <abstract> + <para>WinMerge is an Open Source differencing and merging tool for + Windows. Use it to detect changes between files and folders, and then to + merge changes selectively. You can use WinMerge by itself, or launch it + from a version control system or another application.</para> + + <para>When you compare two files or folders, the result is displayed in + the WinMerge window. The WinMerge window's visual display and functions + are designed to help you see differences between your targets, and to + merge selected differences if you want to.</para> + + <formalpara> + <title>In a file comparison</title> + + <para>WinMerge shows differences between lines. The built-in text editor + provides syntax highlighting for several programming languages and other + file formats.</para> + </formalpara> + + <formalpara> + <title>In a folder comparison</title> + + <para>WinMerge indicates various kinds of differences between the files + that the folders contain.</para> + </formalpara> + + <para>Take this brief, guided tour if you are considering installing + WinMerge, or if you just want to see what the tool looks like and what you + can do with it. The topics below describe the main WinMerge features. They + include some simple examples of comparing files and folders, and merging + differences between them.</para> + + <para>This tour just scratches the surface. For detailed information and + guidance about using WinMerge, see the Help that is installed with + WinMerge and available <ulink url="http://winmerge.org/docs/manual/">on + our Web site</ulink>.</para> + </abstract> + </bookinfo> + + <toc></toc> + + <xi:include href="tour_sel_targets.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" xpointer="element(/1)" /> + + <xi:include href="tour_comparingfiles.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="tour_comparingdirs.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> +</book> Modified: trunk/Docs/Users/Manual/build/build_common.xsl =================================================================== --- trunk/Docs/Users/Manual/build/build_common.xsl 2009-08-02 17:02:17 UTC (rev 6942) +++ trunk/Docs/Users/Manual/build/build_common.xsl 2009-08-03 13:04:02 UTC (rev 6943) @@ -21,7 +21,6 @@ Changes Created July 2008 ******************************************************************** --> - <!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ html/param.xsl parameters ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> @@ -57,6 +56,7 @@ <!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ html/docbook.xsl ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> +<!-- Link to the appropriate css stylesheets --> <xsl:template name="user.head.content"> <link rel="stylesheet" type="text/css" href="css/all.css" /> <link rel="stylesheet" type="text/css" media="print" href="css/print.css" /> @@ -112,4 +112,28 @@ </span> </xsl:template> +<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +WinMerge custom templates +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> +<xsl:template name="header.ads"> + <div id="ads"> + <script type="text/javascript"><!-- + google_ad_client = "pub-1411904495533584"; + google_ad_width = 728; + google_ad_height = 90; + google_ad_format = "728x90_as"; + google_ad_type = "text"; + google_ad_channel =""; + google_color_border = "FFCC00"; + google_color_bg = "FFFFCC"; + google_color_link = "0000FF"; + google_color_text = "000000"; + google_color_url = "008000"; + //--></script> + <script type="text/javascript" src="http://pagead2.googlesyndication.com/pagead/show_ads.js"> + </script> + </div> +</xsl:template> + + </xsl:stylesheet> Modified: trunk/Docs/Users/Manual/build/build_html.bat =================================================================== --- trunk/Docs/Users/Manual/build/build_html.bat 2009-08-02 17:02:17 UTC (rev 6942) +++ trunk/Docs/Users/Manual/build/build_html.bat 2009-08-03 13:04:02 UTC (rev 6943) @@ -3,14 +3,17 @@ call configuration.bat set docbook_inputfile=..\WinMerge_help.xml +set tour_inputfile=..\WinMerge_tour.xml set docbook_use_stylesheet=build_html.xsl +set tour_use_stylesheet=build_html_page.xsl set docbook_outputdir=%docbook_build_path%\html +set ads=false if "%1" == "withads" goto withads if not "%1" == "" goto withadserror goto start :withads -set docbook_use_stylesheet=build_html_withads.xsl +set ads=true echo ************************************** echo * The manual includes advertisements * echo ************************************** @@ -38,12 +41,15 @@ echo Copy stylesheets... if not exist "%docbook_outputdir%\css" mkdir "%docbook_outputdir%\css" -copy "..\css\all.css" "%docbook_outputdir%\css\all.css" -copy "..\css\print.css" "%docbook_outputdir%\css\print.css" +copy "..\css\*.css" "%docbook_outputdir%\css" +rem copy "..\css\print.css" "%docbook_outputdir%\css\print.css" -echo Create HTML files... -%docbook_java_exe% %docbook_java_parameters% -cp %docbook_saxon_jar%;%docbook_xerces_jar%;%docbook_saxon_xsl% -Djavax.xml.parsers.DocumentBuilderFactory=%DBFACTORY% -Djavax.xml.parsers.SAXParserFactory=%SPFACTORY% -Dorg.apache.xerces.xni.parser.XMLParserConfiguration=%XINCLUDE% com.icl.saxon.StyleSheet %docbook_inputfile% %docbook_use_stylesheet% base.dir=%docbook_outputdir%\ +echo Create Manual HTML files... +%docbook_java_exe% %docbook_java_parameters% -cp %docbook_saxon_jar%;%docbook_xerces_jar%;%docbook_saxon_xsl% -Djavax.xml.parsers.DocumentBuilderFactory=%DBFACTORY% -Djavax.xml.parsers.SAXParserFactory=%SPFACTORY% -Dorg.apache.xerces.xni.parser.XMLParserConfiguration=%XINCLUDE% com.icl.saxon.StyleSheet %docbook_inputfile% %docbook_use_stylesheet% base.dir=%docbook_outputdir%\ withads=%ads% +echo Create tour HTML file... +%docbook_java_exe% %docbook_java_parameters% -cp %docbook_saxon_jar%;%docbook_xerces_jar%;%docbook_saxon_xsl% -Djavax.xml.parsers.DocumentBuilderFactory=%DBFACTORY% -Djavax.xml.parsers.SAXParserFactory=%SPFACTORY% -Dorg.apache.xerces.xni.parser.XMLParserConfiguration=%XINCLUDE% com.icl.saxon.StyleSheet -o %docbook_outputdir%/WinMerge_tour.html %tour_inputfile% %tour_use_stylesheet% headtitle.suffix="' - WinMerge 2.12 Tour'" withads=%ads% + echo Finished! :end Modified: trunk/Docs/Users/Manual/build/build_html.xsl =================================================================== --- trunk/Docs/Users/Manual/build/build_html.xsl 2009-08-02 17:02:17 UTC (rev 6942) +++ trunk/Docs/Users/Manual/build/build_html.xsl 2009-08-03 13:04:02 UTC (rev 6943) @@ -17,15 +17,22 @@ <xsl:import href="../build/xsl/html/chunk.xsl"/> <xsl:import href="build_common.xsl"/> -<!-- Define suffix to appear after title text in head/title element of every topic --> + +<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +Custom parameters ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> +<!-- Define suffix to appear after title text in head/title element of +every topic --> <xsl:param name="headtitle.suffix" select="' - WinMerge 2.12 Manual'"/> +<!-- Detect if we're displaying ads for the Web pages --> +<xsl:param name="withads">false</xsl:param> <!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ html/docbook.xsl - Add suffix to head title text ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> +<!-- Add headtitle.suffix to head title text --> <xsl:template name="head.content"> <xsl:param name="node" select="."/> <xsl:param name="title"> @@ -108,4 +115,11 @@ <xsl:apply-templates select="." mode="head.keywords.content"/> </xsl:template> +<!-- For web pages add banner image and Google ad scripts --> +<xsl:template name="user.header.content"> + <xsl:if test="$withads = 'true'"> + <xsl:call-template name="header.ads"/> + </xsl:if> +</xsl:template> + </xsl:stylesheet> Added: trunk/Docs/Users/Manual/build/build_html_page.xsl =================================================================== --- trunk/Docs/Users/Manual/build/build_html_page.xsl (rev 0) +++ trunk/Docs/Users/Manual/build/build_html_page.xsl 2009-08-03 13:04:02 UTC (rev 6943) @@ -0,0 +1,62 @@ +<?xml version="1.0"?> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + version="1.0"> + +<!-- ******************************************************************** + build_html_page.xsl + WinMerge customization of the XSL DocBook stylesheet distribution. + Contains customized templates and parameters for generating + a single HTML document; all other styles are inherited from the WinMerge + build_common.xsl and the stock DocBook stylesheets in ../build/xsl. + + See build_common.xsl for editing instructions. + ******************************************************************** + Changes: + Created July 2009 + ******************************************************************** --> + +<xsl:import href="../build/xsl/html/docbook.xsl"/> +<xsl:import href="build_common.xsl"/> + +<xsl:output method="html" + encoding="ISO-8859-1" + indent="yes"/> + +<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +Custom parameters ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> +<!-- Define suffix to appear after title text in head/title element of +every topic --> +<xsl:param name="headtitle.suffix" select="' - WinMerge 2.12 Manual'"/> + +<!-- Detect if we're displaying ads for the Web pages --> +<xsl:param name="withads">false</xsl:param> + +<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + html/param.xsl parameters ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> +<xsl:param name="section.autolabel" select="0"/> +<xsl:param name="generate.toc">book nop</xsl:param> +<xsl:param name="generate.meta.abstract" select="0"/> + + +<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +html/docbook.xsl +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> +<!-- Link to the appropriate css stylesheets --> +<xsl:template name="user.head.content"> + <link rel="stylesheet" type="text/css" href="css/onepage.css" /> + <link rel="stylesheet" type="text/css" media="print" href="css/print.css" /> +</xsl:template> + +<!-- For web pages add banner image and Google ad scripts --> +<xsl:template name="user.header.content"> + <div class="header"><a href="http://www.winmerge.org"> + <img src="images/head.gif" alt="winmerge.org"/></a> + </div> + <xsl:if test="$withads = 'true'"> + <xsl:call-template name="header.ads"/> + </xsl:if> +</xsl:template> + +</xsl:stylesheet> Deleted: trunk/Docs/Users/Manual/build/build_html_withads.xsl =================================================================== --- trunk/Docs/Users/Manual/build/build_html_withads.xsl 2009-08-02 17:02:17 UTC (rev 6942) +++ trunk/Docs/Users/Manual/build/build_html_withads.xsl 2009-08-03 13:04:02 UTC (rev 6943) @@ -1,44 +0,0 @@ -<?xml version="1.0"?> -<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" - version="1.0"> - -<!-- ******************************************************************** - build_html_withads.xsl - WinMerge customization of the XSL DocBook stylesheet distribution. - Contains customized templates and parameters for the Web site version - of help; all other styles are inherited from the WinMerge - build_common.xsl and the stock DocBook stylesheets in ../build/xsl. - - See build_common.xsl for editing instructions. - ******************************************************************** - Changes - Created July 2008 - ******************************************************************** --> - -<xsl:import href="build_html.xsl"/> - -<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -html/docbook.xsl -++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> -<!-- WinMerge: commercialize the header --> -<xsl:template name="user.header.content"> - <div id="ads"> - <script type="text/javascript"><!-- - google_ad_client = "pub-1411904495533584"; - google_ad_width = 728; - google_ad_height = 90; - google_ad_format = "728x90_as"; - google_ad_type = "text"; - google_ad_channel =""; - google_color_border = "FFCC00"; - google_color_bg = "FFFFCC"; - google_color_link = "0000FF"; - google_color_text = "000000"; - google_color_url = "008000"; - //--></script> - <script type="text/javascript" src="http://pagead2.googlesyndication.com/pagead/show_ads.js"> - </script> - </div> -</xsl:template> - -</xsl:stylesheet> Added: trunk/Docs/Users/Manual/css/onepage.css =================================================================== --- trunk/Docs/Users/Manual/css/onepage.css (rev 0) +++ trunk/Docs/Users/Manual/css/onepage.css 2009-08-03 13:04:02 UTC (rev 6943) @@ -0,0 +1,33 @@ +@import url("all.css"); + +div.titlepage hr {display: none;} + +div.abstract p.title {display: none;} + +div.article { + margin: 10px 0 0 0; + padding: 0 20px 0 100px; + border: 1px dotted #004080; +} + +div.header { + height: 50px; + background: #FFCC00; + border-top: 1px solid black; + border-bottom: 1px solid black; + padding: 1px 0 1px 0; + text-align: center; +} + +div.header img { + border: none; +} + +div.article h2 { + margin-left: -90px; +} + +div.section h2 { + background-color: inherit; +} + Modified: trunk/Docs/Users/Manual/screenshots/OpenDlg1.png =================================================================== (Binary files differ) Added: trunk/Docs/Users/Manual/screenshots/ctx_menu_advanced_2wins.png =================================================================== (Binary files differ) Property changes on: trunk/Docs/Users/Manual/screenshots/ctx_menu_advanced_2wins.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Modified: trunk/Docs/Users/Manual/screenshots/ctx_menu_simple.png =================================================================== (Binary files differ) Added: trunk/Docs/Users/Manual/screenshots/dragndrop-files.png =================================================================== (Binary files differ) Property changes on: trunk/Docs/Users/Manual/screenshots/dragndrop-files.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Modified: trunk/Docs/Users/Manual/screenshots/equal.png =================================================================== (Binary files differ) Added: trunk/Docs/Users/Manual/screenshots/filecomp_diffpane2.png =================================================================== (Binary files differ) Property changes on: trunk/Docs/Users/Manual/screenshots/filecomp_diffpane2.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/Docs/Users/Manual/screenshots/filecomp_diffpanesel.png =================================================================== (Binary files differ) Property changes on: trunk/Docs/Users/Manual/screenshots/filecomp_diffpanesel.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/Docs/Users/Manual/screenshots/filecomp_merged.png =================================================================== (Binary files differ) Property changes on: trunk/Docs/Users/Manual/screenshots/filecomp_merged.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/Docs/Users/Manual/screenshots/filecompwin01.png =================================================================== (Binary files differ) Property changes on: trunk/Docs/Users/Manual/screenshots/filecompwin01.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/Docs/Users/Manual/screenshots/foldercomp2.png =================================================================== (Binary files differ) Property changes on: trunk/Docs/Users/Manual/screenshots/foldercomp2.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/Docs/Users/Manual/screenshots/mergebtns-on.png =================================================================== (Binary files differ) Property changes on: trunk/Docs/Users/Manual/screenshots/mergebtns-on.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Modified: trunk/Docs/Users/Manual/screenshots/treeview-01.png =================================================================== (Binary files differ) Added: trunk/Docs/Users/Manual/tour_comparingdirs.xml =================================================================== --- trunk/Docs/Users/Manual/tour_comparingdirs.xml (rev 0) +++ trunk/Docs/Users/Manual/tour_comparingdirs.xml 2009-08-03 13:04:02 UTC (rev 6943) @@ -0,0 +1,172 @@ +<?xml version="1.0" encoding="UTF-8"?> +<article id="tour_comparingdirs"> + <title>Comparing Folders</title> + + <para>In addition to comparing files in WinMerge, you can compare the contents + of folders. WinMerge shows which files are different, and provides functions + to merge files between folders.</para> + + <section> + <title>The Folder Compare window</title> + + <para>If you <link linkend="tour_sel_targets">launch a WinMerge compare + operation</link> on two folders, the Folder Compare window opens:</para> + + <mediaobject> + <imageobject> + <imagedata fileref="screenshots/foldercomp1.png" format="PNG" /> + </imageobject> + + <textobject> + <phrase>Folder Compare window</phrase> + </textobject> + </mediaobject> + + <para>The Folder Compare window lists the files and subfolders found in the + target folders. Each row compares a file or subfolder in the two selected + folder targets. As with the File Compare window, the targets are represented + on <quote>left</quote> and <quote>right</quote> sides.</para> + + <para>These columns tells you whether corresponding right and left items in + each row are identical, different, or exist on only one side. The asterisk + in either the left or right date highlights the more recent date. The icons + in the Filename column provide visual cues for each type of file, like text + or binary files, and how the two sides are different. Icons are also used to + mark files and folders that are found only on one side.</para> + + <para>The columns are sortable. By default, rows are sorted by filename in + descending alphabetical order. Click the Filename column title to reverse + the sorting. Or, maybe you're only interested in rows that are different. If + so, click the Comparison result column title to sort by result type. This + groups different files together so they're easy to see.</para> + + <para>If you want to display more information, a simple customization lets + you add additional columns, including file creation time, file encoding + type, file size, and even the number of differences found.</para> + + <para>The Folder Compare window supports common operations on files, like + editing, copying, deleting, moving, and renaming (moving is equivalent to a + copy operation followed by a delete). You can use these file operations and + WinMerge functions to merge the contents of folders. You can also open files + using associated programs or external editors. You can even launch file + compare operations on individual files from the Folder Compare + window.</para> + + <para>The <inlinemediaobject> + <imageobject> + <imagedata contentwidth="23" fileref="screenshots/nav_uparrow_btn.png" /> + </imageobject> + + <textobject> + <phrase>Navigator up arrow button</phrase> + </textobject> + </inlinemediaobject> <guibutton>up arrow</guibutton> button at the top of + the Filename column navigates to the parent folder of each target.</para> + + <para>As we mentioned earlier, the WinMerge main window can contain multiple + Folder Compare or File Compare windows, and each Compare window displays the + result of a single comparison. In the preceding screen shot, the File + Compare window is maximized within the main window:</para> + </section> + + <section> + <title>Navigating folder differences</title> + + <para>To navigate differences at the folder level:</para> + + <itemizedlist> + <listitem> + <para>Use conventional keyboard and mouse actions to move between rows. + To select a difference, simply click its row.</para> + </listitem> + + <listitem> + <para>Use the Difference buttons in the toolbar to select differences + systematically. For example, click the <inlinemediaobject> + <imageobject> + <imagedata contentdepth="15" + fileref="screenshots/nextdiff_btn.png" /> + </imageobject> + + <textobject> + <phrase>Next Difference button</phrase> + </textobject> + </inlinemediaobject> <guibutton>Next Difference</guibutton> button in + the toolbar (or press <keycombo> + <keycap>Alt</keycap> + + <keycap>Enter</keycap> + </keycombo>) to select the next row that is different, automatically + skipping identical rows.</para> + </listitem> + </itemizedlist> + </section> + + <section> + <title>Comparing subfolders</title> + + <para>So far we have looked at a non-recursive comparison, meaning that it + includes only files in the root target folders. It shows subfolders, but not + their contents. If you want to see the files in a subfolder, you have to + launch a new compare operation. For example, if double-click the + <filename>Common</filename> folder in the preceding comparison, WinMerge + opens a new File Compare window that compares the two + <filename>Common</filename> folders.</para> + + <para>You can also compare folders recursively. A recursive comparison + includes all the files in all subfolders, so you don't need to launch + separate compare operations to navigate nested folders. You can As you might + expect, a recursive comparison can can take longer than a non-recursive + comparison for targets with a lot of nested files, and the result can be + harder to read.</para> + + <para>To address these drawbacks, a handy alternative is to display the + results of recursive comparisons in a hierachical tree view, instead of the + default tabular view. In the tree view, subfolders are initially collapsed + for a compact, readable display, but you can expand them to see their + contents:</para> + + <mediaobject> + <imageobject> + <imagedata fileref="screenshots/treeview-01.png" format="PNG" /> + </imageobject> + + <textobject> + <phrase>Folder Compare window</phrase> + </textobject> + </mediaobject> + </section> + + <section> + <title>Merging folder differences</title> + + <para>You merge differences in the Folder Compare window by copying one or + more files or folders from one side to the other, or by deleting + them.</para> + + <para>For example, suppose you want to update files in two folders to the + most recent version. In the preceding screen shot, you can tell from the + asterisk that the left version of <filename>AboutDlg.h</filename> is more + recent. So, to merge <filename>AboutDlg.h</filename> select the row and + click the <inlinemediaobject> + <imageobject> + <imagedata contentwidth="17" fileref="screenshots/copyr_button.png" /> + </imageobject> + + <textobject> + <phrase>Copy Right button</phrase> + </textobject> + </inlinemediaobject> <guibutton>Copy Right</guibutton> button in the + toolbar.</para> + + <para>When you merge a file or folder, the value in the <guilabel>Comparison + result</guilabel> column changes to <literal>Identical</literal>.</para> + + <para>Of course, you might not always want to merge entire files or folders. + For example, you might want to merge selected differences within the files, + or to examine the differences within files before merging them. In such + cases, you can double-click a file to launch a file comparison. WinMerge + displays the result in a new File Compare window, where you can see and + merge the line-level differences.</para> + </section> +</article> \ No newline at end of file Added: trunk/Docs/Users/Manual/tour_comparingfiles.xml =================================================================== --- trunk/Docs/Users/Manual/tour_comparingfiles.xml (rev 0) +++ trunk/Docs/Users/Manual/tour_comparingfiles.xml 2009-08-03 13:04:02 UTC (rev 6943) @@ -0,0 +1,289 @@ +<?xml version="1.0" encoding="UTF-8"?> +<article id="tour_comparingfiles"> + <title>Comparing Files</title> + + <para>When you compare two files, WinMerge shows the differences between their + lines. To demonstrate comparing and merging files, consider these two small + text files named <filename>File1</filename> and + <filename>File2</filename>:</para> + + <formalpara> + <title>File1:</title> + + <para><screen>You can cage a swallow, +can't you? +But you can't swallow +a cage, can you?</screen></para> + </formalpara> + + <formalpara> + <title>File2:</title> + + <para><screen>You can cage a swallow. +But you can't swallow +a cage. Can you?</screen></para> + </formalpara> + + <section> + <title>The File Compare window</title> + + <para>If you <link linkend="tour_sel_targets">launch a WinMerge compare + operation</link> on two files, the File Compare window opens. This screen + shot compares our two sample files:</para> + + <mediaobject> + <imageobject> + <imagedata fileref="screenshots/filecompwin01.png" /> + </imageobject> + + <textobject> + <phrase>Compare Files screen shot</phrase> + </textobject> + </mediaobject> + + <para>The File Compare window makes it easy to see differences between lines + in your files. It also has special functions for merging different lines + from one file to the other, and basic editing capabilities for more detailed + merging within lines. Notice these basic features of the File Compare + window:</para> + + <itemizedlist> + <listitem> + <para>In the bottom right corner of the window, the status bar tells you + how many differences WinMerge detects.</para> + + <para>The Location pane indicates where the differences are located in + the files. The Location pane is helpful for working with long files, + where you can't see all the differences at once in the File + panes.</para> + </listitem> + + <listitem> + <para>Differences are marked in the File panes by a gold background + color. In this comparison, the first difference is a block of two lines; + the second difference is a single line at the end.</para> + </listitem> + + <listitem> + <para>Notice that the first difference has an extra blank line on the + right side. Why does this blank line appear, since it doesn't exist in + the source file?</para> + + <para>The empty line is a placeholder in WinMerge that does not change + the source file. WinMerge inserts blank lines on one side of a + difference whenever the other side has more lines. The extra lines, + marked with a gray background color by default, keep the left and right + sides vertically aligned for ease of comparison. That is, every + difference begins on the same line in the File panes, even when they are + on different lines in the source files. Without this feature, files of + different lengths would be hard to compare.</para> + </listitem> + + <listitem> + <para>The third line is identical in both files, so it has no difference + color (its background is white).</para> + </listitem> + + <listitem> + <para>Within differences, WinMerge highlights the text that makes the + lines different. By default, different words are highlighted. To see + more detail you can highlight changes at the character level; to see + less, you can turn off all highlighting within lines.</para> + </listitem> + </itemizedlist> + + <note> + <para>The WinMerge main window can contain multiple File Compare (and + Folder compare) windows. Each File Compare window displays the result of a + single comparison, representing the two files in the left and right File + panes. In our screen shot, the File Compare window is maximized within the + main window:</para> + </note> + </section> + + <section> + <title>Navigating line differences</title> + + <para>In the File Compare window you can use standard mouse and cursor + actions to select and edit text in either File pane. But in WinMerge, + working with text and working with differences are not the same thing. + WinMerge provides special functions to navigate differences.</para> + + <para>For example, click anywhere in an area that is marked as a difference, + then click the <inlinemediaobject> + <imageobject> + <imagedata contentdepth="15" fileref="screenshots/currentdiff_btn.png" /> + </imageobject> + + <textobject> + <phrase>Current Difference button</phrase> + </textobject> + </inlinemediaobject> <guibutton>Current Difference</guibutton> button in + the toolbar.</para> + + <para>The next two screen shots show the first difference in our sample + comparison, after it's selected. When you select a difference, several + things happen:</para> + + <itemizedlist> + <listitem> + <para>The Selected Difference background color (red by default) + highlights the difference in the File panes. The Location Pane also + highlights the selected difference and marks its location with arrows. + :</para> + + <mediaobject> + <imageobject> + <imagedata fileref="screenshots/filecomp_diffpanesel.png" /> + </imageobject> + + <textobject> + <phrase>Difference selected in Compare Files panes</phrase> + </textobject> + </mediaobject> + </listitem> + + <listitem> + <para>The selected difference is loaded in the Diff pane, where you can + examine it in isolation from other differences.</para> + + <mediaobject> + <imageobject> + <imagedata fileref="screenshots/filecomp_diffpane2.png" /> + </imageobject> + + <textobject> + <phrase>Compare Files Diff Pane</phrase> + </textobject> + </mediaobject> + </listitem> + + <listitem> + <para>All the merge buttons in the toolbar are enabled: + <inlinemediaobject> + <imageobject> + <imagedata fileref="screenshots/mergebtns-on.png" /> + </imageobject> + </inlinemediaobject></para> + </listitem> + + <listitem> + <para>The status bar confirms which difference is selected.</para> + </listitem> + </itemizedlist> + </section> + + <section> + <title>Merging differences in files</title> + + <para>You can merge differences at two levels in the File Compare + window:</para> + + <variablelist> + <varlistentry> + <term>Line-level differences</term> + + <listitem> + <para>As we have seen, a difference includes one or more lines. Use + the WinMerge merge functions to copy an entire selected difference + from one side to the other. For example, click the <inlinemediaobject> + <imageobject> + <imagedata contentdepth="15" + fileref="screenshots/copyr_adv_btn.png" /> + </imageobject> + + <textobject> + <phrase>Copy Right and Advance button</phrase> + </textobject> + </inlinemediaobject> <guibutton>Copy Right and Advance</guibutton> + button.</para> + + <mediaobject> + <imageobject> + <imagedata fileref="screenshots/filecomp_merged.png" /> + </imageobject> + + <textobject> + <phrase>Compare Files window after merge</phrase> + </textobject> + </mediaobject> + + <para>Notice the changes:</para> + + <itemizedlist> + <listitem> + <para>The first difference is gone: the lines are now identical + and have no difference color.</para> + </listitem> + + <listitem> + <para>WinMerge automatically selects the next difference, skipping + over the identical line. The Location Pane also moves its + indicator.</para> + </listitem> + + <listitem> + <para>The status bar indicates that only one difference + remains.</para> + </listitem> + </itemizedlist> + + <para>You can see that the navigation and merge functions provide a + good way to systematically step through all the differences in a + comparison.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Differences within lines</term> + + <listitem> + <para>Instead of merging entire differences using the Merge functions, + you can change text within them by manually editing either file + directly in the File Compare window. For example, if you don't want to + use either side of the first difference, you can delete the line. Or, + you might replace <quote>words</quote> on the right side with + <quote>text</quote>.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>After you finish merging, you can click <menuchoice> + <guimenu>File</guimenu> + + <guimenuitem>Save</guimenuitem> + </menuchoice> to save changes to both sides. Or, to save just one side, + click <menuchoice> + <guimenu>File</guimenu> + + <guimenuitem>Save Left</guimenuitem> + </menuchoice> or <menuchoice> + <guimenu>File</guimenu> + + <guimenuitem>Save</guimenuitem> + </menuchoice>.</para> + + <para>This was a trivial example — there were only two differences and we + only merged one of them. But you can use the methods shown here to navigate + and merge line differences between files of any length.</para> + + <!-- + <para>When you launch a file compare operation, WinMerge opens the File + Compare window. The window features two columns representing the + <quote>left</quote> and <quote>right</quote> files that you are comparing, and + indicates whether the corresponding lines on each side are identical or + different. WinMerge can also highlight the content within lines that makes + them different.</para> + + <para>You can tailor how differences are detected and displayed. For example, + if whitespace differences are not meaningful to your comparison, you can + choose to ignore whitespace or different line ending encodings. You can change + the colors used to highlight line differences and the text within them.</para> + + <para>The Compare window has special functions that make it easy to step + through line differences quickly and systematically, and functions to merge + differences from one file to the other if you want to. You can also edit the + files directly in the Compare window.</para> +--> + </section> +</article> \ No newline at end of file Added: trunk/Docs/Users/Manual/tour_sel_targets.xml =================================================================== --- trunk/Docs/Users/Manual/tour_sel_targets.xml (rev 0) +++ trunk/Docs/Users/Manual/tour_sel_targets.xml 2009-08-03 13:04:02 UTC (rev 6943) @@ -0,0 +1,184 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"build/dtd/docbookx.dtd"> +<article id="tour_sel_targets"> + <title>Starting WinMerge compare operations</title> + + <para>Every WinMerge compare operation has two targets: either two files or + two folders. WinMerge makes it easy to select targets and launch comparisons + from different places in your Windows environment. Here are some commonly used + methods:</para> + + <section> + <title>Drag and drop</title> + + <para>Select two files or two folders in Windows Explorer and drag them to + the WinMerge shortcut on your desktop, or into the WinMerge window if it's + already open.</para> + + <mediaobject> + <imageobject> + <imagedata fileref="screenshots/dragndrop-files.png" format="PNG" /> + </imageobject> + + <textobject> + <phrase>Drag and drop to WinMerge Desktop icon</phrase> + </textobject> + </mediaobject> + + <note> + <para>If you drop only one file or folder into the WinMerge icon or + window, WinMerge opens the <xref linkend="sel_targets_dialog" />, where + you can specify the other target.</para> + </note> + </section> + + <section> + <title>Windows Explorer context menu shortcuts</title> + + <para>WinMerge has an option that adds a <guimenuitem>WinMerge</guimenuitem> + shortcut to the context menu when you select one or two files or folders in + Windows Explorer. Choosing the shortcut opens WinMerge and compares the + selected items:</para> + + <mediaobject> + <imageobject> + <imagedata fileref="screenshots/ctx_menu_simple.png" format="PNG" /> + </imageobject> + + <textobject> + <phrase>Windows Explorer basic context menu integration</phrase> + </textobject> + </mediaobject> + + <para>For even more flexibility, you can replace the basic + <guimenuitem>WinMerge</guimenuitem> shortcut with a set of advanced + shortcuts. Use these shortcuts to select objects separately, even from + different Explorer folders or windows. The next screen shot shows a typical + sequence: we choose the first compare target in one Explorer view, then the + second target in another Explorer view.</para> + + <mediaobject> + <imageobject> + <imagedata fileref="screenshots/ctx_menu_advanced_2wins.png" + format="PNG" /> + </imageobject> + + <textobject> + <phrase>Windows Explorer advanced context menu integration</phrase> + </textobject> + </mediaobject> + </section> + + <section id="sel_targets_dialog"> + <title>Select Files or Folder dialog</title> + + <para>For maximum flexibility in launching compare operations, click + <menuchoice> + <guimenu>File</guimenu> + + <guimenuitem>Open</guimenuitem> + </menuchoice> in the main WinMerge window to open the Select Files or + Folders dialog:</para> + + <mediaobject> + <imageobject> + <imagedata fileref="screenshots/OpenDlg1.png" format="PNG" /> + </imageobject> + + <textobject> + <phrase>Select Files or Folders window</phrase> + </textobject> + </mediaobject> + + <para>This dialog lets you browse anywhere for the files or folders to + compare. Alternatively, you might choose a recently-used file or folder from + the <guilabel>Left</guilabel> and <guilabel>Right</guilabel> drop-down + controls. You can even drag a file or folder from Windows Explorer into the + <guilabel>Left</guilabel> or <guilabel>Right</guilabel> field. A message + prompts you if either target is not found, or if you entered a combination + of file and folder (WinMerge can't compare files to folders!) in the two + fields.</para> + + <para>The dialog contains several options to tailor your compare operation, + including these:</para> + + <variablelist> + <varlistentry> + <term>Filter</term> + + <listitem> + <para>Use this option to apply a filter to narrow the scope of the + comparison. There two kinds of filters:</para> + + <formalpara> + <title>File filters</title> + + <para>include or exclude files that match regular expressions. For + example, the expression <code>^test</code> matches files that start + with the string, <literal>test</literal>, like + <filename>testheaders.h</filename>. WinMerge installs a number of + filter files that specify commonly-excluded files for various + languages, like C#, C++, and Visual Basic. You can edit these files + and, of course, add your own.</para> + </formalpara> + + <formalpara> + <title>Line filters</title> + + <para>ignore lines <emphasis>within</emphasis> files that match + patterns. For example, the expression <code>^[1-5]00</code> ignores + lines beginning with numbers <literal>100</literal>, + <literal>200</literal>, <literal>300</literal>, + <literal>400</literal>, and <literal>500</literal>.</para> + </formalpara> + + <para>WinMerge provides the Filters dialog for creating and managing + filters.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Include Subfolders</term> + + <listitem> + <para>This option lets you control the depth of a folder comparison. + Enabling it compares all folder levels, which might take a while if + there are a lot of files. Disable it to compare only the top level of + the target folders. This is the fastest option, and you can + <quote>drill down</quote> into nested folders later in the Compare + Folders window.</para> + </listitem> + </varlistentry> + </variablelist> + </section> + + <section> + <title>Command line</title> + + <para>The WinMerge CLI includes commands with a full set of parameters and + options that you can use in a script or Command Prompt window to launch + comparisons. This example compares two folders recursively and displays the + result in the WinMerge window:</para> + + <para><userinput>WinMergeU <filename>/r C:\folder1</filename> <filename + class="directory"><filename>C:\folder2</filename> + </filename></userinput></para> + </section> + + <section> + <title>Version control systems</title> + + <para>If you run TortoiseSVN, TortoiseCVS, or Rational ClearCase, you can + configure your version control system to open WinMerge directly. That is, if + you compare files using one of these VCS tools, WinMerge opens instead of + the tool's native diff utility.</para> + + <note> + <para>Another handy VCS integration automatically launches your version + control system's checkout dialog whenever you change a managed file in the + WinMerge window. This integration works with version control systems that + lock files, specifically ClearCase and Visual Source Safe.</para> + </note> + </section> +</article> \ No newline at end of file This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |