# HG changeset patch # User joachim99 # Date 1065466815 0 # Node ID 922a2b458fb2c597d691ecd1d397f0a99c60a80e # Parent b6b488467677414385d469d2e958cc34f819fec9 Now the html files will be automatically generated from the index.docbook. (Using meinproc from KDE.) diff -r b6b488467677 -r 922a2b458fb2 kdiff3/doc/en/index.html --- 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 @@ - - - - - - - - - - -

KDiff3 - Text Diff And Merge Tool

- Author: Joachim Eibl -
- Copyright 2002
- Documentation for version 0.81.
-
-KDiff3 is a program that
- -

KDiff3 Home -

- -

Screenshots -

- -

Documentation -

- -

Features -

- -

Questions and Answers -
-  
-  
-  

- -

- Screenshots

- This screenshot shows the difference between two text files:
- - -

This screenshot shows three input files being merged:
- -

- -

- Features

- -

Line-By-Line And Char-By-Char Diff-Viewer

- By using the possiblities of a graphical color display KDiff3 shows exactly - what the difference is:
- -
-   -

See White-Space Differences At One Glance

- 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.
- -
-   -

Triple-Diff

- Analyze three files and see where they differ.
- The left/middle/right windows are named A/B/C and have the blue/green/magenta - color respectively.
- 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.
- -
-   -

Comfortable Merge Of Two Or Three Input Files

- 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.
-   -

And ...

- - - -

Diff Algorithm

- 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. -

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.
-  

- -

- Documentation

- -

Command-Line Options

- - Comparing 2 files:
-                     - kdiff3 file1 file2 -

- Merging 2 files:
-                     - kdiff3 file1 file2 -m
-                     - kdiff3 file1 file2 -o outputfile

- -

- Comparing 3 files:
-                     - kdiff3 file1 file2 file3

- -

- Merging 3 files:
-                     - kdiff3 file1 file2 file3 -m
-                     - kdiff3 file1 file2 file3 -o outputfile
-      Note that file1 will be treated as base of file2 -and file3.

- -

For more information use:
-                     - kdiff3 --help

- -

Open-Dialog

- Since many input files must be selectable, the program has a special open - dialog:
- -
- 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. -

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.

- -

The "Configure"-button opens the options-dialog, so that you can set the -options before running the analysis.
-  

- -

Interpreting The Information In The Input Windows

- 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.
- 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.)
- 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). -

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.) -
- The vertical line separating the summary column and the text is interrupted - if the input file had no lines there.

- -

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.
-  

- -

Merging And The Merge Output Editor Window

- 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. - -

!!! Saving is disabled until all conflicts are resolved !!!

- -

With only two input files every difference is also a conflict that must - be solved manually.
- 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.

- -

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.) -
- 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.

- -

Besides, you can directly edit any line. The summary column will show -"m" for every line that was modified .

- -

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.

- -

The text "<Merge Conflict>" will not appear either if you copy and - paste some text containing that line. Be careful to do so!

- -

Navigation And Editing

- 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. -

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.)

- -

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).

- -

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.

- -

Select, Copy And Paste

- 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. -

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.

- -

"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.

- -

Options

- Options and the recent-file-list will be saved when you exit the program, - and reloaded when you start it. -

Font

- Select a fixed width font. (On some systems this dialog will also present - variable width fonts, but you should not use them.) -

Colors

- Foreground color: Usually black.
- Background color: Usually white.
- Diff Background color: Usually light gray.
- Color A: Usually dark blue.
- Color B: Usually dark green.
- Color C: Usually dark magenta.
- Conflict Color: Usually red. -

Editor Settings

- 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.
- Tab size: Can be adjusted for your specific needs. Default is 8.
- Auto indentation: When pressing Enter or Return the indentation of the previous -line is used for the new line.
- Auto copy selection: Every selection is immediately copied to the clipboard - when active and you needn't explicitely copy it. -

Diff Settings

- 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.
- 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.
-  
-   -

- Questions And Answers

- -

Why is it called KDiff3?

- Tools named KDiff and KDiff2 already exist. Also "KDiff3" should suggest - that it can merge like the "diff3"-tool in the Diff-Tool collection. -

Why did I release it under GPL?

- 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. -

Often lines that are similar but not identical appear next to each other - but sometimes not. Why?

- 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. - -

Sometimes lines that are identical don't appear next to each other. Why?

- 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. -

Why won't the merge tool automatically merge if both changes are equal?

- 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. -

Why must all conflicts be solved before the merge result can be saved?

- 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. - -

Why does the editor in the merge result window not have an "undo"-function?

- 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. - -

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?

- 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). -

Why doesn't KDiff3 support syntax-highlighting?

- KDiff3 already uses many colors for difference highlighting. More highlighting - would be confusing. Use another editor for this.
- -

There is so much information here, but your question is still not answered?

- Please send me your question. I appreciate every comment.
-   - -