Mercurial > hg > easyhg-kdiff3
changeset 11:ce3ab464a615
KDiff3 version 0.9.70
(KDE's meinproc generates the html-files from this input file.)
| author | joachim99 |
|---|---|
| date | Mon, 06 Oct 2003 19:01:52 +0000 |
| parents | 922a2b458fb2 |
| children | 31907692deee |
| files | kdiff3/doc/en/index.docbook |
| diffstat | 1 files changed, 1401 insertions(+), 0 deletions(-) [+] |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/kdiff3/doc/en/index.docbook Mon Oct 06 19:01:52 2003 +0000 @@ -0,0 +1,1401 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.1.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ + <!ENTITY kdiff3 "<application>KDiff3</application>"> + <!ENTITY kappname "&kdiff3;"> + <!ENTITY package "kdeextragear-1"> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE"> +]> + +<book lang="&language;"> + +<!-- This header contains all of the meta-information for the document such +as Authors, publish date, the abstract, and Keywords --> + +<bookinfo> +<title>The &kdiff3; Handbook</title> + +<authorgroup> +<author> +<!--<personname>--> +<firstname>Joachim</firstname> +<surname>Eibl</surname> +<!--</personname>--> +<affiliation><address> + <email>joachim.eibl@gmx.de</email> +</address></affiliation> +</author> +</authorgroup> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> + +<copyright> +<year>2002-2003</year> +<holder>Joachim Eibl</holder> +</copyright> +<!-- Translators: put here the copyright notice of the translation --> +<!-- Put here the FDL notice. Read the explanation in fdl-notice.docbook + and in the FDL itself on how to use it. --> +<legalnotice>&FDLNotice;</legalnotice> + +<!-- Date and version information of the documentation +Don't forget to include this last date and this last revision number, we +need them for translation coordination ! +Please respect the format of the date (YYYY-MM-DD) and of the version +(V.MM.LL), it could be used by automation scripts. +Do NOT change these in the translation. --> + +<date>2003-09-15</date> +<releaseinfo>0.9.70</releaseinfo> + + +<abstract> +<para></para> +<para> + &kdiff3; is a file and directory diff and merge tool which +<itemizedlist> +<listitem><para>compares and merges two or three text input files or directories,</para></listitem> +<listitem><para>shows the differences line by line and character by character(!),</para></listitem> +<listitem><para>provides an automatic merge-facility,</para></listitem> +<listitem><para>has an editor for comfortable solving of merge-conflicts,</para></listitem> +<listitem><para>provides networktransparency via KIO,</para></listitem> +<listitem><para>and is very colorful (by default) :-)</para></listitem> +</itemizedlist> +</para><para> + This document describes KDiff3-version 0.9.70. +</para> +</abstract> + +<!-- This is a set of Keywords for indexing by search engines. +Please at least include KDE, the KDE package it is in, the name + of your application, and a few relevant keywords. --> + +<keywordset> +<keyword>KDE</keyword> +<keyword>kdeextragear</keyword> +<keyword>kdiff3</keyword> +<keyword>diff</keyword> +<keyword>merge</keyword> +<keyword>CVS</keyword> +<keyword>triplediff</keyword> +<keyword>compare</keyword> +<keyword>files</keyword> +<keyword>directories</keyword> +<keyword>version control</keyword> +<keyword>three-way-merge</keyword> +<keyword>in-line-differences</keyword> +<keyword>synchronise</keyword> +<keyword>kpart</keyword> +<keyword>kio</keyword> +<keyword>networktransparent</keyword> +<keyword>editor</keyword> +</keywordset> + +</bookinfo> + +<chapter id="introduction"><title>Introduction</title> +<sect1 id="why"><title>Yet Another Diff Frontend?</title> +<para> +Several graphical diff tools exist. Why choose KDiff3? Let me say, why I wrote it. +</para><para> +KDiff3 started because I had to do a difficult merge. Merging is necessary when several +people work on the same files in a project. A merge can be somewhat automated, when the +merge-tool not only has the new modified files (called "branches"), but also the original file +(called "base"). The merge tool will automatically choose any modification that was only +done in one branch. When several contributors change the same lines, then the merge tool +detects a conflict which must be solved manually. +</para><para> +The merge then was difficult because one contributor had changed many things and corrected +the indentation in many places. Another contributor also had changed much text in the same file, +which resulted in several merge conflicts. +</para><para> +The tool I used then, only showed the changed lines, but not what had changed within these +lines. And there was no information about where only the indentation was changed. The merge +was a little nightmare. +</para><para> +So this was the start. The first version could show differences within a line and showed white space differences. +Later many other features were added to increase the usefulness. +</para><para> +For example if you want to compare some text quickly, then you can copy it to the clipboard and +paste it into either diff window. +</para><para> +A feature that required a big effort was the directory comparison and merge facility, which turned +the program almost into a full file browser. +</para><para> +I hope KDiff3 works for you too. Have fun! +</para><para> +Joachim Eibl (2003) +</para> +</sect1> + +<sect1 id="screenshots"><title>Screenshots and Features</title> +<para>This screenshot shows the difference between two text files</para> +<para>(Using an early version of KDiff3):</para> +<screenshot><mediaobject> + <imageobject><imagedata fileref="screenshot_diff.png" format="PNG"/></imageobject> +</mediaobject></screenshot> + +<para> + 3-way-merging is fully supported. This is useful if two people change code independently. + The original file (the base) is used to help KDiff3 to automatically select the correct + changes. + The merge-editor below the diff-windows allows you to solve conflicts, while showing you the output you will get. + You can even edit the output. + This screenshot shows three input files being merged: +</para><para> +<screenshot><mediaobject> + <imageobject><imagedata fileref="screenshot_merge.png" format="PNG"/></imageobject> +</mediaobject></screenshot> +</para> + +<para id="dirmergebigscreenshot">KDiff3 also helps you to compare and merge complete directories. +This screenshot shows KDiff3 during a directory merge: +</para><para> +<screenshot><mediaobject> + <imageobject><imagedata fileref="dirmergebig.png" format="PNG"/></imageobject> +</mediaobject></screenshot> +</para> +</sect1> + +<sect1 id="features"><title>More Features</title> +<sect2><title> Line-By-Line And Char-By-Char Diff-Viewer</title> +<para>By using the possiblities of a graphical color display KDiff3 shows + exactly what the difference is. When you have to do many code-reviews, you will like this. +</para> +<screenshot><mediaobject> + <imageobject><imagedata fileref="letter_by_letter.png" format="PNG"/></imageobject> +</mediaobject></screenshot> +</sect2> + +<sect2><title> See White-Space Differences At One Glance</title> +<para>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. (No more worries when people change the indentation.) +</para> +<screenshot><mediaobject> + <imageobject><imagedata fileref="white_space.png" format="PNG"/></imageobject> +</mediaobject></screenshot> +</sect2> + +<sect2><title> Triple-Diff</title> +<para> Analyze three files and see where they differ. +</para><para> + The left/middle/right windows are named A/B/C and have the blue/green/magenta + color respectively. +</para><para> + 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. +</para> +<screenshot><mediaobject> + <imageobject><imagedata fileref="triple_diff.png" format="PNG"/></imageobject> +</mediaobject></screenshot> +</sect2> + +<sect2><title> Comfortable Merge Of Two Or Three Input Files</title> +<para> 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. +</para> +</sect2> + +<sect2><title> And ...</title> +<itemizedlist> + <listitem><para> Fast navigation via buttons.</para></listitem> + <listitem><para> A mouse-click into a summary column sync's all windows to show the same position.</para></listitem> + <listitem><para> Select and copy from any window and paste into the merge result window.</para></listitem> + <listitem><para> Overview column that shows where the changes and conflicts are.</para></listitem> + <listitem><para> The colors are adjustable to your specific preferences.</para></listitem> + <listitem><para> Adjustable Tab size.</para></listitem> + <listitem><para> Option to insert spaces instead of tabs.</para></listitem> + <listitem><para> Open files comfortably via dialog or specify files on the command line.</para></listitem> + <listitem><para> Search for strings in all text windows. Find (Ctrl-F) and Find Next (F3)</para></listitem> + <listitem><para> Show the line numbers for each line. </para></listitem> + <listitem><para> Paste clipboard or drag text into a diff input window.</para></listitem> + <listitem><para> Networktransparency via KIO.</para></listitem> + <listitem><para> ...</para></listitem> +</itemizedlist> +</sect2> +</sect1> +</chapter> + +<chapter id="documentation"><title>Documentation of File Comparison And Merge</title> + +<sect1 id="commandline"><title>Command-Line Options</title> + +<sect2><title>Comparing 2 files: </title> +<screen> + <command>kdiff3</command> <replaceable>file1 file2</replaceable> +</screen> +</sect2> + +<sect2><title>Merging 2 files: </title> +<screen> + <command>kdiff3</command> <replaceable>file1 file2</replaceable> -m + <command>kdiff3</command> <replaceable>file1 file2</replaceable> -o <replaceable>outputfile</replaceable> +</screen> +</sect2> + +<sect2><title>Comparing 3 files: </title> +<screen> + <command>kdiff3</command> <replaceable>file1 file2 file3</replaceable> +</screen> +</sect2> + +<sect2><title>Merging 3 files: </title> +<screen> + <command>kdiff3</command> <replaceable>file1 file2 file3</replaceable> -m + <command>kdiff3</command> <replaceable>file1 file2 file3</replaceable> -o <replaceable>outputfile</replaceable> +</screen> +<para> + Note that <replaceable>file1</replaceable> will be treated as + base of <replaceable>file2</replaceable> and + <replaceable>file3</replaceable>. +</para> +</sect2> + +<sect2><title>Special case: Files with the same name </title> +<para> +If all files have the same name but are in different directories, you can +reduce typework by specifying the filename only for the first file. E.g.: +</para> +<screen> + <command>kdiff3</command> <replaceable>dir1/filename dir2 dir3</replaceable> +</screen> +</sect2> + +<sect2><title>Commandline for starting a directory comparison or merge: </title> +<para>This is very similar, but now it's about directories.</para> +<screen> + <command>kdiff3</command> <replaceable>dir1 dir2</replaceable> + <command>kdiff3</command> <replaceable>dir1 dir2</replaceable> -o <replaceable>destdir</replaceable> + <command>kdiff3</command> <replaceable>dir1 dir2 dir3</replaceable> + <command>kdiff3</command> <replaceable>dir1 dir2 dir3</replaceable> -o <replaceable>destdir</replaceable> +</screen> +<para>For directory comparison and merge you can continue to read <link linkend="dirmerge">here</link>.</para> +</sect2> + +<sect2><title>For more information on command line options use: </title> +<screen> + <command>kdiff3</command> --help +</screen> +</sect2> + +</sect1> + +<sect1 id="opendialog"><title>Open-Dialog</title> +<para> + Since many input files must be selectable, the program has a special open dialog: +</para> +<screenshot><mediaobject> +<imageobject><imagedata fileref="open_dialog.png" format="PNG"/></imageobject> +</mediaobject></screenshot> +<para> + The open dialog allows to edit the filenames by hand, selecting a file + via the file-browser ("File...") 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. +</para><para> + You can also select a directory via "Dir...". If for A a directory is specified + then a directory-comparison/merge starts. If A specifies a file but B, C or + the output specify a directory, then KDiff3 uses the filename from A in the + specified directories. +</para><para> + 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. +</para><para> + The "Configure..."-button opens the options-dialog, so that you can set + the options before running the analysis. +</para> +</sect1> + +<sect1 id="pasteinput"><title>Paste and Drop Input</title> +<para> + Sometimes you want to compare parts of a text that is not an own file. KDiff3 also + allows you to paste text from the clipboard into the diff input window that has the focus. + The diff analysis happens immediately then. + In the open dialog you need not specify files then, but just close it via "Cancel". +</para><para> + You can also use drag and drop: Drag a file from a file manager + or selected text from an editor and drop it onto a diff input window. +</para><para> + What's the idea? Sometimes a file contains two similar functions, but checking how similar + they really are is a big effort if you first must create two files and then load them. Now + you can simply copy, paste and compare the relevant sections. +</para><para> + Note: Currently you can't drag anything from KDiff3. Only dropping in the diff input + is supported. +</para><para> + Warning: Some editors still interpret the drag and drop into another program like cut + (instead of copy) and paste. Your original data might be lost then. +</para> +</sect1> + +<sect1 id="interpretinginformation"><title>Interpreting The Information In The Input Windows</title> +<screenshot><mediaobject> +<imageobject><imagedata fileref="screenshot_diff.png" format="PNG"/></imageobject> +</mediaobject></screenshot> +<para> + 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. (If the paths + are too long to fit, then you can move the mouse onto the info line and + a tooltip will show the complete name.) +</para><para> + 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.) +</para><para> + 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). + This colorscheme is especially useful in the case of three input files, which will be + seen in the next section (<link linkend="merging">Merging</link>). +</para><para> + 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.) +</para><para> + The vertical line separating the summary column and the text is interrupted + if the input file had no lines there. +</para><para> + 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. +</para> +</sect1> + + +<sect1 id="merging"><title>Merging And The Merge Output Editor Window</title> +<screenshot><mediaobject> +<imageobject><imagedata fileref="screenshot_merge.png" format="PNG"/></imageobject> +</mediaobject></screenshot> +<para> + The merge output editor window (below the diff input windows) 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. +</para><para> + !!! Saving is disabled until all conflicts are resolved !!! (Use the "Go + to prev/next unsolved conflicts"-buttons to find the remaining conflicts.) +</para><para> + With only two input files every difference is also a conflict that must + be solved manually. +</para><para> + 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. + When B and C are the same, but not the same as A, then C is selected. +</para><para> + The merge output editor window also has a summary column on the left. 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. + But only-white-space-conflicts are separated from non-white-space-conflicts + in order to ease the merging of files were the indentation changed for many + lines. +</para><para> + 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.) + This group then becomes the "current group". It is highlighted with the + "Current range (diff) background color" and + a black bar appears on the left side of the text. +</para><para> + 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. +</para><para> + Besides, you can directly edit any line. The summary column will show "m" + for every line that was modified. +</para><para> + Sometimes, when a line is removed either by automatic merge or by 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. +</para><para> + The text "<Merge Conflict>" will appear in the clipboard if you + copy and paste some text containing such a line. But still be careful to + do so. +</para><para> + The "Merge" menu contains some actions that let you select "A", "B" or + "C" everywhere. When you select "Automatically solve simple conflicts" then + KDiff3 restarts the merge and solves as many conflicts as it can. "Set deltas + to conflicts" does the opposite: Even simple conflicts have to be solved + manually then. For all these actions the manual selections that happened + before are lost. (KDiff3 will tell you so, before proceeding.) +</para> +</sect1> + +<sect1 id="navigation"><title>Navigation And Editing</title> +<para> + 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. +</para><para> + You can also use the wheel mouse to scroll up and down. +</para><para> + 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.) +</para><para> + 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 + in section <link linkend="merging">"Merging"</link>). +</para><para> + The button bar also contains seven navigation buttons with which you can + jump to the current/first/last difference, to the next/previous difference + (ctrl-down/ctrl-up), to the next/previous conflict (ctrl-pgdown/ctrl-pgup), + or to the next/previous unsolved conflict. Note that for KDiff3 a "conflict" + that was not automatically solved at the start of the merge stays a "conflict" + even if it is solved. Hence the necessity to distinguish "unsolved conflicts". +</para><para> + There also is a button "Automatically go to next unsolved conflict after + source selection" (Auto-Advance). If you enable this, then, when one source + is selected, then KDiff3 will jump to and select the next unsolved conflict + automatically. This can help when you always want to choose one source only. + When you need both sources, or you want to edit after selecting, then you + probably want to switch this off. Before proceeding to the next unsolved conflict + KDiff3 shows you the effect of your choice for a short time. This delay is + adjustable in the Diff- & Merge-Settings: You can + specify the "Auto-Advance delay" in milli seconds between 0 and 2000. Hint: + Tired of many clicks? - Use a small Auto-Advance-delay and the shortcuts + Ctrl-1/2/3 to select A/B/C for many conflicts. +</para> +</sect1> + +<sect1 id="selections"><title>Select, Copy And Paste</title> +<para> + 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. +</para><para> + To copy to the clipboard you must press the "Copy"-button (Ctrl-C or Ctrl-Insert). + 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. +</para><para> + "Cut" (Ctrl-X or Shift-Delete) copies to the clipboard and deletes the + selected text and "Paste" (Ctrl-V or Shift-Insert) inserts the text in + the clipboard at the cursorposition or over the current selection. +</para> +</sect1> + +<sect1 id="saving"><title>Saving</title> +<para> + Saving will only be allowed, when all conflicts were solved. If the file + already exists and the "Backup files"-option is enabled then the existing + file will be renamed with an ".orig"-extension, but if such a file exists + it will be deleted. When you exit or start another diff-analysis and data + wasn't saved yet, then KDiff3 will ask if you want to save, cancel or proceed + without saving. (KDiff3 does not catch any signals. So if you "kill" KDiff3 + then your data will be lost.) +</para><para> + Line endings are saved according to the normal method on the underlying + operating system. For Unices each line ends with an linefeed-character "\n", + while for Win32-based systems each line ends with a carriage-return + a linefeed + "\r\n". KDiff3 does not preserve the line-endings of the input files, which + also means that you shouldn't use KDiff3 with binary files. +</para> +</sect1> + +<sect1 id="find"><title>Finding Strings</title> +<para> + You can search for a string in any text-window of KDiff3. The "Find ..."-command + (Ctrl-F) in the Edit-menu opens a dialog that lets you specify the string + to search for. You can also select the windows which should be searched. + Searching will always start at the top. Use the "Find Next"-command (F3) + to proceed to the next occurance. If you select to search several windows then the first + window will be searched from top to bottom before the search starts in the next + window at the top again, etc. +</para> +</sect1> + + +<sect1 id="options"><title>Options</title> +<para> + Options and the recent-file-list will be saved when you exit the program, + and reloaded when you start it. (Menu Settings->Configure KDiff3 ...) +</para> +<sect2><title>Font</title> +<para> + Select a fixed width font. (On some systems this dialog will also + present variable width fonts, but you should not use them.) +</para> +<variablelist> + <varlistentry><term><emphasis>Italic Font for Deltas:</emphasis></term><listitem><para> If you select this, then text differences + will be drawn with the italic version of the selected font. If the font + doesn't support italic, then this does nothing.</para> + </listitem></varlistentry> +</variablelist> +</sect2> + +<sect2><title>Colors</title> +<variablelist> + <varlistentry><term><emphasis>Foreground color:</emphasis></term><listitem><para> Usually black. </para></listitem></varlistentry> + <varlistentry><term><emphasis>Background color:</emphasis></term><listitem><para> Usually white. </para></listitem></varlistentry> + <varlistentry><term><emphasis>Diff Background color:</emphasis></term><listitem><para> Usually light gray. </para></listitem></varlistentry> + <varlistentry><term><emphasis>Color A:</emphasis></term><listitem><para> Usually dark blue. </para></listitem></varlistentry> + <varlistentry><term><emphasis>Color B:</emphasis></term><listitem><para> Usually dark green. </para></listitem></varlistentry> + <varlistentry><term><emphasis>Color C:</emphasis></term><listitem><para> Usually dark magenta. </para></listitem></varlistentry> + <varlistentry><term><emphasis>Conflict Color:</emphasis></term><listitem><para> Usually red.</para></listitem></varlistentry> + <varlistentry><term><emphasis>Current range background color:</emphasis></term><listitem><para> Usually light yellow.</para></listitem></varlistentry> + <varlistentry><term><emphasis>Current range diff background color:</emphasis></term><listitem><para> Usually dark yellow.</para></listitem></varlistentry> +</variablelist> +<para> + On systems with only 16 or 256 colors some colors are not available in pure + form. On such systems the "Defaults"-button will choose a pure color. +</para> +</sect2> + +<sect2><title>Editor Settings</title> +<variablelist> + <varlistentry><term><emphasis>Tab inserts spaces:</emphasis></term><listitem><para> If this is disabled and you press the + tabulator key, a tab-character is inserted, otherwise the appropriate + amount of characters is inserted.</para></listitem></varlistentry> + <varlistentry><term><emphasis> Tab size:</emphasis></term><listitem><para> Can be adjusted for your specific needs. Default is 8. </para></listitem></varlistentry> + <varlistentry><term><emphasis> Auto indentation:</emphasis></term><listitem><para> When pressing Enter or Return the indentation + of the previous line is used for the new line. </para></listitem></varlistentry> + <varlistentry><term><emphasis> Auto copy selection:</emphasis></term><listitem><para> Every selection is immediately copied + to the clipboard when active and you needn't explicitely copy it. </para></listitem></varlistentry> +</variablelist> +</sect2> + +<sect2><title>Diff & Merge Settings</title> +<para> + When comparing files, KDiff3 first it tries to match lines that are equal + in all input files. Only during this step it might ignore white space. The + second step compares each line. In this step white space will not be ignored. + Also during the merge white space will not be ignored. +</para> + +<variablelist> + <varlistentry><term><emphasis>Ignore white space:</emphasis></term><listitem><para> 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. + </para></listitem></varlistentry> + <varlistentry><term><emphasis>Preserve Carriage Return:</emphasis></term><listitem><para> Some editors (on some systems) save + carriage return '\r' and linefeed '\n'-characters at the end of line, while + others will only save the linefeed '\n'. Usually KDiff3 ignores the carriage + return, but then files that don't have equal sizes, look equal in side by + side comparison. When this option is on, then the carriage return characters + are made visible but are treated as white space. This option must be off + during a merge. Default is off.</para></listitem></varlistentry> + <varlistentry><term><emphasis>Ignore numbers:</emphasis></term><listitem><para> Default is off. Number characters ('0'-'9', '.', '-') + will be ignored in the first part of the analysis in which the line matching is + done. In the result the differences will be shown nevertheless, but they are treated + as white space. + </para></listitem></varlistentry> + <varlistentry><term><emphasis>Convert to Upper Case:</emphasis></term><listitem><para> Default is off. Converts the input to upper case + while reading. Hence the comparison is not case sensitive. Take care during merging + because the case information will be lost in the merge-result too. + </para></listitem></varlistentry> + <varlistentry><term><emphasis>Preprocessor-Command:</emphasis></term><listitem><para> + When any file is read, it will be piped through this external command. + The output of this command will be visible instead of the original file. + You can write your own preprocessor that fulfills your specific needs. + Use this to cut away disturbing parts of the file, or to automatically + correct the indentation etc. + </para></listitem></varlistentry> + <varlistentry><term><emphasis>Line-Matching Preprocessor-Command:</emphasis></term><listitem><para> + When any file is read, it will be piped through this external command. If + a preprocessor-command (see above) is also specified, then the output of the + preprocessor is the input of the line-matching preprocessor. + The output will only be used during the line matching phase of the analysis. + You can write your own preprocessor that fulfills your specific needs. + Each input line must have a corresponding output line. + </para></listitem></varlistentry> + <varlistentry><term><emphasis>Use external diff:</emphasis></term><listitem><para> If you have an external diff-tool (e.g. GNU-diff) + you can use it for the line matching phase. For some complicated files this + might be better than the internal algorithm of KDiff3. + </para></listitem></varlistentry> + <varlistentry><term><emphasis>Try Hard:</emphasis></term><listitem><para> Passes the "--minimal"-option to the external diff + tool, which then will try hard to find an even smaller delta. This will probably + be effective for complicated and big files. And slow for very big files. + </para></listitem></varlistentry> + <varlistentry><term><emphasis>Ignore trivial matches:</emphasis></term><listitem><para> 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. + </para></listitem></varlistentry> + <varlistentry><term><emphasis>Max search length:</emphasis></term><listitem><para> Searching for a match is aborted after this + number of lines. The diff might fail for small values but take too long + for big values. Default is 1000. + </para></listitem></varlistentry> + <varlistentry><term><emphasis>Auto Advance Delay (ms):</emphasis></term><listitem><para> When in auto-advance-mode this setting specifies + how long to show the result of the selection before jumping to the next unsolved + conflict. + </para></listitem></varlistentry> +</variablelist> + +</sect2> + +<sect2><title>Directory Merge</title> +<para> + These options are concerned with scanning the directory and handling the + merge: See the <link linkend="dirmergeoptions">Directory Comparison/Merge + Docs</link> for details. +</para><para> +Yet there is one option here that is also relevant for saving single files: +</para> +<variablelist> + <varlistentry><term><emphasis>Backup files:</emphasis></term><listitem><para> When a file is saved and an older version already + exists, then the original version will be renamed with an ".orig" extension. + If an old backup file with ".orig" extension already exists then this will + be deleted without backup. + </para></listitem></varlistentry> +</variablelist> +</sect2> + +<sect2><title>Miscellaneous</title> +<para>(These options and actions are available in menus or the buttonbar.)</para> +<variablelist> + <varlistentry><term><emphasis>Show line numbers:</emphasis></term><listitem><para> You can select if line numbers should be + shown for the input files.</para></listitem></varlistentry> + <varlistentry><term><emphasis>Show space and tabulator characters for differences:</emphasis></term><listitem><para> Sometimes + the visible spaces and tabs are disturbing. You can turn this off.</para></listitem></varlistentry> + <varlistentry><term><emphasis>Show Window A/B/C:</emphasis></term><listitem><para> Sometimes you want to use the space on + the screen better for long lines. Hide the windows that are not important. + (In the Windows-menu.)</para></listitem></varlistentry> + <varlistentry><term><emphasis>Toggle Split Orientation:</emphasis></term><listitem><para> + Switch between diff windows shown next to each other (A left of B left of C) or above + each other (A above B above C). This should also help for long lines. (In the Windows-menu.) + </para></listitem></varlistentry> + <varlistentry><term><emphasis>Start a merge quickly:</emphasis></term><listitem><para> Sometimes you are viewing the deltas + and decide to merge. <inlinemediaobject><imageobject><imagedata fileref="merge_current.png" format="PNG"/></imageobject></inlinemediaobject> + "Merge current file" in the Directory-menu also works if you only compare + two files. A single click starts the merge and uses the filename of the last + input-file as the default output filename. (When this is used to restart + a merge, then the output filename will be preserved.)</para></listitem></varlistentry> +</variablelist> +</sect2> + +<sect2 id="shortcuts"><title>Configuring Keyboard-Shortcuts</title> +<para> + Currently only the KDE-version supports user-configurable keyboard-shortcuts. + (Menu Settings->Configure Shortcuts...) +</para> +</sect2> +</sect1> +</chapter> + + +<chapter id="dirmerge"><title>Directory Comparison and Merge with KDiff3</title> +<sect1 id="dirmergeintro"><title>Introduction</title> +<para> + Often programmers must modify many files in a directory to achieve their + purpose. For this KDiff3 also lets you compare and merge complete directories + recursively! +</para><para> + Even though comparing and merging directories seems to be quite obvious, + there are several details that you should know about. Most important is of + course the fact that now many files might be affected by each operation. + If you don't have backups of your original data, then it can be very hard + or even impossible to return to the original state. So before starting a merge, + make sure that your data is safe, and going back is possible. If you make + an archive or use some version control system is your decision, but even + experienced programmers and integrators need the old sources now and then. + And note that even though I (the author of KDiff3) try to do my best, I can't + guarantee that there are no bugs. According to the GNU-GPL there is NO WARRANTY + whatsoever for this program. So be humble and always keep in mind: +</para> +<blockquote><para> + <emphasis>To err is human, but to really mess things up you need a computer.</emphasis> +</para></blockquote> +<para> +So this is what this program can do for you: KDiff3 ... +</para> +<itemizedlist> + <listitem><para>... reads and compares two or three directories recursively,</para></listitem> + <listitem><para>... takes special care of symbolic links,</para></listitem> + <listitem><para>... lets you browse files on mouse double click,</para></listitem> + <listitem><para>... for each item proposes a merge operation, which you can change + before starting the directory merge,</para></listitem> + <listitem><para>... lets you simulate the merge and lists the actions that would + take place, without actually doing them,</para></listitem> + <listitem><para>... lets you really do the merge, and lets you interact whenever + manual interaction is needed,</para></listitem> + <listitem><para>... lets you continue the merge after manual interaction with key F5,</para></listitem> + <listitem><para>... optionally creates backups, with the ".orig" extension,</para></listitem> + <listitem><para>...</para></listitem> +</itemizedlist> +</sect1> + +<sect1 id="startingdirmerge"><title>Starting Directory Comparison Or Merge</title> +<para> + This is very similar to the single file merge and comparison. You just + have to specify directories on the command line or in the file-open + dialog. +</para> +<sect2><title>Compare/Merge two directories: </title> +<screen> + <command>kdiff3</command> <replaceable>dir1 dir2</replaceable> + <command>kdiff3</command> <replaceable>dir1 dir2</replaceable> -o <replaceable>destdir</replaceable> +</screen> +<para> + If no destination directory is specified, then KDiff3 will use <replaceable>dir2</replaceable>. +</para> +</sect2> + +<sect2><title>Compare/Merge three directories: </title> +<screen> + <command>kdiff3</command> <replaceable>dir1 dir2 dir3</replaceable> + <command>kdiff3</command> <replaceable>dir1 dir2 dir3</replaceable> -o <replaceable>destdir</replaceable> +</screen> +<para> + When three directories are merged then <replaceable>dir1</replaceable> + is used as the base for the merge. + If no destination directory is specified, then KDiff3 will use <replaceable>dir3</replaceable> + as the destination directory for the merge. +</para> + +<para> + Note that only the comparison starts automatically, not the merge. For this you first must + select a menu entry or the key F5. (More details later.) +</para> +</sect2> +</sect1> + +<sect1 id="dirmergevisible"><title>Visible Information</title> +<para> + While reading the directories a message-box appears that informs you of + the progress. If you abort the directory scan, then only files that have + been compared until then will be listed. +</para><para> + When the directory scan is complete then KDiff3 will show a listbox with + the results left, ... +</para> +<screenshot><mediaobject> +<imageobject><imagedata fileref="dirbrowser.png" format="PNG"/></imageobject> <!--alt="Image of the directory browser."--> +</mediaobject></screenshot> +<para> + ... and details about the currently selected item on the right: +</para> +<screenshot><mediaobject> +<imageobject><imagedata fileref="iteminfo.png" format="PNG"/></imageobject> + <!--alt="Image with information about the selected item."--> +</mediaobject></screenshot> + +<sect2 id="name"><title>The Name Column</title> +<para> + Each file and directory that was found during the scan is shown here in + a tree. You can select an item by clicking it with the mouse once. +</para><para> + The directories are collapsed by default. You can expand and collapse + them by clicking on the "+"/"-" or by double-clicking the item or + by using the left/right-arrow-keys. The "Directory"-menu also contains two + actions "Fold all subdirs" and "Unfold all subdirs" with which you can + collapse or expand all directories at once. +</para><para> + If you double-click a file item then the file comparison starts and the + file-diff-window will appear. +</para> +<para> + The image in the name column reflects the file type in the first + directory ("A"). It can be one of these: +</para> +<itemizedlist> + <listitem><para>Normal file</para></listitem> + <listitem><para>Normal directory (directory-image)</para></listitem> + <listitem><para>Link to a file (file-image with a link arrow)</para></listitem> + <listitem><para>Link to a directory (directory-image with a link arrow)</para></listitem> +</itemizedlist> +<para> + If the file type is different in the other directories, then this is visible + in the columns A/B/C and in the window that shows the details about the selected + item. Note that for such a case no merge operation can be selected automatically. + When starting the merge, then the user will be informed of problems of that + kind. +</para> +</sect2> + +<sect2 id="coloring"><title>The Columns A/B/C and the Coloring Scheme</title> +<para> + As can be seen in the image above the colors red, green, yellow and black + are used in the columns A/B/C. +</para> +<itemizedlist> + <listitem><para>Black: This item doesn't exist in this directory.</para></listitem> + <listitem><para>Green: Newest item.</para></listitem> + <listitem><para>Yellow: Older than green, newer than red.</para></listitem> + <listitem><para>Red: Oldest item.</para></listitem> +</itemizedlist> +<para> + But for items that were identical in the comparison their color also is + identical even if the age is not. +</para><para> + Directories are considered equal if all items they contain are identical. + Then they also will have the same color. But the age of a directory is not + considered for its color. +</para><para> + The idea for this coloring scheme I came upon in + <ulink url="http://samba.org/cgi-bin/cvsweb/dirdiff">dirdiff</ulink>. The colors + resemble the colors of a leaf that is green when new, turns yellow later and red + when old. +</para> + +</sect2><sect2 id="operation"><title>The Operation Column</title> +<para> + After comparing the directories KDiff3 also evaluates a proposal for a + merge operation. This is shown in the "Operation" column. You can modify + the operation by clicking on the operation you want to change. A small menu + will popup and allows you to select an operation for that item. This operation + will be executed during the merge. It depends on the item and on the merge-mode + you are in, what operations are available. The merge-mode is one of +</para> +<itemizedlist> + <listitem><para>Three directory-merge (A is treated as older base of both).</para></listitem> + <listitem><para>Two directory-merge.</para></listitem> + <listitem><para>Two directory-sync-mode (activate via option "Synchronize Directories").</para></listitem> +</itemizedlist> +<para> + In three directory merge the operation proposal will be: If for an item ... +</para> +<itemizedlist> + <listitem><para>... all three directories are equal: Copy from C</para></listitem> + <listitem><para>... A and C are equal but B is not: Copy from B (or if B does not + exist, delete the destination if exists)</para></listitem> + <listitem><para>... A and B are equal but C is not: Copy from C (or if C does not + exist, delete the destination if exists)</para></listitem> + <listitem><para>... B and C are equal but A is not: Copy from C (or if C does not + exist, delete the destination if exists)</para></listitem> + <listitem><para>... only A exists: Delete the destination (if exists)</para></listitem> + <listitem><para>... only B exists: Copy from B</para></listitem> + <listitem><para>... only C exists: Copy from C</para></listitem> + <listitem><para>... A, B and C are not equal: Merge</para></listitem> + <listitem><para>... A, B and C don't have the same file type (e.g. A is a directory, + B is a file): "Error: Conflicting File Types". While such items exist the + directory merge cannot start.</para></listitem> +</itemizedlist> +<para> + In two directory merge the operation proposal will be: If for an item ... +</para> +<itemizedlist> + <listitem><para>... both directories are equal: Copy from B</para></listitem> + <listitem><para>... A exists, but not B: Copy from A</para></listitem> + <listitem><para>... B exists, but not A: Copy from B</para></listitem> + <listitem><para>... A and B exist but are not equal: Merge</para></listitem> + <listitem><para>... A and B don't have the same file type (e.g. A is a directory, + B is a file): "Error: Conflicting File Types". While such items exist the + directory merge cannot start.</para></listitem> +</itemizedlist> +<para> + Sync-mode is active if only two directories and no explicit destination + were specified and if the option "Synchronize directories" is active. KDiff3 + then selects a default operation so that both directories are the same afterwards. + If for an item ... +</para> +<itemizedlist> + <listitem><para>... both directories are equal: Nothing will be done.</para></listitem> + <listitem><para>... A exists, but not B: Copy A to B</para></listitem> + <listitem><para>... B exists, but not A: Copy B to A</para></listitem> + <listitem><para>... A and B exist, but are not equal: Merge and store the result + in both directories. (For the user the visible save-filename is B, + but then KDiff3 copies B also to A.)</para></listitem> + <listitem><para>... A and B don't have the same file type (e.g. A is a directory, + B is a file): "Error: Conflicting File Types". While such items exist the + directory merge cannot start.</para></listitem> +</itemizedlist> +<para> + When two directories are merged and the option "Copy newer instead of merging" is selected, + then KDiff3 looks at the dates and proposes to choose the newer file. If the files are not + equal but have equal dates, then the operation will contain + "Error: Dates are equal but files are not." While such items exist the + directory merge cannot start. +</para> +</sect2> + +<sect2 id="status"><title>The Status Column</title> +<para> + During the merge one file after the other will be processed. The status + column will show "Done" for items where the merge operation has succeeded, + and other texts if something unexpected happened. When a merge is complete, + then you should make a last check to see if the status for all items is + agreeable. +</para> +</sect2> +</sect1> + + +<sect1 id="dothemerge"><title>Doing A Merge</title> +<para> + When you have made all your operation choices (in all subdirectories too) + then you can start the merge. +</para><para> + Be aware that if you didn't specify a destination directory explicitely, + then the destination will be "C" in three directory mode, "B" in two directory + merge mode, and in sync-mode it will be "A" or/and "B". +</para><para> + If you have specified a destination directory also check that all items + that should be in the output, are in the tree. There are some options that + cause certain items to be omitted from the directory comparison and merge. + Check these options to avoid unpleasant surprises: +</para> +<itemizedlist> + <listitem><para>"Recursive Directories": If this is off, then items in subdirectories + will not be found.</para></listitem> + <listitem><para>"Pattern"/"Anti-Pattern": Include/exclude items that match</para></listitem> + <listitem><para>"Exclude Hidden Files"</para></listitem> + <listitem><para>"List only Deltas": Files that match in all directories don't appear + in the tree, and hence also not in the destination.</para></listitem> +</itemizedlist> +<para> + (In the current version, you must do a rescan yourself, after changing + options affecting the directory scan.) +</para><para> + If you are satisfied so far, the rest is easy. +</para><para> + In the "Directory"-menu select "Start/Continue directory merge" or press + F5 (which is the shortcut). +</para><para> + If due to conflicting filetypes still some items with invalid operations + exist, then a messagebox will appear and these items will be pointed out, + so you can select a valid operation for the item. +</para><para> + Otherwise a dialog will appear giving you the options "Do it", "Simulate + it" and "Cancel". +</para> +<itemizedlist> + <listitem><para>Select "Simulate it" if you want to see what would be done without + actually doing it. A verbose list of all operations will be shown.</para></listitem> + <listitem><para>Otherwise select "Do it" to really start merging.</para></listitem> +</itemizedlist> +<para> + Then KDiff3 will run the specified operation for all items. If manual + interaction is required (single file merge), then a merge window will open + (<link linkend="dirmergebigscreenshot">see the big screenshot</link>). +</para><para> + When you have finished with a file, again select "Start/Continue directory + merge" or the key F5. If you haven't saved yet, a dialog will ask you to + do so. Then KDiff3 will continue with the next item. +</para><para> + When KDiff3 encounters an error, it will tell you so and will show the + verbose-status-information. At the bottom of this list, there will be some + error messages which should help you to understand the cause of the problem. + When you continue merging (F5 key) KDiff3 will give you the choice to retry + or skip the item that caused the problem. This means that before continuing + you can choose another operation or solve the problem by other means. +</para><para> + When the merge is complete, then KDiff3 will inform you via a message + box. +</para> +</sect1> + +<sect1 id="dirmergeoptions"><title>Options for Comparing and Merging Directories</title> +<para> + The KDiff3-preferences (menu "Settings"->"Configure KDiff3") now has + a section called "Directory Merge" with these options: +</para> + +<variablelist> + <varlistentry><term><emphasis>Recursive Directories:</emphasis></term><listitem><para> Select whether to search directories + recursively.</para></listitem></varlistentry> + <varlistentry><term><emphasis>File Pattern(s):</emphasis></term><listitem><para> Only files that match any pattern here will + be put in the tree. More than one pattern may be specified here via using + the semicolon ";" as separator. Valid wildcards: '*' and '?'. (e.g. "*.cpp;*.h"). + Default is "*". Directories need not match this pattern.</para></listitem></varlistentry> + <varlistentry><term><emphasis>Anti-Pattern(s):</emphasis></term><listitem><para> Files and directories that match this pattern + will be excluded from the tree. More than one pattern may be specified here + via using the semicolon ";" as separator. Valid wildcards: '*' and '?'. Default + is "*.orig;*.o".</para></listitem></varlistentry> + <varlistentry><term><emphasis>Use CVS-Ignore:</emphasis></term><listitem><para> + Ignore files and directories that would also be ignored by CVS. + Many automatically generated files are ignored by CVS. + The big advantage is that this can be directory specific via a local ".cvsignore"-file. + (See <ulink url="info:/cvs/cvsignore">info:/cvs/cvsignore</ulink>.)</para></listitem></varlistentry> + <varlistentry><term><emphasis>Find Hidden Files and Directories:</emphasis></term><listitem><para> On some filesystems files + have an "Hidden"-attribute. On other systems a filename starting with a dot + "." causes it to be hidden. This option allows you to decide whether to + include these files in the tree or not. Default is on.</para></listitem></varlistentry> + <varlistentry><term><emphasis>Follow File Links:</emphasis></term><listitem><para> For links to files: When disabled, then + the symbolic links are compared. When enabled, then the files behind the + links are compared. Default is off.</para></listitem></varlistentry> + <varlistentry><term><emphasis>Follow Directory Links:</emphasis></term><listitem><para> For links to directories: When disabled, + then the symbolic links will be compared. When enabled then the link will + be treated like a directory and it will be scanned recursively. (Note that + the program doesn't check if the link is "recursive". So for example a directory + that contains a link to the directory would cause an infinite loop, and after + some time when the stack overflows or all memory is used up, crash the program.) + Default is off.</para></listitem></varlistentry> + <varlistentry><term><emphasis>List only deltas:</emphasis></term><listitem><para> Only items that are not equal in all input + directories will be listed and only the changed files are visible. Hence + files that are equal in all directories won't be copied during a merge and + if the destination dir does not contain the files before the merge, you might + miss some files later. (This option is likely to be changed in a later version.) + Default is off.</para></listitem></varlistentry> + <varlistentry><term><emphasis>Trust the modification date:</emphasis></term><listitem><para> If you compare big directories + over a slow network, it might be faster to compare the modification dates + and file length alone. But this speed improvement comes with the price of + a little uncertainty. Use this option with care. Default is off.</para></listitem></varlistentry> + <varlistentry><term><emphasis>Synchronize Directories:</emphasis></term><listitem><para> Activates "Sync-Mode" when two directories + are compared and no explicit destination directory was specified. In this + mode the proposed operations will be chosen so that both source directories + are equal afterwards. Also the merge result will be written to both directories. + Default is off.</para></listitem></varlistentry> + <varlistentry><term><emphasis>Copy newer instead of merging:</emphasis></term><listitem><para> Instead of merging the proposed + operation will copy the newer source if changes happened. (Considered unsafe, + because it implies that the knowledge, that the other file hasn't been edited + too. Check to make sure in every case.) Default is off.</para></listitem></varlistentry> + <varlistentry><term><emphasis>Backup files:</emphasis></term><listitem><para> If a file or complete directory is replaced + by another or is deleted then the original version will be renamed with an + ".orig" extension. If an old backup file with ".orig" extension already exists + then this will be deleted without backup. This also affects the normal merging + of single files, not only in directory-merge mode. Default is on.</para></listitem></varlistentry> +</variablelist> +</sect1> + +<sect1 id="other"><title>Other Functions</title> +<sect2><title>Split/Full Screen Mode</title> +<para> + Usually the directory merge list view remains visible while a single file + is compared or merged. With the mouse you can move the the splitter bar that + separates the file list from the text-diff windows. If you don't want this, + you can disable "Split Screen View" in the "Directory"-menu. Then you can + use "Toggle View" in the "Directory"-menu to switch between the file list + and the text-diff view that then occupy the full screen. +</para> +</sect2> +<sect2><title>Comparing or Merging a Single File</title> +<para> + Probably you will prefer a simple double mouse click on a file in order + to compare it. Nevertheless there also exists an entry in the "Directory"-menu. + You can also directly merge a single file, without starting the directory + merge via the "Merge single file" in the "Directory"-Menu. On saving the + result, the status will be set to done, and the file will not be merged again + if a directory merge is started. +</para><para> + But note that this status information will be lost when you rerun a directory + scan: "Directory"-menu: "Rescan" +</para> +</sect2> +</sect1> +</chapter> + +<chapter id="misc"> +<title>Miscellaneous Topics</title> +<sect1 id="networktransparency"> +<title>Networktransparency via KIO</title> +<sect2><title>KIO-Slaves</title> +<para> +KDE supports networktransparency via KIO-slaves. KDiff3 uses this +for reading input files and for scanning directories. +This means that you can specify files and directories on local and +remote ressources via URLs. +</para><para> +Example: +</para><para> +<screen> + <command>kdiff3</command> test.cpp ftp://ftp.faraway.org/test.cpp + <command>kdiff3</command> tar:/home/hacker/archive.tar.gz/dir ./dir +</screen> +</para> +<para>The first line compares a local file with a file on an FTP-server. The second line +compares a directory within an compressed archive with a local directory. +</para><para> +Other KIO-slaves that are interesting are: +</para> +<itemizedlist> +<listitem><para>Files from the WWW (http:),</para></listitem> +<listitem><para>Files from the FTP (ftp:),</para></listitem> +<listitem><para>Encrypted file transfer (fish:, sftp:),</para></listitem> +<listitem><para>Windows-ressources (smb:),</para></listitem> +<listitem><para>Local files (file:),</para></listitem> +</itemizedlist> +<para> +Other things that are possible, but probably less useful are: +</para> +<itemizedlist> +<listitem><para>Man-pages (man:),</para></listitem> +<listitem><para>Info-pages (info:),</para></listitem> +</itemizedlist> +</sect2> + +<sect2><title>How To Write URLs</title> +<para> + An URL has a different syntax compared with paths for local files and directories. + Some things should be considered: +</para> +<itemizedlist> +<listitem><para> + A path can be relative and can contain "." or "..". This is not possible for URLs which are always absolute. +</para></listitem><listitem><para> + Special characters must be written with "escaping". ("#"->"%23", space->"%20", etc.) + E.g. A file with the name "/#foo#" would have the URL "file:/%23foo%23". +</para></listitem><listitem><para> + When URLs don't work as expected, try to open them in Konqueror first. +</para></listitem> +</itemizedlist> + +</sect2> + +<sect2><title>Capabilities of KIO-Slaves</title> +<para> + Networktransparency has one drawback: Not all ressources have the same cababilities. +</para><para> + Sometimes this is due to the filesystem of the server, sometimes due to the protocol. + Here is a short list of restrictions: +</para> +<itemizedlist> +<listitem><para> + Sometimes there is no support for links. +</para></listitem><listitem><para> + Or there is no way to distinguish if a link points to a file or a directory; always assuming a file. (ftp:, sftp:). +</para></listitem><listitem><para> + Can't always determine the filesize. +</para></listitem><listitem><para> + Limited support for permissions. +</para></listitem><listitem><para> + No possibility to modify permissions or modification time, so permissions or time of a copy will differ from the original. + (Only possible for local files.) +</para></listitem> +</itemizedlist> +</sect2> +</sect1> + +<sect1 id="kpart"> +<title>Using &kdiff3; as a KPart</title> +<para> +&kdiff3; is a KPart. Currently it implements the KParts::ReadOnlyPart-interface. +</para><para> +It's main use is as difference-viewer in KDevelop. KDevelop always starts the +internal difference viewer first. To invoke KDiff3 press the right mouse button +on the difference viewer window and select "Show in KDiff3Part" from the contextmenu. +</para><para> +KDiff3 normally requires two complete files as input. When used as part KDiff3 +will assume that the inputfile is a patch-file in the unified format. KDiff3 +then retrieves the original filenames from the patch-file. At least one of +the two files must be available. KDiff3 will then invoke <command>patch</command> to +recreate the second file. +</para><para> +In Konqueror you can select a patch-file and select "Preview in"-"KDiff3Part" from +the contextmenu. Be aware that this won't work if none of the original files are +available, and it is not reliable if the original file(s) have changed since the +patch-file was generated. +</para><para> +When run as a part KDiff3 only provides the a two-file-diff, a very small toolbar +and menu. Merging or directory-comparison are not supported then. +</para> +</sect1> +</chapter> + +<chapter id="faq"> +<title>Questions and Answers</title> + +&reporting.bugs; +&updating.documentation; + +<qandaset id="faqlist"> + +<qandaentry><question><para> + Why is it called "KDiff3"? +</para></question><answer><para> + Tools named "KDiff" and "KDiff2" (now called "Kompare") already exist. Also "KDiff3" should suggest + that it can merge like the "diff3"-tool in the Diff-Tool collection. +</para></answer></qandaentry> + +<qandaentry><question><para> + Why did I release it under GPL? +</para></question><answer><para> + 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. +</para></answer></qandaentry> + +<qandaentry><question><para> + Some buttons and functions are missing. What's wrong? +</para></question><answer><para> + You compiled from source but you probably didn't specify the correct KDE-prefix + with configure. By default configure wants to install in /usr/local but then KDE can't + find the user-interface ressource file (i.e. kdiff3ui.rc). The README-file contains + more information about the correct prefix. +</para></answer></qandaentry> + +<qandaentry><question><para> + Often lines that are similar but not identical appear next to each other + but sometimes not. Why? +</para></question><answer><para> + 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. +</para></answer></qandaentry> + +<qandaentry><question><para> + Why must all conflicts be solved before the merge result can be saved? +</para></question><answer><para> + 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. +</para></answer></qandaentry> + +<qandaentry><question><para> + Why does the editor in the merge result window not have an "undo"-function? +</para></question><answer><para> + This was too much effort until now. 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. +</para></answer></qandaentry> + +<qandaentry><question><para> + 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? +</para></question><answer><para> + 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). +</para></answer></qandaentry> + +<qandaentry><question><para> + Why doesn't KDiff3 support syntax-highlighting? +</para></question><answer><para> + KDiff3 already uses many colors for difference highlighting. More + highlighting would be confusing. Use another editor for this. +</para></answer></qandaentry> + +<qandaentry><question><para> + There is so much information here, but your question is still not answered? +</para></question><answer><para> + Please send me your question. I appreciate every comment. +</para></answer></qandaentry> + +</qandaset> +</chapter> + +<chapter id="credits"> + +<title>Credits and License</title> + +<para> +&kdiff3; - File and Directory Comparison and Merge Tool +</para> +<para> +Program copyright 2002-2003 Joachim Eibl <email>joachim.eibl@gmx.de</email> +</para> +<para> +Several cool ideas and bugreports came from colleagues and many people out in the Wild Wild Web. Thank you! +</para> + +<para> +Documentation Copyright © 2002-2003 Joachim Eibl <email>joachim.eibl@gmx.de</email> +</para> + +<!-- TRANS:CREDIT_FOR_TRANSLATORS --> + +&underFDL; <!-- FDL: do not remove --> + + +&underGPL; <!-- GPL License --> + +</chapter> + +<appendix id="installation"> +<title>Installation</title> + +<sect1 id="getting-kdiff3"> +<title>How to obtain &kdiff3;</title> + +<para> +You can download the latest version of KDiff3 from its homepage <ulink url="http://kdiff3.sourceforge.net">http://kdiff3.sourceforge.net</ulink>. +</para><para> +KDiff3 is also available for other platforms. See the homepage for details. +</para> + + +</sect1> + +<sect1 id="requirements"> +<title>Requirements</title> + +<para> + In order to successfully use all features of &kdiff3;, you need &kde; >3.1. The + diff-tool from the <ulink url="http://www.gnu.org/software/diffutils/diffutils.html">GNU-diff-utils</ulink> + is recommended for best results. +</para><para> + For information about how to run KDiff3 on other platforms without KDE please see the + <ulink url="http://kdiff3.sourceforge.net">homepage</ulink>. +</para><para> +You can find a list of changes at <ulink +url="http://kdiff3.sourceforge.net/ChangeLog">http://kdiff3.sourceforge.net/ChangeLog</ulink> +or in the "ChangeLog"-file of the source package. +</para> +</sect1> + +<sect1 id="compilation"> +<title>Compilation and Installation</title> + +<para>In order to compile and install &kdiff3; on a system with KDE, type the +following in the base directory of the &kdiff3; distribution:</para> + +<screen><prompt>%</prompt> <userinput><command>./configure --prefix=<replaceable>kde-dir</replaceable></command></userinput> +<prompt>%</prompt> <userinput><command>make</command></userinput> +<prompt>%</prompt> <userinput><command>make</command> install</userinput> +</screen> +<para> +<replaceable>kde-dir</replaceable> specifies the directory +containing KDE on your system. If you are not sure, read the README-file for details. +</para> +<para>Since &kdiff3; uses <command>autoconf</command> and +<command>automake</command> you should have no trouble compiling it. Should you +run into problems please report them to the &kde; mailing lists.</para> + +</sect1> + +</appendix> + +&documentation.index; +</book> + +<!-- +Local Variables: +mode: sgml +sgml-minimize-attributes:nil +sgml-general-insert-case:lower +sgml-indent-step:0 +sgml-indent-data:nil +End: + +vim:tabstop=2:shiftwidth=2:expandtab +-->