Mercurial > hg > easyhg-kdiff3
changeset 10:922a2b458fb2
Now the html files will be automatically generated from the index.docbook.
(Using meinproc from KDE.)
| author | joachim99 |
|---|---|
| date | Mon, 06 Oct 2003 19:00:15 +0000 |
| parents | b6b488467677 |
| children | ce3ab464a615 |
| files | kdiff3/doc/en/index.html |
| diffstat | 1 files changed, 0 insertions(+), 367 deletions(-) [+] |
line wrap: on
line diff
--- a/kdiff3/doc/en/index.html Mon Oct 06 18:57:55 2003 +0000 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,367 +0,0 @@ -<!DOCTYPE html PUBLIC "-//w3c//dtd html 4.0 transitional//en"> -<html> -<head> - - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - - <meta name="GENERATOR" content="Mozilla/4.78 [de] (X11; U; Linux 2.4.10-4GB i686) [Netscape]"> -</head> - <body background="background.png"> - -<h1> KDiff3 - Text Diff And Merge Tool</h1> - Author: <a href="mailto:joachim.eibl@gmx.de">Joachim Eibl</a> - <br> - Copyright 2002 <br> - Documentation for version 0.81.<br> -<br> -KDiff3 is a program that<br> -<ul> - <li>compares two or three text input files,</li> - <li>shows the differences line by line and character by character (!),</li> - <li>provides an automatic merge-facility and</li> - <li>an editor for comfortable solving of merge-conflicts</li> - <li>and has an intuitive graphical user interface.</li> -</ul> -<p><a href="http://kdiff3.sourceforge.net">KDiff3 Home</a> - </p> - -<p><a href="#screenshots">Screenshots</a> - </p> - -<p><a href="#documentation">Documentation</a> - </p> - -<p><a href="#features">Features</a> - </p> - -<p><a href="#faq">Questions and Answers</a> - <br> - <br> - <br> - </p> - -<h2> <a name="screenshots"></a> - Screenshots</h2> - This screenshot shows the difference between two text files: <br> - <img src="screenshot_diff.png" height="269" width="578"> - -<p>This screenshot shows three input files being merged: <br> - <img src="screenshot_merge.png" height="306" width="577"> - </p> - -<h2> <a name="features"></a> - Features</h2> - -<h3> Line-By-Line And Char-By-Char Diff-Viewer</h3> - By using the possiblities of a graphical color display KDiff3 shows exactly - what the difference is: <br> - <img src="letter_by_letter.png" height="63" width="490"> - <br> - -<h3> See White-Space Differences At One Glance</h3> - Spaces and tabs that differ appear visibly. When lines differ only in the - amount of white space this can be seen at one look in the summary -column on the left side. <br> - <img src="white_space.png" height="60" width="480"> - <br> - -<h3> Triple-Diff</h3> - Analyze three files and see where they differ. <br> - The left/middle/right windows are named A/B/C and have the blue/green/magenta - color respectively. <br> - If one file is the same and one file is different on a line then the color -shows which file is different. The red color means that both other files are -different. <br> - <img src="triple_diff.png" height="50" width="512"> - <br> - -<h3> Comfortable Merge Of Two Or Three Input Files</h3> - KDiff3 can be used to merge two or three input files and automatically -merges as much as possible. The result is presented in an editable window -where most conflicts can be solved with a single mouseclick: Select the buttons -A/B/C from the button-bar to select the source that should be used. You can -also select more than one source. Since this output window is an editor even -conflicts which need further corrections can be solved here without requiring -another tool. <br> - -<h3> And ...</h3> - -<ul> - <li> Fast navigation via buttons.</li> - <li>A mouse-click into a summary column sync's all windows to show -the same position.</li> - <li> Select and copy from any window and paste into the merge result window.</li> - <li> Overview column that shows where the changes and conflicts are.</li> - <li> The colors are adjustable to your specific preferences.</li> - <li> Adjustable Tab size. </li> - <li>Option to insert spaces instead of tabs.</li> - <li> Open files comfortably via dialog or specify files on the command -line.</li> - <li> ...</li> - -</ul> - -<h3> Diff Algorithm</h3> - Some graphical diff-tools are just front-ends to the good old command-line - Diff. This is reuse at its best but also limits the possiblities of any -front-end because a diff-analysis of each line is not provided by Diff. -<p>I invented my own diff-algorithm, with the advantage that I could also - reuse it for a line comparison. This algorithm was optimized for use with - C/C++-source files. I hope that the results are useful for you. <br> - </p> - -<h2> <a name="documentation"></a> - Documentation</h2> - -<h3> Command-Line Options</h3> - - Comparing 2 files: <br> - <tt> - kdiff3 <i>file1 file2</i></tt> -<p>- Merging 2 files: <br> - <tt> - kdiff3 <i>file1 file2</i> -m</tt> <br> - <tt> - kdiff3 <i>file1 file2</i> -o <i>outputfile</i></tt> </p> - -<p>- Comparing 3 files: <br> - <tt> - kdiff3 <i>file1 file2 file3</i></tt> </p> - -<p>- Merging 3 files: <br> - <tt> - kdiff3 <i>file1 file2 file3</i> -m</tt> <br> - <tt> - kdiff3 <i>file1 file2 file3</i> -o <i>outputfile</i></tt><i> </i><br> - Note that file1 will be treated as base of file2 -and file3. </p> - -<p>For more information use: <br> - <tt> - kdiff3 --help</tt> </p> - -<h3> Open-Dialog</h3> - Since many input files must be selectable, the program has a special open - dialog: <br> - <img src="open_dialog.png" height="189" width="448"> - <br> - The open dialog allows to edit the filenames by hand, selecting a file via -the file-browser ("Select...") or allows to choose recent files from the drop-down -lists. If you open the dialog again, then the current names still remain -there. The third input file is not required. If the entry for "C" remains -empty, then only a two file diff analysis will be done. -<p>If "Merge" is selected, then the "Output"-line becomes editable. But it -is not required to specify the output filename immediately. You can also postpone -this until saving. </p> - -<p>The "Configure"-button opens the options-dialog, so that you can set the -options before running the analysis. <br> - </p> - -<h3> Interpreting The Information In The Input Windows</h3> - At the top of each text window is its "info line". The info lines of the -input windows contain a letter "A", "B" or "C", the filename and the line -number of the first visible line in the window. (Note that window "C" is optional.) -Each info line appears in a different color. <br> - The three input windows are assigned the letters "A", "B" and "C". "A" has -color blue, "B" has green and "C" has magenta. (These are the defaults, but -can be changed in the Settings-Menu.) <br> - When a difference is detected then the color shows which input file differs. -When both other input files differ then the color used to express this is -red by default ("Conflict color" in the Settings). -<p>Left of each text is the "summary column". If differences occurred on -a line then the summary column shows the respective color. For a white-space-only - difference the summary is chequered. For programming languages where white - space is not so important this is useful to see at one glance if anything - of importance was modified. (In C/C++ white space is only interesting within - strings, comments, for the preprocessor, and some only very esoteric situations.) - <br> - The vertical line separating the summary column and the text is interrupted - if the input file had no lines there. </p> - -<p>On the right side a "overview"-column is visible left of the vertical -scrollbar. It shows the compressed summary column of input "A". All the differences -and conflicts are visible at one glance. When only two input windows are used, -then all differences appear red here because every difference is also a conflict. -A black rectangle frames the visible part of the inputs. For very long input -files, when the number of input lines is bigger than the height of the overview -column in pixels, then several input lines share one overview line. A conflict -then has top priority over simple differences, which have priority over no -change, so that no difference or conflict is lost here. By clicking into -this overview column the corresponding text will be shown.<br> - </p> - -<h3> Merging And The Merge Output Editor Window</h3> - This window also has an info line at the top showing "Output:", the filename - and "[Modified]" if you edited something. Usually it will contain some text -through the automatic merge facilities, but often it will also contain conflicts. - -<p>!!! Saving is disabled until all conflicts are resolved !!! </p> - -<p>With only two input files every difference is also a conflict that must - be solved manually. <br> - With three input files the first file is treated as base, while the second -and third input files contain modifications. When at any line only either -input B or input C have changed but not both then the changed source will -automatically be selected. Only when B and C have changed on the same lines, -then the tool detects a conflict that must be solved manually. </p> - -<p>The merge output editor window also has a summary column. It shows the - letter of the input from which a line was selected or nothing if all three - sources where equal on a line. For conflicts it shows a questionmark "?" -and the line shows "<Merge Conflict>", all in red. Because solving -conflicts line by line would take very long, the lines are grouped into -groups that have the same difference and conflict characteristics. When -clicking into the summary column with the left mouse button in either window -then the group belonging to that line will be selected in all windows and -the beginning of that group will be shown. (This might involve an automatic -position jump in the windows if the beginning of a group is not visible.) -<br> - Note the input selector buttons containing the letters "A", "B" and "C" -in the button bar below the menu bar. When clicking on either input selector -button, the lines from that input will be added at the end of the selected -group if that group didn't contain that source before. Otherwise the lines -from that input will be removed. </p> - -<p>Besides, you can directly edit any line. The summary column will show -"m" for every line that was modified . </p> - -<p>Sometimes, when a line is removed either by automatic merge or be editing - and no other lines remain in that group, then the text <No src line> - will appear in that line. This is just a placeholder for the group for when -you might change your mind and select some source again. This text won't appear -in the saved file or in any selections you want to copy and paste. </p> - -<p>The text "<Merge Conflict>" will not appear either if you copy and - paste some text containing that line. Be careful to do so! </p> - -<h3> Navigation And Editing</h3> - Much navigation will be done with the scroll bars and the mouse but you -can also navigate with the keys. If you click into either window then you -can use the cursor buttons left, right, up, down, page up, page down, home, -end, ctrl-home, ctrl-end as you would in other programs. The overview-column -next to the vertical scroll bar of the input files can also be used -for navigating by clicking into it. -<p>In the merge output editor you can also use the other keys for editing. - You can toggle between insert and overwrite mode with the insert key. (Default - is insert-mode.) </p> - -<p>A left-mouse-button-click into any summary column will synchronise all - windows to show the beginning of the same group of lines (as explained above, -see Merging). </p> - -<p>The button bar also contains six navigation buttons with which you can - jump to the first/last group of lines, to the next/previous difference group -or to the next/previous conflict. </p> - -<h3> Select, Copy And Paste</h3> - The input windows don't show a cursor, so selections must be made with -the mouse by clicking with the left mouse button at the start, holding down -the mousebutton and moving to the end, where you release the mouse button -again. You can also select a word by double clicking it. In the merge output -editor you can also select via the keyboard by holding the "shift"-button -and navigation with the cursor keys. -<p>To copy to the clipboard you must press the "Copy"-button or Ctrl-C. But -there exists an option "Auto Copy Selection". If this is enabled, then whatever -you select is copied immediately and you don't need to explicitely copy. But -pay attention when using this because the contents of the clipboard might -then be destroyed accidentally. </p> - -<p>"Cut" (Ctrl-X) copies to the clipboard and deletes the selected text and -"Paste" (Ctrl-V) inserts the text in the clipboard at the cursorposition -or over the current selection. </p> - -<h3> Options</h3> - Options and the recent-file-list will be saved when you exit the program, - and reloaded when you start it. -<h4> Font</h4> - Select a fixed width font. (On some systems this dialog will also present - variable width fonts, but you should not use them.) -<h4> Colors</h4> - Foreground color: Usually black. <br> - Background color: Usually white. <br> - Diff Background color: Usually light gray. <br> - Color A: Usually dark blue. <br> - Color B: Usually dark green. <br> - Color C: Usually dark magenta. <br> - Conflict Color: Usually red. -<h4> Editor Settings</h4> - Tab inserts spaces: If this is disabled and you press the tabulator key, - a tab-character is inserted, otherwise the appropriate amount of characters - is inserted. <br> - Tab size: Can be adjusted for your specific needs. Default is 8. <br> - Auto indentation: When pressing Enter or Return the indentation of the previous -line is used for the new line. <br> - Auto copy selection: Every selection is immediately copied to the clipboard - when active and you needn't explicitely copy it. -<h4> Diff Settings</h4> - Ignore white space: Default is on. White space will be ignored in the first - part of the analysis in which the line matching is done. In the result the -white space differences will be shown nevertheless. <br> - Ignore trivial matches: Default is on. When trivial lines match after an -difference, this will be ignored and the search for a nontrivial matching -line continues. This improves the results for inputs with empty lines and -lines containing only a open or close-brace character, which is often the -case for C/C++-programs. <br> - <br> - -<h2> <a name="faq"></a> - Questions And Answers</h2> - -<h4> Why is it called KDiff3?</h4> - Tools named KDiff and KDiff2 already exist. Also "KDiff3" should suggest - that it can merge like the "diff3"-tool in the Diff-Tool collection. -<h4> Why did I release it under GPL?</h4> - I'm using GPL programs for a very long time now and learned very much by - having a look at many of the sources. Hence this is my "Thank You" to all - programmers that also did so or will do the same. -<h4> Often lines that are similar but not identical appear next to each other - but sometimes not. Why?</h4> - Lines where only the amount of white space characters is different are -treated as "equal" at first, while just one different non-white character -causes the lines to be "different". If similar lines appear next to each -other, this actually is coincidence but this fortunately is often the case. - -<h4> Sometimes lines that are identical don't appear next to each other. Why?</h4> - Lines that contain very few (less than three) non-white characters are -not used for a match after a difference. Also solitary matching lines in -the middle of differences are not used for matching if they are too far apart. -Most of the time this behaviour improves the quality of the diff-analysis. - But if users (that includes you!) tell me that they need a different behaviour, - then I'll make this an option in the next version. -<h4> Why won't the merge tool automatically merge if both changes are equal?</h4> - Previously I also thought this would be nice, but when I tried it, I saw - that this is dangerous. Sometimes by coincindence two changes are identical - in certain lines but not otherwise. When this is merged automatically then - these lines that are actually needed twice - once for each change - only -appear once in the merge result. It can even happen that no other conflict -appears in the vicinity and then the problem goes completely unnoticed. -<h4> Why must all conflicts be solved before the merge result can be saved?</h4> - For each equal or different section the editor in the merge result window - remembers where it begins or ends. This is needed so that conflicts can -be solved manually by simply selecting the source button (A, B or C). This -information is lost while saving as text and it is too much effort to create -a special file format that supports saving and restoring all necessary information. - -<h4> Why does the editor in the merge result window not have an "undo"-function?</h4> - This was too much effort to do in the first version. And you can always -restore a version from one source (A, B or C) by clicking the respective -button. For big editing the use of another editor is recommended anyway. - -<h4> When I removed some text, then suddenly "<No src line>" appeared -and can't be deleted. What does that mean and how can one remove this?</h4> - For each equal or different section the editor in the merge result window - remembers where it begins or ends. "<No src line>" means that - there is nothing left in a section, not even a new line character. This -can happen either while merging automatically or by editing. This is no problem, -since this hint won't appear in the saved file. If you want the orignal source -back just select the section (click on the left summary column) and then click -the source button with the needed contents (A/B or C). -<h4> Why doesn't KDiff3 support syntax-highlighting?</h4> - KDiff3 already uses many colors for difference highlighting. More highlighting - would be confusing. Use another editor for this. <br> - -<h4>There is so much information here, but your question is still not answered?</h4> - Please send me your question. I appreciate every comment.<br> - -</body> -</html>